kubernetes-client

kubernetes-client

Simplified Kubernetes API client for Node.js.

Installation

Install via npm:

npm i kubernetes-client --save

Initializing

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 load the file automatically through the KUBECONFIG env

const K8sConfig = require('kubernetes-client').config
const config = K8sConfig.fromKubeconfig()

provide your own path to a file:

const K8sConfig = require('kubernetes-client').config
const path = '~/some/path'
const config = K8sConfig.fromKubeconfig(path)

provide a kubeconfig object from memory:

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

and you can also specify the kubeconfig context by passing it as the second argument to fromKubeconfig():

const config = K8sConfig.fromKubeconfig(null, 'dev')

Once you've built a config object, you can combine it with an API spec to build the client, using specifications included with kubernetes-client:

const Client = require('kubernetes-client').Client
const config = require('kubernetes-client').config
const client = new Client({ config: config.fromKubeconfig(), version: '1.9' })

or from a local OpenAPI/Swagger specification:

const Client = require('kubernetes-client').Client
const config = require('kubernetes-client').config
const spec = require('./swagger.json')
const client = new Client({ config: config.fromKubeconfig(), spec})

or from the /swagger.json endpoint on your kube-apiserver:

const Client = require('kubernetes-client').Client
const config = require('kubernetes-client').config
const client = new Client({ config: config.fromKubeconfig() })
await client.loadSpec()

or using basic auth:

const Client = require('kubernetes-client').Client
const client = new Client({
  config: {
    url: 'CLUSTER_URL',
    auth: {
      user: 'admin',
      pass: 'YOUR_PASSWORD',
    },
    insecureSkipTlsVerify: true,
  }
})

or from within a Pod using getInCluster:

const Client = require('kubernetes-client').Client
const config = require('kubernetes-client').config
const client = new Client({ config: config.getInCluster() })
await client.loadSpec()

kubernetes-client supports reading the service account credentials from different locations by setting the KUBERNETES_CLIENT_SERVICEACCOUNT_ROOT environment variable. This is useful, for example, when running Telepresence.

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

Documentation

kubernetes-client generates documentation for the included specifications:

• Kubernetes API v1.7
• Kubernetes API v1.8
• Kubernetes API v1.9
• Kubernetes API v1.10
• Kubernetes API v1.11
• Kubernetes API v1.12
• Kubernetes API v1.13

TypeScript

kubernetes-client includes a typings declartion file for Kubernetes API 1.10 and a complimentry Client1_10 class:

import * as Api from 'kubernetes-client';

const Client = Api.Client1_10;
const config = Api.config;
const client = new Client({ config: config.fromKubeconfig() });

More examples

examples/ has snippets for using kubernetes-client:

• The basic usage example from above: basic.js
• Use error handling to simulate kubectl apply -f: apply-deploy.js
• Create a client from your kube-apiserver's swagger.json: client-from-apiserver-swagger.js
• Create a client from one of the included Swagger specifications: sync-client-version.js
• Using resource aliases supported by kubectl (e.g., .po vs .pods): convenience-properties.js
• Use watch endpoints to get a JSON stream of Deployment events: watch.js
• Extend the Kubernetes API and a client with a CustomerResourceDefinition: using-crds.js
• An extended CustomResourceDefinition example that implements a controller to "notify" on changes to Deployment objects: deployment-notifier.js
• A basic canary controller that removes Pods from a Service if they log an error: canary-controller.js
• Create a client using basic-auth: basic-auth.js
• Create a client using IAM authenticator and cmd auth (works with Amazon EKS): iam-auth.js
• Generate badges showing the status of your Deployments. Illustrates using the in-cluster config: kubernetes-badges
• Create a deployment, patch a change, and rollback to the original version: deployment-create-patch-rollback.js

Contributing

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

Testing

kubernetes-client includes unit tests and integration tests. Minikube is a tool that makes it easy to run integration tests locally.

Run the unit tests:

$ npm test

The integration tests use a running Kubernetes server. You specify the Kubernetes server context via the CONTEXT environment variable. For example, run the integration tests with the minikube context:

$ CONTEXT=minikube npm run test-integration

More Documentation

• Kubernetes Reference Documentation
• Kubernetes Swagger Spec

License

MIT

Changelog

6.10.0 (2019-03-04)

Features

• swagger: add files for latest releases (#415) (bfc28bc)
• ability for a user to specify their own getNames function (#424) (27ec13f), closes #418

<a name="6.9.0"></a>