import * as eks from "@distilled.cloud/aws/eks";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import type { Input } from "alchemy/Input";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags, hasAlchemyTags } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
export class NodegroupOperationFailed extends Data.TaggedError("NodegroupOperationFailed")<{
readonly message: string;
readonly cause?: unknown;
}> {}
export class NodegroupUnexpectedResponse extends Data.TaggedError("NodegroupUnexpectedResponse")<{
readonly message: string;
readonly cause?: unknown;
}> {}
export interface NodegroupProps {
/**
* Name of the EKS cluster that owns this managed node group.
*/
clusterName: Input<string>;
/**
* Name of the managed node group. If omitted, a unique name is generated.
*/
nodegroupName?: string;
/**
* ARN of the IAM role that provides permissions for the node group's worker
* nodes (the `NodeInstanceRole`). Changing this replaces the node group.
*/
nodeRole: Input<string>;
/**
* Subnet IDs to launch worker nodes into. Changing this replaces the node
* group.
*/
subnets: Input<string>[];
/**
* EC2 instance types for the node group. Changing this replaces the node
* group.
* @default ["t3.medium"]
*/
instanceTypes?: string[];
/**
* Scaling configuration (min/max/desired node counts). Mutable — updated in
* place via `updateNodegroupConfig`.
*/
scalingConfig?: eks.NodegroupScalingConfig;
/**
* AMI type for the node group's nodes (e.g. `AL2023_x86_64_STANDARD`,
* `BOTTLEROCKET_x86_64`). Changing this replaces the node group.
*/
amiType?: eks.AMITypes;
/**
* Capacity type for the node group. Changing this replaces the node group.
* @default "ON_DEMAND"
*/
capacityType?: eks.CapacityTypes;
/**
* Root device disk size in GiB. Changing this replaces the node group.
*/
diskSize?: number;
/**
* Kubernetes labels applied to the nodes. Mutable — reconciled in place.
*/
labels?: Record<string, string>;
/**
* Kubernetes taints applied to the nodes. Mutable — reconciled in place.
*/
taints?: eks.Taint[];
/**
* Node group update configuration (`maxUnavailable` /
* `maxUnavailablePercentage`). Mutable — updated in place.
*/
updateConfig?: eks.NodegroupUpdateConfig;
/**
* Remote SSH access configuration. Changing this replaces the node group.
*/
remoteAccess?: eks.RemoteAccessConfig;
/**
* Kubernetes version for the node group. Mutable — upgraded in place via
* `updateNodegroupVersion`.
*/
version?: string;
/**
* AMI release version for the node group. Mutable — upgraded in place.
*/
releaseVersion?: string;
/**
* User-defined tags to apply to the node group.
*/
tags?: Record<string, string>;
}
export interface Nodegroup extends Resource<
"AWS.EKS.Nodegroup",
NodegroupProps,
{
/** The name of the node group. */
nodegroupName: string;
/** The ARN of the node group. */
nodegroupArn: string;
/** The name of the EKS cluster the node group belongs to. */
clusterName: string;
/** The node group status (e.g. `CREATING`, `ACTIVE`, `UPDATING`). */
status: eks.NodegroupStatus;
/** The capacity type (`ON_DEMAND`, `SPOT`, or `CAPACITY_BLOCK`). */
capacityType: eks.CapacityTypes | undefined;
/** The scaling configuration (min/max/desired size). */
scalingConfig: eks.NodegroupScalingConfig | undefined;
/** The EC2 instance types the node group launches. */
instanceTypes: string[];
/** The IDs of the subnets nodes are launched into. */
subnets: string[];
/** The AMI type of the nodes (e.g. `AL2023_x86_64_STANDARD`). */
amiType: eks.AMITypes | undefined;
/** The ARN of the IAM role attached to the nodes. */
nodeRole: string;
/** The Kubernetes labels applied to nodes in the group. */
labels: Record<string, string>;
/** The Kubernetes taints applied to nodes in the group. */
taints: eks.Taint[];
/** The root device disk size in GiB, when not using a launch template. */
diskSize: number | undefined;
/** The Kubernetes version of the node group. */
version: string | undefined;
/** The AMI release version of the node group. */
releaseVersion: string | undefined;
/** The rolling-update configuration (max unavailable). */
updateConfig: eks.NodegroupUpdateConfig | undefined;
/** The tags applied to the node group. */
tags: Record<string, string>;
},
never,
Providers
> {}
/**
* An Amazon EKS managed node group — an EC2 Auto Scaling group of worker nodes
* managed by EKS for a cluster.
*
* Managed node groups provide the compute capacity a non-Auto-Mode EKS cluster
* needs to run pods. Creation is asynchronous (`CREATING` → `ACTIVE`, ~2–5 min)
* and the provider waits for the group to become `ACTIVE` before returning.
* Scaling, labels, taints, update config, and version are mutable in place;
* subnets, instance types, AMI type, disk size, node role, capacity type, and
* remote access are immutable and force a replacement.
* ### Creating Node Groups
* **Example:** Managed Node Group
* ```typescript
* const nodes = yield* Nodegroup("AppNodes", {
* clusterName: cluster.clusterName,
* nodeRole: nodeRole.roleArn,
* subnets: network.privateSubnetIds,
* instanceTypes: ["t3.medium"],
* scalingConfig: { minSize: 1, maxSize: 3, desiredSize: 2 },
* });
* ```
*
* **Example:** Spot Node Group with Labels and Taints
* ```typescript
* const spot = yield* Nodegroup("SpotNodes", {
* clusterName: cluster.clusterName,
* nodeRole: nodeRole.roleArn,
* subnets: network.privateSubnetIds,
* capacityType: "SPOT",
* instanceTypes: ["t3.large", "t3a.large"],
* scalingConfig: { minSize: 0, maxSize: 5, desiredSize: 1 },
* labels: { workload: "batch" },
* taints: [{ key: "spot", value: "true", effect: "NO_SCHEDULE" }],
* });
* ```
*
* @resource
*/
export const Nodegroup = Resource<Nodegroup>("AWS.EKS.Nodegroup");
class NodegroupNotReady extends Data.TaggedError("EKS.NodegroupNotReady")<{
status: eks.NodegroupStatus | undefined;
}> {}
class NodegroupStillExists extends Data.TaggedError("EKS.NodegroupStillExists")<{}> {}
class NodegroupUpdateNotComplete extends Data.TaggedError("EKS.NodegroupUpdateNotComplete")<{
status: eks.UpdateStatus | undefined;
}> {}
const normalizeTags = (tags: Record<string, string | undefined> | undefined) =>
Object.fromEntries(
Object.entries(tags ?? {}).filter((entry): entry is [string, string] => entry[1] !== undefined),
);
const normalizeLabels = (labels: Record<string, string | undefined> | undefined) =>
Object.fromEntries(
Object.entries(labels ?? {}).filter(
(entry): entry is [string, string] => entry[1] !== undefined,
),
);
// Wait budget: ~10 min at 5s spacing — node groups reach ACTIVE in 2–5 min.
const waitSchedule = Schedule.max([Schedule.spaced("5 seconds"), Schedule.recurs(120)]);
const taintKey = (taint: eks.Taint) => `${taint.key ?? ""}::${taint.effect ?? ""}`;
/**
* Compute the `UpdateLabelsPayload` delta between observed and desired labels.
* Returns `undefined` when there is nothing to change.
*/
const diffLabels = (
observed: Record<string, string>,
desired: Record<string, string>,
): eks.UpdateLabelsPayload | undefined => {
const addOrUpdateLabels: Record<string, string> = {};
for (const [key, value] of Object.entries(desired)) {
if (observed[key] !== value) {
addOrUpdateLabels[key] = value;
}
}
const removeLabels = Object.keys(observed).filter((key) => !(key in desired));
if (Object.keys(addOrUpdateLabels).length === 0 && removeLabels.length === 0) {
return undefined;
}
return {
addOrUpdateLabels: Object.keys(addOrUpdateLabels).length > 0 ? addOrUpdateLabels : undefined,
removeLabels: removeLabels.length > 0 ? removeLabels : undefined,
};
};
/**
* Compute the `UpdateTaintsPayload` delta between observed and desired taints,
* keyed by (key, effect). Returns `undefined` when there is nothing to change.
*/
const diffTaints = (
observed: eks.Taint[],
desired: eks.Taint[],
): eks.UpdateTaintsPayload | undefined => {
const observedByKey = new Map(observed.map((t) => [taintKey(t), t]));
const desiredByKey = new Map(desired.map((t) => [taintKey(t), t]));
const addOrUpdateTaints = desired.filter((t) => {
const existing = observedByKey.get(taintKey(t));
return !existing || existing.value !== t.value;
});
const removeTaints = observed.filter((t) => !desiredByKey.has(taintKey(t)));
if (addOrUpdateTaints.length === 0 && removeTaints.length === 0) {
return undefined;
}
return {
addOrUpdateTaints: addOrUpdateTaints.length > 0 ? addOrUpdateTaints : undefined,
removeTaints: removeTaints.length > 0 ? removeTaints : undefined,
};
};
const scalingConfigChanged = (
observed: eks.NodegroupScalingConfig | undefined,
desired: eks.NodegroupScalingConfig | undefined,
) => {
if (!desired) return false;
return (
observed?.minSize !== desired.minSize ||
observed?.maxSize !== desired.maxSize ||
observed?.desiredSize !== desired.desiredSize
);
};
const updateConfigChanged = (
observed: eks.NodegroupUpdateConfig | undefined,
desired: eks.NodegroupUpdateConfig | undefined,
) => {
if (!desired) return false;
return (
observed?.maxUnavailable !== desired.maxUnavailable ||
observed?.maxUnavailablePercentage !== desired.maxUnavailablePercentage ||
observed?.updateStrategy !== desired.updateStrategy
);
};
const mapNodegroup = (
nodegroup: eks.Nodegroup,
tags: Record<string, string>,
): Nodegroup["Attributes"] => ({
nodegroupName: nodegroup.nodegroupName!,
nodegroupArn: nodegroup.nodegroupArn!,
clusterName: nodegroup.clusterName!,
status: nodegroup.status ?? "CREATING",
capacityType: nodegroup.capacityType,
scalingConfig: nodegroup.scalingConfig,
instanceTypes: nodegroup.instanceTypes ?? [],
subnets: nodegroup.subnets ?? [],
amiType: nodegroup.amiType,
nodeRole: nodegroup.nodeRole!,
labels: normalizeLabels(nodegroup.labels),
taints: nodegroup.taints ?? [],
diskSize: nodegroup.diskSize,
version: nodegroup.version,
releaseVersion: nodegroup.releaseVersion,
updateConfig: nodegroup.updateConfig,
tags,
});
export const NodegroupProvider = () =>
Provider.effect(
Nodegroup,
Effect.gen(function* () {
const toNodegroupName = (id: string, props: { nodegroupName?: string } = {}) =>
props.nodegroupName
? Effect.succeed(props.nodegroupName)
: createPhysicalName({ id, maxLength: 63 });
const toClientRequestToken = (id: string, action: string) =>
createPhysicalName({
id: `${id}-${action}`,
maxLength: 64,
delimiter: "-",
});
const readNodegroup = Effect.fn(function* ({
clusterName,
nodegroupName,
}: {
clusterName: string;
nodegroupName: string;
}) {
const described = yield* eks
.describeNodegroup({ clusterName, nodegroupName })
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
const nodegroup = described?.nodegroup;
if (
!nodegroup?.nodegroupArn ||
!nodegroup.nodegroupName ||
!nodegroup.clusterName ||
!nodegroup.nodeRole
) {
return undefined;
}
return mapNodegroup(nodegroup, normalizeTags(nodegroup.tags));
});
const waitForNodegroupActive = (clusterName: string, nodegroupName: string) =>
readNodegroup({ clusterName, nodegroupName }).pipe(
Effect.flatMap(
Effect.fnUntraced(function* (state) {
if (!state) {
return yield* new NodegroupNotReady({ status: undefined });
}
if (state.status === "ACTIVE") {
return state;
}
if (state.status === "CREATE_FAILED" || state.status === "DELETE_FAILED") {
return yield* new NodegroupOperationFailed({
message: `EKS node group '${nodegroupName}' entered ${state.status}`,
});
}
return yield* new NodegroupNotReady({ status: state.status });
}),
),
Effect.retry({
while: (error) => error instanceof NodegroupNotReady,
schedule: waitSchedule,
}),
);
const waitForNodegroupDeleted = (clusterName: string, nodegroupName: string) =>
readNodegroup({ clusterName, nodegroupName }).pipe(
Effect.flatMap((state) =>
state ? Effect.fail(new NodegroupStillExists()) : Effect.undefined,
),
Effect.retry({
while: (error) => error instanceof NodegroupStillExists,
schedule: waitSchedule,
}),
);
const waitForUpdate = (clusterName: string, nodegroupName: string, updateId: string) =>
eks.describeUpdate({ name: clusterName, nodegroupName, updateId }).pipe(
Effect.flatMap(
Effect.fnUntraced(function* ({ update }) {
if (update?.status === "Successful") {
return update;
}
if (update?.status === "Failed" || update?.status === "Cancelled") {
return yield* new NodegroupOperationFailed({
message: `EKS node group update '${updateId}' failed with status '${update?.status}'`,
});
}
return yield* new NodegroupUpdateNotComplete({ status: update?.status });
}),
),
Effect.retry({
while: (error) => error instanceof NodegroupUpdateNotComplete,
schedule: waitSchedule,
}),
);
return {
stables: ["nodegroupArn", "nodegroupName", "clusterName"],
// Enumerate every node group across the account/region. `listNodegroups`
// is cluster-scoped, so first enumerate all clusters, list each
// cluster's node groups, then hydrate each via `describeNodegroup`.
list: () =>
Effect.gen(function* () {
const clusterNames = yield* eks.listClusters.pages({}).pipe(
Stream.runCollect,
Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.clusters ?? [])),
);
const perCluster = yield* Effect.forEach(
clusterNames,
(clusterName) =>
eks.listNodegroups.pages({ clusterName }).pipe(
Stream.runCollect,
Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.nodegroups ?? [])),
Effect.flatMap((names) =>
Effect.forEach(
names,
(nodegroupName) => readNodegroup({ clusterName, nodegroupName }),
{ concurrency: 5 },
),
),
),
{ concurrency: 5 },
);
return perCluster
.flat()
.filter((state): state is Nodegroup["Attributes"] => state !== undefined);
}),
diff: Effect.fn(function* ({ id, olds = {} as NodegroupProps, news }) {
if (!isResolved(news)) return;
if ((yield* toNodegroupName(id, olds)) !== (yield* toNodegroupName(id, news ?? {}))) {
return { action: "replace" } as const;
}
if (olds.clusterName !== news.clusterName) {
return { action: "replace" } as const;
}
if (olds.nodeRole !== news.nodeRole) {
return { action: "replace" } as const;
}
if (JSON.stringify(olds.subnets ?? []) !== JSON.stringify(news.subnets ?? [])) {
return { action: "replace" } as const;
}
if (
JSON.stringify(olds.instanceTypes ?? []) !== JSON.stringify(news.instanceTypes ?? [])
) {
return { action: "replace" } as const;
}
if ((olds.amiType ?? undefined) !== (news.amiType ?? undefined)) {
return { action: "replace" } as const;
}
if ((olds.diskSize ?? undefined) !== (news.diskSize ?? undefined)) {
return { action: "replace" } as const;
}
if ((olds.capacityType ?? "ON_DEMAND") !== (news.capacityType ?? "ON_DEMAND")) {
return { action: "replace" } as const;
}
if (
JSON.stringify(olds.remoteAccess ?? undefined) !==
JSON.stringify(news.remoteAccess ?? undefined)
) {
return { action: "replace" } as const;
}
}),
read: Effect.fn(function* ({ id, olds, output }) {
const clusterName = (output?.clusterName ?? (olds?.clusterName as string | undefined)) as
| string
| undefined;
if (!clusterName) return undefined;
const nodegroupName = output?.nodegroupName ?? (yield* toNodegroupName(id, olds ?? {}));
const state = yield* readNodegroup({ clusterName, nodegroupName });
if (!state) return undefined;
return (yield* hasAlchemyTags(id, state.tags)) ? state : Unowned(state);
}),
reconcile: Effect.fn(function* ({ id, news, session }) {
const clusterName = news.clusterName as string;
const nodegroupName = yield* toNodegroupName(id, news);
const desiredTags = {
...(yield* createInternalTags(id)),
...news.tags,
};
// Observe — cloud state is authoritative.
let state = yield* readNodegroup({ clusterName, nodegroupName });
// Ensure — create if missing; tolerate a create race, then wait for
// the node group to reach ACTIVE before syncing.
if (!state) {
yield* eks
.createNodegroup({
clusterName,
nodegroupName,
nodeRole: news.nodeRole as string,
subnets: news.subnets as string[],
instanceTypes: news.instanceTypes,
scalingConfig: news.scalingConfig,
amiType: news.amiType,
capacityType: news.capacityType,
diskSize: news.diskSize,
labels: news.labels,
taints: news.taints,
updateConfig: news.updateConfig,
remoteAccess: news.remoteAccess,
version: news.version,
releaseVersion: news.releaseVersion,
tags: desiredTags,
clientRequestToken: yield* toClientRequestToken(id, "create"),
})
.pipe(Effect.catchTag("ResourceInUseException", () => Effect.void));
yield* session.note(`Creating EKS node group ${nodegroupName}...`);
state = yield* waitForNodegroupActive(clusterName, nodegroupName);
}
// Sync mutable config (scaling, updateConfig, labels, taints) in a
// single updateNodegroupConfig call when anything changed.
const desiredLabels = normalizeLabels(news.labels);
const labelsDelta = diffLabels(state.labels, desiredLabels);
const taintsDelta = diffTaints(state.taints, news.taints ?? []);
const scalingChanged = scalingConfigChanged(state.scalingConfig, news.scalingConfig);
const updateCfgChanged = updateConfigChanged(state.updateConfig, news.updateConfig);
if (labelsDelta || taintsDelta || scalingChanged || updateCfgChanged) {
const configUpdate = yield* eks.updateNodegroupConfig({
clusterName,
nodegroupName,
scalingConfig: scalingChanged ? news.scalingConfig : undefined,
updateConfig: updateCfgChanged ? news.updateConfig : undefined,
labels: labelsDelta,
taints: taintsDelta,
clientRequestToken: yield* toClientRequestToken(id, "config"),
});
if (configUpdate.update?.id) {
yield* session.note(`Updating EKS node group config ${nodegroupName}...`);
yield* waitForUpdate(clusterName, nodegroupName, configUpdate.update.id);
state = (yield* waitForNodegroupActive(clusterName, nodegroupName)) ?? state;
}
}
// Sync version / release version via updateNodegroupVersion.
if (
(news.version && state.version !== news.version) ||
(news.releaseVersion && state.releaseVersion !== news.releaseVersion)
) {
const versionUpdate = yield* eks.updateNodegroupVersion({
clusterName,
nodegroupName,
version: news.version,
releaseVersion: news.releaseVersion,
clientRequestToken: yield* toClientRequestToken(id, "version"),
});
if (versionUpdate.update?.id) {
yield* session.note(`Updating EKS node group version ${nodegroupName}...`);
yield* waitForUpdate(clusterName, nodegroupName, versionUpdate.update.id);
state = (yield* waitForNodegroupActive(clusterName, nodegroupName)) ?? state;
}
}
// Sync tags — diff observed cloud tags against desired.
const { removed, upsert } = diffTags(state.tags, desiredTags);
if (upsert.length > 0) {
yield* eks.tagResource({
resourceArn: state.nodegroupArn,
tags: Object.fromEntries(upsert.map((tag) => [tag.Key, tag.Value] as const)),
});
}
if (removed.length > 0) {
yield* eks.untagResource({
resourceArn: state.nodegroupArn,
tagKeys: removed,
});
}
yield* session.note(state.nodegroupArn);
const final = yield* readNodegroup({ clusterName, nodegroupName });
if (!final) {
return yield* new NodegroupUnexpectedResponse({
message: `EKS node group '${nodegroupName}' could not be read after reconcile`,
});
}
return final;
}),
delete: Effect.fn(function* ({ output }) {
yield* eks
.deleteNodegroup({
clusterName: output.clusterName,
nodegroupName: output.nodegroupName,
})
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
yield* waitForNodegroupDeleted(output.clusterName, output.nodegroupName);
}),
};
}),
);