kubernetes-client/csharp: the official .NET client for Kubernetes

An officially supported client, still marked beta

The repository describes itself as the officially supported dotnet Kubernetes Client library, and it lives under the kubernetes-client organisation rather than in a personal account. The NuGet package is KubernetesClient.

Two badges in the README set the expectations. The client capabilities badge marks it as Silver in the Kubernetes client capability matrix, and the support level badge marks it as beta. That is worth reading carefully, because the words officially supported and beta sit in the same project. The official part means there is a maintainer team and a support commitment from the project; the beta part means the API surface is still allowed to move.

The client speaks the Kubernetes API through a set of typed C# groups. The sample code reaches them through properties on the client object, with `client.CoreV1` for the core group, and each group exposes the operations for that API version.

The tree shows a fairly conventional .NET repository layout: `src/` for the library, `tests/` for the test project, `examples/` with two dozen sample directories, `doc/`, a `Directory.Build.props`, a `Directory.Packages.props` for central package version management, a `global.json` pinning the SDK, a `stylecop.json` for style rules, a `kubernetes-client.ruleset` for code analysis, and `version.json`.

The primary language is C# and the licence is Apache-2.0, with a LICENSE file at the root.

Adding the package and generating the Visual Studio project

Adding the client to a .NET project is a single command:

dotnet add package KubernetesClient

The README also documents a Visual Studio path, which is a separate step that exists because the solution is not checked in as a plain solution file. The `kubernetes-client.proj` file drives the generation:

dotnet msbuild /Restore /t:SlnGen kubernetes-client.proj

The repository root does contain `kubernetes-client.proj` alongside `global.json` and `Directory.Build.targets`, and the SlnGen target name indicates that this is what produces a solution file for IDE consumption. This is a common pattern in large C# repositories, where a hand-maintained solution file with hundreds of projects becomes a merge conflict magnet, so the solution is generated instead.

If you are not contributing to the client itself, none of that matters. The NuGet package is the artefact you consume, and it carries the same generated model, so the API you code against is identical to the one in the repository.

kubeconfig, in-cluster config and the auth gap

Authentication runs through `KubernetesClientConfiguration`, and there are two entry points.

The first builds from a standard kubeconfig file. Called with no argument it loads the default kubeconfig on the machine, and called with a path it loads that file, which in the sample is read from the `KUBECONFIG` environment variable:

var config = KubernetesClientConfiguration.BuildConfigFromConfigFile();

var config = KubernetesClientConfiguration.BuildConfigFromConfigFile(Environment.GetEnvironmentVariable("KUBECONFIG"));

The second is for workloads running inside the cluster, using the service account:

var config = KubernetesClientConfiguration.InClusterConfig()

The README says most authentication methods are currently supported, but a few are not, and points to the known-issues section for the list. That distinction is the one to check before committing, because the failure mode is confusing: the client type is there, the kubeconfig parses, and the failure happens at the first authenticated call.

The documented workaround is to run the kubectl proxy and point the client at it:

$ kubectl proxy
Starting to serve on 127.0.0.1:8001

var config = new KubernetesClientConfiguration {  Host = "http://127.0.0.1:8001" };

The README is direct that this is a workaround and is not recommended for production use. That is a strong hint that the auth provider gap is a known limitation rather than a configuration mistake on your side.

Listing, creating and deleting typed objects

The API surface follows the shape of the Kubernetes API, with the group and version in the property name and the resource type in the method name.

Listing looks like this:

var namespaces = client.CoreV1.ListNamespace();
foreach (var ns in namespaces.Items) {
    Console.WriteLine(ns.Metadata.Name);
    var list = client.CoreV1.ListNamespacedPod(ns.Metadata.Name);
    foreach (var item in list.Items)
    {
        Console.WriteLine(item.Metadata.Name);
    }
}

Creating and deleting use the same pattern, with the object built as a typed model:

var ns = new V1Namespace
{
    Metadata = new V1ObjectMeta
    {
        Name = "test"
    }
};

var result = client.CoreV1.CreateNamespace(ns);
Console.WriteLine(result);

var status = client.CoreV1.DeleteNamespace(ns.Metadata.Name, new V1DeleteOptions());

The type names carry their API group, so `V1Namespace` is a core v1 namespace and `V1ObjectMeta` is the metadata type that every object shares, which is where the name, labels and annotations live.

The `examples/` directory is where the full range shows up. There are directories for `customResource`, `exec`, `watch`, `portforward`, `patch`, `labels`, `metrics`, `logs`, `aot`, `aks-kubelogin`, `clientset`, `generic` and more, plus dependency injection examples for web APIs and worker services. Running one locally is the fastest way to see a working pattern:

git clone [email protected]:kubernetes-client/csharp.git
cd csharp\examples\simple
dotnet run

The version table that decides your upgrade path

The compatibility table at the end of the README is the most operationally important part of the document, and it is not a simple version number.

There are three axes. The SDK version is the client version, the Kubernetes version is the cluster release it targets, and the.NET targeting list says which frameworks the package supports. SDK version 21.0 pairs with Kubernetes 1.37 and targets net8.0, net9.0, net10.0, plus net48 and netstandard2.0 marked with an asterisk. Version 20.0 pairs with Kubernetes 1.36, 19.0 with 1.35, and so on down the table to 1.3, which pairs with Kubernetes 1.12.

The asterisks matter and the README explains them: starting from 2.0, the.NET SDK versioning scheme was adopted. The asterisked targets are the ones that are not built or tested on every build, so if your service runs on.NET Framework 4.8 you are on a path the project does not exercise on every release.

For a team planning an upgrade, the table is the contract. The current release is v21.0.7, published on 2026-10-13, with v20.0.103 from 2026-10-03 and v20.0.84 from 2026-08-04 behind it, so the project is shipping patch releases against the previous major as well as the newest one.

The last push was on 2026-10-19, and the default branch is master rather than main, which is the older convention and a small hint about the age of the project.

Generated types, testing and observability

The C# types are not hand-written, and the repository documents how they are regenerated.

The process needs a Linux machine with Docker. You clone the generator project into a separate directory, and a shell script under the generator's openapi directory produces a new swagger.json and updates the client source:

cd
${GEN_DIR}/openapi/csharp.sh ${REPO_DIR}/src/KubernetesClient ${REPO_DIR}/csharp.settings

The `swagger.json` file at the repository root and the `csharp.settings` file beside it are the configuration for that generation, and the `kubernetes-client.proj` and ruleset files exist to make the generated output pass the same analysis as the hand-written parts.

Tests use XUnit, and the README shows the two commands to run them:

cd csharp\tests
dotnet restore
dotnet test

There is a `CodeCoverage.runsettings` file in the tree for coverage configuration.

On observability, the client builds metrics into HttpClient using System.Diagnostics.DiagnosticsSource, and the README points at the .NET built-in metrics system and the metrics collection guidance. It also says plainly that there are many ways to consume or expose those metrics, and that the decision is up to the application rather than the client library itself. That is a sensible boundary, and it does mean you wire your own exporter. The `examples/metrics/` and `examples/openTelemetryConsole/` directories cover that ground in practice.

Editorial conclusion

kubernetes-client/csharp fits a .NET team writing controllers, operators or internal tooling that talks to a Kubernetes API and wants the officially maintained client with typed models rather than a hand-rolled HTTP wrapper. It does not fit a team that needs every auth provider, since not all are supported and the documented fallback is a kubectl proxy, which the README says is not recommended for production. Before adopting it, check whether your cluster version falls inside the compatibility table for the SDK version you plan to take, confirm your target framework is listed, and read the known issues for your authentication method.

Frequently asked questions

Official sources

1. Issues
2. kubernetes-client/csharp on GitHub
3. License: Apache-2.0
4. README
5. Releases