/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/kubernetes_client@v0.7.0/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.

Changelog

• 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