hekike / kubernetes-client

Simplified Kubernetes API client for Node.js.

kubernetes-client

Simplified Kubernetes API client for Node.js.

Installation

Install via npm:

$ npm i kubernetes-client --save

Examples

kubernetes-client provides access to all the Kubernetes objects and includes some niceties for writing simpler code.

Basics

kubernetes-client maps the URI paths in the Kubernetes API to sequences of objects chained together via properties and ending in a function. For example, to GET the ReplicationController named 'http-rc' in the Namespace 'my-project':

const K8Api = require('kubernetes-client');
const k8 = new K8Api.Core({
  url: 'http://my-k8-api-server.com',
  version: 'v1',  // Defaults to 'v1'
  namespace: 'my-project' // Defaults to 'default'
});

function print(err, result) {
  console.log(JSON.stringify(err || result, null, 2));
}

k8.namespaces.replicationcontrollers('http-rc').get(print);

kubernetes-client supports the Extensions API group. For example, GET the Deployment named http-deployment:

const k8Ext = new K8Api.Extensions({
  url: 'http://my-k8-api-server.com',
  version: 'v1beta1',  // Defaults to 'v1beta1'
  namespace: 'my-project' // Defaults to 'default'
});

k8Ext.namespaces.deployments('http-deployment').get(print);

Creating and updating

kubernetes-client objects expose .post, .patch, and .put methods. Create the ReplicationController from the example above:

const manifestObject = require('./rc.json');
k8.namespaces.replicationcontrollers.post({ body: manifestObject }, print);

or update the number of replicas:

const patch = { spec: { replicas: 10 } };
k8.namespaces.replicationcontrollers('http-rc').patch({
  body: patch
}, print);

Using the correct API group and version

kubernetes-client client includes functionality to help determine the correct Kubernetes API group and version to use based on manifests:

const K8Api = require('kubernetes-client');
const api = new K8Api.Api({
  url: 'http://my-k8-api-server.com',
  namespace: 'my-project'
});

const manifest0 = {
  kind: 'Deployment',
  apiVersion: 'extensions/v1beta1'
  ...
};
const manifest1 = {
  kind: 'ReplicationController',
  apiVersion: 'v1'
  ...
};

api.group(manifest0).ns.kind(manifest0).post(manifest0, print);
api.group(manifest1).ns.kind(manifest1).post(manifest1, print);

Object name aliases

kubernetes-client supports the same aliases as kubectl (e.g., ns for namespaces) and the singular versions of the resource name (e.g., namespace for namespaces). We can shorten the example above:

k8.ns.rc('http-rc').get(print);

Switching namespaces

You can call the namespace object to specify the namespace:

k8.ns('other-project').rc('http-rc').get(print);

Query parameters

You can optionally specify query string object qs to GET endpoints. kubernetes-client passes qs directly to request. For example to filter based on label selector:

k8.ns.rc.get({ qs: { labelSelector: 'service=http' } }, print);

Label selector filtering

kubernetes-client has a shortcut, matchLabels, for filtering on label selector equality:

k8.ns.rc.matchLabels({ service: 'http' }).get(print);

and a more general match method based on Kubernetes Match Expressions:

k8.ns.rc.match([{
  key: 'service',
  operator: 'In',
  values: ['http']
}, {
  key: 'deploy',
  operator: 'NotIn',
  values: ['production', 'staging']
}]).get(print);

ReplicationController Pods

kubernetes-client provides a shortcut for listing all Pods matching a ReplicationController selector:

k8.ns.rc.po.get(print);

kubernetes-client deletes all the Pods associated with a ReplicationController when it deletes the ReplicationController. You can preserve the Pods:

k8.ns.rc.delete({ rc: 'http-rc', preservePods: true });

Watching and streaming

If you don't pass a callback to get, node-kubernetes returns a stream. This is useful for watching:

const JSONStream = require('json-stream');
const jsonStream = new JSONStream();

const stream = k8.ns.po.get({ qs: { watch: true } });
stream.pipe(jsonStream);
jsonStream.on('data', object => {
  console.log('Pod:', JSON.stringify(object, null, 2));
});

You can access logs in a similar fashion:

const stream = k8.ns.po.log({ name: 'http-123', qs: { follow: true } });
stream.on('data', chunk => {
  process.stdout.write(chunk.toString());
});

Authenticating

kubernetes-client supports Kubernetes apiserver authentication.

Basic authentication (with optional certificate authority):

const k8 = new K8Api({
  url: 'https://my-k8-api-server.com',
  ca: fs.readFileSync('cluster-ca.pem'),
  auth: {
    user: 'user',
    pass: 'pass'
  }
});

token authentication:

const k8 = new K8Api({
  url: 'https://my-k8-api-server.com',
  auth: {
    bearer: 'token'
  }
});

and client certificate authentication:

const k8 = new K8Api({
  url: 'https://my-k8-api-server.com',
  ca: fs.readFileSync('cluster-ca.pem'),
  cert: fs.readFileSync('my-user-cert.pem'),
  key: fs.readFileSync('my-user-key.pem')
});

Passing options to request

kubernetes-client uses request. You can specify request options for kubernetes-client to pass to request:

const k8 = new K8Api({
  url: 'https://my-k8-api-server.com',
  request: {
    timeout: 3000
  }
});

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