kubernetes-client

Node.js client for the Kubernetes API.

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({
  url: 'http://my-k8-api-server.com',
  version: 'v1beta1',  // Defaults to 'v1'
  namespace: 'my-project' // Defaults to 'default'
});

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

k8.namespaces.replicationcontrollers.get('http-rc', 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.patch({
  name: 'http-rc',
  body: patch
}, 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.get('http-rc', print);

Switching namespaces

You can call the namespace object to specify the namespace:

k8.ns('other-project').rc.get('http-rc', 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, matchLabel, for filtering on label selector equality:

k8.ns.rc.matchLabel({ 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
  }
});

More Documentation

• Kubernetes Reference Documentation
• Kubernetes Swagger Spec

License

MIT