Skip to content

Latest commit

 

History

History

lib

README.md

Deno CI

/x/kubernetes_apis

Purpose

Generated, typed interfaces to make every possible Kubernetes API request and work with richer data structures.

The actual request transports are implemented in /x/kubernetes_client.

Usage

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

import { autoDetectClient } from 'https://deno.land/x/[email protected]/mod.ts';
import { CoreV1Api } from 'https://deno.land/x/kubernetes_apis/builtin/core@v1/mod.ts';

const kubernetes = await autoDetectClient();
const coreApi = new CoreV1Api(kubernetes).namespace("default");

const podList = await coreApi.getPodList();
console.log(podList);

// see files in examples/ for more API demos (watching, creation, etc)

When running locally (with kubectl set up), you probably just to add --allow-run=kubectl to run this. For a container being deployed onto a cluster, there's more flags to provide instead; see /x/kubernetes_client for more information.

Usage with JSR Imports

Note that there is no default export, so you will need to import the particular Kubernetes API groups that you want to work with. This layout keeps program size smaller.

import { autoDetectClient } from "jsr:@cloudydeno/[email protected]";
import { CoreV1Api } from "jsr:@cloudydeno/kubernetes-apis/core/v1";

const kubernetes = await autoDetectClient();
const coreApi = new CoreV1Api(kubernetes).namespace("default");

const podList = await coreApi.getPodList();
console.log(podList);

Changelog

  • v0.5.4 on 2025-01-18:

    • Includes 'builtin' APIs generated from K8s v1.32.0.
      • Several API versions were changed, removed, or added.
      • You may need to update imports if you used a non-stable API version which has been moved.
    • cert-manager and argo-cd CRDs have been updated.

  • v0.5.3 on 2024-10-16:

    • Fix CRD codegen issues with particular definitions and when using JSR import paths.

  • v0.5.2 on 2024-09-28:

    • Includes 'builtin' APIs generated from K8s v1.30.4.
      • New kinds ValidatingAdmissionPolicy, ServiceCIDR, ResourceSlice
      • Several API versions changed. You may need to update imports if you used one.
      • Further API changes are detailed in Github Releases.
    • cert-manager, argo-cd, external-dns, and vpa CRDs have been updated.

  • v0.5.1 on 2024-09-18:

    • Updating /x/kubernetes_client API contract to v0.7.3.
    • Add JSR publication of the module.
    • Exposed API surface has been adjusted to satisfy JSR "slow types" checks. Shouldn't affect most code.

  • v0.5.0 on 2023-08-19:

    • Updating /x/kubernetes_client API contract to v0.7.0.
    • Actually implement PodExec, PodAttach, PodPortForward APIs with a new tunnel implementation.
    • Includes 'builtin' APIs generated from K8s v1.28.0.
      • New APIs: admissionregistration.k8s.io/v1beta1, certificates.k8s.io/v1alpha1.
      • Also, API additions for sidecar containers and SelfSubjectReview.
    • Fix several structures incorrectly typed as {} instead of JSONValue.

  • v0.4.0 on 2023-02-10:

    • Updating /x/kubernetes_client API contract to v0.5.0.
    • Breaking change: The return type of delete functions has been widened to a union.
      • If you were using a deletion response, you can use type narrowing to detect which Kind was returned.
      • See #4 for more information.
    • Includes 'builtin' APIs generated from K8s v1.26.1.
      • Numerous alpha and beta APIs removed, including autoscaling, batch, and policy
      • Further API changes are detailed in Github Releases.
    • cert-manager CRDs have been updated. Removes v1beta1, v1alpha3, and v1alpha2 APIs.
    • argo-cd CRDs have been updated. Adds a new ApplicationSet CRD.
      • Some nested structures were deduplicated to reduce code size.
    • Added CRDs for Vertical Pod Autoscaler.
    • Add streamPodLogs to allow fetching pod logs as a ReadableStream<string>.

  • v0.3.2 on 2021-12-02:

    • Updating /x/kubernetes_client API contract to v0.3.2.
    • Includes 'builtin' APIs generated from K8s v1.22.4.
      • Numerous v1beta1 API versions were removed in favor of stable v1 APIs.
      • Further API changes are detailed in Github Releases.
    • cert-manager and external-dns CRDs have been updated from the latest releases.
    • Added CRDs for argo-cd.

  • v0.3.1 on 2021-05-09:

    • Updating /x/kubernetes_client API contract to v0.2.4.
    • Includes 'builtin' APIs generated from K8s v1.21.0.
      • get functions no longer accept export or exact.
    • cert-manager and external-dns CRDs have been updated from the latest releases.

  • v0.3.0 on 2021-02-28:

    • Updating /x/kubernetes_client API contract to v0.2.0.
      • Breaking change!
      • If you import autoDetectClient and other client APIs from this common.ts, those now come from client.ts instead (or just import /x/kubernetes_client yourself).
      • This upstream release vastly improves cluster client detection logic.
    • Now handles v1.Status error payloads when processing any response body.
    • Added shebang and execute bit to every script in examples/.
    • Optimized redundencies out of cert-manager structures (half the file size now)

  • v0.2.0 on 2020-12-29:

    • Includes 'builtin' APIs generated from K8s v1.20.
    • Patching and deletion is more stable; mistype error messages are vastly improved.
    • ApiExtensions and ApiRegistration groups are now included.
    • Updating /x/kubernetes_client API contract to v0.1.2.
    • Reflector implementation has been moved up to /x/kubernetes_client.
    • Core's proxy endpoints (Node/Pod/Service) are now implemented and usable.
    • CRDs are now generated from original YAML instead of from a cluster's generated APIs.
    • cert-manager's CRDs have been updated to v1 and external-dns's CRDs also added.

  • v0.1.0 on 2020-11-17:

    • Initial release, with 'builtin' APIs generated from K8s v1.19.
    • There's still a fair amount of TODOs for particular resources, and structure types.
    • A workable Reflector implementation is included.
    • cert-manager's CRDs have a generated client as well, as an experiment.

TODO

  • PATCH requests
  • Solidify Quantity, Duration, etc
  • Reconcile deletion response kinds (might still be fallout)
  • Story for generating API clients directly from CRD specifications
  • Story for generating the whole API surface of a specific cluster
  • Move Reflector implementation upstream to /x/kubernetes_client