import * as eks from "@distilled.cloud/aws/eks";
import { Unowned } from "alchemy/AdoptPolicy";
import { deepEqual, 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 AddonOperationFailed extends Data.TaggedError("AddonOperationFailed")<{
readonly message: string;
readonly cause?: unknown;
}> {}
export interface AddonProps {
/**
* Target cluster name.
*/
clusterName: Input<string>;
/**
* Add-on name, such as `metrics-server`.
*/
addonName: string;
/**
* Optional add-on version. If omitted, EKS chooses the default compatible version.
*/
addonVersion?: string;
/**
* IAM role ARN used by the add-on's service account.
*/
serviceAccountRoleArn?: Input<string>;
/**
* Conflict resolution strategy used during create and update.
*/
resolveConflicts?: eks.ResolveConflicts;
/**
* Optional add-on configuration JSON string.
*/
configurationValues?: string;
/**
* Optional pod identity associations managed by the add-on.
*/
podIdentityAssociations?: eks.AddonPodIdentityAssociations[];
/**
* Optional namespace override. Changing this requires replacement.
*/
namespaceConfig?: eks.AddonNamespaceConfigRequest;
/**
* Preserve the add-on installation when the Alchemy resource is deleted.
*/
preserveOnDelete?: boolean;
/**
* User-defined tags to apply to the add-on.
*/
tags?: Record<string, string>;
}
export interface Addon extends Resource<
"AWS.EKS.Addon",
AddonProps,
{
/** The ARN of the add-on. */
addonArn: string;
/** The name of the add-on (e.g. `vpc-cni`, `coredns`). */
addonName: string;
/** The name of the EKS cluster the add-on is installed on. */
clusterName: string;
/** The add-on status (e.g. `ACTIVE`, `DEGRADED`). */
status: eks.AddonStatus;
/** The installed version of the add-on. */
addonVersion: string | undefined;
/** The IAM role ARN bound to the add-on's service account, if any. */
serviceAccountRoleArn: string | undefined;
/** The add-on's configuration values (JSON or YAML). */
configurationValues: string | undefined;
/** The ARNs of the pod identity associations owned by the add-on. */
podIdentityAssociations: string[];
/** The Kubernetes namespace the add-on is installed in. */
namespace: string | undefined;
/** The publisher of the add-on. */
publisher: string | undefined;
/** The owner of the add-on. */
owner: string | undefined;
/** The tags applied to the add-on. */
tags: Record<string, string>;
/** Health issues currently reported for the add-on. */
healthIssues: eks.AddonIssue[];
},
never,
Providers
> {}
/**
* An Amazon EKS managed add-on installed on a cluster.
*
* `Addon` is intended for optional managed add-ons. On Auto Mode clusters, many
* core components are already provided by AWS and do not need to be modeled as
* explicit add-on resources.
* ### Managing Add-ons
* **Example:** Install Metrics Server
* ```typescript
* const metricsServer = yield* Addon("MetricsServer", {
* clusterName: cluster.clusterName,
* addonName: "metrics-server",
* });
* ```
*
* @resource
*/
export const Addon = Resource<Addon>("AWS.EKS.Addon");
const normalizeTags = (tags: Record<string, string | undefined> | undefined) =>
Object.fromEntries(
Object.entries(tags ?? {}).filter((entry): entry is [string, string] => entry[1] !== undefined),
);
const mapAddon = (addon: eks.Addon) => ({
addonArn: addon.addonArn!,
addonName: addon.addonName!,
clusterName: addon.clusterName!,
status: addon.status ?? "CREATING",
addonVersion: addon.addonVersion,
serviceAccountRoleArn: addon.serviceAccountRoleArn,
configurationValues: addon.configurationValues,
podIdentityAssociations: addon.podIdentityAssociations ?? [],
namespace: addon.namespaceConfig?.namespace,
publisher: addon.publisher,
owner: addon.owner,
tags: normalizeTags(addon.tags),
healthIssues: addon.health?.issues ?? [],
});
const readAddon = Effect.fn(function* ({
clusterName,
addonName,
}: {
clusterName: string;
addonName: string;
}) {
const response = yield* eks
.describeAddon({
clusterName,
addonName,
})
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
const addon = response?.addon;
if (!addon?.addonArn || !addon.addonName || !addon.clusterName) {
return undefined;
}
return mapAddon(addon);
});
class AddonNotReady extends Data.TaggedError("AddonNotReady")<{
readonly clusterName: string;
readonly addonName: string;
readonly status: string | undefined;
}> {
override get message(): string {
return `addon '${this.clusterName}/${this.addonName}' is not ACTIVE (status: ${this.status ?? "absent"})`;
}
}
class AddonStillExists extends Data.TaggedError("AddonStillExists")<{
readonly clusterName: string;
readonly addonName: string;
}> {}
export const AddonProvider = () =>
Provider.effect(
Addon,
Effect.gen(function* () {
const toClientRequestToken = (id: string, action: string) =>
createPhysicalName({
id: `${id}-${action}`,
maxLength: 64,
delimiter: "-",
});
return {
stables: ["addonArn"],
// Add-ons are keyed by (clusterName, addonName) and `listAddons`
// requires a cluster. Enumerate every cluster, list its add-ons,
// then hydrate each via `describeAddon` to produce full Attributes.
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.listAddons.pages({ clusterName }).pipe(
Stream.runCollect,
Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.addons ?? [])),
Effect.flatMap((addonNames) =>
Effect.forEach(
addonNames,
(addonName) => readAddon({ clusterName, addonName }),
{ concurrency: 5 },
),
),
),
{ concurrency: 5 },
);
return perCluster
.flat()
.filter((addon): addon is NonNullable<typeof addon> => addon !== undefined);
}),
diff: Effect.fn(function* ({ olds, news }) {
if (!isResolved(news)) return;
if (olds.clusterName !== news.clusterName) {
return { action: "replace" } as const;
}
if (olds.addonName !== news.addonName) {
return { action: "replace" } as const;
}
if (!deepEqual(olds.namespaceConfig, news.namespaceConfig)) {
return { action: "replace" } as const;
}
}),
read: Effect.fn(function* ({ id, olds }) {
const clusterName = olds.clusterName as string | undefined;
// A crashed prior run can persist a row before its unresolved
// inputs were stripped — nothing observable yet.
if (clusterName === undefined || olds.addonName === undefined) {
return undefined;
}
const state = yield* readAddon({
clusterName,
addonName: olds.addonName,
});
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 addonName = news.addonName;
const desiredTags = {
...(yield* createInternalTags(id)),
...news.tags,
};
// Observe — fetch live cloud state by (clusterName, addonName).
let state = yield* readAddon({
clusterName,
addonName,
});
// Ensure — create if missing. Tolerate `ResourceInUseException`
// as a race with a peer reconciler: re-read and continue with
// sync.
if (!state) {
yield* eks
.createAddon({
clusterName,
addonName,
addonVersion: news.addonVersion,
serviceAccountRoleArn: news.serviceAccountRoleArn as string | undefined,
resolveConflicts: news.resolveConflicts,
configurationValues: news.configurationValues,
podIdentityAssociations: news.podIdentityAssociations,
namespaceConfig: news.namespaceConfig,
tags: desiredTags,
clientRequestToken: yield* toClientRequestToken(id, "create"),
})
.pipe(Effect.catchTag("ResourceInUseException", () => Effect.void));
state = yield* waitForAddonActive({
clusterName,
addonName,
});
}
// Sync addon version / config — diff observed against desired.
// updateAddon handles version, role, resolve conflicts, config
// values, and pod identity associations atomically.
const podIdentityChanged =
JSON.stringify(state.podIdentityAssociations ?? []) !==
JSON.stringify(news.podIdentityAssociations ?? []);
if (
(news.addonVersion !== undefined && state.addonVersion !== news.addonVersion) ||
state.serviceAccountRoleArn !== (news.serviceAccountRoleArn as string | undefined) ||
state.configurationValues !== news.configurationValues ||
podIdentityChanged
) {
yield* eks.updateAddon({
clusterName,
addonName,
addonVersion: news.addonVersion,
serviceAccountRoleArn: news.serviceAccountRoleArn as string | undefined,
resolveConflicts: news.resolveConflicts,
configurationValues: news.configurationValues,
podIdentityAssociations: news.podIdentityAssociations,
clientRequestToken: yield* toClientRequestToken(id, "update"),
});
state = yield* waitForAddonActive({
clusterName,
addonName,
});
}
// Sync tags — diff observed cloud tags against desired.
const { removed, upsert } = diffTags(state.tags, desiredTags);
if (upsert.length > 0) {
yield* eks.tagResource({
resourceArn: state.addonArn,
tags: Object.fromEntries(upsert.map((tag) => [tag.Key, tag.Value] as const)),
});
}
if (removed.length > 0) {
yield* eks.untagResource({
resourceArn: state.addonArn,
tagKeys: removed,
});
}
yield* session.note(state.addonArn);
return state;
}),
delete: Effect.fn(function* ({ olds, output }) {
yield* eks
.deleteAddon({
clusterName: output.clusterName,
addonName: output.addonName,
preserve: olds.preserveOnDelete,
})
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
if (!olds.preserveOnDelete) {
yield* waitForAddonDeleted({
clusterName: output.clusterName,
addonName: output.addonName,
});
}
}),
};
}),
);
const waitForAddonActive = Effect.fn(function* ({
clusterName,
addonName,
}: {
clusterName: string;
addonName: string;
}) {
return yield* readAddon({
clusterName,
addonName,
}).pipe(
Effect.flatMap(
Effect.fnUntraced(function* (addon) {
if (!addon) {
return yield* new AddonNotReady({
clusterName,
addonName,
status: undefined,
});
}
switch (addon.status) {
case "ACTIVE":
return addon;
case "CREATE_FAILED":
case "UPDATE_FAILED":
case "DELETE_FAILED":
return yield* new AddonOperationFailed({
message: `Addon '${clusterName}/${addonName}' entered terminal status '${addon.status}'`,
});
default:
return yield* new AddonNotReady({
clusterName,
addonName,
status: addon.status,
});
}
}),
),
Effect.retry({
while: (error) => error instanceof AddonNotReady,
// Flat 5s polls, ~20 min budget (uncapped exponential sleeps for
// multi-minute stretches late in the wait — looks like a deadlock).
// Node-bound addons (e.g. HyperPod task governance) stay DEGRADED
// until nodes join and pull images, which can take most of the
// budget when the addon installs alongside its node group.
schedule: Schedule.max([Schedule.spaced("5 seconds"), Schedule.recurs(240)]),
}),
);
});
const waitForAddonDeleted = Effect.fn(function* ({
clusterName,
addonName,
}: {
clusterName: string;
addonName: string;
}) {
yield* readAddon({
clusterName,
addonName,
}).pipe(
Effect.flatMap((addon) =>
addon ? Effect.fail(new AddonStillExists({ clusterName, addonName })) : Effect.void,
),
Effect.retry({
while: (error) => error instanceof AddonStillExists,
// Flat 5s polls, ~10 min budget (uncapped exponential sleeps for
// multi-minute stretches late in the wait — looks like a deadlock).
schedule: Schedule.max([Schedule.spaced("5 seconds"), Schedule.recurs(120)]),
}),
);
});