@kubernetes/client-node

What is @kubernetes/client-node?

@kubernetes/client-node is an official Kubernetes client library for Node.js. It allows developers to interact with Kubernetes clusters programmatically, providing a way to manage Kubernetes resources, perform CRUD operations, and watch for changes in the cluster.

What are @kubernetes/client-node's main functionalities?

CRUD Operations on Kubernetes Resources

This feature allows you to perform CRUD operations on Kubernetes resources. The code sample demonstrates how to list all pods in the default namespace.

const k8s = require('@kubernetes/client-node');
const kc = new k8s.KubeConfig();
kc.loadFromDefault();
const k8sApi = kc.makeApiClient(k8s.CoreV1Api);

// List all pods in the default namespace
k8sApi.listNamespacedPod('default').then((res) => {
  console.log(res.body);
});

Watch for Changes in the Cluster

This feature allows you to watch for changes in the Kubernetes cluster. The code sample demonstrates how to watch for changes in pods in the default namespace.

const k8s = require('@kubernetes/client-node');
const kc = new k8s.KubeConfig();
kc.loadFromDefault();
const watch = new k8s.Watch(kc);

// Watch for changes in pods in the default namespace
watch.watch('/api/v1/namespaces/default/pods', {},
  (type, obj) => {
    console.log(`Type: ${type}`);
    console.log(`Object: ${JSON.stringify(obj)}`);
  },
  (err) => {
    console.error(err);
  }
);

Custom Resource Definitions (CRDs)

This feature allows you to interact with Custom Resource Definitions (CRDs). The code sample demonstrates how to list all custom resources of a specific type in the default namespace.

const k8s = require('@kubernetes/client-node');
const kc = new k8s.KubeConfig();
kc.loadFromDefault();
const customObjectsApi = kc.makeApiClient(k8s.CustomObjectsApi);

// List all custom resources of a specific type
customObjectsApi.listNamespacedCustomObject('example.com', 'v1', 'default', 'examples').then((res) => {
  console.log(res.body);
});

Other packages similar to @kubernetes/client-node

kubernetes-client

The 'kubernetes-client' package, also known as 'node-kubernetes-client', is another Node.js client for Kubernetes. It provides similar functionalities to @kubernetes/client-node, such as managing Kubernetes resources and performing CRUD operations. However, it is not an official client library and may have different API conventions and support.

k8s

The 'k8s' package is a lightweight Kubernetes client for Node.js. It offers basic functionalities for interacting with Kubernetes clusters, such as listing, creating, and deleting resources. Compared to @kubernetes/client-node, it is simpler and may lack some advanced features but can be easier to use for basic tasks.

README

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.

The request library is currently being swapped to fetch. See the fetch migration docs for more information and progress.

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

const main = async () => {
    try {
        const podsRes = await k8sApi.listNamespacedPod('default');
        console.log(podsRes.body);
    } catch (err) {
        console.error(err);
    }
};

main();

Create a new namespace

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

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

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

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

const main = async () => {
    try {
        const createNamespaceRes = await k8sApi.createNamespace(namespace);
        console.log('New namespace created: ', createNamespaceRes.body);

        const readNamespaceRes = await k8sApi.readNamespace(namespace.metadata.name);
        console.log('Namespace: ', readNamespaceRes.body);

        await k8sApi.deleteNamespace(namespace.metadata.name, {});
    } catch (err) {
        console.error(err);
    }
};

main();

Create a cluster configuration programatically

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

Additional Examples and Documentation

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

Documentation for the library is split into two resources:

1. The Kubernetes API Reference is the source-of-truth for all Kubernetes client libraries, including this one. We suggest starting here!
2. The Typedoc autogenerated docs can be viewed online and can also be built locally (see below)

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.

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

client version	older versions	1.22	1.23	1.24	1.25	1.26	1.27	1.28	1.29	1.30
0.16.x	-	✓	x	x	x	x	x	x	x	x
0.17.x	-	+	+	✓	x	x	x	x	x	x
0.18.x	-	+	+	+	✓	x	x	x	x	x
0.19.x	-	-	-	-	+	+	✓	x	x	x
0.20.x	-	-	-	-	-	+	+	✓	x	x
0.21.x	-	-	-	-	-	-	+	+	✓	x
0.22.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.
• The client wasn't generated for Kubernetes 1.23 due to limited time from the maintainer(s)

Development

All dependencies of this project are expressed in its package.json file. Before you start developing, ensure that you have NPM installed, then run:

npm install

(re) Generating code

npm run generate

Documentation

Documentation is generated via typedoc:

npm run docs

To view the generated documentation, open docs/index.html

Formatting

Run npm run format or install an editor plugin like https://github.com/prettier/prettier-vscode and https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig

Linting

Run npm run lint or install an editor plugin like https://github.com/Microsoft/vscode-typescript-tslint-plugin

Testing

Tests are written using the Chai library. See config_test.ts for an example.

To run tests, execute the following:

npm test

Contributing

Please see CONTRIBUTING.md for instructions on how to contribute.