import {
ClusterAdapter,
ClusterNotFoundError,
type ClusterAdapterService,
type ClusterTransport,
type ImageRegistryResolveOptions,
type WorkloadIdentityReconcileOptions,
} from "@alchemy.run/kubernetes/ClusterAdapter";
import type { Connection } from "@alchemy.run/kubernetes/Connection";
import { Credentials } from "@distilled.cloud/aws/Credentials";
import * as ecr from "@distilled.cloud/aws/ecr";
import * as eks from "@distilled.cloud/aws/eks";
import { Region, type RegionName } from "@distilled.cloud/aws/Region";
import * as SigV4 from "@distilled.cloud/aws/SigV4";
import { createPhysicalName } from "alchemy/PhysicalName";
import { Self } from "alchemy/Self";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
import type { HttpClient } from "effect/http/HttpClient";
import * as Layer from "effect/Layer";
import * as Path from "effect/Path";
import * as Redacted from "effect/Redacted";
import { makeImageSource, type ImageSourceLike } from "../ECR/ImageSource.ts";
import { AWSEnvironment } from "../Environment.ts";
import type { PolicyStatement } from "../IAM/Policy.ts";
/**
* The `aws-eks` {@link ClusterAdapter}: everything platform-specific about
* running `Kubernetes.*` workloads on Amazon EKS.
*
* - **connect** — SigV4 bearer tokens (STS presign) against the cluster
* endpoint, re-describing the cluster when the connection doesn't carry
* endpoint/CA (or they've gone stale).
* - **identity** — EKS Pod Identity: a generated IAM role +
* `PodIdentityAssociation`, with `policyStatements` host bindings landed
* as the role's inline policy.
* - **registry** — a per-workload ECR repository; `main` programs are
* bundled, `context` Dockerfiles built, and `image` refs mirrored into
* it.
* - **bootstrap** — generated container entries wiring the AWS credential
* chain so Pod Identity's container-credentials endpoint resolves inside
* the pod.
* - **loadBalancerDefaults** — EKS Auto Mode's `loadBalancerClass` and the
* internet-facing NLB scheme.
*
* Registered by `AWS.providers()`; resolved dynamically by the
* `Kubernetes.*` providers via the connection's `auth.kind`.
*/
import {
attachPolicyStatements,
deleteAssociation,
deletePodRole,
ensureAssociation,
ensurePodRole,
} from "./internal/podIdentity.ts";
export class KubernetesAdapterNotReady extends Data.TaggedError("KubernetesAdapterNotReady")<{
readonly message: string;
readonly cause?: unknown;
}> {}
declare module "@alchemy.run/kubernetes/Connection" {
interface AuthRegistry {
/**
* Authenticate against an Amazon EKS cluster with SigV4 bearer tokens
* minted from the ambient AWS credentials. Contributed by
* `AWS.providers()` — `AWS.EKS.Cluster` attributes expose a ready-made
* `connection` carrying this descriptor.
*/
"aws-eks": {
/** The EKS cluster name. */
clusterName: string;
/**
* The cluster's region.
* @default the ambient AWS region
*/
region?: string;
};
}
}
declare module "@alchemy.run/kubernetes/ClusterAdapter" {
interface IdentityStateRegistry {
/** EKS Pod Identity: generated IAM role + association. */
"aws-pod-identity": {
/** The ARN of the IAM role pods assume via Pod Identity. */
roleArn: string;
/** The name of the IAM role pods assume via Pod Identity. */
roleName: string;
/** The ARN of the Pod Identity association binding the role. */
associationArn: string;
/** The ID of the Pod Identity association binding the role. */
associationId: string;
};
}
interface RegistryStateRegistry {
/** The per-workload ECR repository holding the image. */
"aws-ecr": {
/** The name of the ECR repository holding the image. */
repositoryName: string;
/** The URI of the ECR repository holding the image. */
repositoryUri: string;
};
}
interface WorkloadIdentityOptions {
/**
* Managed policy ARNs attached to the generated pod-identity role in
* addition to the inline policy synthesized from bindings (EKS only).
*/
managedPolicyArns?: string[];
}
interface WorkloadBindingContract {
/**
* IAM policy statements landed on the workload's pod-identity role
* (EKS only) — the same host-binding channel as `AWS.Lambda.Function`
* and `AWS.ECS.Task`.
*/
policyStatements?: PolicyStatement[];
}
interface WorkloadServicesRegistry {
/** AWS credential-chain services ambient inside EKS workload pods. */
aws: Credentials | Region | AWSEnvironment;
}
}
/** Services the adapter's methods close over at layer build. */
type EksAdapterDeps =
| Credentials
| HttpClient
| Region
| AWSEnvironment
| FileSystem.FileSystem
| Path.Path;
/** Mint an EKS SigV4 bearer token (STS `GetCallerIdentity` presign). */
const mintEksToken = Effect.fn(function* (clusterName: string, region: string) {
const credentials = yield* yield* Credentials;
const presigned = yield* SigV4.sign({
method: "GET",
url: `https://sts.${region}.amazonaws.com/?Action=GetCallerIdentity&Version=2011-06-15&X-Amz-Expires=60`,
headers: { "x-k8s-aws-id": clusterName },
accessKeyId: Redacted.value(credentials.accessKeyId),
secretAccessKey: credentials.secretAccessKey,
sessionToken: credentials.sessionToken,
service: "sts",
region,
signQuery: true,
allHeaders: true,
});
return `k8s-aws-v1.${Buffer.from(presigned.url).toString("base64url")}`;
});
/**
* Build a {@link ClusterTransport} for an EKS cluster from known
* endpoint/CA. Captures the ambient AWS services so the per-request token
* mint is self-contained — used by the adapter and by the
* `AWS.EKS.Cluster` provider's own kubernetes-object binding channel.
*/
export const makeEksTransport = Effect.fn(function* (options: {
clusterName: string;
region?: string | undefined;
endpoint: string;
certificateAuthorityData: string;
}) {
const context = yield* Effect.context<Credentials | AWSEnvironment>();
const region = options.region ?? (yield* AWSEnvironment.current).region;
return {
endpoint: options.endpoint,
certificateAuthorityData: options.certificateAuthorityData,
headers: mintEksToken(options.clusterName, region).pipe(
Effect.map((token) => ({ Authorization: `Bearer ${token}` })),
Effect.provideContext(context),
),
} satisfies ClusterTransport;
});
/**
* The `Kubernetes.Connection` of an EKS cluster — stamped on
* `AWS.EKS.Cluster` attributes so the cluster resource can be passed
* directly as any `Kubernetes.*` workload's `cluster`.
*/
export const eksConnectionOf = (options: {
clusterName: string;
region: string;
endpoint?: string | undefined;
certificateAuthorityData?: string | undefined;
}): Connection => ({
endpoint: options.endpoint,
certificateAuthorityData: options.certificateAuthorityData,
auth: {
kind: "aws-eks",
clusterName: options.clusterName,
region: options.region,
},
});
const narrowEksAuth = (connection: Connection) =>
connection.auth.kind === "aws-eks"
? Effect.succeed(connection.auth)
: Effect.die(new Error(`aws-eks adapter received auth kind '${connection.auth.kind}'`));
/**
* Provide a per-connection region override so a cluster in another region
* than the ambient one describes correctly.
*/
const withRegion =
(region: string | undefined) =>
<A, E, R>(self: Effect.Effect<A, E, R>) =>
region === undefined
? self
: Effect.provideService(self, Region, Effect.succeed(region as RegionName));
const createRoleName = (id: string) => createPhysicalName({ id: `${id}-pod-role`, maxLength: 64 });
const createPolicyName = (id: string) =>
createPhysicalName({ id: `${id}-pod-policy`, maxLength: 128 });
const createRepositoryName = (id: string) =>
createPhysicalName({
id: `${id}-repo`,
maxLength: 256,
lowercase: true,
});
/**
* Generated container entry for an Effect-native EKS server: resolves the
* program's registered runners and serves the returned `{ fetch }` handler
* on `PORT`. Credentials use the full chain so EKS Pod Identity's
* container-credentials endpoint resolves inside the pod.
*/
export const makeEksServerBootstrap =
(handler: string) =>
(importPath: string): string =>
`
import { BunServices } from "@effect/platform-bun";
import { BunHttpServer } from "alchemy/Http";
import { Stack } from "alchemy/Stack";
import { Stage } from "alchemy/Stage";
import { makeEntrypointLayer, reifyBoundConfigProvider } from "alchemy/Runtime";
import { provideProcessTelemetry } from "alchemy/Telemetry";
import * as Context from "effect/Context";
import * as Config from "effect/Config";
import * as ConfigProvider from "effect/ConfigProvider";
import * as Credentials from "@distilled.cloud/aws/Credentials";
import * as Effect from "effect/Effect";
import * as FetchHttpClient from "effect/http/FetchHttpClient";
import * as Layer from "effect/Layer";
import * as Logger from "effect/Logger";
import * as Region from "@distilled.cloud/aws/Region";
import { ${handler} as entrypoint } from ${JSON.stringify(importPath)};
// Normalize the entrypoint export: an inline-effect class default export is
// an Effect resolving the platform instance, while the tagged form
// (X.make(props, impl)) exports a Layer providing the Self tag. Both fold
// into a Layer via makeEntrypointLayer (same pattern as the ECS/Lambda/
// Cloudflare Container bridges).
const tag = Context.Service("${Self.key}");
const layer = makeEntrypointLayer(tag, entrypoint);
const platform = Layer.mergeAll(
BunServices.layer,
FetchHttpClient.layer,
Logger.layer([Logger.consolePretty()]),
);
// Resolve the bundled program (the runners registered via host.run / serve)
// and run it with a Bun HTTP server bound to PORT, so a returned { fetch }
// handler is served and host.run loops stay alive. Credentials use the full
// chain so EKS Pod Identity's container-credentials endpoint
// (AWS_CONTAINER_CREDENTIALS_FULL_URI + token file) resolves inside the pod.
const program = tag.pipe(
// Process-lifetime telemetry: built once into the root scope; exporters
// batch on their intervals and flush when the scope closes on graceful
// shutdown.
Effect.flatMap((host) =>
host.RuntimeContext.exports.pipe(
Effect.flatMap((exports) => exports.program),
provideProcessTelemetry(host.RuntimeContext),
),
),
Effect.provide(
layer.pipe(Layer.provideMerge(Layer.mergeAll(
Layer.effect(
Stack,
Effect.all([
Config.String("ALCHEMY_STACK_NAME"),
Config.String("ALCHEMY_STAGE")
]).pipe(
Effect.map(([name, stage]) => ({
name,
stage,
bindings: {},
resources: {}
}))
)
),
// Module-scope declarations shared with the Stack may read the stage.
Layer.effect(Stage, Config.String("ALCHEMY_STAGE")),
)),
Layer.provideMerge(Credentials.fromChain()),
Layer.provideMerge(Region.fromEnv()),
Layer.provideMerge(BunHttpServer()),
Layer.provideMerge(platform),
Layer.provideMerge(
Layer.succeed(
ConfigProvider.ConfigProvider,
reifyBoundConfigProvider(ConfigProvider.fromEnv(), process.env)
)
),
)
),
Effect.scoped
);
console.log(\`EKS Deployment bootstrap starting on port \${process.env.PORT ?? 3000}...\`);
await Effect.runPromise(program).catch((err) => {
console.error("EKS Deployment bootstrap failed:", err);
process.exit(1);
});
`;
/**
* Generated container entry for an Effect-native EKS Job: resolves the
* program's `run` effect, executes it to completion, and exits. No HTTP
* server is started. Credentials use the full chain so EKS Pod Identity's
* container-credentials endpoint resolves inside the pod.
*/
export const makeEksJobBootstrap =
(handler: string) =>
(importPath: string): string =>
`
import { BunServices } from "@effect/platform-bun";
import { Stack } from "alchemy/Stack";
import { Stage } from "alchemy/Stage";
import { makeEntrypointLayer, reifyBoundConfigProvider } from "alchemy/Runtime";
import { provideProcessTelemetry } from "alchemy/Telemetry";
import * as Context from "effect/Context";
import * as Config from "effect/Config";
import * as ConfigProvider from "effect/ConfigProvider";
import * as Credentials from "@distilled.cloud/aws/Credentials";
import * as Effect from "effect/Effect";
import * as FetchHttpClient from "effect/http/FetchHttpClient";
import * as Layer from "effect/Layer";
import * as Logger from "effect/Logger";
import * as Region from "@distilled.cloud/aws/Region";
import { ${handler} as entrypoint } from ${JSON.stringify(importPath)};
// Normalize the entrypoint export (see the server bootstrap).
const tag = Context.Service("${Self.key}");
const layer = makeEntrypointLayer(tag, entrypoint);
const platform = Layer.mergeAll(
BunServices.layer,
FetchHttpClient.layer,
Logger.layer([Logger.consolePretty()]),
);
// Resolve the bundled program's registered one-shot runners (the shape's
// \`run\` effect and any host.run work) and execute them to completion.
const program = tag.pipe(
// Process-lifetime telemetry: built once into the root scope; exporters
// batch on their intervals and flush when the scope closes as the
// one-shot program completes.
Effect.flatMap((host) =>
host.RuntimeContext.exports.pipe(
Effect.flatMap((exports) => exports.program),
provideProcessTelemetry(host.RuntimeContext),
),
),
Effect.provide(
layer.pipe(Layer.provideMerge(Layer.mergeAll(
Layer.effect(
Stack,
Effect.all([
Config.String("ALCHEMY_STACK_NAME"),
Config.String("ALCHEMY_STAGE")
]).pipe(
Effect.map(([name, stage]) => ({
name,
stage,
bindings: {},
resources: {}
}))
)
),
// Module-scope declarations shared with the Stack may read the stage.
Layer.effect(Stage, Config.String("ALCHEMY_STAGE")),
)),
Layer.provideMerge(Credentials.fromChain()),
Layer.provideMerge(Region.fromEnv()),
Layer.provideMerge(platform),
Layer.provideMerge(
Layer.succeed(
ConfigProvider.ConfigProvider,
reifyBoundConfigProvider(ConfigProvider.fromEnv(), process.env)
)
),
)
),
Effect.scoped
);
console.log("EKS Job bootstrap starting...");
await Effect.runPromise(program).catch((err) => {
console.error("EKS Job bootstrap failed:", err);
process.exit(1);
});
// Run-to-completion semantics: exit 0 explicitly so lingering handles
// (sockets, timers) never keep the pod alive after the work is done.
process.exit(0);
`;
/**
* The `aws-eks` cluster adapter layer. Provided (merged) by
* `AWS.providers()` so the `Kubernetes.*` workload providers can resolve
* it from the stack context.
*/
export const EksKubernetesAdapter = () =>
Layer.effect(
ClusterAdapter("aws-eks"),
Effect.gen(function* () {
const imageSource = yield* makeImageSource;
const context = yield* Effect.context<EksAdapterDeps>();
// Discharge the layer-captured AWS services; per-resource engine
// services (ResourceContext/Stack/Stage) stay ambient — they are provided
// by the invoking lifecycle operation, never captured here.
const withAws =
(region: string | undefined) =>
<A, E, R>(self: Effect.Effect<A, E, R>) =>
Effect.provideContext(withRegion(region)(self), context);
/**
* Describe the cluster. NotFound is gone. DELETING is gone only when
* the API endpoint is gone. A live endpoint still needs Service
* deletion so a load balancer finalizer can release the NLB. A missing
* CA with that endpoint is not "gone": connect fails and destroy retries.
*/
const describeLiveCluster = Effect.fn(function* (auth: {
clusterName: string;
region?: string | undefined;
}) {
const described = yield* eks.describeCluster({ name: auth.clusterName }).pipe(
Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
withAws(auth.region),
);
const cluster = described?.cluster;
const apiGone = cluster?.status === "DELETING" && !cluster.endpoint;
if (!cluster || apiGone) {
return yield* new ClusterNotFoundError({
message: `EKS cluster '${auth.clusterName}' no longer exists`,
});
}
return cluster;
});
const connect = Effect.fn(function* (connection: Connection) {
const auth = yield* narrowEksAuth(connection);
// Always describe. A persisted endpoint does not prove the cluster
// still exists, and delete uses ClusterNotFoundError to skip
// in-cluster objects and still remove the pod role and repository.
// Describe also picks up an endpoint rotation.
const cluster = yield* describeLiveCluster(auth);
const endpoint = cluster.endpoint;
const certificateAuthorityData = cluster.certificateAuthority?.data;
if (!endpoint || !certificateAuthorityData) {
return yield* new KubernetesAdapterNotReady({
message:
`EKS cluster '${auth.clusterName}' has no endpoint or ` +
"certificate authority data yet (still creating?)",
});
}
return yield* makeEksTransport({
clusterName: auth.clusterName,
region: auth.region,
endpoint,
certificateAuthorityData,
}).pipe(withAws(auth.region));
});
const identityReconcile = Effect.fn(function* (options: WorkloadIdentityReconcileOptions) {
const auth = yield* narrowEksAuth(options.connection);
return yield* Effect.gen(function* () {
const state = options.state;
const roleName =
typeof state?.roleName === "string"
? state.roleName
: yield* createRoleName(options.id);
const policyName = yield* createPolicyName(options.id);
// Ensure IAM role + inline policy from bindings.
const roleArn =
typeof state?.roleArn === "string"
? state.roleArn
: yield* ensurePodRole({
id: options.id,
roleName,
managedPolicyArns: options.options?.managedPolicyArns,
});
yield* attachPolicyStatements({
roleName,
policyName,
bindings: options.bindings,
});
// Ensure the pod identity association wires the role to the SA.
const { associationArn, associationId } = yield* ensureAssociation({
id: options.id,
clusterName: auth.clusterName,
namespace: options.namespace,
serviceAccount: options.serviceAccount,
roleArn,
});
// Unlike ECS/Fargate (whose agent injects `AWS_REGION`), EKS pods
// get no region env var — inject it so the bootstrap's
// `Region.fromEnv()` resolves inside the pod.
const { region } = yield* AWSEnvironment.current;
return {
env: {
AWS_REGION: auth.region ?? region,
},
state: {
kind: "aws-pod-identity" as const,
roleArn,
roleName,
associationArn,
associationId,
},
};
}).pipe(withAws(auth.region));
});
const identityDelete = Effect.fn(function* (options: {
connection: Connection | undefined;
state: Record<string, unknown> | undefined;
}) {
const state = options.state;
const auth =
options.connection !== undefined ? yield* narrowEksAuth(options.connection) : undefined;
yield* Effect.gen(function* () {
// The association is cluster-scoped: skip it when the cluster is
// gone or DELETING (it dies with the cluster; EKS also rejects
// the delete with `InvalidRequestException: Cluster is in
// invalid state` mid-teardown).
if (auth !== undefined && typeof state?.associationId === "string") {
const cluster = yield* describeLiveCluster(auth).pipe(
Effect.catchTag("Kubernetes.ClusterNotFoundError", () => Effect.undefined),
);
if (cluster) {
yield* deleteAssociation({
clusterName: auth.clusterName,
associationId: state.associationId,
}).pipe(Effect.catchTag("InvalidRequestException", () => Effect.void));
}
}
if (typeof state?.roleName === "string") {
yield* deletePodRole(state.roleName);
}
}).pipe(withAws(auth?.region));
});
const registryResolve = Effect.fn(function* (options: ImageRegistryResolveOptions) {
const state = options.state;
const repositoryName =
typeof state?.repositoryName === "string"
? state.repositoryName
: // Physical-name generation reads the resource's ambient
// ResourceContext/Stack/Stage — do not shadow them with the
// layer-captured context.
yield* createRepositoryName(options.id);
const repositoryUri =
typeof state?.repositoryUri === "string" && state.repositoryName === repositoryName
? state.repositoryUri
: undefined;
const resolved = yield* imageSource
.resolve({
id: options.id,
source: options.source as ImageSourceLike,
repositoryName,
repositoryUri,
tags: options.tags,
platform: options.platform,
port: options.port,
isExternal: options.isExternal,
bootstrap: options.bootstrap,
session: options.session,
})
.pipe(Effect.provideContext(context));
return {
imageUri: resolved.imageUri,
codeHash: resolved.codeHash,
state: {
kind: "aws-ecr" as const,
repositoryName: resolved.repositoryName,
repositoryUri: resolved.repositoryUri,
},
};
});
const registryHash = Effect.fn(function* (options: {
source: ImageSourceLike;
platform: string;
port?: number | undefined;
isExternal?: boolean | undefined;
bootstrap: (importPath: string) => string;
}) {
return yield* imageSource
.hash({
source: options.source,
platform: options.platform,
port: options.port,
isExternal: options.isExternal,
bootstrap: options.bootstrap,
})
.pipe(Effect.provideContext(context));
});
const registryDelete = Effect.fn(function* (options: {
state: Record<string, unknown> | undefined;
}) {
if (typeof options.state?.repositoryName !== "string") return;
yield* ecr
.deleteRepository({
repositoryName: options.state.repositoryName,
force: true,
})
.pipe(
Effect.catchTag("RepositoryNotFoundException", () => Effect.void),
Effect.provideContext(context),
);
});
const loadBalancerDefaults = Effect.fn(function* (options: { connection: Connection }) {
const auth = yield* narrowEksAuth(options.connection);
// EKS Auto Mode's built-in load balancer controller only
// reconciles `LoadBalancer` Services whose `spec.loadBalancerClass`
// is `eks.amazonaws.com/nlb` (there is no in-tree cloud provider on
// Auto Mode), and it defaults new NLBs to the *internal* scheme.
// Detect the Auto Mode LB capability from the live cluster and
// default to an internet-facing NLB so the returned `url` is
// actually reachable.
const cluster = yield* describeLiveCluster(auth).pipe(
Effect.catchTag("Kubernetes.ClusterNotFoundError", () => Effect.undefined),
);
return {
loadBalancerClass: cluster?.kubernetesNetworkConfig?.elasticLoadBalancing?.enabled
? "eks.amazonaws.com/nlb"
: undefined,
annotations: {
"service.beta.kubernetes.io/aws-load-balancer-scheme": "internet-facing",
},
};
});
return {
kind: "Kubernetes.ClusterAdapter" as const,
connect,
identity: {
reconcile: identityReconcile,
delete: identityDelete,
},
registry: {
resolve: registryResolve,
hash: registryHash,
delete: registryDelete,
},
bootstrap: {
server: makeEksServerBootstrap,
job: makeEksJobBootstrap,
},
loadBalancerDefaults,
} satisfies ClusterAdapterService;
}),
);