AWS.EKS reference

AccessEntry

Source: src/AWS/EKS/AccessEntry.ts

An Amazon EKS access entry that grants an IAM principal access to a cluster.

AccessEntry owns both the entry itself and the exact set of associated EKS access policies, making cluster access explicit and updatable after initial cluster bootstrap.

AccessEntry: Managing Cluster Access

const viewer = yield* AccessEntry("ViewerAccess", {
  clusterName: cluster.clusterName,
  principalArn: viewerRole.roleArn,
  accessPolicies: [
    {
      policyArn:
        "arn:aws:eks::aws:cluster-access-policy/AmazonEKSViewPolicy",
      accessScope: {
        type: "cluster",
      },
    },
  ],
});

Addon

Source: src/AWS/EKS/Addon.ts

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.

Addon: Managing Add-ons

const metricsServer = yield* Addon("MetricsServer", {
  clusterName: cluster.clusterName,
  addonName: "metrics-server",
});

Cluster

Source: src/AWS/EKS/Cluster.ts

An Amazon EKS cluster with support for EKS Auto Mode settings.

Cluster: Creating Clusters

Auto Mode Cluster (managed roles)

const cluster = yield* Cluster("AppCluster", {
  compute: "auto",
  resourcesVpcConfig: {
    subnetIds: network.privateSubnetIds,
  },
});

Auto Mode Cluster from Existing Roles and Subnets

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

Cluster: Running Workloads

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

DescribeAccessEntry

Source: src/AWS/EKS/DescribeAccessEntry.ts

Runtime binding for eks:DescribeAccessEntry.

Reads one access entry — the Kubernetes username, groups, and type mapped to an IAM principal. The cluster clusterName is injected from the bound Cluster and eks:DescribeAccessEntry is granted on the cluster’s sub-resource ARNs. Provide the implementation with Effect.provide(AWS.EKS.DescribeAccessEntryHttp).

DescribeAccessEntry: Inspecting Identity and Access

// init
const describeAccessEntry = yield* AWS.EKS.DescribeAccessEntry(cluster);

// runtime
const { accessEntry } = yield* describeAccessEntry({ principalArn });

DescribeAddon

Source: src/AWS/EKS/DescribeAddon.ts

Runtime binding for eks:DescribeAddon.

Reads one installed add-on’s state — version, status, health issues, and pod identity associations. The cluster clusterName is injected from the bound Cluster and eks:DescribeAddon is granted on the cluster’s sub-resource ARNs. Provide the implementation with Effect.provide(AWS.EKS.DescribeAddonHttp).

DescribeAddon: Inspecting Add-ons

// init
const describeAddon = yield* AWS.EKS.DescribeAddon(cluster);

// runtime
const { addon } = yield* describeAddon({ addonName: "vpc-cni" });

DescribeAddonConfiguration

Source: src/AWS/EKS/DescribeAddonConfiguration.ts

Runtime binding for eks:DescribeAddonConfiguration.

Reads an add-on version’s configuration JSON schema — the shape its configurationValues must satisfy. eks:DescribeAddonConfiguration is granted on * — the operation is account-scoped and takes no resource. Provide the implementation with Effect.provide(AWS.EKS.DescribeAddonConfigurationHttp).

DescribeAddonConfiguration: Version Catalogs

// init
const describeAddonConfiguration =
  yield* AWS.EKS.DescribeAddonConfiguration();

// runtime
const { configurationSchema } = yield* describeAddonConfiguration({
  addonName: "vpc-cni",
  addonVersion,
});

DescribeAddonVersions

Source: src/AWS/EKS/DescribeAddonVersions.ts

Runtime binding for eks:DescribeAddonVersions.

Reads the add-on catalog — which add-ons (and versions) are available, per Kubernetes version. eks:DescribeAddonVersions is granted on * — the operation is account-scoped and takes no resource. Provide the implementation with Effect.provide(AWS.EKS.DescribeAddonVersionsHttp).

DescribeAddonVersions: Version Catalogs

// init
const describeAddonVersions = yield* AWS.EKS.DescribeAddonVersions();

// runtime
const { addons } = yield* describeAddonVersions({
  addonName: "vpc-cni",
  kubernetesVersion: "1.31",
});

DescribeCapability

Source: src/AWS/EKS/DescribeCapability.ts

Runtime binding for eks:DescribeCapability.

Reads one EKS capability’s full state — the managed capability (e.g. Argo CD) installed on the bound cluster, its status, version, and configuration. The cluster clusterName is injected from the bound Cluster and eks:DescribeCapability is granted on the cluster’s sub-resource ARNs. Provide the implementation with Effect.provide(AWS.EKS.DescribeCapabilityHttp).

DescribeCapability: Cluster Capabilities

// init
const describeCapability = yield* AWS.EKS.DescribeCapability(cluster);

// runtime
const { capability } = yield* describeCapability({ capabilityName: "argocd" });
const status = capability?.status;

DescribeCluster

Source: src/AWS/EKS/DescribeCluster.ts

Runtime binding for eks:DescribeCluster.

Reads the bound cluster’s live control-plane state — status, Kubernetes API endpoint, certificateAuthority data, version, and network config. The building block for constructing a kubeconfig at runtime. The cluster name is injected from the bound Cluster and eks:DescribeCluster is granted on the cluster’s ARN. Provide the implementation with Effect.provide(AWS.EKS.DescribeClusterHttp).

DescribeCluster: Reading Cluster State

// init
const describeCluster = yield* AWS.EKS.DescribeCluster(cluster);

// runtime
const { cluster: live } = yield* describeCluster();
const endpoint = live?.endpoint;
const caData = live?.certificateAuthority?.data;

DescribeClusterVersions

Source: src/AWS/EKS/DescribeClusterVersions.ts

Runtime binding for eks:DescribeClusterVersions.

Reads the Kubernetes version catalog — which versions EKS currently offers, their support status, and end-of-support dates. eks:DescribeClusterVersions is granted on * — the operation is account-scoped and takes no resource. Provide the implementation with Effect.provide(AWS.EKS.DescribeClusterVersionsHttp).

DescribeClusterVersions: Version Catalogs

// init
const describeClusterVersions = yield* AWS.EKS.DescribeClusterVersions();

// runtime
const { clusterVersions } = yield* describeClusterVersions({
  defaultOnly: true,
});

DescribeFargateProfile

Source: src/AWS/EKS/DescribeFargateProfile.ts

Runtime binding for eks:DescribeFargateProfile.

Reads one Fargate profile’s state — pod execution role, selectors, subnets, and status. The cluster clusterName is injected from the bound Cluster and eks:DescribeFargateProfile is granted on the cluster’s sub-resource ARNs. Provide the implementation with Effect.provide(AWS.EKS.DescribeFargateProfileHttp).

DescribeFargateProfile: Inspecting Compute

// init
const describeFargateProfile = yield* AWS.EKS.DescribeFargateProfile(cluster);

// runtime
const { fargateProfile } = yield* describeFargateProfile({
  fargateProfileName: "default",
});

DescribeIdentityProviderConfig

Source: src/AWS/EKS/DescribeIdentityProviderConfig.ts

Runtime binding for eks:DescribeIdentityProviderConfig.

Reads one OIDC identity provider configuration associated with the bound cluster — issuer URL, client ID, claim mappings, and association status. The cluster clusterName is injected from the bound Cluster and eks:DescribeIdentityProviderConfig is granted on the cluster’s sub-resource ARNs. Provide the implementation with Effect.provide(AWS.EKS.DescribeIdentityProviderConfigHttp).

DescribeIdentityProviderConfig: Identity Provider Configs

// init
const describeIdentityProviderConfig =
  yield* AWS.EKS.DescribeIdentityProviderConfig(cluster);

// runtime
const { identityProviderConfig } = yield* describeIdentityProviderConfig({
  identityProviderConfig: { type: "oidc", name: "corp-oidc" },
});
const issuer = identityProviderConfig?.oidc?.issuerUrl;

DescribeInsight

Source: src/AWS/EKS/DescribeInsight.ts

Runtime binding for eks:DescribeInsight.

Reads one insight’s full detail — category, status, recommendation, and the resources it flags. The cluster clusterName is injected from the bound Cluster and eks:DescribeInsight is granted on the cluster’s ARN. Provide the implementation with Effect.provide(AWS.EKS.DescribeInsightHttp).

DescribeInsight: Cluster Insights

// init
const describeInsight = yield* AWS.EKS.DescribeInsight(cluster);

// runtime
const { insight } = yield* describeInsight({ id: insightId });

DescribeInsightsRefresh

Source: src/AWS/EKS/DescribeInsightsRefresh.ts

Runtime binding for eks:DescribeInsightsRefresh.

Reads the status of the bound cluster’s insights refresh — whether an on-demand refresh (kicked off via StartInsightsRefresh) is in progress, completed, or failed. The cluster clusterName is injected from the bound Cluster and eks:DescribeInsightsRefresh is granted on the cluster’s ARN. Provide the implementation with Effect.provide(AWS.EKS.DescribeInsightsRefreshHttp).

DescribeInsightsRefresh: Cluster Insights

// init
const describeInsightsRefresh = yield* AWS.EKS.DescribeInsightsRefresh(cluster);

// runtime
const { status } = yield* describeInsightsRefresh();

DescribeNodegroup

Source: src/AWS/EKS/DescribeNodegroup.ts

Runtime binding for eks:DescribeNodegroup.

Reads one managed node group’s full state — scaling config, instance types, AMI release version, health issues. The cluster clusterName is injected from the bound Cluster and eks:DescribeNodegroup is granted on the cluster’s sub-resource ARNs. Provide the implementation with Effect.provide(AWS.EKS.DescribeNodegroupHttp).

DescribeNodegroup: Inspecting Compute

// init
const describeNodegroup = yield* AWS.EKS.DescribeNodegroup(cluster);

// runtime
const { nodegroup } = yield* describeNodegroup({ nodegroupName: "general" });
const issues = nodegroup?.health?.issues ?? [];

DescribePodIdentityAssociation

Source: src/AWS/EKS/DescribePodIdentityAssociation.ts

Runtime binding for eks:DescribePodIdentityAssociation.

Reads one EKS Pod Identity association — the IAM role wired to a Kubernetes service account. The cluster clusterName is injected from the bound Cluster and eks:DescribePodIdentityAssociation is granted on the cluster’s sub-resource ARNs. Provide the implementation with Effect.provide(AWS.EKS.DescribePodIdentityAssociationHttp).

DescribePodIdentityAssociation: Inspecting Identity and Access

// init
const describePodIdentityAssociation =
  yield* AWS.EKS.DescribePodIdentityAssociation(cluster);

// runtime
const { association } = yield* describePodIdentityAssociation({
  associationId,
});

DescribeUpdate

Source: src/AWS/EKS/DescribeUpdate.ts

Runtime binding for eks:DescribeUpdate.

Reads one update’s status and parameters — poll it to track an in-flight version upgrade or config change. The cluster name is injected from the bound Cluster and eks:DescribeUpdate is granted on the cluster’s ARN and sub-resource ARNs. Provide the implementation with Effect.provide(AWS.EKS.DescribeUpdateHttp).

DescribeUpdate: Tracking Updates

// init
const describeUpdate = yield* AWS.EKS.DescribeUpdate(cluster);

// runtime
const { update } = yield* describeUpdate({ updateId });
const done = update?.status === "Successful";

FargateProfile

Source: src/AWS/EKS/FargateProfile.ts

An Amazon EKS Fargate profile — declares which pods (by namespace + labels) run on AWS Fargate serverless compute instead of on EC2 nodes.

Fargate profiles are immutable except for tags: any change to selectors, the pod execution role, or subnets forces a replacement. Create and delete are asynchronous (CREATING → ACTIVE, DELETING → gone, ~1–2 min each) and the provider waits for the terminal state. EKS allows only one Fargate profile per cluster to be creating or deleting at a time, so the provider retries the ResourceInUseException that surfaces when a peer profile operation is in flight.

Fargate pods must run in private subnets — pass private subnet IDs only.

FargateProfile: Creating Fargate Profiles

Run the default Namespace on Fargate

const profile = yield* FargateProfile("DefaultFargate", {
  clusterName: cluster.clusterName,
  podExecutionRoleArn: podRole.roleArn,
  subnets: network.privateSubnetIds,
  selectors: [{ namespace: "default" }],
});

Select Pods by Namespace and Labels

const profile = yield* FargateProfile("BatchFargate", {
  clusterName: cluster.clusterName,
  podExecutionRoleArn: podRole.roleArn,
  subnets: network.privateSubnetIds,
  selectors: [
    { namespace: "batch", labels: { compute: "fargate" } },
  ],
});

ListAccessEntries

Source: src/AWS/EKS/ListAccessEntries.ts

Runtime binding for eks:ListAccessEntries.

Enumerates the IAM principal ARNs granted Kubernetes access to the bound cluster via access entries. The cluster clusterName is injected from the bound Cluster and eks:ListAccessEntries is granted on the cluster’s ARN. Provide the implementation with Effect.provide(AWS.EKS.ListAccessEntriesHttp).

ListAccessEntries: Inspecting Identity and Access

// init
const listAccessEntries = yield* AWS.EKS.ListAccessEntries(cluster);

// runtime
const { accessEntries } = yield* listAccessEntries();

ListAccessPolicies

Source: src/AWS/EKS/ListAccessPolicies.ts

Runtime binding for eks:ListAccessPolicies.

Enumerates the AWS-managed EKS access policies (AmazonEKSAdminPolicy, AmazonEKSViewPolicy, …) that can be associated with access entries. eks:ListAccessPolicies is granted on * — the operation is account-scoped and takes no resource. Provide the implementation with Effect.provide(AWS.EKS.ListAccessPoliciesHttp).

ListAccessPolicies: Discovering Clusters

// init
const listAccessPolicies = yield* AWS.EKS.ListAccessPolicies();

// runtime
const { accessPolicies } = yield* listAccessPolicies();

ListAddons

Source: src/AWS/EKS/ListAddons.ts

Runtime binding for eks:ListAddons.

Enumerates the add-on names installed on the bound cluster. The cluster clusterName is injected from the bound Cluster and eks:ListAddons is granted on the cluster’s ARN. Provide the implementation with Effect.provide(AWS.EKS.ListAddonsHttp).

ListAddons: Inspecting Add-ons

// init
const listAddons = yield* AWS.EKS.ListAddons(cluster);

// runtime
const { addons } = yield* listAddons();

ListAssociatedAccessPolicies

Source: src/AWS/EKS/ListAssociatedAccessPolicies.ts

Runtime binding for eks:ListAssociatedAccessPolicies.

Enumerates the EKS access policies associated with one access entry’s IAM principal. The cluster clusterName is injected from the bound Cluster and eks:ListAssociatedAccessPolicies is granted on the cluster’s sub-resource ARNs. Provide the implementation with Effect.provide(AWS.EKS.ListAssociatedAccessPoliciesHttp).

ListAssociatedAccessPolicies: Inspecting Identity and Access

// init
const listAssociatedAccessPolicies =
  yield* AWS.EKS.ListAssociatedAccessPolicies(cluster);

// runtime
const { associatedAccessPolicies } = yield* listAssociatedAccessPolicies({
  principalArn,
});

ListCapabilities

Source: src/AWS/EKS/ListCapabilities.ts

Runtime binding for eks:ListCapabilities.

Enumerates the managed capabilities (e.g. Argo CD) installed on the bound cluster. The cluster clusterName is injected from the bound Cluster and eks:ListCapabilities is granted on the cluster’s ARN. Provide the implementation with Effect.provide(AWS.EKS.ListCapabilitiesHttp).

ListCapabilities: Cluster Capabilities

// init
const listCapabilities = yield* AWS.EKS.ListCapabilities(cluster);

// runtime
const { capabilities } = yield* listCapabilities();

ListClusters

Source: src/AWS/EKS/ListClusters.ts

Runtime binding for eks:ListClusters.

Enumerates the EKS cluster names in the caller’s account and region. eks:ListClusters is granted on * — the operation is account-scoped and takes no resource. Provide the implementation with Effect.provide(AWS.EKS.ListClustersHttp).

ListClusters: Discovering Clusters

// init
const listClusters = yield* AWS.EKS.ListClusters();

// runtime
const { clusters } = yield* listClusters();

ListFargateProfiles

Source: src/AWS/EKS/ListFargateProfiles.ts

Runtime binding for eks:ListFargateProfiles.

Enumerates the Fargate profile names configured on the bound cluster. The cluster clusterName is injected from the bound Cluster and eks:ListFargateProfiles is granted on the cluster’s ARN. Provide the implementation with Effect.provide(AWS.EKS.ListFargateProfilesHttp).

ListFargateProfiles: Inspecting Compute

// init
const listFargateProfiles = yield* AWS.EKS.ListFargateProfiles(cluster);

// runtime
const { fargateProfileNames } = yield* listFargateProfiles();

ListIdentityProviderConfigs

Source: src/AWS/EKS/ListIdentityProviderConfigs.ts

Runtime binding for eks:ListIdentityProviderConfigs.

Enumerates the OIDC identity provider configurations associated with the bound cluster. The cluster clusterName is injected from the bound Cluster and eks:ListIdentityProviderConfigs is granted on the cluster’s ARN. Provide the implementation with Effect.provide(AWS.EKS.ListIdentityProviderConfigsHttp).

ListIdentityProviderConfigs: Identity Provider Configs

// init
const listIdentityProviderConfigs =
  yield* AWS.EKS.ListIdentityProviderConfigs(cluster);

// runtime
const { identityProviderConfigs } = yield* listIdentityProviderConfigs();

ListInsights

Source: src/AWS/EKS/ListInsights.ts

Runtime binding for eks:ListInsights.

Enumerates EKS upgrade/configuration insights for the bound cluster — findings that block or degrade a Kubernetes version upgrade. The cluster clusterName is injected from the bound Cluster and eks:ListInsights is granted on the cluster’s ARN. Provide the implementation with Effect.provide(AWS.EKS.ListInsightsHttp).

ListInsights: Cluster Insights

// init
const listInsights = yield* AWS.EKS.ListInsights(cluster);

// runtime
const { insights } = yield* listInsights({
  filter: { statuses: ["ERROR", "WARNING"] },
});

ListNodegroups

Source: src/AWS/EKS/ListNodegroups.ts

Runtime binding for eks:ListNodegroups.

Enumerates the managed node group names attached to the bound cluster. The cluster clusterName is injected from the bound Cluster and eks:ListNodegroups is granted on the cluster’s ARN. Provide the implementation with Effect.provide(AWS.EKS.ListNodegroupsHttp).

ListNodegroups: Inspecting Compute

// init
const listNodegroups = yield* AWS.EKS.ListNodegroups(cluster);

// runtime
const { nodegroups } = yield* listNodegroups();

ListPodIdentityAssociations

Source: src/AWS/EKS/ListPodIdentityAssociations.ts

Runtime binding for eks:ListPodIdentityAssociations.

Enumerates the EKS Pod Identity associations on the bound cluster, optionally filtered by namespace or service account. The cluster clusterName is injected from the bound Cluster and eks:ListPodIdentityAssociations is granted on the cluster’s ARN. Provide the implementation with Effect.provide(AWS.EKS.ListPodIdentityAssociationsHttp).

ListPodIdentityAssociations: Inspecting Identity and Access

// init
const listPodIdentityAssociations =
  yield* AWS.EKS.ListPodIdentityAssociations(cluster);

// runtime
const { associations } = yield* listPodIdentityAssociations({
  namespace: "default",
});

ListUpdates

Source: src/AWS/EKS/ListUpdates.ts

Runtime binding for eks:ListUpdates.

Enumerates the update IDs issued against the bound cluster (or one of its node groups / add-ons). The cluster name is injected from the bound Cluster and eks:ListUpdates is granted on the cluster’s ARN and sub-resource ARNs. Provide the implementation with Effect.provide(AWS.EKS.ListUpdatesHttp).

ListUpdates: Tracking Updates

// init
const listUpdates = yield* AWS.EKS.ListUpdates(cluster);

// runtime
const { updateIds } = yield* listUpdates();

Nodegroup

Source: src/AWS/EKS/Nodegroup.ts

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.

Nodegroup: Creating Node Groups

Managed Node Group

const nodes = yield* Nodegroup("AppNodes", {
  clusterName: cluster.clusterName,
  nodeRole: nodeRole.roleArn,
  subnets: network.privateSubnetIds,
  instanceTypes: ["t3.medium"],
  scalingConfig: { minSize: 1, maxSize: 3, desiredSize: 2 },
});

Spot Node Group with Labels and Taints

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" }],
});

PodIdentityAssociation

Source: src/AWS/EKS/PodIdentityAssociation.ts

An Amazon EKS pod identity association that binds a service account to an IAM role.

PodIdentityAssociation is the canonical workload-identity resource for EKS clusters that use EKS Pod Identity instead of IRSA.

PodIdentityAssociation: Managing Pod Identity

const association = yield* PodIdentityAssociation("ApiIdentity", {
  clusterName: cluster.clusterName,
  namespace: "default",
  serviceAccount: "api",
  roleArn: podRole.roleArn,
});

StartInsightsRefresh

Source: src/AWS/EKS/StartInsightsRefresh.ts

Runtime binding for eks:StartInsightsRefresh.

Kicks off an on-demand refresh of the bound cluster’s upgrade/configuration insights instead of waiting for the periodic automatic evaluation. Track progress with DescribeInsightsRefresh. The cluster clusterName is injected from the bound Cluster and eks:StartInsightsRefresh is granted on the cluster’s ARN. Provide the implementation with Effect.provide(AWS.EKS.StartInsightsRefreshHttp).

StartInsightsRefresh: Cluster Insights

// init
const startInsightsRefresh = yield* AWS.EKS.StartInsightsRefresh(cluster);

// runtime
const { status } = yield* startInsightsRefresh();