aws-cdk-lib.aws_ecs.Cluster

class Cluster (construct)

LanguageType name
.NETAmazon.CDK.AWS.ECS.Cluster
Gogithub.com/aws/aws-cdk-go/awscdk/v2/awsecs#Cluster
Javasoftware.amazon.awscdk.services.ecs.Cluster
Pythonaws_cdk.aws_ecs.Cluster
TypeScript (source)aws-cdk-lib » aws_ecs » Cluster

Implements 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

NameTypeDescription
capacity?AddCapacityOptionsThe ec2 capacity to add to the cluster.
clusterName?stringThe name for the cluster.
containerInsights?booleanIf true CloudWatch Container Insights will be enabled for the cluster.
defaultCloudMapNamespace?CloudMapNamespaceOptionsThe service discovery namespace created in this cluster.
enableFargateCapacityProviders?booleanWhether to enable Fargate Capacity Providers.
executeCommandConfiguration?ExecuteCommandConfigurationThe execute command configuration for the cluster.
vpc?IVpcThe 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.


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

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

NameTypeDescription
capacityProviderNamesstring[]Getter for _capacityProviderNames added to cluster.
clusterArnstringThe Amazon Resource Name (ARN) that identifies the cluster.
clusterNamestringThe name of the cluster.
connectionsConnectionsManage the allowed network connections for the cluster with Security Groups.
defaultCapacityProviderStrategyCapacityProviderStrategy[]Getter for _defaultCapacityProviderStrategy.
envResourceEnvironmentThe environment this resource belongs to.
hasEc2CapacitybooleanWhether the cluster has EC2 capacity associated with it.
nodeNodeThe tree node.
stackStackThe stack in which this resource is defined.
vpcIVpcThe VPC associated with the cluster.
autoscalingGroup?IAutoScalingGroupGetter for autoscaling group added to cluster.
defaultCloudMapNamespace?INamespaceGetter for namespace added to cluster.
executeCommandConfiguration?ExecuteCommandConfigurationGetter for execute command configuration associated with the cluster.

capacityProviderNames

Type: string[]

Getter for _capacityProviderNames added to 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.


defaultCapacityProviderStrategy

Type: CapacityProviderStrategy[]

Getter for _defaultCapacityProviderStrategy.

This is necessary to correctly create Capacity Provider Associations.


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: Node

The tree node.


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

NameDescription
addAsgCapacityProvider(provider, options?)This method adds an Auto Scaling Group Capacity Provider to a cluster.
addCapacity(id, options)It is highly recommended to use Cluster.addAsgCapacityProvider instead of this method.
addDefaultCapacityProviderStrategy(defaultCapacityProviderStrategy)Add default capacity provider strategy for this 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.
static isCluster(x)Return whether the given object is a Cluster.

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.


addCapacity(id, options)

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

Parameters

  • id string
  • options AddCapacityOptions

Returns

  • AutoScalingGroup

It is highly recommended to use 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.


addDefaultCapacityProviderStrategy(defaultCapacityProviderStrategy)

public addDefaultCapacityProviderStrategy(defaultCapacityProviderStrategy: CapacityProviderStrategy[]): void

Parameters

  • defaultCapacityProviderStrategy CapacityProviderStrategy[] — cluster default capacity provider strategy. This takes the form of a list of CapacityProviderStrategy objects.

Add default capacity provider strategy for this 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 supported only for use cases involving Service Connect. For use cases involving both Service- Discovery and Service Connect, customers should manage the HttpNamespace outside of the Cluster.addDefaultCloudMapNamespace method.


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.


static isCluster(x)

public static isCluster(x: any): boolean

Parameters

  • x any

Returns

  • boolean

Return whether the given object is a Cluster.