npm package: @kubelib/config
Description: ## Kubernetes Kubeconfig Client
Author: Torben Köhn
Latest version: 0.1.9

# @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

```sh
yarn add @kubelib/config
```

## Usage

### Basic Kubeconfig manipulation

**Build a Kubeconfig from scratch**

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

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

```ts
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)
  })
```

<details>
  <summary>
    <strong>Understand how it works in detail</strong>
  </summary>

```ts
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)
  })
```
</details>

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

```ts
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
})