@alchemy.run/kubernetes 0.0.0 → 2.0.0-beta.84

package/lib/ClusterAdapter.js

@@ -0,0 +1,65 @@
+/**
+ * The extension seam between the cluster-agnostic `Kubernetes.*` workloads
+ * and the platform a cluster runs on.
+ *
+ * A {@link ClusterAdapterService} is registered under a keyed Context tag —
+ * `Kubernetes.ClusterAdapter/<auth kind>` — and resolved dynamically from
+ * the ambient provider context by {@link findClusterAdapter}, mirroring how
+ * resource providers are resolved by type. `Kubernetes.providers()` ships
+ * the built-in adapters (`kubeconfig`, `token`, `client-cert`, `exec`);
+ * cloud provider layers contribute theirs (`AWS.providers()` registers
+ * `aws-eks`).
+ *
+ * An adapter owns everything platform-specific:
+ *
+ * - **connect** (required) — resolve the API server endpoint/CA and mint
+ *   per-request auth headers.
+ * - **identity** (optional) — provision workload identity for a namespace +
+ *   service account and translate host bindings into cloud credentials
+ *   (EKS Pod Identity, GKE Workload Identity Federation).
+ * - **registry** (optional) — build/mirror container images into a managed
+ *   registry the cluster can pull from (ECR on EKS, Artifact Registry on GKE).
+ * - **bootstrap** (optional) — platform-specific generated container
+ *   entries for Effect-native workloads (e.g. wiring the AWS credential
+ *   chain for Pod Identity).
+ * - **loadBalancerDefaults** (optional) — platform defaults for
+ *   `LoadBalancer` Services (EKS Auto Mode's `loadBalancerClass` +
+ *   internet-facing scheme).
+ */
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+/**
+ * The target cluster no longer exists (definitively — e.g. the managed
+ * control plane is deleted or deleting). Distinct from transient
+ * unreachability: `read`/`delete` treat this as "everything in-cluster is
+ * already gone".
+ */
+export class ClusterNotFoundError extends Data.TaggedError("Kubernetes.ClusterNotFoundError") {
+}
+const adapterKey = (authKind) => `Kubernetes.ClusterAdapter/${authKind}`;
+/**
+ * The keyed Context tag for an adapter. Same auth kind → same tag, so a
+ * layer built with `ClusterAdapter("aws-eks")` is found by any dynamic
+ * lookup for that kind.
+ */
+export const ClusterAdapter = (authKind) => Context.Service()(adapterKey(authKind));
+/**
+ * Resolve the {@link ClusterAdapterService} for a connection's auth kind
+ * from the ambient context (the stack's composed provider layers). Dies
+ * with setup guidance when no adapter is registered — that means the
+ * provider layer contributing it (e.g. `AWS.providers()` for `aws-eks`)
+ * is missing from the stack.
+ */
+export const findClusterAdapter = (authKind) => Effect.serviceOption(ClusterAdapter(authKind)).pipe(Effect.flatMap(Option.match({
+    onSome: (adapter) => Effect.succeed(adapter),
+    onNone: () => Effect.die(new Error(`No Kubernetes cluster adapter is registered for auth kind ` +
+        `'${authKind}'. Add the provider layer that contributes it ` +
+        `to the stack's providers — e.g. 'aws-eks' ships with ` +
+        "`AWS.providers()`; the built-in kinds (kubeconfig, token, " +
+        "client-cert, exec) ship with `Kubernetes.providers()`. " +
+        "Compose multiple provider layers with " +
+        "`Layer.mergeAll(AWS.providers(), Kubernetes.providers())`.")),
+})));
+//# sourceMappingURL=ClusterAdapter.js.map

package/lib/ClusterAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClusterAdapter.js","sourceRoot":"","sources":["../src/ClusterAdapter.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,IAAI,MAAM,aAAa,CAAC;AACpC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAYxC;;;;;GAKG;AACH,MAAM,OAAO,oBAAqB,SAAQ,IAAI,CAAC,WAAW,CAAC,iCAAiC,CAE1F;CAAG;AAkRL,MAAM,UAAU,GAAG,CAAC,QAAgB,EAAE,EAAE,CAAC,6BAA6B,QAAQ,EAAE,CAAC;AAEjF;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAC5B,QAAgB,EAC+C,EAAE,CACjE,OAAO,CAAC,OAAO,EAAgD,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAQ,CAAC;AAE/F;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,QAAgB,EAAwC,EAAE,CAC3F,MAAM,CAAC,aAAa,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CACjD,MAAM,CAAC,OAAO,CACZ,MAAM,CAAC,KAAK,CAAC;IACX,MAAM,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC;IAC5C,MAAM,EAAE,GAAG,EAAE,CACX,MAAM,CAAC,GAAG,CACR,IAAI,KAAK,CACP,4DAA4D;QAC1D,IAAI,QAAQ,gDAAgD;QAC5D,uDAAuD;QACvD,4DAA4D;QAC5D,yDAAyD;QACzD,wCAAwC;QACxC,4DAA4D,CAC/D,CACF;CACJ,CAAC,CACH,CACF,CAAC"}

package/lib/Connection.d.ts

@@ -0,0 +1,210 @@
+import type * as Redacted from "effect/Redacted";
+/**
+ * The cluster-agnostic Kubernetes connection model.
+ *
+ * Every `Kubernetes.*` workload (`Deployment`, `Job`, `Manifest`,
+ * `HelmChart`) targets a cluster through a serializable {@link Connection}:
+ * the API server endpoint (or enough information to discover it) plus an
+ * {@link ConnectionAuth} descriptor whose `kind` selects the
+ * {@link ClusterAdapter} that knows how to authenticate requests — and,
+ * for managed clouds, how to provision workload identity and container
+ * images.
+ *
+ * A `Connection` is plain data on purpose: it is resolved from resource
+ * attributes at reconcile time and persisted on workload attributes so
+ * `delete` can reconnect without the original resource graph.
+ */
+/**
+ * The auth descriptor registry, keyed by adapter kind. Cloud providers
+ * extend it via module augmentation — e.g. AWS registers:
+ *
+ * ```ts
+ * declare module "@alchemy.run/kubernetes/Connection" {
+ *   interface AuthRegistry {
+ *     "aws-eks": { clusterName: string; region?: string };
+ *   }
+ * }
+ * ```
+ *
+ * The built-in kinds cover anything `kubectl` can reach: a kubeconfig
+ * context (including `exec` credential plugins — `aws eks get-token`,
+ * `kubelogin`, `gke-gcloud-auth-plugin`), a static bearer token, a client
+ * certificate, or a raw exec credential plugin invocation.
+ */
+export interface AuthRegistry {
+    /**
+     * Resolve the cluster, user, and credentials from a kubeconfig file —
+     * the "anything kubectl can reach" adapter. Honors client certificates,
+     * static tokens, and `exec` credential plugins declared in the file.
+     */
+    kubeconfig: {
+        /**
+         * Path to the kubeconfig file.
+         * @default `$KUBECONFIG` or `~/.kube/config`
+         */
+        path?: string;
+        /**
+         * The context to use.
+         * @default the file's `current-context`
+         */
+        context?: string;
+    };
+    /** Authenticate with a static bearer token. */
+    token: {
+        /** The bearer token sent as `Authorization: Bearer <token>`. */
+        token: string;
+    };
+    /** Authenticate with a client certificate (mutual TLS). */
+    "client-cert": {
+        /** PEM-encoded client certificate. */
+        certificate: string;
+        /** PEM-encoded client private key. */
+        key: string;
+    };
+    /**
+     * Mint credentials with a kubeconfig-style exec credential plugin
+     * (`client.authentication.k8s.io` ExecCredential protocol).
+     */
+    exec: {
+        /** The command to run (e.g. `aws`). */
+        command: string;
+        /** Arguments (e.g. `["eks", "get-token", "--cluster-name", "x"]`). */
+        args?: string[];
+        /** Extra environment variables for the plugin process. */
+        env?: Record<string, string>;
+    };
+}
+/**
+ * The discriminated auth union — one member per {@link AuthRegistry} entry,
+ * each tagged with its registry key as `kind`.
+ */
+export type ConnectionAuth = {
+    [K in keyof AuthRegistry]: {
+        readonly kind: K;
+    } & AuthRegistry[K];
+}[keyof AuthRegistry];
+/**
+ * A container registry the cluster's nodes can pull from. `Deployment` and
+ * `Job` workloads with a `main` program or a `context` Dockerfile are built
+ * on the deploying machine and pushed here as `<server>/<name>:<hash>`.
+ *
+ * Clusters whose platform adapter provides its own registry (EKS pushes to
+ * ECR) ignore this setting.
+ */
+export interface ContainerRegistry {
+    /**
+     * Registry host, optionally followed by the namespace images are pushed
+     * under — e.g. `localhost:5001`, `ghcr.io/acme`, or
+     * `us-docker.pkg.dev/my-project/apps`.
+     */
+    server: string;
+    /**
+     * Username for pushing. Omit `username` and `password` to push with the
+     * deploying machine's own Docker login (`docker login`, credential
+     * helpers).
+     */
+    username?: string;
+    /** Password or access token for pushing. */
+    password?: string | Redacted.Redacted<string>;
+}
+/**
+ * A serializable description of how to reach and authenticate against a
+ * Kubernetes API server.
+ */
+export interface Connection {
+    /**
+     * The API server endpoint URL. Optional when the auth adapter can
+     * discover it (a kubeconfig file carries the server; the EKS adapter
+     * re-describes the cluster).
+     */
+    endpoint?: string;
+    /** Base64-encoded PEM certificate authority bundle for the endpoint. */
+    certificateAuthorityData?: string;
+    /** Skip TLS verification (self-signed local clusters). */
+    insecureSkipTlsVerify?: boolean;
+    /** How to authenticate — selects the {@link ClusterAdapter} by `kind`. */
+    auth: ConnectionAuth;
+    /**
+     * Where `main` and `context` workloads push their images. Required for
+     * those sources unless the cluster's platform adapter provides a
+     * registry (EKS → ECR).
+     */
+    registry?: ContainerRegistry;
+    /**
+     * CPU architecture of the cluster's nodes — the default target of
+     * workload image builds when a workload doesn't set `architecture`.
+     * @default "amd64"
+     */
+    architecture?: "amd64" | "arm64";
+}
+/**
+ * Anything a `Kubernetes.*` workload accepts as its `cluster` prop: a raw
+ * {@link Connection}, or any value exposing one as a `connection` field —
+ * which is how managed cluster resources (`AWS.EKS.Cluster`) participate:
+ * their attributes carry a `connection`, so the whole resource can be
+ * passed directly.
+ */
+export type ClusterLike = Connection | {
+    connection: Connection;
+};
+/**
+ * Normalize a {@link ClusterLike} to its {@link Connection}. Throws when
+ * the value carries neither shape — e.g. a managed cluster resource whose
+ * attributes predate the `connection` field.
+ */
+export declare const toConnection: (cluster: ClusterLike) => Connection;
+/**
+ * Connect `Kubernetes.*` workloads to any cluster your local kubeconfig can
+ * reach — k3s, kind, on-prem, AKS, GKE, anything `kubectl` works against.
+ * Exec credential plugins declared in the file (`aws eks get-token`,
+ * `kubelogin`, `gke-gcloud-auth-plugin`) are honored, so cloud-CLI-managed
+ * contexts work as-is.
+ *
+ * This is a plain helper, not a resource: nothing is provisioned and the
+ * cluster appears in no plan — it only describes how to reach the API
+ * server.
+ *
+ * ```ts
+ * const cluster = Kubernetes.KubeConfig({ context: "prod-east" });
+ *
+ * const api = yield* Kubernetes.Deployment("Api", {
+ *   cluster,
+ *   image: "ghcr.io/acme/api:v3",
+ *   port: 8080,
+ * });
+ * ```
+ *
+ * Add a `registry` to build `main` programs and `context` Dockerfiles for
+ * the cluster:
+ *
+ * ```ts
+ * const cluster = Kubernetes.KubeConfig({
+ *   context: "prod-east",
+ *   registry: { server: "ghcr.io/acme" },
+ * });
+ * ```
+ */
+export declare const KubeConfig: (options?: {
+    /**
+     * Path to the kubeconfig file.
+     * @default `$KUBECONFIG` or `~/.kube/config`
+     */
+    path?: string;
+    /**
+     * The context to use.
+     * @default the file's `current-context`
+     */
+    context?: string;
+    /**
+     * Where `main` and `context` workloads push their images. The cluster's
+     * nodes must be able to pull from it.
+     */
+    registry?: ContainerRegistry;
+    /**
+     * CPU architecture of the cluster's nodes, used as the default image
+     * build target.
+     * @default "amd64"
+     */
+    architecture?: "amd64" | "arm64";
+}) => Connection;
+//# sourceMappingURL=Connection.d.ts.map

package/lib/Connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Connection.d.ts","sourceRoot":"","sources":["../src/Connection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AAEjD;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,UAAU,EAAE;QACV;;;WAGG;QACH,IAAI,CAAC,EAAE,MAAM,CAAC;QACd;;;WAGG;QACH,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,+CAA+C;IAC/C,KAAK,EAAE;QACL,gEAAgE;QAChE,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;IACF,2DAA2D;IAC3D,aAAa,EAAE;QACb,sCAAsC;QACtC,WAAW,EAAE,MAAM,CAAC;QACpB,sCAAsC;QACtC,GAAG,EAAE,MAAM,CAAC;KACb,CAAC;IACF;;;OAGG;IACH,IAAI,EAAE;QACJ,uCAAuC;QACvC,OAAO,EAAE,MAAM,CAAC;QAChB,sEAAsE;QACtE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;QAChB,0DAA0D;QAC1D,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAC9B,CAAC;CACH;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG;KAC1B,CAAC,IAAI,MAAM,YAAY,GAAG;QAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAA;KAAE,GAAG,YAAY,CAAC,CAAC,CAAC;CAClE,CAAC,MAAM,YAAY,CAAC,CAAC;AAEtB;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;CAC/C;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,0DAA0D;IAC1D,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,0EAA0E;IAC1E,IAAI,EAAE,cAAc,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;CAClC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG;IAAE,UAAU,EAAE,UAAU,CAAA;CAAE,CAAC;AAKlE;;;;GAIG;AACH,eAAO,MAAM,YAAY,YAAa,WAAW,KAAG,UAUnD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,UAAU,aAAc;IACnC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;CAClC,KAAG,UAQF,CAAC"}

package/lib/Connection.js

@@ -0,0 +1,58 @@
+const isConnection = (value) => "auth" in value && value.auth !== undefined;
+/**
+ * Normalize a {@link ClusterLike} to its {@link Connection}. Throws when
+ * the value carries neither shape — e.g. a managed cluster resource whose
+ * attributes predate the `connection` field.
+ */
+export const toConnection = (cluster) => {
+    if (isConnection(cluster))
+        return cluster;
+    if (cluster.connection !== undefined)
+        return cluster.connection;
+    throw new Error("The `cluster` value carries no Kubernetes connection. Pass a cluster " +
+        "resource whose attributes expose `connection` (e.g. `AWS.EKS.Cluster`" +
+        " — redeploy the cluster if it was created before the `connection` " +
+        "attribute existed), a `Kubernetes.KubeConfig(...)`, or a raw " +
+        "`Kubernetes.Connection`.");
+};
+/**
+ * Connect `Kubernetes.*` workloads to any cluster your local kubeconfig can
+ * reach — k3s, kind, on-prem, AKS, GKE, anything `kubectl` works against.
+ * Exec credential plugins declared in the file (`aws eks get-token`,
+ * `kubelogin`, `gke-gcloud-auth-plugin`) are honored, so cloud-CLI-managed
+ * contexts work as-is.
+ *
+ * This is a plain helper, not a resource: nothing is provisioned and the
+ * cluster appears in no plan — it only describes how to reach the API
+ * server.
+ *
+ * ```ts
+ * const cluster = Kubernetes.KubeConfig({ context: "prod-east" });
+ *
+ * const api = yield* Kubernetes.Deployment("Api", {
+ *   cluster,
+ *   image: "ghcr.io/acme/api:v3",
+ *   port: 8080,
+ * });
+ * ```
+ *
+ * Add a `registry` to build `main` programs and `context` Dockerfiles for
+ * the cluster:
+ *
+ * ```ts
+ * const cluster = Kubernetes.KubeConfig({
+ *   context: "prod-east",
+ *   registry: { server: "ghcr.io/acme" },
+ * });
+ * ```
+ */
+export const KubeConfig = (options) => ({
+    auth: {
+        kind: "kubeconfig",
+        path: options?.path,
+        context: options?.context,
+    },
+    ...(options?.registry !== undefined ? { registry: options.registry } : {}),
+    ...(options?.architecture !== undefined ? { architecture: options.architecture } : {}),
+});
+//# sourceMappingURL=Connection.js.map

package/lib/Connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Connection.js","sourceRoot":"","sources":["../src/Connection.ts"],"names":[],"mappings":"AAwJA,MAAM,YAAY,GAAG,CAAC,KAAkB,EAAuB,EAAE,CAC/D,MAAM,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC;AAE9C;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,OAAoB,EAAc,EAAE;IAC/D,IAAI,YAAY,CAAC,OAAO,CAAC;QAAE,OAAO,OAAO,CAAC;IAC1C,IAAI,OAAO,CAAC,UAAU,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC,UAAU,CAAC;IAChE,MAAM,IAAI,KAAK,CACb,uEAAuE;QACrE,uEAAuE;QACvE,oEAAoE;QACpE,+DAA+D;QAC/D,0BAA0B,CAC7B,CAAC;AACJ,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,OAsB1B,EAAc,EAAE,CAAC,CAAC;IACjB,IAAI,EAAE;QACJ,IAAI,EAAE,YAAY;QAClB,IAAI,EAAE,OAAO,EAAE,IAAI;QACnB,OAAO,EAAE,OAAO,EAAE,OAAO;KAC1B;IACD,GAAG,CAAC,OAAO,EAAE,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1E,GAAG,CAAC,OAAO,EAAE,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;CACvF,CAAC,CAAC"}