baxshopnl / kube-watch

Kubernetes Watch API for node

kube-watch

Kubernetes Watch API for node.

Forked from subk/kube-watch

Installation

$ npm i @baxmusic/kube-watch

Quick start

new KubeWatch(resource, options) -> EventEmitter

import KubeWatch from '@baxmusic/kube-watch';

const pods = new KubeWatch('pods', {
  url: 'http://kube-api-server'   // Kubernetes API URL
});

pods
  .on('added', event => {
    console.log('Pod %s added to namespace %s with IP address %s',
      event.metadata.name, event.metadata.namespace, event.status.podIP);
  })
  .on('modified', event => {
    // do something...
  })
  .on('deleted', event => {
    // ..do something else..
  })
  .on('error', err => {
    console.error('Error %d: %s', err.code, err.message);
  });

Watching resources

By default, kube-watch will first request Kubernetes API to fetch the last resourceVersion for requested resource. See Kubernetes documentation for more details.
If you want to specify resourceVersion manually, see Query Parameters section.

Supported API & Resources

See Kubernetes API documentation for more details.

API v1

• namespaces
• endpoints
• events
• limitranges
• persistentvolumeclaims
• persistentvolumes
• pods
• podtemplates
• replicationcontrollers
• resourcequotas
• secrets
• serviceaccounts
• service

API v1beta1

• horizontalpodautoscalers
• ingresses
• jobs

API version will be automatically selected depending on requested resource.

by namespace

Watch all services in namespace public :

const services = new KubeWatch('services', {
  url: 'http://kube-api-server',
  namespace: 'public'
});

by name

Only watch service named www in namespace public :

const services = new KubeWatch('services', {
  url: 'http://kube-api-server',
  namespace: 'public',
  name: 'www'
});

Filtering events

You can filter which events will be emitted using events option.
By default, kube-watch will emit all k8s events: added, modified, deleted.

const namespaces = new KubeWatch('namespaces', {
  url: 'http://kube-api-server',
  events: [ 'added' ]   // watcher will only emit 'added' event
});

Query parameters

These extra query parameters are supported as option :

• labelSelector
• fieldSelector
• resourceVersion
• timeoutSeconds

const services = new KubeWatch('services', {
  url: 'http://kube-api-server',
  labelSelector: 'public-http',
  fieldSelector: 'event.status.podIP',
  resourceVersion: '6587423'
});

See documentation for more details about these options.

Request options

HTTP requests are performed using request package.
Pass custom options using request property.

const services = new KubeWatch('services', {
  url: 'http://kube-api-server',
  request: {
    timeout: 30000    // change HTTP request timeout
  }
});

HTTP Auth

See request's http authentication

const services = new KubeWatch('services', {
  url: 'http://kube-api-server',
  request: {
    auth: {
      user: 'foobar'
      pass: 'el8'
    }
  }
});

TLS/SSL support

See request's TLS/SSL support.

const services = new KubeWatch('services', {
  url: 'http://kube-api-server',
  request: {
    cert: fs.readFileSync(certFile),
    key: fs.readFileSync(keyFile),
    passphrase: 'password',
    ca: fs.readFileSync(caFile)
  }
});

Tests

Run test.js in watch mode :

$ env KUBE_API_SERVER=http://kube-api-server \
    npm run test:watch

Single run :

$ env KUBE_API_SERVER=http://kube-api-server \
    npm run test:single

Run tests using minikube to simulate workload.
See test/run-test.sh.

$ npm test

TODO

• Improve test suites by simulating workload

kube-watch's Issues

Convert to Typescript project

Need to convert to a TypeScript project.

Add 'end' event when a watch is terminated

Add an end event for when a watch is terminated.

Use case:

When watching is terminated, the service will no longer be watching changes. When using health-checks, this can trigger an unhealthy pod so k8s will restart the pod.

Update documentation to watch "forever"

The documentation needs some updating, because watching "forever" is not built-in. But it's possible by listening to the end event and starting a new watch based on the previously given resourceVersion.

Maybe we need to have it built-in by default.