kube-js
Simplified, lightweight Kubernetes API client with some useful extensions for Nod.js.
Installation
Install via npm:
$ npm i kube-js --save
Examples
kube-js
provides access to all the Kubernetes objects and
includes some niceties for writing simpler code.
Basics
kube-js
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 Api = ;const core = url: 'http://my-k8s-api-server.com' version: 'v1' // Defaults to 'v1' namespace: 'my-project' // Defaults to 'default'; { console;} corenamespaces;
kube-js
supports the Extensions API group. For example, GET
the Deployment
named http-deployment
:
const ext = url: 'http://my-k8s-api-server.com' version: 'v1beta1' // Defaults to 'v1beta1' namespace: 'my-project' // Defaults to 'default'; extnamespaces;
kube-js
provides a helper to get in-cluster config and accessing the API from a Pod:
const Api = ;const core = Apiconfig;
and a helper to get the current-context config from ~/.kube/config
:
const Api = ;const core = Apiconfig;
Creating and updating
kube-js
objects expose .post
, .patch
, and .put
methods. Create the ReplicationController from the example above:
const manifestObject = ;corenamespacesreplicationcontrollers;
or update the number of replicas:
const patch = spec: replicas: 10 ;corenamespaces;
Using the correct API group and version
kube-js
client includes functionality to help determine the
correct Kubernetes API group and version to use based on manifests:
const Api = ;const api = url: 'http://my-k8s-api-server.com' namespace: 'my-project'; const manifest0 = kind: 'Deployment' apiVersion: 'extensions/v1beta1' ...;const manifest1 = kind: 'ReplicationController' apiVersion: 'v1' ...; apins;apins;
Object name aliases
kube-js
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:
corens;
Switching namespaces
You can call the namespace
object to specify the namespace:
core;
Query parameters
You can optionally specify query string object qs
to GET
endpoints. kube-js
passes qs
directly to
request
.
For example to filter based on label
selector:
corensrc;
Label selector filtering
kube-js
has a shortcut, matchLabels
, for filtering on label
selector equality:
corensrc;
and a more general match
method based on Kubernetes Match Expressions:
corensrc;
ThirdPartyResources
You can extend the Kubernetes API using a
ThirdPartyResource
and kube-js
:
const newResoure = apiVersion: 'extensions/v1beta1' kind: 'ThirdPartyResource' metadata: name: 'new-resource.kubernetes-client.io' description: 'Example resource' versions: name: 'v1' ; extthirdpartyresources;
and then extend an ThirdPartyResource
API client with your new resources:
const thirdPartyResources = url: 'http://my-k8s-api-server.com' group: 'kubernetes-client.io' resources: 'customresources' // Notice pluralization!; // Access `customresources` as if they were a regular Kubernetes objectthirdPartyResourcesnscustomresources;thirdPartyResources; // Notice pluralization!// Now access `newresources`thirdPartyResourcesnsnewresources;
ReplicationController Pods
kube-js
provides a shortcut for listing all Pods matching a
ReplicationController selector:
corensrcpo;
kube-js
deletes all the Pods associated with a
ReplicationController when it deletes the ReplicationController. You
can preserve the Pods:
corensrc;
Watching and streaming
If you don't pass a callback to get
, node-kubernetes returns a
stream. This is useful for watching:
const JSONStream = ;const jsonStream = ; const stream = corenspo;stream;jsonStream;
You can access logs in a similar fashion:
const stream = corenspo;stream;
Note: the kube-apiserver will close watch connections eventually
according to the
[--min-request-timeout
](http://kubernetes.io/docs/admin/kube-apiserver/
command line argument. kube-js
does not attempt to reconnect
when the kube-apiserver closes a connection.
Authenticating
kube-js
supports Kubernetes apiserver
authentication.
Basic authentication (with optional certificate authority):
const core = url: 'https://my-k8s-api-server.com' ca: fs auth: user: 'user' pass: 'pass' ;
or without a certificate authority:
const core = url: 'https://my-k8s-api-server.com' insecureSkipTlsVerify: true auth: user: 'user' pass: 'pass' ;
token authentication:
const core = url: 'https://my-k8s-api-server.com' auth: bearer: 'token' ;
and client certificate authentication:
const core = url: 'https://my-k8s-api-server.com' ca: fs cert: fs key: fs;
request
Passing options to kube-js
uses
request
. You can specify
request
options
for kube-js
to pass to request
:
const core = url: 'https://my-k8s-api-server.com' request: timeout: 3000 ;
Testing
kube-js
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