How to use the Kubernetes C# client library

Working with Kubernetes isn’t always easy. Managing your clusters and pods requires work, and although cloud-hosted Kubernetes instances such as Azure’s AKS can handle much of the heavy lifting for you, they’re not available if you’re running Kubernetes on-premises or on your own virtual infrastructures.

That’s where Kubernetes’ API comes in to play, as it’s how Kubernetes communicates between components and external controllers. You can use the kubectl command line tools to communicate with the API or use it through familiar REST (Representational State Transfer) calls. The API helps you manage workloads, configure clusters, and manage the behavior of your applications and cluster.

RESTful APIs like this are useful tools, but they require significant development work if you’re building your own controllers. You can remove the associated development overhead by working through one of the official Kubernetes API clients, which now include a .NET library. In addition to the official versions, there are unofficial clients, which include two alternative .NET implementations if the official release doesn’t quite fit with how you want to use it.

Introducing the .NET Kubernetes API client library

The official .NET client library is available on GitHub, managed by a team of open source developers that includes Microsoft staff. The current release is 1.6.21, and development is ongoing. You can download the code from GitHub and compile it yourself or add the library to an application via NuGet as a package called KubernetesClient. Once installed, add the library to your code with a using statement that loads the client, as k8s. The library supports both .NET and .NET Core, so you can use it to write cross-platform apps as well as purely Windows code.

Once installed you can start using the library to build your own tools for Kubernetes, such as specific event handlers to respond to events within your distributed application. Start with a listener for events on a Kubernetes namespace. You can do this using C#’s existing asynchronous programming features, setting an await to watch for events and attaching a handler to the result. Kubernetes offers custom resources that can be used to monitor your own events and manage your custom Kubernetes infrastructure.

On the Kubernetes side, first build an appropriate custom resource definition for the controller your code will use. This will require an API version, a kind, and a lot of the appropriate metadata needed for your resource. These elements map to objects in the C# Kubernetes API, and can be read from their objects. Finally, you can add your own data in both the spec and status fields of the resource, with custom resource classes to manage them.

Once you have those elements, you’re able to build a controller by wrapping them in an instance of the Kubernetes API client, using the custom resource definition of the resource we want to watch. Once you have the results of your event handler you can use them in the rest of your Kubernetes management application, to write logs or to modify your Kubernetes instance, for example. A handler like this could spawn new pods as required if your Kubernetes code writes a message to your custom resource’s status field.

Creating Kubernetes clients

Creating a client means loading the Kubernetes configuration data for your instance. You can do this from the default local kubeconfig, from a specific file, or from the current cluster. Once you have the configuration data as a configuration object, you can create a client using the configuration you’ve loaded.

That gives you a client object that can be used with Kubernetes API calls. There’s a useful set of sample code in the library’s GitHub repository. It’s worth cloning and running the examples, as they can help you understand how to use the .NET Kubernetes client, how to understand the syntax, and how to work with the APIs to handle create, read, update, and delete operations.

One useful sample is a short 25-line program that lists the namespaces in a pod. If you’re building an application to control a Kubernetes instance, it’s important to get a list of all of the current namespaces, as these allow you to target APIs to specific parts of your Kubernetes infrastructure.

Coming to grips with the Kubernetes API documentation

To get the most from the .NET API libraries, it’s a good idea to spend some time with the documentation for Kubernetes’ APIs. Although there’s enough in the libraries to get you started, you’ll need to drill down into the official documentation to get the details needed to build your own controllers. Looking at documentation for some of the other API library implementations is helpful; it’s not difficult to translate a Java or Go call to C#, and you can see how others use the APIs.

Another option is to use the kubectl documentation to see how you might use key kubectl verbs in your code. It’s a good idea to initially use tools like the API to build apps that automate common operations before working on more complex tasks. Before writing any new code, you should check if existing Kubernetes extensions such as KEDA (Kubernetes-based event-driven autoscaling) might already implement the features you’re considering.

Automating Kubernetes operations with your own code

Managing Kubernetes can be complex, so it’s nice to see a set of official libraries that can help you build your own tools to work with the Kubernetes API. With an active community and cross-fertilization with unofficial clients, it’s clear that the .NET API team is working to deliver a useful framework for building code that can work with Kubernetes, both on the .NET Framework and on .NET Core.

Tools like this are essential if we’re to build a new generation of operations tools needed for distributed applications running on cloud-native platforms. By using familiar languages, especially those with access to other platform libraries, we can build tools that bridge platforms like Azure Pipelines, GitHub, and Kubernetes, automating much of what we currently do by hand.