Class Cluster

A Cluster represents a managed Kubernetes Service (EKS).

Inheritance

object

Resource

Cluster

FargateCluster

Implements

ICluster

IResource

IConstruct

IDependable

IConnectable

Inherited Members

Resource.IsOwnedResource(IConstruct)

Resource.IsResource(IConstruct)

Resource.ApplyRemovalPolicy(RemovalPolicy)

Resource.GeneratePhysicalName()

Resource.GetResourceArnAttribute(string, IArnComponents)

Resource.GetResourceNameAttribute(string)

Resource.Env

Resource.PhysicalName

Resource.Stack

Namespace: Amazon.CDK.AWS.EKS

Assembly: Amazon.CDK.Lib.dll

Syntax (csharp)

public class Cluster : Resource, ICluster, IResource, IConstruct, IDependable, IConnectable

Syntax (vb)

Public Class Cluster Inherits Resource Implements ICluster, IResource, IConstruct, IDependable, IConnectable

Remarks

This is a fully managed cluster of API Servers (control-plane) The user is still required to create the worker nodes.

ExampleMetadata: infused

Examples

using Amazon.CDK.LambdaLayer.KubectlV32;

             // or
             Vpc vpc;


             new Cluster(this, "MyCluster", new ClusterProps {
                 KubectlMemory = Size.Gibibytes(4),
                 Version = KubernetesVersion.V1_32,
                 KubectlLayer = new KubectlV32Layer(this, "kubectl")
             });
             Cluster.FromClusterAttributes(this, "MyCluster", new ClusterAttributes {
                 KubectlMemory = Size.Gibibytes(4),
                 Vpc = vpc,
                 ClusterName = "cluster-name"
             });

Synopsis

Constructors

Cluster(Construct, string, IClusterProps)

Initiates an EKS Cluster with the supplied arguments.

Properties

AdminRole	An IAM role with administrative permissions to create or update the cluster.
AlbController	The ALB Controller construct defined for this cluster.
AuthenticationMode	The authentication mode for the Amazon EKS cluster.
AwsAuth	Lazily creates the AwsAuth resource, which manages AWS authentication mapping.
AwscliLayer	An AWS Lambda layer that contains the `aws` CLI.
ClusterArn	The AWS generated ARN for the Cluster resource.
ClusterCertificateAuthorityData	The certificate-authority-data for your cluster.
ClusterEncryptionConfigKeyArn	Amazon Resource Name (ARN) or alias of the customer master key (CMK).
ClusterEndpoint	The endpoint URL for the Cluster.
ClusterHandlerSecurityGroup	A security group to associate with the Cluster Handler's Lambdas.
ClusterName	The Name of the created EKS Cluster.
ClusterOpenIdConnectIssuer	If this cluster is kubectl-enabled, returns the OpenID Connect issuer.
ClusterOpenIdConnectIssuerUrl	If this cluster is kubectl-enabled, returns the OpenID Connect issuer url.
ClusterSecurityGroup	The cluster security group that was created by Amazon EKS for the cluster.
ClusterSecurityGroupId	The id of the cluster security group that was created by Amazon EKS for the cluster.
Connections	Manages connection rules (Security Group Rules) for the cluster.
DefaultCapacity	The auto scaling group that hosts the default capacity for this cluster.
DefaultNodegroup	The node group that hosts the default capacity for this cluster.
EksPodIdentityAgent	Retrieves the EKS Pod Identity Agent addon for the EKS cluster.
IpFamily	Specify which IP family is used to assign Kubernetes pod and service IP addresses.
KubectlEnvironment	Custom environment variables when running `kubectl` against this cluster.
KubectlLambdaRole	An IAM role that can perform kubectl operations against this cluster.
KubectlLayer	An AWS Lambda layer that includes `kubectl` and `helm`.
KubectlMemory	The amount of memory allocated to the kubectl provider's lambda function.
KubectlPrivateSubnets	Subnets to host the `kubectl` compute resources.
KubectlRole	An IAM role that can perform kubectl operations against this cluster.
KubectlSecurityGroup	A security group to use for `kubectl` execution.
OnEventLayer	The AWS Lambda layer that contains the NPM dependency `proxy-agent`.
OpenIdConnectProvider	An `OpenIdConnectProvider` resource associated with this cluster, and which can be used to link this cluster to AWS IAM.
PROPERTY_INJECTION_ID	Uniquely identifies this class.
Prune	Determines if Kubernetes resources can be pruned automatically.
Role	IAM role assumed by the EKS Control Plane.
Vpc	The VPC in which this Cluster was created.

Methods

AddAutoScalingGroupCapacity(string, IAutoScalingGroupCapacityOptions)	Add nodes to this EKS cluster.
AddCdk8sChart(string, Construct, IKubernetesManifestOptions?)	Defines a CDK8s chart in this cluster.
AddFargateProfile(string, IFargateProfileOptions)	Adds a Fargate profile to this cluster.
AddHelmChart(string, IHelmChartOptions)	Defines a Helm chart in this cluster.
AddManifest(string, params IDictionary<string, object>[])	Defines a Kubernetes resource in this cluster.
AddNodegroupCapacity(string, INodegroupOptions?)	Add managed nodegroup to this Amazon EKS cluster.
AddServiceAccount(string, IServiceAccountOptions?)	Creates a new service account with corresponding IAM Role (IRSA).
ConnectAutoScalingGroupCapacity(AutoScalingGroup, IAutoScalingGroupOptions)	Connect capacity in the form of an existing AutoScalingGroup to the EKS cluster.
FromClusterAttributes(Construct, string, IClusterAttributes)	Import an existing cluster.
GetIngressLoadBalancerAddress(string, IIngressLoadBalancerAddressOptions?)	Fetch the load balancer address of an ingress backed by a load balancer.
GetServiceLoadBalancerAddress(string, IServiceLoadBalancerAddressOptions?)	Fetch the load balancer address of a service of type 'LoadBalancer'.
GrantAccess(string, string, IAccessPolicy[])	Grants the specified IAM principal access to the EKS cluster based on the provided access policies.

Constructors

Cluster(Construct, string, IClusterProps)

Initiates an EKS Cluster with the supplied arguments.

public Cluster(Construct scope, string id, IClusterProps props)

Parameters

scope Construct: a Construct, most likely a cdk.Stack created.
id string: the id of the Construct to create.
props IClusterProps: properties in the IClusterProps interface.

Remarks

This is a fully managed cluster of API Servers (control-plane) The user is still required to create the worker nodes.

ExampleMetadata: infused

Properties

AdminRole

An IAM role with administrative permissions to create or update the cluster.

public virtual Role AdminRole { get; }

Property Value

Role

Remarks

This role also has systems:master permissions.

AlbController

The ALB Controller construct defined for this cluster.

public virtual AlbController? AlbController { get; }

Property Value

AlbController

Remarks

Will be undefined if albController wasn't configured.

AuthenticationMode

The authentication mode for the Amazon EKS cluster.

public virtual AuthenticationMode? AuthenticationMode { get; }

Property Value

AuthenticationMode?

Remarks

The authentication mode determines how users and applications authenticate to the Kubernetes API server.

Default: CONFIG_MAP.

Property: {AuthenticationMode} [authenticationMode] - The authentication mode for the Amazon EKS cluster.

AwsAuth

Lazily creates the AwsAuth resource, which manages AWS authentication mapping.

public virtual AwsAuth AwsAuth { get; }

Property Value

AwsAuth

Remarks

This is a fully managed cluster of API Servers (control-plane) The user is still required to create the worker nodes.

ExampleMetadata: infused

AwscliLayer

An AWS Lambda layer that contains the aws CLI.

public virtual ILayerVersion? AwscliLayer { get; }

Property Value

ILayerVersion

Remarks

If not defined, a default layer will be used containing the AWS CLI 1.x.

ClusterArn

The AWS generated ARN for the Cluster resource.

public virtual string ClusterArn { get; }

Property Value

string

Remarks

For example, arn:aws:eks:us-west-2:666666666666:cluster/prod

ClusterCertificateAuthorityData

The certificate-authority-data for your cluster.

public virtual string ClusterCertificateAuthorityData { get; }

Property Value

string

Remarks

This is a fully managed cluster of API Servers (control-plane) The user is still required to create the worker nodes.

ExampleMetadata: infused

ClusterEncryptionConfigKeyArn

Amazon Resource Name (ARN) or alias of the customer master key (CMK).

public virtual string ClusterEncryptionConfigKeyArn { get; }

Property Value

string

Remarks

This is a fully managed cluster of API Servers (control-plane) The user is still required to create the worker nodes.

ExampleMetadata: infused

ClusterEndpoint

The endpoint URL for the Cluster.

public virtual string ClusterEndpoint { get; }

Property Value

string

Remarks

This is the URL inside the kubeconfig file to use with kubectl

For example, https://5E1D0CEXAMPLEA591B746AFC5AB30262.yl4.us-west-2.eks.amazonaws.com

ClusterHandlerSecurityGroup

A security group to associate with the Cluster Handler's Lambdas.

public virtual ISecurityGroup? ClusterHandlerSecurityGroup { get; }

Property Value

ISecurityGroup

Remarks

The Cluster Handler's Lambdas are responsible for calling AWS's EKS API.

Requires placeClusterHandlerInVpc to be set to true.

Default: - No security group.

ClusterName

The Name of the created EKS Cluster.

public virtual string ClusterName { get; }

Property Value

string

Remarks

This is a fully managed cluster of API Servers (control-plane) The user is still required to create the worker nodes.

ExampleMetadata: infused

ClusterOpenIdConnectIssuer

If this cluster is kubectl-enabled, returns the OpenID Connect issuer.

public virtual string ClusterOpenIdConnectIssuer { get; }

Property Value

string

Remarks

This is because the values is only be retrieved by the API and not exposed by CloudFormation. If this cluster is not kubectl-enabled (i.e. uses the stock CfnCluster), this is undefined.

Attribute: true

ClusterOpenIdConnectIssuerUrl

If this cluster is kubectl-enabled, returns the OpenID Connect issuer url.

public virtual string ClusterOpenIdConnectIssuerUrl { get; }

Property Value

string

Remarks

This is because the values is only be retrieved by the API and not exposed by CloudFormation. If this cluster is not kubectl-enabled (i.e. uses the stock CfnCluster), this is undefined.

Attribute: true

ClusterSecurityGroup

The cluster security group that was created by Amazon EKS for the cluster.

public virtual ISecurityGroup ClusterSecurityGroup { get; }

Property Value

ISecurityGroup

Remarks

This is a fully managed cluster of API Servers (control-plane) The user is still required to create the worker nodes.

ExampleMetadata: infused

ClusterSecurityGroupId

The id of the cluster security group that was created by Amazon EKS for the cluster.

public virtual string ClusterSecurityGroupId { get; }

Property Value

string

Remarks

This is a fully managed cluster of API Servers (control-plane) The user is still required to create the worker nodes.

ExampleMetadata: infused

Connections

Manages connection rules (Security Group Rules) for the cluster.

public virtual Connections_ Connections { get; }

Property Value

Connections_

Remarks

Memberof: Cluster

Type: {ec2.Connections}

DefaultCapacity

The auto scaling group that hosts the default capacity for this cluster.

public virtual AutoScalingGroup? DefaultCapacity { get; }

Property Value

AutoScalingGroup

Remarks

This will be undefined if the defaultCapacityType is not EC2 or defaultCapacityType is EC2 but default capacity is set to 0.

DefaultNodegroup

The node group that hosts the default capacity for this cluster.

public virtual Nodegroup? DefaultNodegroup { get; }

Property Value

Nodegroup

Remarks

This will be undefined if the defaultCapacityType is EC2 or defaultCapacityType is NODEGROUP but default capacity is set to 0.

EksPodIdentityAgent

Retrieves the EKS Pod Identity Agent addon for the EKS cluster.

public virtual IAddon? EksPodIdentityAgent { get; }

Property Value

IAddon

Remarks

The EKS Pod Identity Agent is responsible for managing the temporary credentials used by pods in the cluster to access AWS resources. It runs as a DaemonSet on each node and provides the necessary credentials to the pods based on their associated service account.

IpFamily

Specify which IP family is used to assign Kubernetes pod and service IP addresses.

public virtual IpFamily? IpFamily { get; }

Property Value

IpFamily?

Remarks

Default: - IpFamily.IP_V4

See: https://docs.aws.amazon.com/eks/latest/APIReference/API_KubernetesNetworkConfigRequest.html#AmazonEKS-Type-KubernetesNetworkConfigRequest-ipFamily

KubectlEnvironment

Custom environment variables when running kubectl against this cluster.

public virtual IDictionary<string, string>? KubectlEnvironment { get; }

Property Value

IDictionary<string, string>

Remarks

This is a fully managed cluster of API Servers (control-plane) The user is still required to create the worker nodes.

ExampleMetadata: infused

KubectlLambdaRole

An IAM role that can perform kubectl operations against this cluster.

public virtual IRole? KubectlLambdaRole { get; }

Property Value

IRole

Remarks

The role should be mapped to the system:masters Kubernetes RBAC role.

This role is directly passed to the lambda handler that sends Kube Ctl commands to the cluster.

Default: - if not specified, the default role created by a lambda function will be used.

KubectlLayer

An AWS Lambda layer that includes kubectl and helm.

public virtual ILayerVersion? KubectlLayer { get; }

Property Value

ILayerVersion

Remarks

This is a fully managed cluster of API Servers (control-plane) The user is still required to create the worker nodes.

ExampleMetadata: infused

KubectlMemory

The amount of memory allocated to the kubectl provider's lambda function.

public virtual Size? KubectlMemory { get; }

Property Value

Size

Remarks

This is a fully managed cluster of API Servers (control-plane) The user is still required to create the worker nodes.

ExampleMetadata: infused

KubectlPrivateSubnets

Subnets to host the kubectl compute resources.

public virtual ISubnet[]? KubectlPrivateSubnets { get; }

Property Value

ISubnet[]

Remarks

Default: - If not specified, the k8s endpoint is expected to be accessible publicly.

KubectlRole

An IAM role that can perform kubectl operations against this cluster.

public virtual IRole? KubectlRole { get; }

Property Value

IRole

Remarks

The role should be mapped to the system:masters Kubernetes RBAC role.

KubectlSecurityGroup

A security group to use for kubectl execution.

public virtual ISecurityGroup? KubectlSecurityGroup { get; }

Property Value

ISecurityGroup

Remarks

Default: - If not specified, the k8s endpoint is expected to be accessible publicly.

OnEventLayer

The AWS Lambda layer that contains the NPM dependency proxy-agent.

public virtual ILayerVersion? OnEventLayer { get; }

Property Value

ILayerVersion

Remarks

If undefined, a SAR app that contains this layer will be used.

OpenIdConnectProvider

An OpenIdConnectProvider resource associated with this cluster, and which can be used to link this cluster to AWS IAM.

public virtual IOpenIdConnectProvider OpenIdConnectProvider { get; }

Property Value

IOpenIdConnectProvider

Remarks

A provider will only be defined if this property is accessed (lazy initialization).

PROPERTY_INJECTION_ID

Uniquely identifies this class.

public static string PROPERTY_INJECTION_ID { get; }

Property Value

string

Remarks

This is a fully managed cluster of API Servers (control-plane) The user is still required to create the worker nodes.

ExampleMetadata: infused

Prune

Determines if Kubernetes resources can be pruned automatically.

public virtual bool Prune { get; }

Property Value

bool

Remarks

This is a fully managed cluster of API Servers (control-plane) The user is still required to create the worker nodes.

ExampleMetadata: infused

Role

IAM role assumed by the EKS Control Plane.

public virtual IRole Role { get; }

Property Value

IRole

Remarks

This is a fully managed cluster of API Servers (control-plane) The user is still required to create the worker nodes.

ExampleMetadata: infused

Vpc

The VPC in which this Cluster was created.

public virtual IVpc Vpc { get; }

Property Value

IVpc

Remarks

This is a fully managed cluster of API Servers (control-plane) The user is still required to create the worker nodes.

ExampleMetadata: infused

Methods

AddAutoScalingGroupCapacity(string, IAutoScalingGroupCapacityOptions)

Add nodes to this EKS cluster.

public virtual AutoScalingGroup AddAutoScalingGroupCapacity(string id, IAutoScalingGroupCapacityOptions options)

Parameters

id string
options IAutoScalingGroupCapacityOptions

Returns

AutoScalingGroup

Remarks

The nodes will automatically be configured with the right VPC and AMI for the instance type and Kubernetes version.

Note that if you specify updateType: RollingUpdate or updateType: ReplacingUpdate, your nodes might be replaced at deploy time without notice in case the recommended AMI for your machine image type has been updated by AWS. The default behavior for updateType is None, which means only new instances will be launched using the new AMI.

Spot instances will be labeled lifecycle=Ec2Spot and tainted with PreferNoSchedule. In addition, the spot interrupt handler daemon will be installed on all spot instances to handle EC2 Spot Instance Termination Notices.

AddCdk8sChart(string, Construct, IKubernetesManifestOptions?)

Defines a CDK8s chart in this cluster.

public virtual KubernetesManifest AddCdk8sChart(string id, Construct chart, IKubernetesManifestOptions? options = null)

Parameters

id string: logical id of this chart.
chart Construct: the cdk8s chart.
options IKubernetesManifestOptions: logical id of this chart.

Returns

KubernetesManifest

a KubernetesManifest construct representing the chart.

Remarks

This is a fully managed cluster of API Servers (control-plane) The user is still required to create the worker nodes.

ExampleMetadata: infused

AddFargateProfile(string, IFargateProfileOptions)

Adds a Fargate profile to this cluster.

public virtual FargateProfile AddFargateProfile(string id, IFargateProfileOptions options)

Parameters

id string: the id of this profile.
options IFargateProfileOptions: profile options.

Returns

FargateProfile

Remarks

See: https://docs.aws.amazon.com/eks/latest/userguide/fargate-profile.html

AddHelmChart(string, IHelmChartOptions)

Defines a Helm chart in this cluster.

public virtual HelmChart AddHelmChart(string id, IHelmChartOptions options)

Parameters

id string: logical id of this chart.
options IHelmChartOptions: options of this chart.

Returns

HelmChart

a HelmChart construct

Remarks

This is a fully managed cluster of API Servers (control-plane) The user is still required to create the worker nodes.

ExampleMetadata: infused

AddManifest(string, params IDictionary<string, object>[])

Defines a Kubernetes resource in this cluster.

public virtual KubernetesManifest AddManifest(string id, params IDictionary<string, object>[] manifest)

Parameters

id string: logical id of this manifest.
manifest IDictionary<string, object>[]: a list of Kubernetes resource specifications.

Returns

KubernetesManifest

a KubernetesResource object.

Remarks

The manifest will be applied/deleted using kubectl as needed.

AddNodegroupCapacity(string, INodegroupOptions?)

Add managed nodegroup to this Amazon EKS cluster.

public virtual Nodegroup AddNodegroupCapacity(string id, INodegroupOptions? options = null)

Parameters

id string: The ID of the nodegroup.
options INodegroupOptions: options for creating a new nodegroup.

Returns

Nodegroup

Remarks

This method will create a new managed nodegroup and add into the capacity.

See: https://docs.aws.amazon.com/eks/latest/userguide/managed-node-groups.html

AddServiceAccount(string, IServiceAccountOptions?)

Creates a new service account with corresponding IAM Role (IRSA).

public virtual ServiceAccount AddServiceAccount(string id, IServiceAccountOptions? options = null)

Parameters

id string
options IServiceAccountOptions

Returns

ServiceAccount

Remarks

This is a fully managed cluster of API Servers (control-plane) The user is still required to create the worker nodes.

ExampleMetadata: infused

ConnectAutoScalingGroupCapacity(AutoScalingGroup, IAutoScalingGroupOptions)

Connect capacity in the form of an existing AutoScalingGroup to the EKS cluster.

public virtual void ConnectAutoScalingGroupCapacity(AutoScalingGroup autoScalingGroup, IAutoScalingGroupOptions options)

Parameters

autoScalingGroup AutoScalingGroup: [disable-awslint:ref-via-interface].
options IAutoScalingGroupOptions: options for adding auto scaling groups, like customizing the bootstrap script.

Remarks

The AutoScalingGroup must be running an EKS-optimized AMI containing the /etc/eks/bootstrap.sh script. This method will configure Security Groups, add the right policies to the instance role, apply the right tags, and add the required user data to the instance's launch configuration.

Spot instances will be labeled lifecycle=Ec2Spot and tainted with PreferNoSchedule. If kubectl is enabled, the spot interrupt handler daemon will be installed on all spot instances to handle EC2 Spot Instance Termination Notices.

Prefer to use addAutoScalingGroupCapacity if possible.

See: https://docs.aws.amazon.com/eks/latest/userguide/launch-workers.html

FromClusterAttributes(Construct, string, IClusterAttributes)

Import an existing cluster.

public static ICluster FromClusterAttributes(Construct scope, string id, IClusterAttributes attrs)

Parameters

scope Construct: the construct scope, in most cases 'this'.
id string: the id or name to import as.
attrs IClusterAttributes: the cluster properties to use for importing information.

Returns

ICluster

Remarks

This is a fully managed cluster of API Servers (control-plane) The user is still required to create the worker nodes.

ExampleMetadata: infused

GetIngressLoadBalancerAddress(string, IIngressLoadBalancerAddressOptions?)

Fetch the load balancer address of an ingress backed by a load balancer.

public virtual string GetIngressLoadBalancerAddress(string ingressName, IIngressLoadBalancerAddressOptions? options = null)

Parameters

ingressName string: The name of the ingress.
options IIngressLoadBalancerAddressOptions: Additional operation options.

Returns

string

Remarks

This is a fully managed cluster of API Servers (control-plane) The user is still required to create the worker nodes.

ExampleMetadata: infused

GetServiceLoadBalancerAddress(string, IServiceLoadBalancerAddressOptions?)

Fetch the load balancer address of a service of type 'LoadBalancer'.

public virtual string GetServiceLoadBalancerAddress(string serviceName, IServiceLoadBalancerAddressOptions? options = null)

Parameters

serviceName string: The name of the service.
options IServiceLoadBalancerAddressOptions: Additional operation options.

Returns

string

Remarks

This is a fully managed cluster of API Servers (control-plane) The user is still required to create the worker nodes.

ExampleMetadata: infused

GrantAccess(string, string, IAccessPolicy[])

Grants the specified IAM principal access to the EKS cluster based on the provided access policies.

public virtual void GrantAccess(string id, string principal, IAccessPolicy[] accessPolicies)

Parameters

id string

The ID of the AccessEntry construct to be created.

principal string

The IAM principal (role or user) to be granted access to the EKS cluster.

accessPolicies IAccessPolicy[]

An array of IAccessPolicy objects that define the access permissions to be granted to the IAM principal.

Remarks

This method creates an AccessEntry construct that grants the specified IAM principal the access permissions defined by the provided IAccessPolicy array. This allows the IAM principal to perform the actions permitted by the access policies within the EKS cluster.

Implements

ICluster

IResource

Constructs.IConstruct

Constructs.IDependable

IConnectable