Javascript Kubernetes Client information

The Javascript clients for Kubernetes is implemented in typescript, but can be called from either Javascript or Typescript. The client is implemented for server-side use with Node.

Installation

npm install @kubernetes/client-node

Example code

List all pods

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);
});

Create a new namespace

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

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

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

var namespace = {
    metadata: {
        name: 'test',
    },
};

k8sApi.createNamespace({ body: namespace }).then(
    (response) => {
        console.log('Created namespace');
        console.log(response);
        k8sApi.readNamespace({ name: namespace.metadata.name }).then((response) => {
            console.log(response);
            k8sApi.deleteNamespace({ name: namespace.metadata.name });
        });
    },
    (err) => {
        console.log('Error!: ' + err);
    },
);

Create a cluster configuration programmatically

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);
...

Documentation

📖 View Documentation

Documentation is built with Docusaurus and includes:

• SDK Reference (KubeConfig, Watch, Informer, Exec, etc.)
• Kubernetes API Reference (all API groups)
• Version selector for historical releases
• Kubernetes API Reference — source-of-truth for all Kubernetes client libraries

Preview docs locally

# From the repo root — install the client library (needed by typedoc)
npm install

# Install docs dependencies and start the dev server
cd docs
npm install
npm start          # opens http://localhost:3000 with hot-reload

npm start automatically runs the prestart hook which generates the API reference, SDK docs, and model pages from source before launching the dev server. Changes to hand-written docs (e.g. docs/docs/examples/) are reflected instantly; changes to the generated sources require restarting the server.

To do a full production build (which also validates all links):

cd docs
npm run build      # generates + builds static site into docs/build/
npm run serve      # preview the production build at http://localhost:3000

There are several more JS and TS examples in the examples directory.

Compatibility

Prior to the 0.13.0 release, release versions did not track Kubernetes versions. Starting with the 0.13.0 release, we will increment the minor version whenever we update the minor Kubernetes API version (e.g. 1.19.x) that this library is generated from.

request was migrated to node-fetch as the HTTP(S) backend for release 1.0.0 tracked in #754

node-fetch was migrated to undici which is the native node.js fetch package for release 2.0.0 tracked in #2306

Generally speaking newer clients will work with older Kubernetes, but compatibility isn't 100% guaranteed.

| client version | older versions | 1.28 | 1.29 | 1.30 | 1.31 | 1.32 | 1.33 | 1.34 | | -------------- | -------------- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | | 0.19.x | - | ✓ | x | x | x | x | x | x | | 0.20.x | - | + | ✓ | x | x | x | x | x | | 0.21.x | - | + | + | ✓ | x | x | x | x | | 0.22.x | - | + | + | + | ✓ | x | x | x | | 1.0.x | - | + | + | + | + | ✓ | x | x | | 1.1.x | - | + | + | + | + | ✓ | x | x | | 1.2.x | - | + | + | + | + | + | ✓ | x | | 1.3.x | - | + | + | + | + | + | ✓ | x | | 1.4.x | - | + | + | + | + | + | + | ✓ |

Key:

• ✓ Exactly the same features / API objects in both javascript-client and the Kubernetes version.
• + javascript-client has features or api objects that may not be present in the Kubernetes cluster, but everything they have in common will work.
• - The Kubernetes cluster has features the javascript-client library can't use (additional API objects, etc).
• x The Kubernetes cluster has no guarantees to support the API client of this version, as it only promises n-2 version support. It is not tested, and operations using API versions that have been deprecated and removed in later server versions won't function correctly.

Known Issues

• Multiple kubeconfigs are not completely supported. Credentials are cached based on the kubeconfig username and these can collide across configs. Here is the related issue.

• In scenarios where multiple headers with the same key are required in a request, such as Impersonate-Group, avoid using fetch. Fetch will merge the values into a single header key, with the values as a single string vs a list of strings, Impersonate-Group: "group1,group2". The workaround is to use a low-level library such as https to make the request. Refer to issue #2474 for more details.

Contributing

Please see CONTRIBUTING.md for development setup, testing, and contribution guidelines.