sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ EKS/ Cluster.ts

import { deleteObjects, reconcileObjects } from "@alchemy.run/kubernetes/Client";
import type { Connection } from "@alchemy.run/kubernetes/Connection";
import {
  type KubernetesObjectBinding,
  type KubernetesObjectDefinition,
  type KubernetesObjectRef,
} from "@alchemy.run/kubernetes/Objects";
import * as eks from "@distilled.cloud/aws/eks";
import * as iam from "@distilled.cloud/aws/iam";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource, type ResourceBinding } from "alchemy/Resource";
import { createInternalTags, diffTags, hasAlchemyTags, hasTags } 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 { AccountID } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
import type { RegionID } from "../Region.ts";
import { eksConnectionOf, makeEksTransport } from "./KubernetesAdapter.ts";

export class EKSClusterUnexpectedResponse extends Data.TaggedError("EKSClusterUnexpectedResponse")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

export class EKSClusterInvalidProps extends Data.TaggedError("EKSClusterInvalidProps")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

export class EKSClusterConflict extends Data.TaggedError("EKSClusterConflict")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

export class EKSClusterOperationFailed extends Data.TaggedError("EKSClusterOperationFailed")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

export type ClusterName = string;
export type ClusterArn = `arn:aws:eks:${RegionID}:${AccountID}:cluster/${ClusterName}`;

export interface ClusterProps {
  /**
   * Cluster name. If omitted, a unique name is generated.
   */
  clusterName?: string;
  /**
   * `"auto"` turns on EKS Auto Mode with sensible defaults: managed compute
   * (`system` + `general-purpose` node pools), block storage, elastic load
   * balancing, and `API` authentication with bootstrap admin permissions.
   * When `roleArn` (or `computeConfig.nodeRoleArn`) is omitted, the cluster
   * provisions and owns the required IAM roles with the standard Auto Mode
   * managed policies. Explicit `accessConfig` / `computeConfig` /
   * `storageConfig` / `kubernetesNetworkConfig` props override the defaults.
   */
  compute?: "auto";
  /**
   * IAM role ARN assumed by the EKS control plane. Required unless
   * `compute: "auto"`, in which case an Auto Mode cluster role is created
   * and managed automatically when omitted.
   */
  roleArn?: string;
  /**
   * VPC configuration for the cluster control plane.
   */
  resourcesVpcConfig: eks.VpcConfigRequest;
  /**
   * Desired Kubernetes version.
   */
  version?: string;
  /**
   * Cluster access configuration.
   */
  accessConfig?: eks.CreateAccessConfigRequest;
  /**
   * Auto Mode compute configuration.
   */
  computeConfig?: eks.ComputeConfigRequest;
  /**
   * Auto Mode storage configuration.
   */
  storageConfig?: eks.StorageConfigRequest;
  /**
   * Kubernetes network configuration.
   */
  kubernetesNetworkConfig?: eks.KubernetesNetworkConfigRequest;
  /**
   * Control plane logging configuration.
   */
  logging?: eks.Logging;
  /**
   * Upgrade support policy for the cluster.
   */
  upgradePolicy?: eks.UpgradePolicyRequest;
  /**
   * Whether deletion protection is enabled.
   * @default false
   */
  deletionProtection?: boolean;
  /**
   * User-defined tags to apply to the cluster.
   */
  tags?: Record<string, string>;
}

export interface Cluster extends Resource<
  "AWS.EKS.Cluster",
  ClusterProps,
  {
    /** The ARN of the cluster. */
    clusterArn: ClusterArn;
    /** The name of the cluster. */
    clusterName: ClusterName;
    /** The cluster status (e.g. `CREATING`, `ACTIVE`, `UPDATING`). */
    status: string;
    /** The Kubernetes API server endpoint URL. */
    endpoint: string | undefined;
    /** The base64-encoded certificate authority data for the cluster. */
    certificateAuthorityData: string | undefined;
    /** The Kubernetes version the cluster is running (e.g. `1.31`). */
    version: string | undefined;
    /** The EKS platform version of the cluster. */
    platformVersion: string | undefined;
    /** The ARN of the IAM role the EKS control plane assumes. */
    roleArn: string;
    /** The VPC configuration of the cluster (subnets, security groups, endpoint access). */
    resourcesVpcConfig: eks.VpcConfigResponse;
    /** The access configuration (authentication mode, bootstrap admin). */
    accessConfig: eks.AccessConfigResponse | undefined;
    /** The EKS Auto Mode compute configuration, if enabled. */
    computeConfig: eks.ComputeConfigResponse | undefined;
    /** The EKS Auto Mode block storage configuration, if enabled. */
    storageConfig: eks.StorageConfigResponse | undefined;
    /** The Kubernetes network configuration (service CIDR, IP family, elastic load balancing). */
    kubernetesNetworkConfig: eks.KubernetesNetworkConfigResponse | undefined;
    /** The control-plane log types shipped to CloudWatch. */
    logging: eks.Logging | undefined;
    /** The cluster's upgrade policy (support type). */
    upgradePolicy: eks.UpgradePolicyResponse | undefined;
    /** Whether deletion protection is enabled on the cluster. */
    deletionProtection: boolean;
    /** The OIDC identity provider issuer URL for the cluster. */
    oidcIssuer: string | undefined;
    /** The tags applied to the cluster. */
    tags: Record<string, string>;
    /** References to Kubernetes objects applied via `kubernetes` props. */
    kubernetesObjects: KubernetesObjectRef[];
    /**
     * The cluster-agnostic `Kubernetes.Connection` for this cluster.
     * Passing the whole cluster resource as a `Kubernetes.*` workload's
     * `cluster` prop resolves through this — auth uses SigV4 tokens
     * minted from the ambient AWS credentials.
     */
    connection: Connection;
    /** The name of the cluster IAM role created for `compute: "auto"`, if managed by alchemy. */
    managedClusterRoleName: string | undefined;
    /** The name of the node IAM role created for `compute: "auto"`, if managed by alchemy. */
    managedNodeRoleName: string | undefined;
  },
  KubernetesObjectBinding,
  Providers
> {}

/**
 * An Amazon EKS cluster with support for EKS Auto Mode settings.
 * ### Creating Clusters
 * **Example:** Auto Mode Cluster (managed roles)
 * ```typescript
 * const cluster = yield* Cluster("AppCluster", {
 *   compute: "auto",
 *   resourcesVpcConfig: {
 *     subnetIds: network.privateSubnetIds,
 *   },
 * });
 * ```
 *
 * **Example:** Auto Mode Cluster from Existing Roles and Subnets
 * ```typescript
 * const cluster = yield* Cluster("AppCluster", {
 *   roleArn: clusterRole.roleArn,
 *   resourcesVpcConfig: {
 *     subnetIds: network.privateSubnetIds,
 *     endpointPublicAccess: true,
 *     endpointPrivateAccess: true,
 *   },
 *   accessConfig: {
 *     authenticationMode: "API",
 *   },
 *   computeConfig: {
 *     enabled: true,
 *     nodeRoleArn: nodeRole.roleArn,
 *     nodePools: ["system", "general-purpose"],
 *   },
 *   kubernetesNetworkConfig: {
 *     elasticLoadBalancing: { enabled: true },
 *   },
 *   storageConfig: {
 *     blockStorage: { enabled: true },
 *   },
 * });
 * ```
 *
 * ### Running Workloads
 * **Example:** Cluster with a Managed Node Group and an Add-on
 * ```typescript
 * const cluster = yield* AWS.EKS.Cluster("AppCluster", {
 *   roleArn: clusterRole.roleArn,
 *   resourcesVpcConfig: { subnetIds: network.privateSubnetIds },
 *   accessConfig: { authenticationMode: "API" },
 * });
 *
 * const nodes = yield* AWS.EKS.Nodegroup("AppNodes", {
 *   clusterName: cluster.clusterName,
 *   nodeRole: nodeRole.roleArn,
 *   subnets: network.privateSubnetIds,
 *   instanceTypes: ["t3.medium"],
 *   scalingConfig: { minSize: 1, maxSize: 2, desiredSize: 1 },
 * });
 *
 * const metricsServer = yield* AWS.EKS.Addon("MetricsServer", {
 *   clusterName: cluster.clusterName,
 *   addonName: "metrics-server",
 * });
 * ```
 *
 * @resource
 */
export const Cluster = Resource<Cluster>("AWS.EKS.Cluster");

class ClusterNotReady extends Data.TaggedError("EKS.ClusterNotReady")<{
  status: string | undefined;
}> {}

class ClusterStillExists extends Data.TaggedError("EKS.ClusterStillExists")<{}> {}

class ClusterUpdateNotComplete extends Data.TaggedError("EKS.ClusterUpdateNotComplete")<{
  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),
  );

// Wait budget: ~30 min at 10s spacing. Cluster create/delete takes ~10–15 min
// and async config/version updates ~5–15 min. The interval MUST be flat, not
// exponential: `Schedule.exponential` with no delay cap sleeps 8.5/17/34 min
// between late attempts — a silent multi-minute park that presents as a
// deadlocked (0% CPU, no output) deploy and blows any hook budget.
const updateRetrySchedule = Schedule.max([Schedule.spaced("10 seconds"), Schedule.recurs(180)]);

const getKubernetesTransport = (
  state: Pick<
    Cluster["Attributes"],
    "clusterArn" | "clusterName" | "endpoint" | "certificateAuthorityData"
  >,
) =>
  Effect.suspend(() => {
    if (!state.endpoint || !state.certificateAuthorityData) {
      throw new Error(
        `EKS cluster '${state.clusterName}' is missing endpoint or certificate authority data`,
      );
    }
    return makeEksTransport({
      clusterName: state.clusterName,
      region: regionOfClusterArn(state.clusterArn),
      endpoint: state.endpoint,
      certificateAuthorityData: state.certificateAuthorityData,
    });
  });

/** The region segment of a cluster ARN (`arn:aws:eks:REGION:...`). */
const regionOfClusterArn = (arn: string | undefined): string | undefined =>
  arn?.split(":")[3] || undefined;

const getDesiredKubernetesObjects = (
  bindings: ReadonlyArray<ResourceBinding<KubernetesObjectBinding>>,
): KubernetesObjectDefinition[] =>
  bindings
    .filter(
      (binding): binding is ResourceBinding<KubernetesObjectBinding> =>
        binding.data.type === "kubernetes-object",
    )
    .map((binding) => binding.data.object);

const autoClusterManagedPolicyArns = [
  "arn:aws:iam::aws:policy/AmazonEKSClusterPolicy",
  "arn:aws:iam::aws:policy/AmazonEKSComputePolicy",
  "arn:aws:iam::aws:policy/AmazonEKSBlockStoragePolicy",
  "arn:aws:iam::aws:policy/AmazonEKSLoadBalancingPolicy",
  "arn:aws:iam::aws:policy/AmazonEKSNetworkingPolicy",
];

const autoNodeManagedPolicyArns = [
  "arn:aws:iam::aws:policy/AmazonEKSWorkerNodeMinimalPolicy",
  "arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryPullOnly",
];

/**
 * Expand `compute: "auto"` into the concrete EKS Auto Mode configuration
 * (explicit user props always win over the defaults).
 */
const applyAutoModeDefaults = (
  news: ClusterProps,
  roles: { roleArn: string; nodeRoleArn: string | undefined },
): ClusterProps & { roleArn: string } =>
  news.compute === "auto"
    ? {
        ...news,
        roleArn: roles.roleArn,
        accessConfig: {
          bootstrapClusterCreatorAdminPermissions: true,
          authenticationMode: "API",
          ...news.accessConfig,
        },
        computeConfig: {
          enabled: true,
          nodePools: ["system", "general-purpose"],
          ...news.computeConfig,
          nodeRoleArn: roles.nodeRoleArn,
        },
        kubernetesNetworkConfig: {
          ...news.kubernetesNetworkConfig,
          elasticLoadBalancing: {
            enabled: true,
            ...news.kubernetesNetworkConfig?.elasticLoadBalancing,
          },
        },
        storageConfig: {
          blockStorage: {
            enabled: true,
            ...news.storageConfig?.blockStorage,
          },
        },
      }
    : { ...news, roleArn: roles.roleArn };

const stringSetEqual = (a: readonly string[] | undefined, b: readonly string[] | undefined) =>
  JSON.stringify([...(a ?? [])].sort()) === JSON.stringify([...(b ?? [])].sort());

/** Flatten an EKS `Logging` shape into a `logType -> enabled` map. */
const loggingByType = (logging: eks.Logging | undefined) => {
  const byType: Record<string, boolean> = {};
  for (const setup of logging?.clusterLogging ?? []) {
    for (const type of setup.types ?? []) {
      byType[type] = setup.enabled ?? false;
    }
  }
  return byType;
};

interface ClusterConfigUpdate {
  /** Stable category slug — also feeds the per-category idempotency token. */
  category: string;
  request: Omit<eks.UpdateClusterConfigRequest, "name" | "clientRequestToken">;
}

/**
 * Plan the `updateClusterConfig` calls needed to converge observed cloud
 * state to the desired props.
 *
 * EKS's UpdateClusterConfig API accepts exactly ONE update category per call
 * (`InvalidParameterException: Only one type of update can be allowed.`), so
 * drift is computed per category and each drifted category becomes its own
 * request — the caller issues them serially, waiting for each async update
 * to complete before the next.
 *
 * Comparison is desired-subset only: a field the user did not specify is
 * "don't care" and is never diffed against server-populated response fields
 * (vpcId, clusterSecurityGroupId, default upgradePolicy, ...). A freshly
 * created cluster therefore plans zero updates.
 */
const planClusterConfigUpdates = (
  observed: Cluster["Attributes"],
  desired: ClusterProps,
): ClusterConfigUpdate[] => {
  const updates: ClusterConfigUpdate[] = [];

  // Access config — authenticationMode is the only mutable field.
  const desiredAuthMode = desired.accessConfig?.authenticationMode;
  if (
    desiredAuthMode !== undefined &&
    desiredAuthMode !== observed.accessConfig?.authenticationMode
  ) {
    updates.push({
      category: "access",
      request: { accessConfig: { authenticationMode: desiredAuthMode } },
    });
  }

  // Auto Mode trio — computeConfig, storageConfig and kubernetesNetworkConfig
  // count as ONE update category and must ship together in a single call.
  const desiredCompute = desired.computeConfig;
  const observedCompute = observed.computeConfig;
  const computeDrift =
    desiredCompute !== undefined &&
    ((desiredCompute.enabled !== undefined &&
      desiredCompute.enabled !== (observedCompute?.enabled ?? false)) ||
      (desiredCompute.nodePools !== undefined &&
        !stringSetEqual(desiredCompute.nodePools, observedCompute?.nodePools)) ||
      (desiredCompute.nodeRoleArn !== undefined &&
        desiredCompute.nodeRoleArn !== observedCompute?.nodeRoleArn));
  const desiredBlockStorage = desired.storageConfig?.blockStorage?.enabled;
  const storageDrift =
    desiredBlockStorage !== undefined &&
    desiredBlockStorage !== (observed.storageConfig?.blockStorage?.enabled ?? false);
  const desiredElb = desired.kubernetesNetworkConfig?.elasticLoadBalancing?.enabled;
  const elbDrift =
    desiredElb !== undefined &&
    desiredElb !== (observed.kubernetesNetworkConfig?.elasticLoadBalancing?.enabled ?? false);
  if (computeDrift || storageDrift || elbDrift) {
    updates.push({
      category: "auto-mode",
      request: {
        computeConfig: desiredCompute ?? {
          enabled: observedCompute?.enabled ?? false,
          nodePools: observedCompute?.nodePools,
          nodeRoleArn: observedCompute?.nodeRoleArn,
        },
        storageConfig: {
          blockStorage: {
            enabled: desiredBlockStorage ?? observed.storageConfig?.blockStorage?.enabled ?? false,
          },
        },
        // serviceIpv4Cidr / ipFamily are create-only (diff replaces on
        // change) — never send them on update.
        kubernetesNetworkConfig: {
          elasticLoadBalancing: {
            enabled:
              desiredElb ??
              observed.kubernetesNetworkConfig?.elasticLoadBalancing?.enabled ??
              false,
          },
        },
      },
    });
  }

  // VPC endpoint access (public/private endpoint + public access CIDRs).
  const desiredVpc = desired.resourcesVpcConfig;
  const observedVpc = observed.resourcesVpcConfig;
  const endpointPublicDrift =
    desiredVpc.endpointPublicAccess !== undefined &&
    desiredVpc.endpointPublicAccess !== observedVpc.endpointPublicAccess;
  const endpointPrivateDrift =
    desiredVpc.endpointPrivateAccess !== undefined &&
    desiredVpc.endpointPrivateAccess !== observedVpc.endpointPrivateAccess;
  const publicCidrsDrift =
    desiredVpc.publicAccessCidrs !== undefined &&
    !stringSetEqual(desiredVpc.publicAccessCidrs, observedVpc.publicAccessCidrs);
  if (endpointPublicDrift || endpointPrivateDrift || publicCidrsDrift) {
    updates.push({
      category: "vpc-endpoint",
      request: {
        resourcesVpcConfig: {
          endpointPublicAccess: desiredVpc.endpointPublicAccess,
          endpointPrivateAccess: desiredVpc.endpointPrivateAccess,
          publicAccessCidrs: desiredVpc.publicAccessCidrs,
        },
      },
    });
  }

  // VPC subnet / security-group membership — separate from endpoint access.
  const subnetsDrift =
    desiredVpc.subnetIds !== undefined &&
    !stringSetEqual(desiredVpc.subnetIds, observedVpc.subnetIds);
  const securityGroupsDrift =
    desiredVpc.securityGroupIds !== undefined &&
    !stringSetEqual(desiredVpc.securityGroupIds, observedVpc.securityGroupIds);
  if (subnetsDrift || securityGroupsDrift) {
    updates.push({
      category: "vpc-network",
      request: {
        resourcesVpcConfig: {
          subnetIds: desiredVpc.subnetIds,
          securityGroupIds: desiredVpc.securityGroupIds,
        },
      },
    });
  }

  // Control-plane logging — compare per log type; types the user didn't
  // mention are "don't care".
  if (desired.logging !== undefined) {
    const observedLogging = loggingByType(observed.logging);
    const desiredLogging = loggingByType(desired.logging);
    if (
      Object.entries(desiredLogging).some(
        ([type, enabled]) => (observedLogging[type] ?? false) !== enabled,
      )
    ) {
      updates.push({
        category: "logging",
        request: { logging: desired.logging },
      });
    }
  }

  // Upgrade policy.
  if (
    desired.upgradePolicy?.supportType !== undefined &&
    desired.upgradePolicy.supportType !== observed.upgradePolicy?.supportType
  ) {
    updates.push({
      category: "upgrade-policy",
      request: { upgradePolicy: desired.upgradePolicy },
    });
  }

  // Deletion protection.
  if (
    desired.deletionProtection !== undefined &&
    desired.deletionProtection !== observed.deletionProtection
  ) {
    updates.push({
      category: "deletion-protection",
      request: { deletionProtection: desired.deletionProtection },
    });
  }

  return updates;
};

const mapClusterState = (
  cluster: eks.Cluster,
  tags: Record<string, string>,
  kubernetesObjects: KubernetesObjectRef[],
  managedRoles: {
    managedClusterRoleName?: string;
    managedNodeRoleName?: string;
  } = {},
): Cluster["Attributes"] => ({
  managedClusterRoleName: managedRoles.managedClusterRoleName,
  managedNodeRoleName: managedRoles.managedNodeRoleName,
  clusterArn: cluster.arn as ClusterArn,
  clusterName: cluster.name!,
  status: cluster.status ?? "CREATING",
  endpoint: cluster.endpoint,
  certificateAuthorityData: cluster.certificateAuthority?.data,
  connection: eksConnectionOf({
    clusterName: cluster.name!,
    region: regionOfClusterArn(cluster.arn) ?? "",
    endpoint: cluster.endpoint,
    certificateAuthorityData: cluster.certificateAuthority?.data,
  }),
  version: cluster.version,
  platformVersion: cluster.platformVersion,
  roleArn: cluster.roleArn!,
  resourcesVpcConfig: {
    subnetIds: cluster.resourcesVpcConfig?.subnetIds ?? [],
    securityGroupIds: cluster.resourcesVpcConfig?.securityGroupIds ?? [],
    clusterSecurityGroupId: cluster.resourcesVpcConfig?.clusterSecurityGroupId,
    vpcId: cluster.resourcesVpcConfig?.vpcId,
    endpointPublicAccess: cluster.resourcesVpcConfig?.endpointPublicAccess,
    endpointPrivateAccess: cluster.resourcesVpcConfig?.endpointPrivateAccess,
    publicAccessCidrs: cluster.resourcesVpcConfig?.publicAccessCidrs ?? [],
  },
  accessConfig: cluster.accessConfig,
  computeConfig: cluster.computeConfig,
  storageConfig: cluster.storageConfig,
  kubernetesNetworkConfig: cluster.kubernetesNetworkConfig,
  logging: cluster.logging,
  upgradePolicy: cluster.upgradePolicy,
  deletionProtection: cluster.deletionProtection ?? false,
  oidcIssuer: cluster.identity?.oidc?.issuer,
  tags,
  kubernetesObjects,
});

export const ClusterProvider = () =>
  Provider.effect(
    Cluster,
    Effect.gen(function* () {
      const toClusterName = (id: string, props: { clusterName?: string } = {}) =>
        props.clusterName
          ? Effect.succeed(props.clusterName)
          : createPhysicalName({ id, maxLength: 100 });

      const toClientRequestToken = (id: string, action: string) =>
        createPhysicalName({
          id: `${id}-${action}`,
          maxLength: 64,
          delimiter: "-",
        });

      const validateProps = Effect.fn(function* (props: ClusterProps) {
        const subnetIds = props.resourcesVpcConfig.subnetIds ?? [];
        if (subnetIds.length < 2) {
          return yield* new EKSClusterInvalidProps({
            message: "AWS.EKS.Cluster requires at least two subnet IDs",
          });
        }
        if (!props.roleArn && props.compute !== "auto") {
          return yield* new EKSClusterInvalidProps({
            message: "AWS.EKS.Cluster requires roleArn unless compute is 'auto'",
          });
        }
        if (
          props.computeConfig?.enabled &&
          props.accessConfig?.authenticationMode === "CONFIG_MAP"
        ) {
          return yield* new EKSClusterInvalidProps({
            message:
              "AWS.EKS.Cluster Auto Mode requires accessConfig.authenticationMode to include API access",
          });
        }
      });

      // Ensure an alchemy-managed IAM role for `compute: "auto"` (cluster or
      // node role). Idempotent: creates on miss, adopts our own role on race,
      // and converges managed policy attachments.
      const ensureManagedRole = Effect.fn(function* ({
        id,
        roleName,
        service,
        actions,
        managedPolicyArns,
        userTags,
      }: {
        id: string;
        roleName: string;
        service: string;
        actions: string[];
        managedPolicyArns: string[];
        userTags: Record<string, string> | undefined;
      }) {
        const tags = yield* createInternalTags(id);
        const role = yield* iam
          .createRole({
            RoleName: roleName,
            AssumeRolePolicyDocument: JSON.stringify({
              Version: "2012-10-17",
              Statement: [
                {
                  Effect: "Allow",
                  Principal: { Service: service },
                  Action: actions,
                },
              ],
            }),
            Tags: Object.entries({ ...tags, ...userTags }).map(([Key, Value]) => ({ Key, Value })),
          })
          .pipe(
            Effect.catchTag("EntityAlreadyExistsException", () =>
              iam.getRole({ RoleName: roleName }).pipe(
                Effect.filterOrFail(
                  (existing) => hasTags(tags, existing.Role?.Tags),
                  () =>
                    new EKSClusterConflict({
                      message: `Role '${roleName}' already exists and is not managed by alchemy`,
                    }),
                ),
              ),
            ),
          );
        for (const policyArn of managedPolicyArns) {
          yield* iam
            .attachRolePolicy({ RoleName: roleName, PolicyArn: policyArn })
            .pipe(Effect.catchTag("LimitExceededException", () => Effect.void));
        }
        return role.Role!.Arn!;
      });

      const deleteManagedRole = Effect.fn(function* (roleName: string) {
        yield* iam.listAttachedRolePolicies.items({ RoleName: roleName }).pipe(
          Stream.mapEffect((policy) =>
            iam
              .detachRolePolicy({
                RoleName: roleName,
                PolicyArn: policy.PolicyArn!,
              })
              .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void)),
          ),
          Stream.runDrain,
          Effect.catchTag("NoSuchEntityException", () => Effect.void),
        );
        yield* iam.listRolePolicies.items({ RoleName: roleName }).pipe(
          Stream.mapEffect((policyName) =>
            iam
              .deleteRolePolicy({
                RoleName: roleName,
                PolicyName: policyName,
              })
              .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void)),
          ),
          Stream.runDrain,
          Effect.catchTag("NoSuchEntityException", () => Effect.void),
        );
        yield* iam
          .deleteRole({ RoleName: roleName })
          .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void));
      });

      const readCluster = Effect.fn(function* ({
        clusterName,
        kubernetesObjects,
        managedRoles,
      }: {
        clusterName: string;
        kubernetesObjects?: KubernetesObjectRef[];
        managedRoles?: {
          managedClusterRoleName?: string;
          managedNodeRoleName?: string;
        };
      }) {
        const described = yield* eks
          .describeCluster({
            name: clusterName,
          })
          .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
        const cluster = described?.cluster;
        if (!cluster?.arn || !cluster.name || !cluster.roleArn) {
          return undefined;
        }
        const listedTags = yield* eks
          .listTagsForResource({
            resourceArn: cluster.arn,
          })
          .pipe(Effect.catchTag("NotFoundException", () => Effect.undefined));
        const tags = normalizeTags(listedTags?.tags ?? cluster.tags);
        return mapClusterState(cluster, tags, kubernetesObjects ?? [], managedRoles);
      });

      const waitForClusterActive = (
        clusterName: string,
        kubernetesObjects: KubernetesObjectRef[] = [],
        managedRoles?: {
          managedClusterRoleName?: string;
          managedNodeRoleName?: string;
        },
      ) =>
        readCluster({
          clusterName,
          kubernetesObjects,
          managedRoles,
        }).pipe(
          Effect.flatMap(
            Effect.fnUntraced(function* (state) {
              if (!state) {
                return yield* new ClusterNotReady({
                  status: undefined,
                });
              }
              if (state.status === "ACTIVE") {
                return state;
              }
              if (state.status === "FAILED") {
                return yield* new EKSClusterOperationFailed({
                  message: `EKS cluster '${clusterName}' entered FAILED state`,
                });
              }
              return yield* new ClusterNotReady({
                status: state.status,
              });
            }),
          ),
          Effect.retry({
            while: (error) => error instanceof ClusterNotReady,
            schedule: updateRetrySchedule,
          }),
        );

      const waitForClusterDeleted = (clusterName: string) =>
        readCluster({
          clusterName,
        }).pipe(
          Effect.flatMap((state) =>
            state ? Effect.fail(new ClusterStillExists()) : Effect.undefined,
          ),
          Effect.retry({
            while: (error) => error instanceof ClusterStillExists,
            schedule: updateRetrySchedule,
          }),
        );

      const waitForUpdate = (clusterName: string, updateId: string) =>
        eks
          .describeUpdate({
            name: clusterName,
            updateId,
          })
          .pipe(
            Effect.flatMap(
              Effect.fnUntraced(function* ({ update }) {
                if (update?.status === "Successful") {
                  return update;
                }
                if (update?.status === "Failed" || update?.status === "Cancelled") {
                  return yield* new EKSClusterOperationFailed({
                    message: `EKS cluster update '${updateId}' failed with status '${update?.status}'`,
                  });
                }
                return yield* new ClusterUpdateNotComplete({
                  status: update?.status,
                });
              }),
            ),
            Effect.retry({
              while: (error) => error instanceof ClusterUpdateNotComplete,
              schedule: updateRetrySchedule,
            }),
          );

      return {
        stables: ["clusterArn", "clusterName", "connection"],
        // Enumerate every cluster in the ambient account/region. `listClusters`
        // returns only names, so we paginate it exhaustively then hydrate each
        // name through `readCluster` (describe + tags) to produce the full
        // `Attributes` shape `read` returns. Concurrency is bounded so we don't
        // stampede `describeCluster`.
        list: () =>
          Effect.gen(function* () {
            const names = yield* eks.listClusters.pages({}).pipe(
              Stream.runCollect,
              Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.clusters ?? [])),
            );
            const states = yield* Effect.forEach(
              names,
              (clusterName) => readCluster({ clusterName }),
              { concurrency: 8 },
            );
            return states.filter((state): state is Cluster["Attributes"] => state !== undefined);
          }),
        diff: Effect.fn(function* ({ id, olds = {} as ClusterProps, news }) {
          if (!isResolved(news)) return;
          if ((yield* toClusterName(id, olds)) !== (yield* toClusterName(id, news ?? {}))) {
            return { action: "replace" } as const;
          }
          if (olds.roleArn !== news.roleArn) {
            return { action: "replace" } as const;
          }
          if (
            olds.accessConfig?.bootstrapClusterCreatorAdminPermissions !==
            news.accessConfig?.bootstrapClusterCreatorAdminPermissions
          ) {
            return { action: "replace" } as const;
          }
          if (
            olds.kubernetesNetworkConfig?.serviceIpv4Cidr !==
              news.kubernetesNetworkConfig?.serviceIpv4Cidr ||
            olds.kubernetesNetworkConfig?.ipFamily !== news.kubernetesNetworkConfig?.ipFamily
          ) {
            return { action: "replace" } as const;
          }
          if (
            olds.computeConfig?.nodeRoleArn !== news.computeConfig?.nodeRoleArn &&
            (olds.computeConfig?.enabled || news.computeConfig?.enabled)
          ) {
            return { action: "replace" } as const;
          }
        }),
        read: Effect.fn(function* ({ id, olds, output }) {
          const clusterName = output?.clusterName ?? (yield* toClusterName(id, olds ?? {}));
          const state = yield* readCluster({
            clusterName,
            kubernetesObjects: output?.kubernetesObjects,
            managedRoles: output,
          });
          if (!state) return undefined;
          return (yield* hasAlchemyTags(id, state.tags)) ? state : Unowned(state);
        }),
        reconcile: Effect.fn(function* ({ id, news, output, bindings, session }) {
          yield* validateProps(news);

          const clusterName = yield* toClusterName(id, news);
          const desiredObjects = getDesiredKubernetesObjects(bindings);
          const desiredTags = {
            ...(yield* createInternalTags(id)),
            ...news.tags,
          };

          // Ensure `compute: "auto"` managed IAM roles before touching the
          // cluster. Physical names are cached in the output so re-runs and
          // updates converge on the same roles.
          const auto = news.compute === "auto";
          let managedClusterRoleName = output?.managedClusterRoleName;
          let managedNodeRoleName = output?.managedNodeRoleName;
          let roleArn = news.roleArn;
          if (!roleArn && auto) {
            managedClusterRoleName ??= yield* createPhysicalName({
              id: `${id}-cluster-role`,
              maxLength: 64,
            });
            roleArn = yield* ensureManagedRole({
              id,
              roleName: managedClusterRoleName,
              service: "eks.amazonaws.com",
              actions: ["sts:AssumeRole", "sts:TagSession"],
              managedPolicyArns: autoClusterManagedPolicyArns,
              userTags: news.tags,
            });
          } else if (roleArn) {
            managedClusterRoleName = undefined;
          }
          let nodeRoleArn = news.computeConfig?.nodeRoleArn;
          if (!nodeRoleArn && auto) {
            managedNodeRoleName ??= yield* createPhysicalName({
              id: `${id}-node-role`,
              maxLength: 64,
            });
            nodeRoleArn = yield* ensureManagedRole({
              id,
              roleName: managedNodeRoleName,
              service: "ec2.amazonaws.com",
              actions: ["sts:AssumeRole"],
              managedPolicyArns: autoNodeManagedPolicyArns,
              userTags: news.tags,
            });
          } else if (nodeRoleArn) {
            managedNodeRoleName = undefined;
          }
          if (!roleArn) {
            return yield* new EKSClusterInvalidProps({
              message: "AWS.EKS.Cluster requires roleArn unless compute is 'auto'",
            });
          }
          const managedRoles = { managedClusterRoleName, managedNodeRoleName };
          const effective = applyAutoModeDefaults(news, {
            roleArn,
            nodeRoleArn,
          });

          // Observe — fetch live cloud state. We always fetch fresh so
          // adoption, drift, and partial-prior-runs all converge.
          let state = yield* readCluster({
            clusterName,
            kubernetesObjects: output?.kubernetesObjects,
            managedRoles,
          });

          // Ensure — create cluster if missing. Tolerate
          // `ResourceInUseException` as a race with a peer reconciler:
          // re-read and continue with the sync path. The control plane
          // takes 10+ minutes; we wait for ACTIVE before any sync work.
          if (!state) {
            yield* eks
              .createCluster({
                name: clusterName,
                version: effective.version,
                roleArn: effective.roleArn,
                resourcesVpcConfig: effective.resourcesVpcConfig,
                kubernetesNetworkConfig: effective.kubernetesNetworkConfig,
                logging: effective.logging,
                accessConfig: effective.accessConfig,
                computeConfig: effective.computeConfig,
                storageConfig: effective.storageConfig,
                deletionProtection: effective.deletionProtection,
                upgradePolicy: effective.upgradePolicy,
                tags: desiredTags,
                clientRequestToken: yield* toClientRequestToken(id, "create"),
              })
              .pipe(Effect.catchTag("ResourceInUseException", () => Effect.void));

            yield* session.note(`Creating EKS cluster ${clusterName}...`);
            state = yield* waitForClusterActive(clusterName, [], managedRoles);
          }

          const clusterArn = state.clusterArn;

          // Sync cluster config — EKS's UpdateClusterConfig accepts exactly
          // ONE update category per call ("Only one type of update can be
          // allowed"), so we plan the observed↔desired drift per category and
          // issue one serialized updateClusterConfig per drifted category,
          // waiting for each async update to land (Successful + cluster back
          // to ACTIVE) before the next. Everything settable at create time is
          // already passed to createCluster, so a greenfield create plans
          // zero updates.
          for (const { category, request } of planClusterConfigUpdates(state, effective)) {
            const configUpdate = yield* eks.updateClusterConfig({
              name: clusterName,
              ...request,
              clientRequestToken: yield* toClientRequestToken(id, `config-${category}`),
            });
            if (configUpdate.update?.id) {
              yield* session.note(`Updating EKS cluster ${category} config (${clusterName})...`);
              yield* waitForUpdate(clusterName, configUpdate.update.id);
              state =
                (yield* waitForClusterActive(
                  clusterName,
                  output?.kubernetesObjects ?? [],
                  managedRoles,
                )) ?? state;
            }
          }

          // Sync version — observed ↔ desired.
          if (effective.version && state.version !== effective.version) {
            const versionUpdate = yield* eks.updateClusterVersion({
              name: clusterName,
              version: effective.version,
              clientRequestToken: yield* toClientRequestToken(id, "version"),
            });
            if (versionUpdate.update?.id) {
              yield* session.note(`Updating EKS cluster version ${clusterName}...`);
              yield* waitForUpdate(clusterName, versionUpdate.update.id);
              state =
                (yield* waitForClusterActive(
                  clusterName,
                  output?.kubernetesObjects ?? [],
                  managedRoles,
                )) ?? state;
            }
          }

          // Sync tags — diff observed cloud tags against desired.
          const { removed, upsert } = diffTags(state.tags, desiredTags);
          if (upsert.length > 0) {
            yield* eks.tagResource({
              resourceArn: clusterArn,
              tags: Object.fromEntries(upsert.map((tag) => [tag.Key, tag.Value] as const)),
            });
          }
          if (removed.length > 0) {
            yield* eks.untagResource({
              resourceArn: clusterArn,
              tagKeys: removed,
            });
          }

          yield* session.note(clusterArn);

          // Re-read final state so returned attributes reflect the post-
          // sync cloud state.
          const final = yield* readCluster({
            clusterName,
            kubernetesObjects: output?.kubernetesObjects ?? [],
            managedRoles,
          });
          if (!final) {
            return yield* new EKSClusterUnexpectedResponse({
              message: `EKS cluster '${clusterName}' could not be read after reconcile`,
            });
          }

          const kubernetesObjects = yield* reconcileObjects({
            transport: yield* getKubernetesTransport(final),
            previousObjects: output?.kubernetesObjects ?? [],
            desiredObjects,
          });

          return {
            ...final,
            kubernetesObjects,
          };
        }),
        delete: Effect.fn(function* ({ id, output }) {
          if ((output.kubernetesObjects ?? []).length > 0) {
            yield* deleteObjects({
              transport: yield* getKubernetesTransport(output),
              objects: output.kubernetesObjects ?? [],
            });
          }

          if (output.deletionProtection) {
            const disableDeletionProtection = yield* eks.updateClusterConfig({
              name: output.clusterName,
              deletionProtection: false,
              clientRequestToken: yield* toClientRequestToken(id, "disable-deletion-protection"),
            });
            if (disableDeletionProtection.update?.id) {
              yield* waitForUpdate(output.clusterName, disableDeletionProtection.update.id);
              yield* waitForClusterActive(output.clusterName, output.kubernetesObjects ?? []);
            }
          }

          // A cluster with an update in flight (an access-entry or config change
          // a crashed deploy left behind) refuses deletion with
          // ResourceInUseException: let its updates settle first.
          const updateIds = yield* eks.listUpdates({ name: output.clusterName }).pipe(
            Effect.map((response) => response.updateIds ?? []),
            Effect.catchTag("ResourceNotFoundException", () => Effect.succeed([] as string[])),
          );
          for (const updateId of updateIds) {
            yield* waitForUpdate(output.clusterName, updateId).pipe(
              Effect.catchTag(
                ["EKSClusterOperationFailed", "ResourceNotFoundException"],
                () => Effect.void,
              ),
            );
          }

          yield* eks
            .deleteCluster({
              name: output.clusterName,
            })
            .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));

          yield* waitForClusterDeleted(output.clusterName);

          // Delete the `compute: "auto"` managed IAM roles this cluster owns.
          if (output.managedClusterRoleName) {
            yield* deleteManagedRole(output.managedClusterRoleName);
          }
          if (output.managedNodeRoleName) {
            yield* deleteManagedRole(output.managedNodeRoleName);
          }
        }),
      };
    }),
  );