Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?


Failed to load latest commit information.
Latest commit message
Commit time


Join Slack Build Status Greenkeeper badge

Simplified Kubernetes API client for Node.js.


Install via npm:

npm i kubernetes-client --save


kubernetes-client generates a Kubernetes API client at runtime based on a Swagger / OpenAPI specification. You can generate a client using the cluster's kubeconfig file and that cluster's API specification.

To create the config required to make a client, you can either:

let kubernetes-client configure automatically by trying the KUBECONFIG environment variable first, then ~/.kube/config, then an in-cluster service account, and lastly settling on a default proxy configuration:

const client = new Client({ version: '1.13' })

provide your own path to a file:

const { KubeConfig } = require('kubernetes-client')
const kubeconfig = new KubeConfig()
const Request = require('kubernetes-client/backends/request')

const backend = new Request({ kubeconfig })
const client = new Client({ backend, version: '1.13' })

provide a configuration object from memory:

// Should match the kubeconfig file format exactly
const config = {
  apiVersion: 'v1',
  clusters: [],
  contexts: [],
  'current-context': '',
  kind: 'Config',
  users: []
const { KubeConfig } = require('kubernetes-client')
const kubeconfig = new KubeConfig()

const Request = require('kubernetes-client/backends/request')
const backend = new Request({ kubeconfig })
const client = new Client({ backend, version: '1.13' })

and you can also specify the context by setting it in the kubeconfig object:


You can also elide the .version and pass an OpenAPI specification:

const spec = require('./swagger.json')
const client = new Client({ spec })

or load a specification dynamically from the kube-apiserver:

const client = new Client()
await client.loadSpec()

See Examples for more configuration examples.

Basic usage

kubernetes-client translates Path Item Objects [1] (e.g., /api/v1/namespaces) to object chains ending in HTTP methods (e.g., api.v1.namespaces.get).

So, to fetch all Namespaces:

const namespaces = await client.api.v1.namespaces.get()

kubernetes-client translates Path Templating [2] (e.g., /apis/apps/v1/namespaces/{namespace}/deployments) to function calls (e.g., apis.apps.v1.namespaces('default').deployments).

So, to create a new Deployment in the default Namespace:

const deploymentManifest = require('./nginx-deployment.json')
const create = await client.apis.apps.v1.namespaces('default'){ body: deploymentManifest })

and then fetch your newly created Deployment:

const deployment = await client.apis.apps.v1.namespaces('default').deployments(

and finally, remove the Deployment:

await client.apis.apps.v1.namespaces('default').deployments(

kubernetes-client supports .delete, .get, .patch, .post, and .put.


kubernetes-client generates documentation for the included specifications:


kubernetes-client includes a typings declartion file for Kubernetes API 1.13 and a complimentry Client1_13 class:

import * as ApiClient from 'kubernetes-client';

const Client = ApiClient.Client1_13;
const client = new Client({ version: '1.13' });

When using TypeScript, kubernetes-client does not support dynamically generating a client via .loadSpec().


examples/ has snippets for using kubernetes-client:


See the kubernetes-client Issues if you're interested in helping out; and look over the before submitting new Issues and Pull Requests.


Run the unit tests:

npm test

The integration tests use the current-context in your kubeconfig file. Run the integration tests:

npm run test-integration

Run integration tests with the @kubernetes/client-node backend:

KUBERNETES_CLIENT_BACKEND=client-node npm run test-integration