Example usages of the official Kubernetes Go client (client-go).
The example programs are adapted from the examples in the client-go GitHub repository.
Compile and run the example programs as follows:
go run example.goOne of the first thing every program using a Kubernetes client library does is reading a kubeconfig file (the same type of file read by kubectl).
All example programs in this repository read the default kubeconfig file ~/.kube/config. So, before running the programs, make sure that this file exists ad that the context is set to the Kubernetes cluster that you want to work on.
You can check the active context in the kubeconfig file like this:
kubectl config current-contextTo be able to build the example programs, you first need to install the Go client library according to the instructions here:
go get k8s.io/client-go/...
go get -u k8s.io/apimachinery/...This example shows how to list different types of resources across all namespaces. The listed resources include:
This example shows how to create a new deployment in the default namespace, list all deployments in the default namespace, and finally delete the created deployment.
The carried out steps are:
- Create deployment
- List deployments
- Delete deployment
The execution of the program stops after each steps until you press Enter. This allows you to inspect the resources in the cluster with kubectl after each step.
This example shows how to create a deployment and a service that exposes this deployment. All resources are created in the default namespace.
The service is of type load balancer and listens on port 80. The deployment manages multiple replicas of NGINX containers.
The steps carried out are:
- Create deployment
- Create service
- Delete service
- Delete deployment
The execution of the program stops after each steps until you press Enter. This allows you to inspect the resources in the cluster with kubectl after each step.
Note that after step 2, it might take some minutes until the service is accessible through the load balancer's IP address or DNS name (this depends on the cloud provider). Once the load balancer is initialised, you should see the NGINX welcome page when you access the service.
This example shows how to read a Kubernetes API object (in this case a deployment) from a YAML file, and then deploy it to the cluster.
The client-go library provides no straightforward way to read API objects from YAML files (see here). We can work around this by using the github.com/ghodss/yaml package to parse a YAML file and convert it to a client-go Kubernetes API object struct.
The github.com/ghodss/yaml package is suitable, because it converts the YAML to JSON before reading it into a struct. This is good because the client-go API object structs contain tags for the JSON format, that is, the structs themselves define their serialisation/deserialisation to and from JSON. In this way, the overall conversion from YAML to a client-go API object struct works correctly, even if the structs have no YAML tags.
Note that if we defined the API objects in JSON instead of YAML, we could convert them to client-go API object structs with the standard encoding/json package (see here).
This example shows how to create and update secrets. Kubernetes secrets are similar to config maps except that secrets are intended to contain sensitive data (and are stored in encrypted form in the Kubernetes control plane). The purpose of secrets is to securely distribute sensitive data to pods.
A single secret objects contains a data field that contains any number of key/value pairs. The keys are strings and the values are Base64 encodings of arbitrary bytes. The decoded values may be strings or non-strings (e.g. binary data).
There is a small complication: the secret object also provides a stringData field which allows to specify values as unencoded strings rather than Base64-encoded bytes. The values are then automatically Base64-encoded and the key/value pairs are saved in the data field of the object (overwriting any existing values with identical keys). The stringData field exists for convenience (to more easily specify secret data with string values) and it is write-only. That means, when reading a secret, only the data field contains any data, no matter whether the data has been specified through the data or stringData field.
When reading a secret specification from a YAML file, client-go (as well as kubectl) expect values under data to be Base64-encodings and values under stringData to be plain strings. However, when defining new secret data programmatically, client-go does the Base64 encoding automatically, and it simply requires values for data to be byte arrays and values for stringData to be strings. Similarly, when reading a secret, client-go returns the values of the data field as non-Base64-encoded byte arrays (regarding the stringData field, remember that it is never read). However, when you read a secret with kubectl, the data values are always output as Base64 encodings.
All of this is summarised in the following.
Secret specified in YAML file:
| client-go | kubectl |
-----------+-----------+---------+
data | Base64 | Base64 |
stringData | string | string |
Adding and reading secret values in client-go, and reading secret values with kubectl:
| client-go | |
| add | read | kubectl get |
-----------+--------------------+--------------------+-------------|
data | []byte (unencoded) | []byte (unencoded) | Base64 |
stringData | string | - | - |
To read the data of a secret with kubectl, use the following command:
kubectl get -o yaml secret/my-secretThe example reads an initial secret specification from a YAML file and then adds new key/value pairs to it, both through the data and the stringData fields. After each step the execution pauses until you press Enter. It is helpful to inspect the secret after each step with the above command.