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())`.",
),
),
}),
),
);