client-go Documentation

1. Project Overview & Quickstart (kubernetes/client-go) Copy Chapter

File: README.md Copy Chapter

⚠️ This is an automatically published staged repository for Kubernetes.
Contributions, including issues and pull requests, should be made to the main Kubernetes repository: https://github.com/kubernetes/kubernetes.
This repository is read-only for importing, and not used for direct contributions.
See CONTRIBUTING.md for more details.

client-go

Go clients for talking to a kubernetes cluster.

We recommend using the v0.x.y tags for Kubernetes releases >= v1.17.0 and
kubernetes-1.x.y tags for Kubernetes releases < v1.17.0.

The fastest way to add this library to a project is to run go get k8s.io/client-go@latest with go1.16+.
See INSTALL.md for detailed installation instructions and troubleshooting.

Table of Contents Copy Chapter

• What's included
• Versioning
  • Compatibility: your code <-> client-go
  • Compatibility: client-go <-> Kubernetes clusters
  • Compatibility matrix
  • Why do the 1.4 and 1.5 branch contain top-level folder named after the version?
• Kubernetes tags
• How to get it
• How to use it
• Dependency management
• Contributing code

What's included Copy Section

• The kubernetes package contains the clientset to access Kubernetes API.
• The discovery package is used to discover APIs supported by a Kubernetes API server.
• The dynamic package contains a dynamic client that can perform generic operations on arbitrary Kubernetes API objects.
• The plugin/pkg/client/auth packages contain optional authentication plugins for obtaining credentials from external sources.
• The transport package is used to set up auth and start a connection.
• The tools/cache package is useful for writing controllers.

Versioning Copy Section

• For each v1.x.y Kubernetes release, the major version (first digit)
  would remain 0.

• Bugfixes will result in the patch version (third digit) changing. PRs that are
  cherry-picked into an older Kubernetes release branch will result in an update
  to the corresponding branch in client-go, with a corresponding new tag
  changing the patch version.

Branches and tags.

We will create a new branch and tag for each increment in the minor version
number. We will create only a new tag for each increment in the patch
version number. See semver for definitions of major,
minor, and patch.

The HEAD of the master branch in client-go will track the HEAD of the master
branch in the main Kubernetes repo.

Compatibility: your code <-> client-go

The v0.x.y tags indicate that go APIs may change in incompatible ways in
different versions.

See INSTALL.md for guidelines on requiring a specific
version of client-go.

Compatibility: client-go <-> Kubernetes clusters

Since Kubernetes is backwards compatible with clients, older client-go
versions will work with many different Kubernetes cluster versions.

We will backport bugfixes--but not new features--into older versions of
client-go.

Compatibility matrix

Key:

• ✓ Exactly the same features / API objects in both client-go and the Kubernetes
  version.
• + client-go has features or API objects that may not be present in the
  Kubernetes cluster, either due to that client-go has additional new API, or
  that the server has removed old API. However, everything they have in
  common (i.e., most APIs) will work. Please note that alpha APIs may vanish or
  change significantly in a single release.
• - The Kubernetes cluster has features the client-go library can't use,
  either due to the server has additional new API, or that client-go has
  removed old API. However, everything they share in common (i.e., most APIs)
  will work.

See the CHANGELOG for a detailed description of changes
between client-go versions.

Key:

• ✓ Changes in main Kubernetes repo are actively published to client-go by a bot
• = Maintenance is manual, only severe security bugs will be patched.
• - Deprecated; please upgrade.

Deprecation policy

We will maintain branches for at least six months after their first stable tag
is cut. (E.g., the clock for the release-2.0 branch started ticking when we
tagged v2.0.0, not when we made the first alpha.) This policy applies to
every version greater than or equal to 2.0.

Why do the 1.4 and 1.5 branch contain top-level folder named after the version?

For the initial release of client-go, we thought it would be easiest to keep
separate directories for each minor version. That soon proved to be a mistake.
We are keeping the top-level folders in the 1.4 and 1.5 branches so that
existing users won't be broken.

Kubernetes tags Copy Section

This repository is still a mirror of
k8s.io/kubernetes/staging/src/client-go,
the code development is still done in the staging area.

Since Kubernetes v1.8.0, when syncing the code from the staging area,
we also sync the Kubernetes version tags to client-go, prefixed with
kubernetes-. From Kubernetes v1.17.0, we also create matching semver
v0.x.y tags for each v1.x.y Kubernetes release.

For example, if you check out the kubernetes-1.17.0 or the v0.17.0 tag in
client-go, the code you get is exactly the same as if you check out the v1.17.0
tag in Kubernetes, and change directory to staging/src/k8s.io/client-go.

The purpose is to let users quickly find matching commits among published repos,
like sample-apiserver,
apiextension-apiserver,
etc. The Kubernetes version tag does NOT claim any backwards compatibility
guarantees for client-go. Please check the semantic versions if
you care about backwards compatibility.

How to get it Copy Section

To get the latest version, use go1.16+ and fetch using the go get command. For example:

go get k8s.io/client-go@latest

To get a specific version, use go1.11+ and fetch the desired version using the go get command. For example:

go get k8s.io/[email protected]

See INSTALL.md for detailed instructions and troubleshooting.

How to use it Copy Section

If your application runs in a Pod in the cluster, please refer to the
in-cluster example, otherwise please
refer to the out-of-cluster example.

Dependency management Copy Section

For details on how to correctly use a dependency management for installing client-go, please see INSTALL.md.

Contributing code Copy Section

Please send pull requests against the client packages in the Kubernetes main repository. Changes in the staging area will be published to this repository every day.

File: examples/out-of-cluster-client-configuration/README.md Copy Chapter

Authenticating outside the cluster

This example shows you how to configure a client with client-go to authenticate
to the Kubernetes API from an application running outside the Kubernetes
cluster.

You can use your kubeconfig file that contains the context information
of your cluster to initialize a client. The kubeconfig file is also used
by the kubectl command to authenticate to the clusters.

Running this example Copy Chapter

Make sure your kubectl is configured and pointed to a cluster. Run
kubectl get nodes to confirm.

Run this application with:

cd out-of-cluster-client-configuration
go build -o app .
./app

Running this application will use the kubeconfig file and then authenticate to the
cluster, and print the number of pods in the cluster every 10 seconds:

./app
There are 3 pods in the cluster
There are 3 pods in the cluster
There are 3 pods in the cluster
...

Press Ctrl+C to quit this application.

Note: You can use the -kubeconfig option to use a different config file. By default
this program picks up the default file used by kubectl (when KUBECONFIG
environment variable is not set).

File: examples/leader-election/README.md Copy Chapter

Leader Election Example

This example demonstrates how to use the leader election package.

Running Copy Chapter

Run the following three commands in separate terminals. Each terminal needs a unique id.

# first terminal
go run main.go -kubeconfig=/path/to/kubeconfig -logtostderr=true -lease-lock-name=example -lease-lock-namespace=default -id=1

# second terminal
go run main.go -kubeconfig=/path/to/kubeconfig -logtostderr=true -lease-lock-name=example -lease-lock-namespace=default -id=2

# third terminal
go run main.go -kubeconfig=/path/to/kubeconfig -logtostderr=true -lease-lock-name=example -lease-lock-namespace=default -id=3

You can ignore the -kubeconfig flag if you are running these commands in the Kubernetes cluster.

Now kill the existing leader. You will see from the terminal outputs that one of the remaining two processes will be elected as the new leader.

File: examples/in-cluster-client-configuration/README.md Copy Chapter

Authenticating inside the cluster

This example shows you how to configure a client with client-go to authenticate
to the Kubernetes API from an application running inside the Kubernetes cluster.

client-go uses the Service Account token mounted inside the Pod at the
/var/run/secrets/kubernetes.io/serviceaccount path when the
rest.InClusterConfig() is used.

Running this example Copy Chapter

First compile the application for Linux:

cd in-cluster-client-configuration
GOOS=linux go build -o ./app .

Then package it to a docker image using the provided Dockerfile to run it on
Kubernetes.

If you are running a Minikube cluster, you can build this image directly
on the Docker engine of the Minikube node without pushing it to a registry. To
build the image on Minikube:

eval $(minikube docker-env)
docker build -t in-cluster .

If you are not using Minikube, you should build this image and push it to a registry
that your Kubernetes cluster can pull from.

If you have RBAC enabled on your cluster, use the following
snippet to create role binding which will grant the default service account view
permissions.

kubectl create clusterrolebinding default-view --clusterrole=view --serviceaccount=default:default

Then, run the image in a Pod with a single instance Deployment:

kubectl run --rm -i demo --image=in-cluster

There are 4 pods in the cluster
There are 4 pods in the cluster
There are 4 pods in the cluster
...

The example now runs on Kubernetes API and successfully queries the number of
pods in the cluster every 10 seconds.

Clean up Copy Section

To stop this example and clean up the pod, press Ctrl+C on
the kubectl run command and then run:

kubectl delete deployment demo

File: examples/fake-client/README.md Copy Chapter

Fake Client Example

This example demonstrates how to use a fake client with SharedInformerFactory in tests.

It covers:

• Creating the fake client
• Setting up real informers
• Injecting events into those informers

Running Copy Chapter

go test -v k8s.io/client-go/examples/fake-client

File: examples/dynamic-create-update-delete-deployment/README.md Copy Chapter

Create, Update & Delete Deployment with the Dynamic Package

This example program demonstrates the fundamental operations for managing on
Deployment resources, such as Create, List, Update and Delete using client-go's dynamic package.

Typed Vs. Dynamic Copy Chapter

The code in this directory is based on a similar example that uses Kubernetes typed client sets. The typed client sets make it simple to communicate with the API server using pre-generated local API objects to achieve an RPC-like programming experience. Typed clients uses program compilations to enforce data safety and some validation. However, when using typed clients, programs are forced to be tightly coupled with the version and the types used.

The dynamic package on the other hand, uses a simple type, unstructured.Unstructured, to represent all object values from the API server. Type Unstructured uses a collection of nested map[string]interface{} values to create an internal structure that closely resemble the REST payload from the server.

The dynamic package defers all data bindings until runtime. This means programs that use the dynamic client will not get any of the benefits of type validation until the program is running. This may be a problem for certain types of applications that require strong data type check and validation.

Being loosely coupled, however, means that programs that uses the dynamic package do not require recompilation when the client API changes. The client program has more flexibility in handling updates to the API surface without knowing ahead of time what those changes are.

Running this example Copy Chapter

Make sure you have a Kubernetes cluster and kubectl is configured:

kubectl get nodes

Compile this example on your workstation:

cd dynamic-create-update-delete-deployment
go build -o ./app

Now, run this application on your workstation with your local kubeconfig file:

./app
# or specify a kubeconfig file with flag
./app -kubeconfig=$HOME/.kube/config

Running this command will execute the following operations on your cluster:

1. Create Deployment: This will create a 2 replica Deployment. Verify with
   kubectl get pods.
2. Update Deployment: This will update the Deployment resource created in
   previous step by setting the replica count to 1 and changing the container
   image to nginx:1.13. You are encouraged to inspect the retry loop that
   handles conflicts. Verify the new replica count and container image with
   kubectl describe deployment demo.
3. List Deployments: This will retrieve Deployments in the default
   namespace and print their names and replica counts.
4. Delete Deployment: This will delete the Deployment object and its
   dependent ReplicaSet resource. Verify with kubectl get deployments.

Each step is separated by an interactive prompt. You must hit the
Return key to proceed to the next step. You can use these prompts as
a break to take time to run kubectl and inspect the result of the operations
executed.

You should see an output like the following:

Creating deployment...
Created deployment "demo-deployment".
-> Press Return key to continue.

Updating deployment...
Updated deployment...
-> Press Return key to continue.

Listing deployments in namespace "default":
 * demo-deployment (1 replicas)
-> Press Return key to continue.

Deleting deployment...
Deleted deployment.

Cleanup Copy Chapter

Successfully running this program will clean the created artifacts. If you
terminate the program without completing, you can clean up the created
deployment with:

kubectl delete deploy demo-deployment

Troubleshooting Copy Chapter

If you are getting the following error, make sure Kubernetes version of your
cluster is v1.13 or higher in kubectl version:

panic: the server could not find the requested resource

File: examples/create-update-delete-deployment/README.md Copy Chapter

Create, Update & Delete Deployment

This example program demonstrates the fundamental operations for managing on
Deployment resources, such as Create, List, Update and Delete.

You can adopt the source code from this example to write programs that manage
other types of resources through the Kubernetes API.

Running this example Copy Chapter

Make sure you have a Kubernetes cluster and kubectl is configured:

kubectl get nodes

Compile this example on your workstation:

cd create-update-delete-deployment
go build -o ./app

Now, run this application on your workstation with your local kubeconfig file:

./app
# or specify a kubeconfig file with flag
./app -kubeconfig=$HOME/.kube/config

Running this command will execute the following operations on your cluster:

1. Create Deployment: This will create a 2 replica Deployment. Verify with
   kubectl get pods.
2. Update Deployment: This will update the Deployment resource created in
   previous step by setting the replica count to 1 and changing the container
   image to nginx:1.13. You are encouraged to inspect the retry loop that
   handles conflicts. Verify the new replica count and container image with
   kubectl describe deployment demo.
3. List Deployments: This will retrieve Deployments in the default
   namespace and print their names and replica counts.
4. Delete Deployment: This will delete the Deployment object and its
   dependent ReplicaSet resource. Verify with kubectl get deployments.

Each step is separated by an interactive prompt. You must hit the
Return key to proceed to the next step. You can use these prompts as
a break to take time to run kubectl and inspect the result of the operations
executed.

You should see an output like the following:

Creating deployment...
Created deployment "demo-deployment".
-> Press Return key to continue.

Updating deployment...
Updated deployment...
-> Press Return key to continue.

Listing deployments in namespace "default":
 * demo-deployment (1 replicas)
-> Press Return key to continue.

Deleting deployment...
Deleted deployment.

Cleanup Copy Chapter

Successfully running this program will clean the created artifacts. If you
terminate the program without completing, you can clean up the created
deployment with:

kubectl delete deploy demo-deployment

Troubleshooting Copy Chapter

If you are getting the following error, make sure Kubernetes version of your
cluster is v1.6 or above in kubectl version:

panic: the server could not find the requested resource

File: examples/workqueue/README.md Copy Chapter

Workqueue Example

This example demonstrates how to write a controller which follows the states
of watched resources.

It demonstrates how to:

• combine the workqueue with a cache to a full controller
• synchronize the controller on startup

The example is based on https://git.k8s.io/community/contributors/devel/sig-api-machinery/controllers.md.

Running Copy Chapter

# if outside of the cluster
go run *.go -kubeconfig=/my/config

File: examples/README.md Copy Chapter

client-go Examples

This directory contains examples that cover various use cases and functionality
for client-go.

Auth plugins Copy Section

Client configuration is typically loaded from kubeconfig files containing server and credential configuration.
Several plugins for obtaining credentials from external sources are available, but are not loaded by default.
To enable these plugins in your program, import them in your main package.

You can load all auth plugins:

import _ "k8s.io/client-go/plugin/pkg/client/auth"

Or you can load specific auth plugins:

import _ "k8s.io/client-go/plugin/pkg/client/auth/azure"
import _ "k8s.io/client-go/plugin/pkg/client/auth/gcp"
import _ "k8s.io/client-go/plugin/pkg/client/auth/oidc"

Configuration Copy Section

• Authenticate in cluster: Configure a
  client while running inside the Kubernetes cluster.
• Authenticate out of cluster:
  Configure a client to access a Kubernetes cluster from outside.

Basics Copy Section

• Managing resources with API: Create,
  get, update, delete a Deployment resource.

Advanced Concepts Copy Section

• Work queues: Create a hotloop-free controller with the
  rate-limited workqueue and the informer framework.
• Custom Resource Definition (CRD):
  Register a custom resource type with the API, create/update/query this custom
  type, and write a controller that drives the cluster state based on the changes to
  the custom resources.
• Leader election: Demonstrates the use of the leader election package, which can be used to implement HA controllers.

Testing Copy Section

• Fake Client: Use a fake client in tests.

2. Official Technical Reference & Guides (kubernetes/kubernetes.github.io) Copy Chapter

The Kubernetes documentation

This repository contains the assets required to build the Kubernetes website and documentation. We're glad that you want to contribute!

• Contributing to the docs
• Localization READMEs

Using this repository Copy Chapter

You can run the website locally using Hugo (Extended version), or you can run it in a container runtime. We strongly recommend using the container runtime, as it gives deployment consistency with the live website.

Prerequisites Copy Chapter

To use this repository, you need the following installed locally:

• npm
• Go
• Hugo (Extended version)
• A container runtime, like Docker.

[!NOTE]
Make sure to install the Hugo extended version specified by the HUGO_VERSION environment variable in the netlify.toml file.

Before you start, install the dependencies. Clone the repository and navigate to the directory:

git clone https://github.com/kubernetes/website.git
cd website

The Kubernetes website uses the Docsy Hugo theme,
which can be installed via npm. You can also download a pre-configured
development container image that includes Hugo and Docsy. Additionally, a Git
submodule is used for tools that generate the reference documentation.

Windows Copy Section

# fetch submodule dependencies
git submodule update --init --recursive --depth 1

Linux / other Unix Copy Section

# fetch submodule dependencies
make module-init

Running the website using a container Copy Chapter

To build the site in a container, run the following:

# You can set $CONTAINER_ENGINE to the name of any Docker-like container tool

# Render the full website
make container-serve

# Render only a specific language segment (e.g., English)
make container-serve segments=en

# Render multiple languages (e.g., English and Korean)
make container-serve segments=en,ko

💡 Tip: Using Hugo segments speeds up local preview builds, by rendering only selected language(s).

If you see errors, it probably means that the Hugo container did not have enough computing resources available. To solve it, increase the amount of allowed CPU and memory usage for Docker on your machine (macOS and Windows).

Open up your browser to http://localhost:1313 to view the website. As you make changes to the source files, Hugo updates the website and forces a browser refresh.

Running the website locally using Hugo Copy Chapter

To install dependencies, deploy and test the site locally, run:

• For macOS and Linux

  bash Copy

  npm ci
  
  # Render the full site (default)
  make serve
  
  # Render only a specific language segment
  make serve segments=en
  
  # Render multiple language segments
  make serve segments=en,ko

💡 Tip: Hugo segments are defined in hugo.toml and allow faster rendering by limiting the scope to specific language(s).

• For Windows (PowerShell)

  powershell Copy

  npm ci
  hugo.exe server --config hugo.toml,hugo.server.toml --buildFuture --environment development

This will start the local Hugo server on port 1313. Open up your browser to http://localhost:1313 to view the website. As you make changes to the source files, Hugo updates the website and forces a browser refresh.

Building the API reference pages Copy Chapter

The API reference pages located in content/en/docs/reference/kubernetes-api are built from the Swagger specification, also known as OpenAPI specification, using https://github.com/kubernetes-sigs/reference-docs/tree/master/gen-resourcesdocs.

To update the reference pages for a new Kubernetes release follow these steps:

1. Pull in the api-ref-generator submodule:

   bash Copy

   git submodule update --init --recursive --depth 1

2. Update the Swagger specification:

   bash Copy

   curl 'https://raw.githubusercontent.com/kubernetes/kubernetes/master/api/openapi-spec/swagger.json' > api-ref-assets/api/swagger.json

3. In api-ref-assets/config/, adapt the files toc.yaml and fields.yaml to reflect the changes of the new release.

4. Next, build the pages:

   bash Copy

   make api-reference

   You can test the results locally by building and serving the site from a container:

   bash Copy

   make container-serve

   In a web browser, go to http://localhost:1313/docs/reference/kubernetes-api/ to view the API reference.

5. When all changes of the new contract are reflected into the configuration files toc.yaml and fields.yaml, create a Pull Request with the newly generated API reference pages.

Troubleshooting Copy Chapter

If you experience any issues with running website locally, please refer
to the Troubleshooting section of the contributing documentation.

Get involved with SIG Docs Copy Chapter

Learn more about SIG Docs Kubernetes community and meetings on the community page.

You can also reach the maintainers of this project at:

• Slack
  • Get an invite for this Slack
• Mailing List

Contributing to the docs Copy Chapter

You can click the Fork button in the upper-right area of the screen to create a copy of this repository in your GitHub account. This copy is called a fork. Make any changes you want in your fork, and when you are ready to send those changes to us, go to your fork and create a new pull request to let us know about it.

Once your pull request is created, a Kubernetes reviewer will take responsibility for providing clear, actionable feedback. As the owner of the pull request, it is your responsibility to modify your pull request to address the feedback that has been provided to you by the Kubernetes reviewer.

Also, note that you may end up having more than one Kubernetes reviewer provide you feedback or you may end up getting feedback from a Kubernetes reviewer that is different than the one initially assigned to provide you feedback.

Furthermore, in some cases, one of your reviewers might ask for a technical review from a Kubernetes tech reviewer when needed. Reviewers will do their best to provide feedback in a timely fashion but response time can vary based on circumstances.

For more information about contributing to the Kubernetes documentation, see:

• Contribute to Kubernetes docs
• Page Content Types
• Documentation Style Guide
• Localizing Kubernetes Documentation
• Introduction to Kubernetes Docs

New contributor ambassadors Copy Section

If you need help at any point when contributing, the New Contributor Ambassadors are a good point of contact. These are SIG Docs approvers whose responsibilities include mentoring new contributors and helping them through their first few pull requests. The best place to contact the New Contributors Ambassadors would be on the Kubernetes Slack. Current New Contributors Ambassadors for SIG Docs:

Localization READMEs Copy Chapter

Code of conduct Copy Chapter

Participation in the Kubernetes community is governed by the CNCF Code of Conduct.

Thank you Copy Chapter

Kubernetes thrives on community participation, and we appreciate your contributions to our website and our documentation!