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()
kubeconfig.loadFromFile('~/some/path')
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()
kubeconfig.loadFromString(JSON.stringify(config))
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:
kubeconfig.setCurrentContext('dev')
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.
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').deployments.post({ body: deploymentManifest })
and then fetch your newly created Deployment:
const deployment = await client.apis.apps.v1.namespaces('default').deployments(deploymentManifest.metadata.name).get()
and finally, remove the Deployment:
await client.apis.apps.v1.namespaces('default').deployments(deploymentManifest.metadata.name).delete()
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:
kubectl apply -f
: apply-deploy.jsclient
from your kube-apiserver's swagger.json:
client-from-apiserver-swagger.jsclient
from one of the included Swagger specifications:
sync-client-version.jskubectl
(e.g., .po
vs
.pods
): convenience-properties.jsclient
with a
CustomerResourceDefinition: using-crds.jsclient
using basic-auth:
basic-auth.jsclient
using IAM authenticator and cmd auth (works with Amazon EKS):
iam-auth.jsclient
using an in-cluster configuration: in-cluster-auth.jsSee the kubernetes-client Issues if you're interested in helping out; and look over the CONTRIBUTING.md 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