kubernetes-client

[![Build Status][build]](https://travis-ci.org/godaddy/kubernetes-client) [![Greenkeeper badge][greenkeeper]](https://greenkeeper.io/)

[greenkeeper]: https://badges.greenkeeper.io/godaddy/kubernetes-client.svg
[build]: https://travis-ci.org/godaddy/kubernetes-client.svg?branch=master

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 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:

`js
const client = new Client({ version: '1.13' })
`

provide your own path to a file:

`js
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:

`js
// 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:

`js
kubeconfig.setCurrentContext('dev')
`

You can also elide the .version and pass an OpenAPI specification:

`js
const spec = require('./swagger.json')
const client = new Client({ spec })
`

or load a specification dynamically from the kube-apiserver:

`js
const client = new Client()
await client.loadSpec()
`

See Examples for more configuration examples.

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:

`js
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:

`js
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:

`js
const deployment = await client.apis.apps.v1.namespaces('default').deployments(deploymentManifest.metadata.name).get()
`

and finally, remove the Deployment:

`js
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.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.13 and a complimentry Client1_13 class:

`typescript
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

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
* Access VerticalPodAutoscalers: vpas/
* Create a client using an in-cluster configuration: in-cluster-auth.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

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
``

References

* An Intuitive Node.js Client for the Kubernetes API
* Kubernetes Reference Documentation

License

MIT

[1]: https://swagger.io/specification/#pathItemObject
[2]: https://swagger.io/specification/#pathTemplating