search

cloudydeno / deno-kubernetes_client

Typescript library for accessing a Kubernetes API server
https://deno.land/x/kubernetes_client
Apache License 2.0
18 stars 4 forks source link
deno kubernetes kubernetes-api

readme

Deno CI

/x/kubernetes_client

This module implements several ways of sending authenticated requests to the Kubernetes API from deno scripts.

Kubernetes is a complex architechure which likes using sophisticated networking concepts, while Deno is a relatively young runtime, so there's some mismatch in capabilities. Therefor one client implementation cannot work in every case, and different Deno flags enable supporting different setups.

This library is intended as a building block. If you are unsure how to issue a specific request from your own library/code, or if your usage results in any TODO: ... error message from my code, please feel free to file a Github Issue.

Usage

Here's a basic request, listing all Pods in the default namespace. It uses the autoDetectClient() entrypoint which returns the first usable client.

Note: This example shows a manual HTTP request. To use the Kubernetes APIs more easily, consider also using /x/kubernetes_apis

import { autoDetectClient } from 'https://deno.land/x/kubernetes_client/mod.ts';
const kubernetes = await autoDetectClient();

const podList = await kubernetes.performRequest({
  method: 'GET',
  path: `/api/v1/namespaces/default/pods`,
  expectJson: true, // run JSON.parse on the response body
});
console.log(podList);

// see demo.ts for more request examples (streaming responses, etc)

To get started on local development, autoDetectClient will most likely decide to call out to your kubectl installation to make each network call. This only requires the --allow-run=kubectl Deno flag.

To use other clients, more flags are necesary. See "Client Implementations" below for more information on flags and other HTTP clients.

The kubectl client logs the issued commands if --verbose is passed to the Deno program.

Check out lib/contract.ts to see the type/API contract.

Changelog

Client Implementations

An error message is shown when no client is usable, something like this:

Error: Failed to load any possible Kubernetes clients:
  - InCluster PermissionDenied: Requires read access to "/var/run/secrets/kubernetes.io/serviceaccount/namespace", run again with the --allow-read flag
  - KubeConfig PermissionDenied: Requires env access to "KUBECONFIG", run again with the --allow-env flag
  - KubectlProxy PermissionDenied: Requires net access to "localhost:8001", run again with the --allow-net flag
  - KubectlRaw PermissionDenied: Requires run access to "kubectl", run again with the --allow-run flag

Each client has different pros and cons:

Related: API Typings

This module is only implementing the HTTP/transport part of talking to Kubernetes. You'll likely also want Typescript interfaces around actually working with Kubernetes resources.

API typings are available in a sibling project: kubernetes_apis published to /x/kubernetes_apis.

Of course, for some situations it might make sense to issue specific requests directly in which case using this client library alone might make more sense.

TODO