Class Cluster

A Cluster represents a managed Kubernetes Service (EKS).

Inheritance

System.Object

Resource

Cluster

FargateCluster

Implements

ICluster

IResource

Constructs.IConstruct

Constructs.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, IConnectable

Syntax (vb)

Public Class Cluster
    Inherits Resource
    Implements ICluster, IResource, 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

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

Synopsis

Constructors

Cluster(ByRefValue)	Used by jsii to construct an instance of this class from a Javascript-owned object reference
Cluster(DeputyBase.DeputyProps)	Used by jsii to construct an instance of this class from DeputyProps
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.
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, 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(ByRefValue)

Used by jsii to construct an instance of this class from a Javascript-owned object reference

protected Cluster(ByRefValue reference)

Parameters

reference Amazon.JSII.Runtime.Deputy.ByRefValue: The Javascript-owned object reference

Cluster(DeputyBase.DeputyProps)

Used by jsii to construct an instance of this class from DeputyProps

protected Cluster(DeputyBase.DeputyProps props)

Parameters

props Amazon.JSII.Runtime.Deputy.DeputyBase.DeputyProps: The deputy props

Cluster(Construct, String, IClusterProps)

Initiates an EKS Cluster with the supplied arguments.

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

Parameters

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

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 Nullable<AuthenticationMode> AuthenticationMode { get; }

Property Value

System.Nullable<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

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

System.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

System.String

ClusterEncryptionConfigKeyArn

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

public virtual string ClusterEncryptionConfigKeyArn { get; }

Property Value

System.String

ClusterEndpoint

The endpoint URL for the Cluster.

public virtual string ClusterEndpoint { get; }

Property Value

System.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

System.String

ClusterOpenIdConnectIssuer

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

public virtual string ClusterOpenIdConnectIssuer { get; }

Property Value

System.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

System.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

ClusterSecurityGroupId

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

public virtual string ClusterSecurityGroupId { get; }

Property Value

System.String

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 Nullable<IpFamily> IpFamily { get; }

Property Value

System.Nullable<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

System.Collections.Generic.IDictionary<System.String, System.String>

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

If not defined, a default layer will be used containing Kubectl 1.20 and Helm 3.8

KubectlMemory

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

public virtual Size KubectlMemory { get; }

Property Value

Size

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).

Prune

Determines if Kubernetes resources can be pruned automatically.

public virtual bool Prune { get; }

Property Value

System.Boolean

Role

IAM role assumed by the EKS Control Plane.

public virtual IRole Role { get; }

Property Value

IRole

Vpc

The VPC in which this Cluster was created.

public virtual IVpc Vpc { get; }

Property Value

IVpc

Methods

AddAutoScalingGroupCapacity(String, IAutoScalingGroupCapacityOptions)

Add nodes to this EKS cluster.

public virtual AutoScalingGroup AddAutoScalingGroupCapacity(string id, IAutoScalingGroupCapacityOptions options)

Parameters

id System.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 System.String: logical id of this chart.
chart Constructs.Construct: the cdk8s chart.
options IKubernetesManifestOptions: logical id of this chart.

Returns

KubernetesManifest

a KubernetesManifest construct representing the chart.

AddFargateProfile(String, IFargateProfileOptions)

Adds a Fargate profile to this cluster.

public virtual FargateProfile AddFargateProfile(string id, IFargateProfileOptions options)

Parameters

id System.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 System.String: logical id of this chart.
options IHelmChartOptions: options of this chart.

Returns

HelmChart

a HelmChart construct

AddManifest(String, IDictionary<String, Object>[])

Defines a Kubernetes resource in this cluster.

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

Parameters

id System.String: logical id of this manifest.
manifest System.Collections.Generic.IDictionary<System.String, System.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 System.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 System.String
options IServiceAccountOptions

Returns

ServiceAccount

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 Constructs.Construct: the construct scope, in most cases 'this'.
id System.String: the id or name to import as.
attrs IClusterAttributes: the cluster properties to use for importing information.

Returns

ICluster

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 System.String: The name of the ingress.
options IIngressLoadBalancerAddressOptions: Additional operation options.

Returns

System.String

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 System.String: The name of the service.
options IServiceLoadBalancerAddressOptions: Additional operation options.

Returns

System.String

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 System.String

The ID of the AccessEntry construct to be created.

principal System.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