aws-eks-v2-alpha: update EKS access entry types and add type property on grantAccess

[daniel-rhoades]

Describe the bug

When provisioning an EKS cluster in Auto Mode using the L2 construct within the aws_eks_v2_alpha library, construct users may elect to define their own node classes and pools, disabling the default node classes and pools as a result. After defining their own node classes and pools, they must create/use an IAM role to act as the "Node Role". This role must be explicitly granted access to the cluster.

When creating an access entry, the following must be specified:

• Principal ARN
• Type
• Access Policies

However, the grantAccess method on the Cluster class does not currently support specifying a type argument, instead defaulting to STANDARD - which is incorrect for an Node Role when using EKS Auto Mode which requires the type EC2 .

Within CloudFormation, the AWS::EKS::AccessEntry (now) supports the following types:

• STANDARD
• FARGATE_LINUX
• EC2_LINUX
• EC2_WINDOWS
• EC2 (for EKS Auto Mode)
• HYBRID_LINUX
• HYPERPOD_LINUX

Even if grantAccess were to accept a type, currently AccessEntry only accepts the following types:

• STANDARD
• FARGATE_LINUX
• EC2_LINUX
• EC2_WINDOWS

Regression Issue

• Select this option if this issue appears to be a regression.

Last Known Working CDK Library Version

No response

Expected Behavior

The grantAccess method should accept and honour a given type argument so EKS Node Roles can be correctly authorised.

Current Behavior

When an IAM role (intended to be used as an EKS Node Role) is granted access via grantAccess, an access entry of type STANDARD is created which prevents node creation.

Reproduction Steps

1. Define an EKS cluster using the L2 aws_eks_v2_alpha construct and specify an empty node pool within the compute config
2. Use/create an appropriate IAM Role intended to be used as an EKS Node Role
3. Define at least one custom node class and pool
4. Grant IAM Role access to the cluster via cluster.grantAccess

After provisioning the above, the access entry for the IAM Role is only STANDARD and as a result no nodes are created.

Possible Solution

Suggested Solution

• In Cluster, for the grantAccess method, accept an optional type argument and pass it along accordingly
• Update the list of available choices in AccessEntryType to reflect that which is available within CloudFormation

Workarounds
Option 1
A manual workaround would be to delete the corresponding access entry (as the type can't be changed), then manually recreate it with the type EC2. Afterwards nodes will start being created as expected.

Option 2
Use an L1 CfnAccessEntry construct to create the required access entry in lieu of using grantAccess on the L2 cluster construct.

Option 3
Use an escape hatch to change the type property in the corresponding AccessEntry (Python example):

# Define the cluster
cluster = ...

# Define an IAM Role to use as the EKS Node
node_role = ...

# Grant the node role access to the cluster
cluster.grant_access(
  'DefaultNodeRoleClusterAdminAccess', 
  node_role.role_arn,
  [eks_v2.AccessPolicy.from_access_policy_name('AmazonEKSAutoNodePolicy', access_scope_type=eks_v2.AccessScopeType.CLUSTER)]
)

# Find the corresponding L1 CfnAccessEntry for the previously referenced node role  
access_entry = next(filter(
  lambda c: isinstance(c, eks_v2.AccessEntry) and c.node.default_child.principal_arn == node_role.role_arn, 
  cluster.node.children
))

# Use an escape-hatch to override the Access Entry type for the node role from STANDARD to EC2
access_entry.node.default_child.add_property_override('Type', 'EC2')

Additional Information/Context

If relevant, this was observed on a fully-private cluster but shouldn't be a factor for this issue.

AWS CDK Library version (aws-cdk-lib)

2.182.0

AWS CDK CLI version

2.1012.0 (build e4c1f15)

Node.js Version

v22.14.0

OS

macOS

Language

Python

Language Version

3.11.11

Other information

No response

[ykethan]

Hey @daniel-rhoades, Thanks for reporting this issue. I was able to reproduce the issue and can confirm this does appear to occur on both the alpha and stable CDK libraries.

When provisioning an EKS cluster in Auto Mode with custom node pools, the grantAccess method creates access entries with the default STANDARD type, which prevents node roles from joining the cluster since Auto Mode specifically requires the EC2 type.

As you have correctly pointed, currently:

1. The AccessEntryType enum doesn't include the EC2 type needed for Auto Mode:

export enum AccessEntryType {
  STANDARD = 'STANDARD',
  FARGATE_LINUX = 'FARGATE_LINUX',
  EC2_LINUX = 'EC2_LINUX',
  EC2_WINDOWS = 'EC2_WINDOWS'
  // Missing: EC2, HYBRID_LINUX, HYPERPOD_LINUX
}

2. The grantAccess method doesn't allow specifying an access entry type:

public grantAccess(id: string, principal: string, accessPolicies: IAccessPolicy[]) {
  this.addToAccessEntry(id, principal, accessPolicies);
}

reproduction:

import * as cdk from 'aws-cdk-lib';
import * as ec2 from 'aws-cdk-lib/aws-ec2';
import * as iam from 'aws-cdk-lib/aws-iam';
import { Construct } from 'constructs';
import * as eks from '@aws-cdk/aws-eks-v2-alpha';
import { KubectlV32Layer } from '@aws-cdk/lambda-layer-kubectl-v32';

export class EksAutoModeIssueStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // Create a VPC
    const vpc = new ec2.Vpc(this, 'Vpc', { natGateways: 1 });

    // Create roles
    const mastersRole = new iam.Role(this, 'MastersRole', {
      assumedBy: new iam.AccountRootPrincipal(),
    });

    // Create a custom node role 
    const nodeRole = new iam.Role(this, 'NodeRole', {
      assumedBy: new iam.ServicePrincipal('ec2.amazonaws.com'),
      managedPolicies: [
        iam.ManagedPolicy.fromAwsManagedPolicyName('AmazonEKSWorkerNodePolicy'),
        iam.ManagedPolicy.fromAwsManagedPolicyName('AmazonEKS_CNI_Policy'),
        iam.ManagedPolicy.fromAwsManagedPolicyName(
          'AmazonEC2ContainerRegistryReadOnly',
        ),
      ],
    });

    // Create the cluster with Auto Mode enabled but no default node pools
    const cluster = new eks.Cluster(this, 'Cluster', {
      vpc,
      mastersRole,
      version: eks.KubernetesVersion.V1_32,
      kubectlProviderOptions: {
        kubectlLayer: new KubectlV32Layer(this, 'KubectlLayer'),
      },
      defaultCapacityType: eks.DefaultCapacityType.AUTOMODE,
      compute: {
        // Empty node pools - create our own
        nodePools: [],
        // Explicitly use our custom node role
        nodeRole: nodeRole,
      },
    });

    cluster.grantAccess('NodeRoleAccess', nodeRole.roleArn, [
      eks.AccessPolicy.fromAccessPolicyName('AmazonEKSAutoNodePolicy', {
        accessScopeType: eks.AccessScopeType.CLUSTER,
      }),
    ]);
  
  }
}

cdk synth output:

ClusterNodeRoleAccess19ECC9D3:
  Type: AWS::EKS::AccessEntry
  Properties:
    AccessPolicies:
      - AccessScope:
          Type: cluster
        PolicyArn: arn:${AWS::Partition}:eks::aws:cluster-access-policy/AmazonEKSAutoNodePolicy
    ClusterName:
      Ref: ClusterEB0386A7
    PrincipalArn:
      Fn::GetAtt: [NodeRoleB5643E21, Arn]
    # Missing Type property - defaults to STANDARD internally

Proposed fix

Update the AccessEntryType enum and add type parameter to grantAccess:

// In packages/aws-cdk-lib/aws-eks/lib/access-entry.ts and alpha package

export enum AccessEntryType {
  STANDARD = 'STANDARD',
  FARGATE_LINUX = 'FARGATE_LINUX',
  EC2_LINUX = 'EC2_LINUX',
  EC2_WINDOWS = 'EC2_WINDOWS',
  EC2 = 'EC2',
  HYBRID_LINUX = 'HYBRID_LINUX',
  HYPERPOD_LINUX = 'HYPERPOD_LINUX'
}

// In packages/aws-cdk-lib/aws-eks/lib/cluster.ts and alpha package
public grantAccess(
  id: string, 
  principal: string, 
  accessPolicies: IAccessPolicy[], 
  accessEntryType?: AccessEntryType
) {
  this.addToAccessEntry(id, principal, accessPolicies, accessEntryType);
}

Workarounds

Option 1: Use the L1 CfnAccessEntry directly

import { CfnAccessEntry } from 'aws-cdk-lib/aws-eks';

new CfnAccessEntry(this, 'NodeRoleAccess', {
  clusterName: cluster.clusterName,
  principalArn: nodeRole.roleArn,
  type: 'EC2',  // set type
  accessPolicies: [{
    policyArn: `arn:${Stack.of(this).partition}:eks::aws:cluster-access-policy/AmazonEKSAutoNodePolicy`,
    accessScope: {
      type: 'cluster',
    },
  }],
});

Option 2: Use the L2 AccessEntry with an escape hatch

import { AccessEntry, AccessPolicy, AccessScopeType } from 'aws-cdk-lib/aws-eks';

// Create the AccessEntry with L2 construct
const accessEntry = new AccessEntry(this, 'NodeRoleAccessWithHatch', {
  cluster: cluster,
  principal: nodeRole.roleArn,
  accessPolicies: [
    AccessPolicy.fromAccessPolicyName('AmazonEKSAutoNodePolicy', {
      accessScopeType: AccessScopeType.CLUSTER,
    }),
  ],
});

// Use escape hatch to modify the type property
const cfnAccessEntry = accessEntry.node.defaultChild as CfnAccessEntry;
cfnAccessEntry.addPropertyOverride('Type', 'EC2');

Marking as P2 feature request to update EKS entry types and add entry type on grantAccess.
We greatly appreciate community contributions! If you or someone else is interested in implementing this, we'd be happy to review a Pull Request. Please check our contribution guidelines before starting.

We'll leave this issue open to track the request. Meanwhile, welcome to add 👍 to help us prioritize.