klient

README

Klient

Klient is a Simple Kubernetes Client in Go. Its goal is to provide an easy interface to communicate with a Kubernetes cluster similar to using the kubectl commands apply, create, delete and replace.

This package is not a replacement of k8s.io/client-go, its main purpose is to apply, create, delete or replace resources using the YAML or JSON representation of Kubernetes objects. The package k8s.io/client-go requires to know what objects are going to be managed and uses the Kubernetes API to manage them. If you have a file, URL, stream or string with a Kubernetes object to apply (not knowing exactly what's inside) then klient will help you.

This package is part of the blog article Building a Kubernetes Client in Go. Refer to this blog post to know why and how Klient was made.

How to use

Start by importing the package using (import github.com/johandry/klient) and making sure it is in your go.mod file using the latest version executing any go tool command or just go mod tidy. Create the client providing - optionally - the Kubernetes context and the Kubeconfig file location, finally use the methods Apply(), Create(), Delete(), Replace() or it's variations to interact with the Kubernetes cluster.

Example

The following example is to apply a ConfigMap from a []byte variable. It assumes you have a Kubernetes cluster running, accessible and with the Kubeconfig in the default location (~/.kube/config).

It uses klient to apply the ConfigMap and uses the Kubernetes client k8s.io/client-go to get it. This simple example can be done using only k8s.io/client-go to do it all as we know, in advance the object to work with (ConfigMap), however we are dealing with a JSON string representing the ConfigMap, that's why we use klient.

It's unpractical in a real program to apply a resource and then delete it, but just for the purpose of explain how to delete a resource the example deletes the ConfigMap once it's over.

package main

import (
  "log"

  "github.com/johandry/klient"
  metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)

func main() {
  name := "apple"
  cm := []byte(`{"apiVersion": "v1", "kind": "ConfigMap", "metadata": { "name": "fruit" }, "data": {	"name": "` + name + `" } }`)

  c := klient.New("", "") // Take the Kubernetes config from the default location (~/.kube/config) and using the default context.
  if err := c.Apply(cm); err != nil {
    log.Fatal("failed to apply the ConfigMap")
  }

  cmFruit, err := c.Clientset.CoreV1().ConfigMaps("default").Get("fruit", metav1.GetOptions{})
  if err != nil {
    log.Fatal("Failed to get the ConfigMap fruits")
  }
  log.Printf("Fruit name: %s", cmFruit.Data["name"])

  if err := c.Delete(cm); err != nil {
    log.Fatal("failed to delete the ConfigMap")
  }
}

For more examples go to the GitHub repository johandry/klient-examples.

Sources and Acknowledge

Many thanks to the contributors of Kubectl and Helm. This package was made inspired by these two amazing projects.

Although it's not so easy or intuitive to use the kubectl code from your Go projects, it's not complex to import and use the Helm Kubernetes client package, so you could either use Klient or the Helm Kubernetes client package to communicate with a Kubernetes cluster.

Documentation

Index

• Constants
• type BuilderOptions
  • func NewBuilderOptions() *BuilderOptions
• type Client
  • func New(context, kubeconfig string) *Client
  • func NewE(context, kubeconfig string) (*Client, error)
  • func (c *Client) Apply(content []byte) error
  • func (c *Client) ApplyFiles(filenames ...string) error
  • func (c *Client) ApplyResource(r *resource.Result) error
  • func (c *Client) Create(content []byte) error
  • func (c *Client) CreateFile(filenames ...string) error
  • func (c *Client) CreateNamespace(namespace string) error
  • func (c *Client) CreateResource(r *resource.Result) error
  • func (c *Client) Delete(content []byte) error
  • func (c *Client) DeleteFiles(filenames ...string) error
  • func (c *Client) DeleteNamespace(namespace string) error
  • func (c *Client) DeleteResource(r *resource.Result) error
  • func (c *Client) NodesReady() (ready int, total int, err error)
  • func (c *Client) Replace(content []byte) error
  • func (c *Client) ReplaceFiles(filenames ...string) error
  • func (c *Client) ReplaceResource(r *resource.Result) error
  • func (c *Client) ResultForContent(content []byte, opt *BuilderOptions) *Result
  • func (c *Client) ResultForFilenameParam(filenames []string, opt *BuilderOptions) *Result
  • func (c *Client) ResultForReader(r io.Reader, opt *BuilderOptions) *Result
  • func (c *Client) Version() (string, error)
• type Result

Constants

const DefaultValidation = true

DefaultValidation default action to validate. If `true` all resources by default will be validated.

Types

type BuilderOptions

type BuilderOptions struct {
	Unstructured  bool
	Validate      bool
	Namespace     string
	LabelSelector string
	FieldSelector string
	All           bool
	AllNamespaces bool
}

BuilderOptions parameters to create a Resource Builder

func NewBuilderOptions

func NewBuilderOptions() *BuilderOptions

NewBuilderOptions creates a BuilderOptions with the default values for the parameters to create a Resource Builder

type Client

type Client struct {
	Clientset *kubernetes.Clientset

	ServerSideApply bool
	// contains filtered or unexported fields
}

Client is a kubernetes client, like `kubectl`

func New

func New(context, kubeconfig string) *Client

New creates a kubernetes client

func NewE

func NewE(context, kubeconfig string) (*Client, error)

NewE creates a kubernetes client, returns an error if fail

func (*Client) Apply

func (c *Client) Apply(content []byte) error

Apply creates a resource with the given content

func (*Client) ApplyFiles

func (c *Client) ApplyFiles(filenames ...string) error

ApplyFiles create the resource(s) from the given filenames (file, directory or STDIN) or HTTP URLs

func (*Client) ApplyResource

func (c *Client) ApplyResource(r *resource.Result) error

ApplyResource applies the given resource. Create the resources with `ResultForFilenameParam` or `ResultForContent`

func (*Client) Create

func (c *Client) Create(content []byte) error

Create creates a resource with the given content

func (*Client) CreateFile

func (c *Client) CreateFile(filenames ...string) error

CreateFile creates a resource with the given content

func (*Client) CreateNamespace

func (c *Client) CreateNamespace(namespace string) error

CreateNamespace creates a namespace with the given name

func (*Client) CreateResource

func (c *Client) CreateResource(r *resource.Result) error

CreateResource creates the given resource. Create the resources with `ResultForFilenameParam` or `ResultForContent`

func (*Client) Delete

func (c *Client) Delete(content []byte) error

Delete creates a resource with the given content

func (*Client) DeleteFiles

func (c *Client) DeleteFiles(filenames ...string) error

DeleteFiles create the resource(s) from the given filenames (file, directory or STDIN) or HTTP URLs

func (*Client) DeleteNamespace

func (c *Client) DeleteNamespace(namespace string) error

DeleteNamespace deletes the namespace with the given name

func (*Client) DeleteResource

func (c *Client) DeleteResource(r *resource.Result) error

DeleteResource applies the given resource. Create the resources with `ResultForFilenameParam` or `ResultForContent`

func (*Client) NodesReady

func (c *Client) NodesReady() (ready int, total int, err error)

NodesReady returns the number of nodes ready

func (*Client) Replace

func (c *Client) Replace(content []byte) error

Replace creates a resource with the given content

func (*Client) ReplaceFiles

func (c *Client) ReplaceFiles(filenames ...string) error

ReplaceFiles create the resource(s) from the given filenames (file, directory or STDIN) or HTTP URLs

func (*Client) ReplaceResource

func (c *Client) ReplaceResource(r *resource.Result) error

ReplaceResource applies the given resource. Create the resources with `ResultForFilenameParam` or `ResultForContent`

func (*Client) ResultForContent

func (c *Client) ResultForContent(content []byte, opt *BuilderOptions) *Result

ResultForContent returns the builder results for the given content

func (*Client) ResultForFilenameParam

func (c *Client) ResultForFilenameParam(filenames []string, opt *BuilderOptions) *Result

ResultForFilenameParam returns the builder results for the given list of files or URLs

func (*Client) ResultForReader

func (c *Client) ResultForReader(r io.Reader, opt *BuilderOptions) *Result

ResultForReader returns the builder results for the given reader

func (*Client) Version

func (c *Client) Version() (string, error)

Version returns the cluster version. It can be used to verify if the cluster is reachable. It will return an error if failed to connect.

type Result

type Result = resource.Result

Result is an alias for the Kubernetes CLI runtime resource.Result