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
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:
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:
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
References
License
MIT