Kubernetes JavaScript Client

The client versioning tracks Kubernetes minor versions. Starting from 0.13.0, the client minor version increments when the underlying Kubernetes API version is updated.

Compatibility Rules:

• Newer clients generally work with older Kubernetes clusters, but compatibility is not 100% guaranteed.
• The client supports $n-2$ versions of Kubernetes.
• If a Kubernetes cluster is newer than the client's supported range (marked as x in compatibility tables), operations using API versions that were deprecated or removed in the cluster may fail.

HTTP Backend Evolution:

• 1.0.0: Migrated from request to node-fetch.
• 2.0.0: Migrated from node-fetch to undici (native Node.js fetch).

To use the Javascript Kubernetes client in a Node.js environment, install the @kubernetes/client-node package using npm.

npm install @kubernetes/client-node

An Informer is an abstraction used to watch for changes to specific Kubernetes resources (like Pods or Namespaces) in real-time. It combines a list of current resources with a watch stream to keep a local cache synchronized.

An Informer allows you to register callbacks for specific event types:

• Object Events: add, update, delete, and change (which triggers on both add and update).
• Lifecycle Events: connect (when the watch connection is established or re-established) and error.

To create an informer, use the makeInformer function, providing the KubeConfig, the API path for the resource, and a listPromiseFn to fetch the initial state. The returned object implements the Informer interface for event handling and the ObjectCache interface for querying the current state of resources.

If the stdout stream provided to the exec method implements the isResizable interface (a ResizableStream), the Exec class will automatically handle terminal resizing.

It uses an internal TerminalSizeQueue to manage resize events, ensuring that changes to the terminal dimensions are communicated to the container via the WebSocket connection. This is useful for interactive TTY sessions where the layout depends on the terminal size.

To interact with any Kubernetes resource dynamically without needing specific typed clients for every resource, use KubernetesObjectApi.makeApiClient. This method is preferred over KubeConfig.makeApiClient because it automatically detects and sets the default namespace from your current KubeConfig context.

import { KubeConfig } from '@kubernetes/client-node';
import { KubernetesObjectApi } from './path-to-object-api';

const kc = new KubeConfig();
kc.loadFromDefault();

const api = KubernetesObjectApi.makeApiClient(kc);

const client = kc.makeApiClient(KubernetesObjectApi);
client.setDefaultNamespace(kc);
return client;

Multiple Kubeconfigs

Credentials are cached based on the kubeconfig username. If you use multiple kubeconfigs with overlapping usernames, credentials may collide.

Duplicate Header Keys (e.g., Impersonate-Group)

Because the client uses fetch (via undici), it may merge multiple headers with the same key into a single string (e.g., Impersonate-Group: "group1,group2") instead of a list of strings. If your use case requires multiple distinct header entries for the same key, avoid using the standard client methods and use a low-level library like https instead.

Instead of loading a file, you can construct a KubeConfig manually using loadFromOptions. You must provide arrays for clusters, users, and contexts, and specify the currentContext name.

const k8s = require('@kubernetes/client-node');

const cluster = {
    name: 'my-server',
    server: 'http://server.com',
};

const user = {
    name: 'my-user',
    password: 'some-password',
};

const context = {
    name: 'my-context',
    user: user.name,
    cluster: cluster.name,
};

const kc = new k8s.KubeConfig();
kc.loadFromOptions({
    clusters: [cluster],
    users: [user],
    contexts: [context],
    currentContext: context.name,
});
const k8sApi = kc.makeApiClient(k8s.CoreV1Api);

To list pods, initialize a KubeConfig object, load your default configuration (e.g., from ~/.kube/config), and create an API client using CoreV1Api. Use the listNamespacedPod method, passing the namespace in the options object.

const k8s = require('@kubernetes/client-node');

const kc = new k8s.KubeConfig();
kc.loadFromDefault();

const k8sApi = kc.makeApiClient(k8s.CoreV1Api);

k8sApi.listNamespacedPod({ namespace: 'default' }).then((res) => {
    console.log(res);
});

When using helper functions like newClusters, newUsers, or newContexts to parse raw configuration data, you can specify how the client should handle malformed or missing entries using the ConfigOptions object.

By default, the client uses ActionOnInvalid.THROW, which will cause the parsing process to fail and throw an error if an entry is invalid. Alternatively, you can use ActionOnInvalid.FILTER to silently skip invalid entries and return only the valid ones.

The replace method performs a full replacement of a resource (HTTP PUT).

Parameters:

• spec: The full Kubernetes resource spec.
• pretty: (Optional) If 'true', output is pretty printed.
• dryRun: (Optional) Valid values: All.
• fieldManager: (Optional) Name of the actor making changes.
• options: (Optional) Overriding Configuration object.

Returns a Promise containing the replaced resource.