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 } : {}),
});