Kubernetes API Interaction

This document outlines the methods of interaction with the Kubernetes API using client-go. The client-go library provides a rich set of functionalities for interacting with the Kubernetes API.

The library allows you to interact with Kubernetes resources using various methods, including:

• Create: Creating new Kubernetes resources.
• Retrieve: Retrieving existing Kubernetes resources.
• Update: Updating existing Kubernetes resources.
• Delete: Deleting existing Kubernetes resources.

The following code examples demonstrate various interactions with the Kubernetes API:

// Create a Deployment
          deployment, err := clientset.AppsV1().Deployments(namespace).Create(context.TODO(), deployment, metav1.CreateOptions{})
          if err != nil {
              // handle error
          }
          
          // Retrieve a Deployment
          deployment, err := clientset.AppsV1().Deployments(namespace).Get(context.TODO(), deploymentName, metav1.GetOptions{})
          if err != nil {
              // handle error
          }
          
          // Update a Deployment
          deployment, err := clientset.AppsV1().Deployments(namespace).Update(context.TODO(), deployment, metav1.UpdateOptions{})
          if err != nil {
              // handle error
          }
          
          // Delete a Deployment
          err := clientset.AppsV1().Deployments(namespace).Delete(context.TODO(), deploymentName, metav1.DeleteOptions{})
          if err != nil {
              // handle error
          }
          

In-Cluster Client Configuration

This method is used when running the application inside the Kubernetes cluster.

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

To authenticate an application running inside the cluster:

1. Create a role binding that grants the default service account view permissions.

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

2. Run the application within a Pod.

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

Out-of-Cluster Client Configuration

This method is used when running the application outside the Kubernetes cluster.

The client-go library relies on the kubeconfig file that holds context information about the cluster.

To authenticate an application running outside the cluster:

1. Configure kubectl to point to the cluster.

   kubectl get nodes
             

2. Use the kubeconfig file to initialize the client.

   clientset, err := kubernetes.NewForConfig(config)
             

Authentication Mechanisms

The client-go library supports various authentication mechanisms.

• Service Account Tokens: This method is primarily used for applications running inside the cluster. The token is mounted at /var/run/secrets/kubernetes.io/serviceaccount path.
• Kubeconfig: This method allows connecting to a cluster from outside the cluster. It uses a kubeconfig file containing cluster information.
• External Plugins: The client-go library offers optional authentication plugins for obtaining credentials from external sources. These plugins allow connecting to clusters with different authentication methods.

Packages

The client-go library comprises several packages:

• kubernetes: This package provides the clientset to interact with the Kubernetes API.
• discovery: This package assists in discovering the APIs supported by a Kubernetes API server.
• dynamic: This package provides a dynamic client for performing generic operations on arbitrary Kubernetes API objects.
• plugin/pkg/client/auth: These packages contain optional authentication plugins for obtaining credentials from external sources.
• transport: This package sets up the authentication and connection.
• tools/cache: This package proves useful when writing controllers.

Supported Versions

The client-go library supports various Kubernetes versions, including:

• client-go HEAD: Synchronized with the Kubernetes main repo, master branch.
• Kubernetes main repo, master branch: Synchronized with the client-go HEAD.

The compatibility between the client-go version and the Kubernetes version is crucial to avoid unexpected behavior. Always refer to the official documentation and semantic versions for compatibility information.

Additional Notes

• The client-go library requires a running Kubernetes cluster for interaction.
• Ensure proper authentication and authorization are configured for accessing the Kubernetes API.
• Refer to the client-go documentation for detailed information and advanced use cases.

Top-Level Directory Explanations

examples/ - This directory contains example usage of the client-go library.

informers/ - This directory contains code for caching Kubernetes resources using informers.

kubernetes/ - This directory contains the main package for the client-go library, which provides types and functions for interacting with the Kubernetes API.

metadata/ - This directory contains code related to metadata in Kubernetes.

pkg/ - This directory contains compiled Go packages for the client-go library.

plugin/ - This directory contains code for loading plugins for the client-go library.

rest/ - This directory contains code for working with the REST API in the client-go library.

tools/ - This directory contains various tools for working with the client-go library.