API Version Management

This outline covers the different options and examples for handling Kubernetes API versions within the Kubernetes Client library for C#.

Motivation

The Kubernetes API evolves over time, introducing new features and making changes to existing resources. Therefore, a client library needs to manage compatibility with different API versions.

The library uses the apiVersion field in Kubernetes objects to ensure proper communication with the API server.

API Version Handling

The library provides several ways to handle API versions:

1. Version Specific Clients: The library provides version-specific clients for each major Kubernetes API version. For example, CoreV1 interacts with the v1 version of the core API, while AppsV1 interacts with the v1 version of the apps API. This ensures the use of the correct API models and resources for the intended API version.

2. API Version Field: The apiVersion field is present in all Kubernetes objects. This field determines the version of the API that the object conforms to. When making API requests, the library sets the appropriate apiVersion based on the client used and the object being interacted with.

3. Automatic API Version Detection: The library can automatically detect the supported API versions of the Kubernetes cluster using the /apis endpoint. This allows the library to use the latest supported API versions.

Examples

Example 1: Using Version Specific Clients:

// Create a client for the Kubernetes v1 API
          var client = new KubernetesClient.Default.KubernetesClient();
          
          // Create a namespace using the CoreV1 client
          var ns = new V1Namespace
          {
              Metadata = new V1ObjectMeta
              {
                  Name = "test"
              }
          };
          
          var result = client.CoreV1.CreateNamespace(ns);
          Console.WriteLine(result);
          
          // Delete the namespace using the CoreV1 client
          var status = client.CoreV1.DeleteNamespace(ns.Metadata.Name, new V1DeleteOptions());
          

Example 2: Setting API Version Explicitly:

// Set the API version for a Deployment object
          var deployment = new AppsV1.Deployment
          {
              ApiVersion = "apps/v1",
              // ... other properties ...
          };
          

Example 3: Automatic API Version Detection:

// The library automatically detects the supported API versions of the cluster.
          // The client will use the latest supported version for API calls.
          

Kubernetes API Version Compatibility

The Kubernetes API server guarantees compatibility with the previous two (or three after 1.28) versions. For example:

• An SDK based on Kubernetes v1.19 should work with a v1.21 cluster.
• An SDK based on Kubernetes v1.21 should work with a v1.19 cluster.

However, compatibility is not guaranteed for older versions. See Issue #1511 for more details.

Contributing

Contributions from the community are welcomed. See CONTRIBUTING.md for instructions on how to contribute.

Notes

• The library supports netstandard2.0, netstandard1.4, net452 and net451 for different versions of the Kubernetes API.
• The library supports KubernetesClient.Classic with limited features for netstandard2.0 and net48.
• Fixes (including security fixes) are not automatically back-ported to older SDK versions.

Top-Level Directory Explanations

src/ - This directory contains the source code for the project.

src/KubernetesClient/ - This subdirectory contains the main Kubernetes client library source code.

src/KubernetesClient/Models/ - This subdirectory contains model classes for various Kubernetes resources and objects.

src/LibKubernetesGenerator/ - This subdirectory contains code for generating C# code from OpenAPI definitions.