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);
...
Call APIs with protocol buffers
const k8s = require('@kubernetes/client-node');
const kc = new k8s.KubeConfig();
kc.loadFromDefault();
const protoClient = new k8s.ProtoClient(kc);
const result = await protoClient.get(k8s.MetaV1.Status.decode, '/version');
if (result.status) {
console.log(result.status.message);
} else {
console.log(result.object);
}
ProtoClient uses Kubernetes protocol-buffer framing (application/vnd.kubernetes.protobuf) and
returns either the decoded object (result.object) or a decoded v1.Status (result.status).
The bundled protobuf files are generated from Kubernetes proto definitions with:
generate-protobuf.sh fetches and uses upstream kubernetes-client/gen/proto/generate.sh
and dependencies.sh directly so the proto source list stays in sync.
Exec credential plugin policy
Kubeconfig exec credential plugins start local processes. By default all plugins are allowed,
so only load trusted kubeconfigs. Applications can restrict which plugins may run with the same
policy that kubectl reads from its kuberc
file:
const kc = new k8s.KubeConfig();
kc.loadFromDefault();
// Never run exec plugins
kc.setExecCredentialPluginPolicy({ credentialPluginPolicy: 'DenyAll' });
// Only run approved plugins, by basename or full path
kc.setExecCredentialPluginPolicy({
credentialPluginPolicy: 'Allowlist',
credentialPluginAllowlist: [{ command: 'kubelogin' }, { command: '/usr/local/bin/my-trusted-plugin' }],
});
// Or use the policy from the user's kuberc file ($KUBERC or ~/.kube/kuberc)
kc.loadExecCredentialPluginPolicyFromKuberc();
The policy semantics match kubectl:
- An unspecified or empty
credentialPluginPolicy is the same as AllowAll.
credentialPluginAllowlist is required (and must be non-empty) for Allowlist, and is an error for any other
policy. Entries must specify a non-empty command (the deprecated name alias is accepted, but not both).
- A plugin is allowed if its command exactly matches an allowlist entry, or if both resolve to the same executable
using
PATH. Neither symlinks nor shell globs are resolved.
- In
Allowlist mode the resolved full path of the plugin is executed, so the plugin env from the kubeconfig cannot
change which executable is started. Plugin arguments and environment are not otherwise restricted.
- Denied plugins throw an
ExecCredentialPluginDeniedError before any process is started; the policy is checked
for the initial execution and every token refresh.
KUBERC=off or KUBECTL_KUBERC=false disables loading the kuberc file.
This policy is a defense-in-depth measure, not a sandbox. Allowing an interpreter or other general purpose launcher
can permit arbitrary code execution.
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
Package versioning
Client releases follow Semantic Versioning:
- Major: new Kubernetes API targets and incompatible client changes. Regeneration may remove
exported clients or models and change existing TypeScript types.
- Minor: backward-compatible features.
- Patch: backward-compatible bug and security fixes.
We align major client releases with new Kubernetes API targets, as discussed in
#2582.
Client and Kubernetes version numbers do not match. Check the release notes when upgrading majors.
The 1.0.0 release migrated from
request to node-fetch and became ESM-only. The
2.0.0 release migrated from
node-fetch to the npm undici package and changed supported Node.js versions.
Generated Kubernetes API targets
This table lists the Kubernetes API specification used to generate each client version.
| Client version |
Generated Kubernetes API target |
| 0.19.0 |
1.27 |
| 0.20.0 |
1.28 |
| 0.21.0 |
1.29 |
| 0.22.0 |
1.30 |
| 1.0.0 |
1.32 |
| 1.1.2 |
1.32 |
| 1.2.0 |
1.33 |
| 1.3.0 |
1.33 |
| 1.4.0 |
1.34 |
| 2.0.0–2.0.2 |
1.36 |
| 3.0.0 |
1.37 |
Compatibility with clusters
Clients generally work with older or newer clusters when both support the APIs your application
uses. New APIs may be unavailable on older clusters, and deprecated APIs may be removed from newer
clusters or clients. The generation targets above do not guarantee compatibility with every cluster.
See the Kubernetes API deprecation policy
and client release notes, and test against the cluster versions your application supports.
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.