@kubelib/config

Kubernetes Kubeconfig Client

The last Kubeconfig abstraction in JS you will need

What can it do?

• Provides types and utilities to handle, load, manage, extend and introspect Kubeconfig files and objects
• Provides authentication facilities to authenticate against Kubernetes clusters using Kubeconfig files and objects
• Is compatible in all environments, including browsers, Node.js and more

What can't it do?

• This is not a replacement for a fully-fledged Kubernetes client library
• It is quite low-level, even though it comes with powerful abstractions

Installation

yarn add @kubelib/config

Usage

Basic Kubeconfig manipulation

Build a Kubeconfig from scratch

import { buildConfig, addCluster, addUser, addContext } from '@kubelib/config'

// build a config from scratch with modifiers
const config = buildConfig(
  addCluster('foo', {
    server: 'https://my-kubernetes-cp.example.com'
  }),
  addUser('bar', {
    username: 'admin',
    password: 'admin'
  }),
  addContext('foobar', {
    cluster: 'foo',
    user: 'bar'
  }),
)

Load default kubeconfig and modify it

import {
  loadDefaultConfig,
  modifyConfig,
  addCluster,
  addContext,
  setDefaultContext
} from '@kubelib/config'

// load ~/.kube/config
const config = await loadDefaultConfig()

// modify config with modifiers
const newConfig = modifyConfig(config)(
  addCluster('foo', {
    server: 'https://my-kubernetes-cp.example.com'
  }),
  addContext('newfoo', {
    cluster: 'foo',
    user: 'existing-user'
  }),
  setDefaultContext('newfoo')
)

Authenticate a request with a Kubeconfig

The easiest way is to use the kubeFetch abstraction provided

import { loadDefaultConfig, kubeFetch } from '@kubelib/config'

const fetchNamespaces = () =>
  kubeFetch('/api/v1/namespaces', {
    headers: {
      // You can pass your own config like this:
      // kube: { config: myOwnKubeconfig },
      'Content-Type': 'application/json',
    }
  })

fetchNamespaces()
  .then(response => response.json())
  .then(namespaceList => {
     // Logs all namespaces in the cluster
    console.log(namespaceList.items)
  })

Understand how it works in detail

import {
  loadDefaultConfig,
  createAuthenticateOptions,
  authenticate,
  getCurrentCluster
} from '@kubelib/config'

const fetchNamespaces = () => {

  // Load ~/.kube/config
  const config = await loadDefaultConfig()

  // Create options for authenticating
  const authenticateOptions = createAuthenticateOptions({
    config,
    // Much more can be configured here!
  })

  // Get the currently selected cluster from the config
  const currentCluster = getCurrentCluster(config)

  // fetch stuff from the Kubernetes API
  const url = `${currentCluster.server}/api/v1/namespaces`
  
  // Create a request to make with the full URL
  const request = new Request(url, {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
    },
  })
  
  // Authenticate the request with the Kubeconfig
  const authenticatedRequest = authenticate(request, authenticateOptions)

  // Send the request
  return authenticateOptions.fetch(authenticatedRequest)
}

fetchNamespaces()
  .then(response => response.json())
  .then(namespaceList => {
     // Logs all namespaces in the cluster
    console.log(namespaceList.items)
  })

Configuration

Configuration is done by creating an AuthenticateOptions object and passing it to the authenticate function. You can construct it completely manually or partially by using createAuthenticateOptions as seen below

import { createAuthenticateOptions } from '@kubelib/config'

const options = createAuthenticateOptions({
 /**
   * The kubeconfig to authenticate with.
   * 
   * By default it will load the default kubeconfig from `~/.kube/config`.
   */
  config: Config
  /**
   * The authenticator to use.
   *
   * By default this is a stack of authenticators that supports some
   * known authentication methods.
   */
  authenticator: Authenticator
  /**
   * The credential cache to use.
   *
   * By default this is a memory cache.
   */
  credentialCache: CredentialCache
  /**
   * The http loader to use.
   *
   * By default this is a stack of http loaders that supports some
   * known authentication methods.
   */
  httpLoader: HttpLoader
  /**
   * The file loader to use.
   *
   * By default this is a stack of file loaders that supports some
   * known authentication methods.
   */
  fileLoader: FileLoader
  /**
   * The url loaders to use.
   *
   * By default this is a loader that supports file: urls
   * through `fileLoader` and http: and https: urls through `httpLoader`.
   */
  urlLoader: UrlLoader
  /**
   * The command executor to use.
   *
   * By default this is a node exec executor.
   */
   commandExecutor: CommandExecutor
  /**
   * The config locator to use.
   *
   * By default it will yield `~/.kube/config`.
   */
  configLocator: ConfigLocator
})