# Cluster

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

Extends: Construct › Resource › Cluster
Implements: IResource, ICluster, IEnvironmentAware, IClusterRef, IConstruct, IDependable

- CloudFormation: [`AWS::ECS::Cluster`](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-ecs-cluster.html)
- L1 type: [`CfnCluster`](/cdk/api/v2/docs/aws-cdk-lib.aws_ecs.CfnCluster.html)
- Source: [`aws-ecs/lib/cluster.ts`](https://github.com/aws/aws-cdk/blob/v2.275.0/packages/aws-cdk-lib/aws-ecs/lib/cluster.ts#L146)
- Type last changed: v2.263.0 · 31 Jul 2026

## Example

```ts
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,
  instanceWarmupPeriod: 300,
});
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,
  minHealthyPercent: 100,
  capacityProviderStrategies: [
    {
      capacityProvider: capacityProvider.capacityProviderName,
      weight: 1,
    },
  ],
});
```

## Initializer

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

## Construct Props

- `capacity`: [AddCapacityOptions](/cdk/api/v2/docs/aws-cdk-lib.aws_ecs.AddCapacityOptions.html) — The ec2 capacity to add to the cluster.

  **Default:** no EC2 capacity will be added, you can use `addCapacity` to add capacity later.

- `clusterName`: string — The name for the cluster.

  **Default:** CloudFormation-generated name

- `containerInsights`: boolean — See {@link containerInsightsV2 }

  **Default:** Container Insights will be disabled for this cluster.

- `containerInsightsV2`: [ContainerInsights](/cdk/api/v2/docs/aws-cdk-lib.aws_ecs.ContainerInsights.html) — The CloudWatch Container Insights configuration for the cluster.

  **Default:** {@link ContainerInsights.DISABLED } This may be overridden by ECS account level settings.

- `defaultCloudMapNamespace`: [CloudMapNamespaceOptions](/cdk/api/v2/docs/aws-cdk-lib.aws_ecs.CloudMapNamespaceOptions.html) — The service discovery namespace created in this cluster.

  **Default:** no service discovery namespace created, you can use `addDefaultCloudMapNamespace` to add a default service discovery namespace later.

- `enableFargateCapacityProviders`: boolean = false — Whether to enable Fargate Capacity Providers.

- `executeCommandConfiguration`: [ExecuteCommandConfiguration](/cdk/api/v2/docs/aws-cdk-lib.aws_ecs.ExecuteCommandConfiguration.html) — The execute command configuration for the cluster.

  **Default:** no configuration will be provided.

- `managedStorageConfiguration`: [ManagedStorageConfiguration](/cdk/api/v2/docs/aws-cdk-lib.aws_ecs.ManagedStorageConfiguration.html) — Encryption configuration for ECS Managed storage.

  **Default:** no encryption will be applied.

- `vpc`: [IVpc](/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.IVpc.html) — The VPC where your ECS instances will be running or your ENIs will be deployed.

  **Default:** creates a new VPC with two AZs

## Properties

- `autoscalingGroup`: [IAutoScalingGroup](/cdk/api/v2/docs/aws-cdk-lib.aws_autoscaling.IAutoScalingGroup.html) — Getter for autoscaling group added to cluster.

- `capacityProviderNames`: string[] — Getter for _capacityProviderNames added to cluster.

- `clusterArn`: string — The Amazon Resource Name (ARN) that identifies the cluster.

- `clusterName`: string — The name of the cluster.

- `clusterRef`: [ClusterReference](/cdk/api/v2/docs/aws-cdk-lib.interfaces.aws_ecs.ClusterReference.html) — A reference to a Cluster resource.

- `clusterScopedCapacityProviderNames`: string[] — Getter for _clusterScopedCapacityProviderNames.

- `connections`: [Connections](/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.Connections.html) — Manage the allowed network connections for the cluster with Security Groups.

- `defaultCapacityProviderStrategy`: [CapacityProviderStrategy](/cdk/api/v2/docs/aws-cdk-lib.aws_ecs.CapacityProviderStrategy.html)[] — Getter for _defaultCapacityProviderStrategy.

  This is necessary to correctly create Capacity Provider Associations.

- `defaultCloudMapNamespace`: [INamespace](/cdk/api/v2/docs/aws-cdk-lib.aws_servicediscovery.INamespace.html) — Getter for namespace added to cluster.

- `env`: [ResourceEnvironment](/cdk/api/v2/docs/aws-cdk-lib.interfaces.ResourceEnvironment.html) — The environment this resource belongs to.

  For resources that are created and managed in a Stack (those created by
  creating new class instances like `new Role()`, `new Bucket()`, etc.), this
  is always the same as the environment of the stack they belong to.

  For referenced resources (those obtained from referencing methods like
  `Role.fromRoleArn()`, `Bucket.fromBucketName()`, etc.), they might be
  different than the stack they were imported into.

- `executeCommandConfiguration`: [ExecuteCommandConfiguration](/cdk/api/v2/docs/aws-cdk-lib.aws_ecs.ExecuteCommandConfiguration.html) — Getter for execute command configuration associated with the cluster.

- `grants`: [ClusterGrants](/cdk/api/v2/docs/aws-cdk-lib.aws_ecs.ClusterGrants.html) — Collection of grant methods for a Cluster.

- `hasEc2Capacity`: boolean — Whether the cluster has EC2 capacity associated with it.

- `node`: [Node](/cdk/api/v2/docs/constructs.Node.html) — The tree node.

- `PROPERTY_INJECTION_ID`: string (static) — Uniquely identifies this class.

- `stack`: [Stack](/cdk/api/v2/docs/aws-cdk-lib.Stack.html) — The stack in which this resource is defined.

- `vpc`: [IVpc](/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.IVpc.html) — The VPC associated with the cluster.

## Methods

- `addAsgCapacityProvider(provider: AsgCapacityProvider, options?: AddAutoScalingGroupCapacityOptions): void` — This method adds an Auto Scaling Group Capacity Provider to a cluster.

  **Parameters**

  - `provider` — the capacity provider to add to this cluster.

- `addCapacity(id: string, options: AddCapacityOptions): 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: CapacityProviderStrategy[]): void` — Add default capacity provider strategy for this cluster.

  **Parameters**

  - `defaultCapacityProviderStrategy` — cluster default capacity provider strategy. This takes the form of a list of CapacityProviderStrategy objects.

- `addDefaultCloudMapNamespace(options: CloudMapNamespaceOptions): 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.

- `addExistingDefaultCloudMapNamespace(options: ExistingCloudMapNamespaceOptions): INamespace` — Use an existing AWS Cloud Map namespace as the default namespace for this cluster.

  Unlike `addDefaultCloudMapNamespace`, this method does not create a new namespace;
  it registers a namespace that already exists (created elsewhere in the app or
  imported) as the cluster's default namespace.

- `addManagedInstancesCapacityProvider(provider: ManagedInstancesCapacityProvider): void` — This method adds a Managed Instances Capacity Provider to a cluster.

  **Parameters**

  - `provider` — the capacity provider to add to this cluster.

- `applyCrossStackReferenceStrength(strength: ReferenceStrength): void` — Override the cross-stack reference strength for this resource.

  When set, any cross-stack reference to this resource will use the specified
  mechanism instead of the global default determined by the
  `@aws-cdk/core:defaultCrossStackReferences` context key. This is useful for
  selectively weakening specific references to avoid the "deadly embrace" problem
  without changing the app-wide default.

  **Parameters**

  - `strength` — - The reference strength to use for this resource.

- `applyRemovalPolicy(policy: RemovalPolicy): void` — 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`).

- `arnForTasks(keyPattern: string): string` — Returns an ARN that represents all tasks within the cluster that match the task pattern specified.

  To represent all tasks, specify ``"*"``.

  **Parameters**

  - `keyPattern` — Task id pattern.

- `enableFargateCapacityProviders(): void` — Enable the Fargate capacity providers for this cluster.

- `fromClusterArn(scope: Construct, id: string, clusterArn: string): ICluster` (static) — 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.

- `fromClusterAttributes(scope: Construct, id: string, attrs: ClusterAttributes): ICluster` (static) — Import an existing cluster to the stack from its attributes.

- `grantTaskProtection(grantee: IGrantable): Grant` — Grants an ECS Task Protection API permission to the specified grantee.

  This method provides a streamlined way to assign the 'ecs:UpdateTaskProtection'
  permission, enabling the grantee to manage task protection in the ECS cluster.
  [disable-awslint:no-grants]

  **Parameters**

  - `grantee` — The entity (e.g., IAM role or user) to grant the permissions to.

- `isCluster(x: any): boolean` (static) — Return whether the given object is a Cluster.

- `isConstruct(x: any): boolean` (static) — Checks if `x` is a construct.

  Use this method instead of `instanceof` to properly detect `Construct`
  instances, even when the construct library is symlinked.

  Explanation: in JavaScript, multiple copies of the `constructs` library on
  disk are seen as independent, completely different libraries. As a
  consequence, the class `Construct` in each copy of the `constructs` library
  is seen as a different class, and an instance of one class will not test as
  `instanceof` the other class. `npm install` will not create installations
  like this, but users may manually symlink construct libraries together or
  use a monorepo tool: in those cases, multiple copies of the `constructs`
  library can be accidentally installed, and `instanceof` will behave
  unpredictably. It is safest to avoid using `instanceof`, and using
  this type-testing method instead.

  **Parameters**

  - `x` — Any object.

  **Returns:** true if `x` is an object created from a class which extends `Construct`.

- `isOwnedResource(construct: IConstruct): boolean` (static) — Returns true if the construct was created by CDK, and false otherwise.

- `isResource(construct: IConstruct): boolean` (static) — Check whether the given construct is a Resource.

- `metric(metricName: string, props?: MetricOptions): Metric` — This method returns the specified CloudWatch metric for this cluster.

- `metricCpuReservation(props?: MetricOptions): Metric` — This method returns the CloudWatch metric for this clusters CPU reservation.

- `metricCpuUtilization(props?: MetricOptions): Metric` — This method returns the CloudWatch metric for this clusters CPU utilization.

- `metricMemoryReservation(props?: MetricOptions): Metric` — This method returns the CloudWatch metric for this clusters memory reservation.

- `metricMemoryUtilization(props?: MetricOptions): Metric` — This method returns the CloudWatch metric for this clusters memory utilization.

- `toString(): string` — Returns a string representation of this construct.

- `with(...mixins: IMixin[]): IConstruct` — Applies one or more mixins to this construct.

  Mixins are applied in order. The list of constructs is captured at the
  start of the call, so constructs added by a mixin will not be visited.
  Use multiple `with()` calls if subsequent mixins should apply to added
  constructs.