class Cluster (construct)

This page is available in another version. Click here for the v2 documentation.

Language	Type name
.NET	`Amazon.CDK.AWS.ECS.Cluster`
Java	`software.amazon.awscdk.services.ecs.Cluster`
Python	`aws_cdk.aws_ecs.Cluster`
TypeScript (source)	`@aws-cdk/aws-ecs` » `Cluster`

Implements IConstruct, IConstruct, IDependable, IResource, ICluster

A regional grouping of one or more container instances on which you can run tasks and services.

Example

declare const vpc: ec2.Vpc;

const cluster = new ecs.Cluster(this, 'Cluster', {
  vpc,
});

const autoScalingGroup = new autoscaling.AutoScalingGroup(this, 'ASG', {
  vpc,
  instanceType: new ec2.InstanceType('t2.micro'),
  machineImage: ecs.EcsOptimizedImage.amazonLinux2(),
  minCapacity: 0,
  maxCapacity: 100,
});

const capacityProvider = new ecs.AsgCapacityProvider(this, 'AsgCapacityProvider', {
  autoScalingGroup,
});
cluster.addAsgCapacityProvider(capacityProvider);

const taskDefinition = new ecs.Ec2TaskDefinition(this, 'TaskDef');

taskDefinition.addContainer('web', {
  image: ecs.ContainerImage.fromRegistry('amazon/amazon-ecs-sample'),
  memoryReservationMiB: 256,
});

new ecs.Ec2Service(this, 'EC2Service', {
  cluster,
  taskDefinition,
  capacityProviderStrategies: [
    {
      capacityProvider: capacityProvider.capacityProviderName,
      weight: 1,
    },
  ],
});

Initializer

new Cluster(scope: Construct, id: string, props?: ClusterProps)

Parameters

scope Construct
id string
props ClusterProps

Constructs a new instance of the Cluster class.

Construct Props

Name	Type	Description
capacity?	`AddCapacityOptions`	The ec2 capacity to add to the cluster.
capacityProviders?⚠️	`string[]`	The capacity providers to add to the cluster.
clusterName?	`string`	The name for the cluster.
containerInsights?	`boolean`	If true CloudWatch Container Insights will be enabled for the cluster.
defaultCloudMapNamespace?	`CloudMapNamespaceOptions`	The service discovery namespace created in this cluster.
enableFargateCapacityProviders?	`boolean`	Whether to enable Fargate Capacity Providers.
executeCommandConfiguration?	`ExecuteCommandConfiguration`	The execute command configuration for the cluster.
vpc?	`IVpc`	The VPC where your ECS instances will be running or your ENIs will be deployed.

capacity?

Type: AddCapacityOptions (optional, default: no EC2 capacity will be added, you can use addCapacity to add capacity later.)

The ec2 capacity to add to the cluster.

capacityProviders?⚠️

⚠️ Deprecated: Use {@link ClusterProps.enableFargateCapacityProviders} instead.

Type: string[] (optional, default: None. Currently only FARGATE and FARGATE_SPOT are supported.)

The capacity providers to add to the cluster.

clusterName?

Type: string (optional, default: CloudFormation-generated name)

The name for the cluster.

containerInsights?

Type: boolean (optional, default: Container Insights will be disabled for this cluser.)

If true CloudWatch Container Insights will be enabled for the cluster.

defaultCloudMapNamespace?

Type: CloudMapNamespaceOptions (optional, default: no service discovery namespace created, you can use addDefaultCloudMapNamespace to add a default service discovery namespace later.)

The service discovery namespace created in this cluster.

enableFargateCapacityProviders?

Type: boolean (optional, default: false)

Whether to enable Fargate Capacity Providers.

executeCommandConfiguration?

Type: ExecuteCommandConfiguration (optional, default: no configuration will be provided.)

The execute command configuration for the cluster.

vpc?

Type: IVpc (optional, default: creates a new VPC with two AZs)

The VPC where your ECS instances will be running or your ENIs will be deployed.

Properties

Name	Type	Description
clusterArn	`string`	The Amazon Resource Name (ARN) that identifies the cluster.
clusterName	`string`	The name of the cluster.
connections	`Connections`	Manage the allowed network connections for the cluster with Security Groups.
env	`ResourceEnvironment`	The environment this resource belongs to.
hasEc2Capacity	`boolean`	Whether the cluster has EC2 capacity associated with it.
node	`ConstructNode`	The construct tree node associated with this construct.
stack	`Stack`	The stack in which this resource is defined.
vpc	`IVpc`	The VPC associated with the cluster.
autoscalingGroup?	`IAutoScalingGroup`	Getter for autoscaling group added to cluster.
defaultCloudMapNamespace?	`INamespace`	Getter for namespace added to cluster.
executeCommandConfiguration?	`ExecuteCommandConfiguration`	Getter for execute command configuration associated with the cluster.

clusterArn

Type: string

The Amazon Resource Name (ARN) that identifies the cluster.

clusterName

Type: string

The name of the cluster.

connections

Type: Connections

Manage the allowed network connections for the cluster with Security Groups.

env

Type: ResourceEnvironment

The environment this resource belongs to.

For resources that are created and managed by the CDK (generally, those created by creating new class instances like Role, Bucket, etc.), this is always the same as the environment of the stack they belong to; however, for imported resources (those obtained from static methods like fromRoleArn, fromBucketName, etc.), that might be different than the stack they were imported into.

hasEc2Capacity

Type: boolean

Whether the cluster has EC2 capacity associated with it.

node

Type: ConstructNode

The construct tree node associated with this construct.

stack

Type: Stack

The stack in which this resource is defined.

vpc

Type: IVpc

The VPC associated with the cluster.

autoscalingGroup?

Type: IAutoScalingGroup (optional)

Getter for autoscaling group added to cluster.

defaultCloudMapNamespace?

Type: INamespace (optional)

Getter for namespace added to cluster.

executeCommandConfiguration?

Type: ExecuteCommandConfiguration (optional)

Getter for execute command configuration associated with the cluster.

Methods

Name	Description
addAsgCapacityProvider(provider, options?)	This method adds an Auto Scaling Group Capacity Provider to a cluster.
addAutoScalingGroup(autoScalingGroup, options?)⚠️	This method adds compute capacity to a cluster using the specified AutoScalingGroup.
addCapacity(id, options)	It is highly recommended to use {@link Cluster.addAsgCapacityProvider} instead of this method.
addCapacityProvider(provider)⚠️	This method enables the Fargate or Fargate Spot capacity providers on the cluster.
addDefaultCloudMapNamespace(options)	Add an AWS Cloud Map DNS namespace for this cluster.
applyRemovalPolicy(policy)	Apply the given removal policy to this resource.
enableFargateCapacityProviders()	Enable the Fargate capacity providers for this cluster.
metric(metricName, props?)	This method returns the specifed CloudWatch metric for this cluster.
metricCpuReservation(props?)	This method returns the CloudWatch metric for this clusters CPU reservation.
metricCpuUtilization(props?)	This method returns the CloudWatch metric for this clusters CPU utilization.
metricMemoryReservation(props?)	This method returns the CloudWatch metric for this clusters memory reservation.
metricMemoryUtilization(props?)	This method returns the CloudWatch metric for this clusters memory utilization.
toString()	Returns a string representation of this construct.
static fromClusterArn(scope, id, clusterArn)	Import an existing cluster to the stack from the cluster ARN.
static fromClusterAttributes(scope, id, attrs)	Import an existing cluster to the stack from its attributes.

addAsgCapacityProvider(provider, options?)

public addAsgCapacityProvider(provider: AsgCapacityProvider, options?: AddAutoScalingGroupCapacityOptions): void

Parameters

provider AsgCapacityProvider — the capacity provider to add to this cluster.
options AddAutoScalingGroupCapacityOptions

This method adds an Auto Scaling Group Capacity Provider to a cluster.

addAutoScalingGroup(autoScalingGroup, options?)⚠️

public addAutoScalingGroup(autoScalingGroup: AutoScalingGroup, options?: AddAutoScalingGroupCapacityOptions): void

⚠️ Deprecated: Use {@link Cluster.addAsgCapacityProvider} instead.

Parameters

autoScalingGroup AutoScalingGroup — the ASG to add to this cluster.
options AddAutoScalingGroupCapacityOptions

This method adds compute capacity to a cluster using the specified AutoScalingGroup.

addCapacity(id, options)

public addCapacity(id: string, options: AddCapacityOptions): AutoScalingGroup

Parameters

id string
options AddCapacityOptions

Returns

AutoScalingGroup

It is highly recommended to use {@link Cluster.addAsgCapacityProvider} instead of this method.

This method adds compute capacity to a cluster by creating an AutoScalingGroup with the specified options.

Returns the AutoScalingGroup so you can add autoscaling settings to it.

addCapacityProvider(provider)⚠️

public addCapacityProvider(provider: string): void

⚠️ Deprecated: Use {@link enableFargateCapacityProviders} instead.

Parameters

provider string — the capacity provider to add to this cluster.

This method enables the Fargate or Fargate Spot capacity providers on the cluster.

See also: [{@link addAsgCapacityProvider} to add an Auto Scaling Group capacity provider to the cluster.]({@link addAsgCapacityProvider} to add an Auto Scaling Group capacity provider to the cluster.)

addDefaultCloudMapNamespace(options)

public addDefaultCloudMapNamespace(options: CloudMapNamespaceOptions): INamespace

Parameters

options CloudMapNamespaceOptions

Returns

INamespace

Add an AWS Cloud Map DNS namespace for this cluster.

NOTE: HttpNamespaces are not supported, as ECS always requires a DNSConfig when registering an instance to a Cloud Map service.

applyRemovalPolicy(policy)

public applyRemovalPolicy(policy: RemovalPolicy): void

Parameters

policy RemovalPolicy

Apply the given removal policy to this resource.

The Removal Policy controls what happens to this resource when it stops being managed by CloudFormation, either because you've removed it from the CDK application or because you've made a change that requires the resource to be replaced.

The resource can be deleted (RemovalPolicy.DESTROY), or left in your AWS account for data recovery and cleanup later (RemovalPolicy.RETAIN).

enableFargateCapacityProviders()

public enableFargateCapacityProviders(): void

Enable the Fargate capacity providers for this cluster.

metric(metricName, props?)

public metric(metricName: string, props?: MetricOptions): Metric

Parameters

metricName string
props MetricOptions

Returns

Metric

This method returns the specifed CloudWatch metric for this cluster.

metricCpuReservation(props?)

public metricCpuReservation(props?: MetricOptions): Metric

Parameters

props MetricOptions

Returns

Metric

This method returns the CloudWatch metric for this clusters CPU reservation.

metricCpuUtilization(props?)

public metricCpuUtilization(props?: MetricOptions): Metric

Parameters

props MetricOptions

Returns

Metric

This method returns the CloudWatch metric for this clusters CPU utilization.

metricMemoryReservation(props?)

public metricMemoryReservation(props?: MetricOptions): Metric

Parameters

props MetricOptions

Returns

Metric

This method returns the CloudWatch metric for this clusters memory reservation.

metricMemoryUtilization(props?)

public metricMemoryUtilization(props?: MetricOptions): Metric

Parameters

props MetricOptions

Returns

Metric

This method returns the CloudWatch metric for this clusters memory utilization.

toString()

public toString(): string

Returns

string

Returns a string representation of this construct.

static fromClusterArn(scope, id, clusterArn)

public static fromClusterArn(scope: Construct, id: string, clusterArn: string): ICluster

Parameters

scope Construct
id string
clusterArn string

Returns

ICluster

Import an existing cluster to the stack from the cluster ARN.

This does not provide access to the vpc, hasEc2Capacity, or connections - use the fromClusterAttributes method to access those properties.

static fromClusterAttributes(scope, id, attrs)

public static fromClusterAttributes(scope: Construct, id: string, attrs: ClusterAttributes): ICluster

Parameters

scope Construct
id string
attrs ClusterAttributes

Returns

ICluster

Import an existing cluster to the stack from its attributes.