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

package/src/ClusterAdapter.ts

@@ -0,0 +1,373 @@
+import type { InlineDockerfile } from "@alchemy.run/docker/Dockerfile";
+import type { DockerfileBuild } from "@alchemy.run/docker/ImageSource";
+import type * as Bundle from "alchemy/Bundle/Bundle";
+import type { ResourceBinding } from "alchemy/Resource";
+import type { ResourceContext } from "alchemy/ResourceContext";
+import type { Stack } from "alchemy/Stack";
+import type { Stage } from "alchemy/Stage";
+/**
+ * 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";
+import type { Connection } from "./Connection.ts";
+
+/**
+ * Per-resource engine services ambient inside every provider lifecycle
+ * operation. Adapter methods run inside the workload providers' lifecycle
+ * ops, so they may require these (physical-name generation needs the
+ * resource's ResourceContext + Stack + Stage) — everything else an adapter
+ * needs is captured at its layer build.
+ */
+export type AdapterLifecycleServices = ResourceContext | Stack | Stage;
+
+/**
+ * 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")<{
+  message: string;
+}> {}
+
+/**
+ * A resolved transport to a cluster's API server. `headers` is an Effect
+ * so short-lived tokens (EKS SigV4 presigns, exec plugin credentials) are
+ * minted per request.
+ */
+export interface ClusterTransport {
+  /** The API server endpoint URL. */
+  endpoint: string;
+  /** Base64-encoded PEM certificate authority bundle. */
+  certificateAuthorityData?: string;
+  /** Skip TLS verification (self-signed local clusters). */
+  insecureSkipTlsVerify?: boolean;
+  /** Mint the auth headers for one request. */
+  headers: Effect.Effect<Record<string, string>, Error>;
+  /** PEM client certificate credentials for mutual TLS. */
+  clientCert?: { certificate: string; key: string };
+}
+
+/**
+ * Workload identity state persisted on a workload's attributes, keyed by
+ * adapter kind. Cloud providers extend it via module augmentation — AWS
+ * registers:
+ *
+ * ```ts
+ * declare module "@alchemy.run/kubernetes/ClusterAdapter" {
+ *   interface IdentityStateRegistry {
+ *     "aws-pod-identity": {
+ *       roleArn: string;
+ *       roleName: string;
+ *       associationArn: string;
+ *       associationId: string;
+ *     };
+ *   }
+ * }
+ * ```
+ */
+export interface IdentityStateRegistry {}
+
+/** The discriminated identity-state union across all registered adapters. */
+export type IdentityState = {
+  [K in keyof IdentityStateRegistry]: {
+    readonly kind: K;
+  } & IdentityStateRegistry[K];
+}[keyof IdentityStateRegistry];
+
+/**
+ * Image-registry state persisted on a workload's attributes, keyed by
+ * adapter kind (AWS registers `"aws-ecr"` with the repository name/URI).
+ * The built-in `"registry"` entry records images pushed to a connection's
+ * {@link Connection.registry}.
+ */
+export interface RegistryStateRegistry {
+  registry: {
+    /** The registry `server` the image was pushed to. */
+    server: string;
+    /** The repository the image was pushed to (`<server>/<name>`). */
+    repository: string;
+  };
+}
+
+/** The discriminated registry-state union across all registered adapters. */
+export type RegistryState = {
+  [K in keyof RegistryStateRegistry]: {
+    readonly kind: K;
+  } & RegistryStateRegistry[K];
+}[keyof RegistryStateRegistry];
+
+/**
+ * Cloud-specific workload identity options, extended via module
+ * augmentation (AWS adds `managedPolicyArns`, GCP `gcpServiceAccount`).
+ */
+export interface WorkloadIdentityOptions {}
+
+/**
+ * The binding contract of `Kubernetes.Deployment` / `Kubernetes.Job`
+ * hosts. The core contract is environment variables; cloud providers
+ * augment it with their credential-grant channels (AWS adds
+ * `policyStatements`, GCP adds `iam`), which the matching {@link ClusterAdapterService}'s
+ * identity adapter materializes at deploy time.
+ */
+export interface WorkloadBindingContract {
+  env?: Record<string, any>;
+}
+
+/**
+ * Ambient runtime services the workload platforms assume inside the
+ * deployed container, keyed by contributor and extended via module
+ * augmentation — AWS registers its credential-chain services so inline
+ * impls can use AWS bindings without providing them:
+ *
+ * ```ts
+ * declare module "@alchemy.run/kubernetes/ClusterAdapter" {
+ *   interface WorkloadServicesRegistry {
+ *     aws: Credentials | Region | AWSEnvironment;
+ *   }
+ * }
+ * ```
+ */
+export interface WorkloadServicesRegistry {}
+
+/** The union of all registered ambient workload services. */
+export type WorkloadServices = WorkloadServicesRegistry[keyof WorkloadServicesRegistry];
+
+/**
+ * The image-source shape shared by every workload: exactly one of `main`
+ * (bundle an inline Effect program), `context`/`dockerfile` (build the
+ * user's Dockerfile), or `image` (a pre-built registry reference).
+ * Structurally mirrors the AWS container platforms' source props.
+ */
+export interface WorkloadImageSource {
+  main?: string;
+  handler?: string;
+  /**
+   * Bundler configuration for `main`, or Docker build args and secrets for
+   * a `context`/`dockerfile` build. Unused bundled code is tree-shaken.
+   * `effect`, alchemy, and `@distilled.cloud` are marked pure so unused
+   * parts prune more aggressively. List extra packages with
+   * `pure.packages`, or disable with `pure: false`.
+   */
+  build?: Bundle.BundleConfig & DockerfileBuild;
+  context?: string;
+  dockerfile?: string | InlineDockerfile;
+  image?: string;
+}
+
+export interface WorkloadIdentityReconcileOptions {
+  /** Logical resource id. */
+  id: string;
+  /** The resolved cluster connection. */
+  connection: Connection;
+  /** The namespace the workload runs in. */
+  namespace: string;
+  /** The service account name the workload's pods run as. */
+  serviceAccount: string;
+  /** Host bindings attached to the workload. */
+  bindings: ResourceBinding<WorkloadBindingContract>[];
+  /** Cloud-specific identity options from the workload's `identity` prop. */
+  options: WorkloadIdentityOptions | undefined;
+  /**
+   * Previously persisted identity state, if any — untyped hints because
+   * legacy pre-rename rows carry the old flat attribute shape; adapters
+   * narrow structurally and re-observe cloud state as the authority.
+   */
+  state: Record<string, unknown> | undefined;
+  /** Internal + user tags for identity-owned cloud resources. */
+  tags: Record<string, string>;
+}
+
+export interface WorkloadIdentityResult {
+  /** Extra container environment collected from bindings. */
+  env: Record<string, any>;
+  /** Annotations to stamp on the workload's ServiceAccount object. */
+  serviceAccountAnnotations?: Record<string, string>;
+  /** Serializable state persisted on the workload's attributes. */
+  // oxlint-disable-next-line typescript/no-redundant-type-constituents -- registry type is `never` until cloud packages augment it
+  state: IdentityState | undefined;
+}
+
+export interface WorkloadIdentityDeleteOptions {
+  /** The persisted cluster connection (may reference a gone cluster). */
+  connection: Connection | undefined;
+  /**
+   * The persisted identity state. Untyped because legacy pre-rename rows
+   * carry the old flat attribute shape — adapters narrow structurally.
+   */
+  state: Record<string, unknown> | undefined;
+}
+
+export interface ImageRegistryResolveOptions {
+  /** Logical resource id — keys generated repository names. */
+  id: string;
+  /** The image-source props bag. */
+  source: WorkloadImageSource;
+  /** Target image platform (`linux/amd64` / `linux/arm64`). */
+  platform: string;
+  /** Port the generated Dockerfile exposes (`main` sources only). */
+  port?: number;
+  /** True when `main` bundles as-is (no Effect bootstrap entry). */
+  isExternal?: boolean;
+  /** The generated-entry bootstrap wrapped around `main`. */
+  bootstrap: (importPath: string) => string;
+  /** Tags for registry-owned cloud resources. */
+  tags: Record<string, string>;
+  /**
+   * Previously persisted registry state, if any — untyped hints because
+   * legacy pre-rename rows carry the old flat attribute shape; adapters
+   * narrow structurally.
+   */
+  state: Record<string, unknown> | undefined;
+  /** Plan-status session for build/push progress notes. */
+  session: { note: (message: string) => Effect.Effect<void> };
+}
+
+export interface ImageRegistryResult {
+  /** Full image reference the pod spec should run. */
+  imageUri: string;
+  /** Content hash identifying the image. */
+  codeHash: string;
+  /** Serializable state persisted on the workload's attributes. */
+  state: RegistryState | undefined;
+}
+
+export interface ImageRegistryHashOptions {
+  source: WorkloadImageSource;
+  platform: string;
+  port?: number;
+  isExternal?: boolean;
+  bootstrap: (importPath: string) => string;
+}
+
+export interface ImageRegistryDeleteOptions {
+  /**
+   * The persisted registry state. Untyped because legacy pre-rename rows
+   * carry the old flat attribute shape — adapters narrow structurally.
+   */
+  state: Record<string, unknown> | undefined;
+}
+
+export interface ClusterAdapterService {
+  readonly kind: "Kubernetes.ClusterAdapter";
+  /**
+   * Resolve the transport for a connection: discover the endpoint/CA when
+   * the connection doesn't carry them, and return a per-request auth
+   * header mint. Fails with {@link ClusterNotFoundError} when the cluster
+   * definitively no longer exists.
+   */
+  readonly connect: (
+    connection: Connection,
+  ) => Effect.Effect<ClusterTransport, ClusterNotFoundError | Error>;
+  /** Workload identity provisioning (Pod Identity on EKS, Workload Identity Federation on GKE). */
+  readonly identity?: {
+    readonly reconcile: (
+      options: WorkloadIdentityReconcileOptions,
+    ) => Effect.Effect<WorkloadIdentityResult, any, AdapterLifecycleServices>;
+    readonly delete: (
+      options: WorkloadIdentityDeleteOptions,
+    ) => Effect.Effect<void, any, AdapterLifecycleServices>;
+  };
+  /** Managed container-image registry (ECR on EKS, Artifact Registry on GKE). */
+  readonly registry?: {
+    readonly resolve: (
+      options: ImageRegistryResolveOptions,
+    ) => Effect.Effect<ImageRegistryResult, any, AdapterLifecycleServices>;
+    /** Plan-time content hash used by `diff` to surface source drift. */
+    readonly hash: (
+      options: ImageRegistryHashOptions,
+    ) => Effect.Effect<string | undefined, any, AdapterLifecycleServices>;
+    readonly delete: (
+      options: ImageRegistryDeleteOptions,
+    ) => Effect.Effect<void, any, AdapterLifecycleServices>;
+  };
+  /**
+   * Platform-specific generated container entries for Effect-native
+   * workloads. Defaults to the platform-neutral bootstraps when omitted.
+   */
+  readonly bootstrap?: {
+    readonly server?: (handler: string) => (importPath: string) => string;
+    readonly job?: (handler: string) => (importPath: string) => string;
+  };
+  /**
+   * Platform defaults applied to a `LoadBalancer` Service (EKS Auto Mode
+   * sets `loadBalancerClass: eks.amazonaws.com/nlb` and defaults the
+   * scheme to internet-facing). User `serviceAnnotations` always win.
+   */
+  readonly loadBalancerDefaults?: (options: { connection: Connection }) => Effect.Effect<
+    {
+      loadBalancerClass?: string | undefined;
+      annotations?: Record<string, string>;
+    },
+    any,
+    AdapterLifecycleServices
+  >;
+}
+
+const adapterKey = (authKind: string) => `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: string,
+): Context.Service<ClusterAdapterService, ClusterAdapterService> =>
+  Context.Service<ClusterAdapterService, ClusterAdapterService>()(adapterKey(authKind)) as any;
+
+/**
+ * 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: string): Effect.Effect<ClusterAdapterService> =>
+  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())`.",
+            ),
+          ),
+      }),
+    ),
+  );

package/src/Connection.ts

@@ -0,0 +1,234 @@
+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 };
+
+const isConnection = (value: ClusterLike): value is Connection =>
+  "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: ClusterLike): Connection => {
+  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?: {
+  /**
+   * 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 => ({
+  auth: {
+    kind: "kubeconfig",
+    path: options?.path,
+    context: options?.context,
+  },
+  ...(options?.registry !== undefined ? { registry: options.registry } : {}),
+  ...(options?.architecture !== undefined ? { architecture: options.architecture } : {}),
+});