Connecting to Kubernetes API Programmatically with Go and client-go

Using Go's client-go Library to Interact with the Kubernetes API

When working with Kubernetes, different roles interact with the API server in unique ways. On a very high-level, Administrators ensure the cluster infrastructure scales appropriately, Operators maintain the platform and applications within it, and Developers often build upon Kubernetes by interacting with its API programmatically – creating custom controllers, CRDs, and other tools.

For most of my career in Security and DevOps, my focus has been through the Administrator and Operator lens, dealing with operational concerns, mainly using the command line and the ‘kubectl’ utility. As is reflected in my usual online tutorials/ labs (like on YouTube and LinkedIn).

Recently, however, I've been expanding my scope towards the Developer perspective. This involves interacting with the Kubernetes API programmatically using Go and the client-go library. The fundamental process of creating a client, authenticating, and interacting with the server is something I'll repeat in many applications. Therefore, I decided to document it here – primarily as a reference for myself, but hopefully, it will be useful for you too!

Golang prodding and poking kubernetes

GitHub Repository

Let's GO right into the code (pun intended haha).

Setting Up the Go Program: Package and Imports

Every executable Go application must begin with the package main declaration. This tells the Go compiler to produce a runnable program, with execution starting in the main function.

Following this, we use the import statement to include all the necessary code libraries (packages). We need standard libraries for handling context, command-line flags, printing, logging, OS interaction, and file paths, along with the crucial client-go libraries:

• k8s.io/apimachinery/pkg/apis/meta/v1: Common Kubernetes API types.

• k8s.io/client-go/kubernetes: Provides the main clientset for API interaction.

• k8s.io/client-go/tools/clientcmd: Utilities for loading kubeconfig files.

Here’s the initial setup:

package main

import (
	"context"
	"flag"
	"fmt"
	"log" // Added for fatal error handling
	"os"  // Added for finding home directory
	"path/filepath" // Added for constructing paths

	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
	"k8s.io/client-go/kubernetes"
	"k8s.io/client-go/tools/clientcmd"
)

Entering the main Function

Execution begins in func main(). Our first job is to figure out how to connect to the Kubernetes cluster.

Handling kubeconfig Location

The kubeconfig file contains the connection details. We need its path.

• We attempt to find the user's home directory using os.UserHomeDir() to construct a default path (~/.kube/config).

• We define a command-line flag --kubeconfig using flag.String. This allows the user to override the default path if needed. If the home directory couldn't be found, the flag is defined without a default, making it required.

• Finally, flag.Parse() reads and processes any flags the user provided when running the application.

func main() {
	var kubeconfig *string

	// Dynamically find the user's home directory to set default kubeconfig path
	home, err := os.UserHomeDir()
	if err != nil {
		// If home dir can't be found, still define the flag but without a default
		log.Printf("Warning: Could not find home directory: %v. Kubeconfig flag will be required.", err)
		kubeconfig = flag.String("kubeconfig", "", "absolute path to the kubeconfig file (required if home dir not found)")
	} else {
		// Define flag with default path if home directory was found
		defaultPath := filepath.Join(home, ".kube", "config")
		kubeconfig = flag.String("kubeconfig", defaultPath, "(optional) absolute path to the kubeconfig file")
	}

	// Parse command-line flags provided by the user
	flag.Parse()

Building the Client Configuration

With the path (*kubeconfig) determined, we use the clientcmd library to load the file's contents into a configuration object that client-go can understand.

• clientcmd.BuildConfigFromFlags("", *kubeconfig) does this work. The first argument (masterURL) is empty as we rely solely on the kubeconfig file.

• If this fails (e.g., file not found, invalid format), it's a critical error. We use log.Fatalf to print the error message and exit the program.

	// Build configuration from the kubeconfig file path
	config, err := clientcmd.BuildConfigFromFlags("", *kubeconfig)
	if err != nil {
		log.Fatalf("Error building kubeconfig: %v", err) // Use log.Fatalf for critical errors
	}

Creating the Kubernetes Clientset

Now we create the clientset, which is the primary object used to interact with the Kubernetes API.

• kubernetes.NewForConfig(config) takes the configuration object we just built.

• If clientset creation fails, it's another critical error, so we again use log.Fatalf.

	// Create the clientset using the configuration
	clientset, err := kubernetes.NewForConfig(config)
	if err != nil {
		log.Fatalf("Error creating clientset: %v", err) // Use log.Fatalf
	}

Querying the API: Listing Pods

We're ready to make an API call! Let's list the Pods in the default namespace.

• We need a context.Context; context.Background() provides a simple default.

• We use the clientset to navigate to the resource: clientset.CoreV1() accesses the core API group, .Pods("default") specifies the Pod resource in the "default" namespace.

• .List(ctx, metav1.ListOptions{}) executes the request. We provide the context and empty ListOptions to get all pods without filtering.

• An error during the API call (e.g., network issues, permissions) is also treated as fatal using log.Fatalf.

	// Use the clientset to list Pods in the "default" namespace
	ctx := context.Background()
	pods, err := clientset.CoreV1().Pods("default").List(ctx, metav1.ListOptions{})
	if err != nil {
		log.Fatalf("Error listing pods: %v", err) // Use log.Fatalf
	}

Processing and Displaying Results

If the API call succeeded, the pods variable holds the results.

• The actual Pod objects are in the pods.Items slice.

• We loop through this slice and use fmt.Printf to print the Name of each pod found.

	// Print the names of the pods found
	fmt.Println("Pods in default Namespace:")
	for _, pod := range pods.Items {
		fmt.Printf("- %s\n", pod.Name)
	}

} // End of main function

Running the Code

To run this:

1. Save the complete code (package, imports, main function) as main.go.

2. Make sure you have Go installed and client-go libraries available (go get k8s.io/client-go@latest k8s.io/apimachinery@latest).

3. Open your terminal in the directory where you saved main.go.

4. Ensure your kubectl context points to the cluster you want to query, or that your specified kubeconfig file is correctly configured.

5. Compile and run.

go run main.go

1. If your config is elsewhere or you want to override the default:

go run main.go --kubeconfig /path/to/your/kubeconfig

You should see a list of the pods running in the default namespace of your target cluster!

Wrapping Up

And there you have it! A step-by-step walkthrough of connecting to a Kubernetes cluster and performing a basic read operation (listing Pods) using Go and the client-go library. We covered setting up flags, building configuration from kubeconfig, creating a clientset, making an API call, and handling critical errors.

This pattern forms the foundation for building more complex Kubernetes tools, operators, or controllers in Go. While this was a simple example, the possibilities from here are vast.

Hopefully, this breakdown was useful for getting started or as a quick reference. Happy coding with client-go!

---