Package software.amazon.awscdk.services.ecs

Class Cluster

java.lang.Object
software.amazon.jsii.JsiiObject
software.constructs.Construct
software.amazon.awscdk.Resource
software.amazon.awscdk.services.ecs.Cluster
All Implemented Interfaces:
IEnvironmentAware, IResource, ICluster, software.amazon.jsii.JsiiSerializable, software.constructs.IConstruct, software.constructs.IDependable
@Generated(value="jsii-pacmak/1.118.0 (build 02eec31)", date="2025-11-04T09:27:40.866Z") @Stability(Stable) public class Cluster extends Resource implements ICluster
A regional grouping of one or more container instances on which you can run tasks and services.

Example: 

 Vpc vpc;
 Cluster cluster = Cluster.Builder.create(this, "Cluster")
         .vpc(vpc)
         .build();
 AutoScalingGroup autoScalingGroup = AutoScalingGroup.Builder.create(this, "ASG")
         .vpc(vpc)
         .instanceType(new InstanceType("t2.micro"))
         .machineImage(EcsOptimizedImage.amazonLinux2())
         .minCapacity(0)
         .maxCapacity(100)
         .build();
 AsgCapacityProvider capacityProvider = AsgCapacityProvider.Builder.create(this, "AsgCapacityProvider")
         .autoScalingGroup(autoScalingGroup)
         .instanceWarmupPeriod(300)
         .build();
 cluster.addAsgCapacityProvider(capacityProvider);
 Ec2TaskDefinition taskDefinition = new Ec2TaskDefinition(this, "TaskDef");
 taskDefinition.addContainer("web", ContainerDefinitionOptions.builder()
         .image(ContainerImage.fromRegistry("amazon/amazon-ecs-sample"))
         .memoryReservationMiB(256)
         .build());
 Ec2Service.Builder.create(this, "EC2Service")
         .cluster(cluster)
         .taskDefinition(taskDefinition)
         .minHealthyPercent(100)
         .capacityProviderStrategies(List.of(CapacityProviderStrategy.builder()
                 .capacityProvider(capacityProvider.getCapacityProviderName())
                 .weight(1)
                 .build()))
         .build();

  • Field Details

    • PROPERTY_INJECTION_ID

      @Stability(Stable) public static final String PROPERTY_INJECTION_ID
      Uniquely identifies this class.

  • Constructor Details

    • Cluster

      protected Cluster(software.amazon.jsii.JsiiObjectRef objRef)

    • Cluster

      protected Cluster(software.amazon.jsii.JsiiObject.InitializationMode initializationMode)

    • Cluster

      @Stability(Stable) public Cluster(@NotNull software.constructs.Construct scope, @NotNull String id, @Nullable ClusterProps props)
      Constructs a new instance of the Cluster class.

      Parameters:
      scope - This parameter is required.
      id - This parameter is required.
      props -

    • Cluster

      @Stability(Stable) public Cluster(@NotNull software.constructs.Construct scope, @NotNull String id)
      Constructs a new instance of the Cluster class.

      Parameters:
      scope - This parameter is required.
      id - This parameter is required.

  • Method Details

    • fromClusterArn

      @Stability(Stable) @NotNull public static ICluster fromClusterArn(@NotNull software.constructs.Construct scope, @NotNull String id, @NotNull String clusterArn)
      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.

      Parameters:
      scope - This parameter is required.
      id - This parameter is required.
      clusterArn - This parameter is required.

    • fromClusterAttributes

      @Stability(Stable) @NotNull public static ICluster fromClusterAttributes(@NotNull software.constructs.Construct scope, @NotNull String id, @NotNull ClusterAttributes attrs)
      Import an existing cluster to the stack from its attributes.

      Parameters:
      scope - This parameter is required.
      id - This parameter is required.
      attrs - This parameter is required.

    • isCluster

      @Stability(Stable) @NotNull public static Boolean isCluster(@NotNull Object x)
      Return whether the given object is a Cluster.

      Parameters:
      x - This parameter is required.

    • addAsgCapacityProvider

      @Stability(Stable) public void addAsgCapacityProvider(@NotNull AsgCapacityProvider provider, @Nullable AddAutoScalingGroupCapacityOptions options)
      This method adds an Auto Scaling Group Capacity Provider to a cluster.

      Parameters:
      provider - the capacity provider to add to this cluster. This parameter is required.
      options -

    • addAsgCapacityProvider

      @Stability(Stable) public void addAsgCapacityProvider(@NotNull AsgCapacityProvider provider)
      This method adds an Auto Scaling Group Capacity Provider to a cluster.

      Parameters:
      provider - the capacity provider to add to this cluster. This parameter is required.

    • addCapacity

      @Stability(Stable) @NotNull public AutoScalingGroup addCapacity(@NotNull String id, @NotNull AddCapacityOptions options)
      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.

      Parameters:
      id - This parameter is required.
      options - This parameter is required.

    • addDefaultCapacityProviderStrategy

      @Stability(Stable) public void addDefaultCapacityProviderStrategy(@NotNull List<CapacityProviderStrategy> defaultCapacityProviderStrategy)
      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. This parameter is required.

    • addDefaultCloudMapNamespace

      @Stability(Stable) @NotNull public INamespace addDefaultCloudMapNamespace(@NotNull CloudMapNamespaceOptions options)
      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.

      Parameters:
      options - This parameter is required.

    • addManagedInstancesCapacityProvider

      @Stability(Stable) public void addManagedInstancesCapacityProvider(@NotNull ManagedInstancesCapacityProvider provider)
      This method adds a Managed Instances Capacity Provider to a cluster.

      Parameters:
      provider - the capacity provider to add to this cluster. This parameter is required.

    • arnForTasks

      @Stability(Stable) @NotNull public String arnForTasks(@NotNull String keyPattern)
      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. This parameter is required.

    • enableFargateCapacityProviders

      @Stability(Stable) public void enableFargateCapacityProviders()
      Enable the Fargate capacity providers for this cluster.

    • grantTaskProtection

      @Stability(Stable) @NotNull public Grant grantTaskProtection(@NotNull IGrantable grantee)
      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.

      Parameters:
      grantee - The entity (e.g., IAM role or user) to grant the permissions to. This parameter is required.

    • metric

      @Stability(Stable) @NotNull public Metric metric(@NotNull String metricName, @Nullable MetricOptions props)
      This method returns the specified CloudWatch metric for this cluster.

      Parameters:
      metricName - This parameter is required.
      props -

    • metric

      @Stability(Stable) @NotNull public Metric metric(@NotNull String metricName)
      This method returns the specified CloudWatch metric for this cluster.

      Parameters:
      metricName - This parameter is required.

    • metricCpuReservation

      @Stability(Stable) @NotNull public Metric metricCpuReservation(@Nullable MetricOptions props)
      This method returns the CloudWatch metric for this clusters CPU reservation.

      Default: average over 5 minutes

      Parameters:
      props -

    • metricCpuReservation

      @Stability(Stable) @NotNull public Metric metricCpuReservation()
      This method returns the CloudWatch metric for this clusters CPU reservation.

      Default: average over 5 minutes

    • metricCpuUtilization

      @Stability(Stable) @NotNull public Metric metricCpuUtilization(@Nullable MetricOptions props)
      This method returns the CloudWatch metric for this clusters CPU utilization.

      Default: average over 5 minutes

      Parameters:
      props -

    • metricCpuUtilization

      @Stability(Stable) @NotNull public Metric metricCpuUtilization()
      This method returns the CloudWatch metric for this clusters CPU utilization.

      Default: average over 5 minutes

    • metricMemoryReservation

      @Stability(Stable) @NotNull public Metric metricMemoryReservation(@Nullable MetricOptions props)
      This method returns the CloudWatch metric for this clusters memory reservation.

      Default: average over 5 minutes

      Parameters:
      props -

    • metricMemoryReservation

      @Stability(Stable) @NotNull public Metric metricMemoryReservation()
      This method returns the CloudWatch metric for this clusters memory reservation.

      Default: average over 5 minutes

    • metricMemoryUtilization

      @Stability(Stable) @NotNull public Metric metricMemoryUtilization(@Nullable MetricOptions props)
      This method returns the CloudWatch metric for this clusters memory utilization.

      Default: average over 5 minutes

      Parameters:
      props -

    • metricMemoryUtilization

      @Stability(Stable) @NotNull public Metric metricMemoryUtilization()
      This method returns the CloudWatch metric for this clusters memory utilization.

      Default: average over 5 minutes

    • getCapacityProviderNames

      @Stability(Stable) @NotNull public List<String> getCapacityProviderNames()
      Getter for _capacityProviderNames added to cluster.

    • getClusterArn

      @Stability(Stable) @NotNull public String getClusterArn()
      The Amazon Resource Name (ARN) that identifies the cluster.
      Specified by:
      getClusterArn in interface ICluster

    • getClusterName

      @Stability(Stable) @NotNull public String getClusterName()
      The name of the cluster.
      Specified by:
      getClusterName in interface ICluster

    • getClusterScopedCapacityProviderNames

      @Stability(Stable) @NotNull public List<String> getClusterScopedCapacityProviderNames()
      Getter for _clusterScopedCapacityProviderNames.

    • getConnections

      @Stability(Stable) @NotNull public Connections getConnections()
      Manage the allowed network connections for the cluster with Security Groups.
      Specified by:
      getConnections in interface ICluster

    • getDefaultCapacityProviderStrategy

      @Stability(Stable) @NotNull public List<CapacityProviderStrategy> getDefaultCapacityProviderStrategy()
      Getter for _defaultCapacityProviderStrategy.

      This is necessary to correctly create Capacity Provider Associations.

    • getHasEc2Capacity

      @Stability(Stable) @NotNull public Boolean getHasEc2Capacity()
      Whether the cluster has EC2 capacity associated with it.
      Specified by:
      getHasEc2Capacity in interface ICluster

    • getVpc

      @Stability(Stable) @NotNull public IVpc getVpc()
      The VPC associated with the cluster.
      Specified by:
      getVpc in interface ICluster

    • getAutoscalingGroup

      @Stability(Stable) @Nullable public IAutoScalingGroup getAutoscalingGroup()
      Getter for autoscaling group added to cluster.
      Specified by:
      getAutoscalingGroup in interface ICluster

    • getDefaultCloudMapNamespace

      @Stability(Stable) @Nullable public INamespace getDefaultCloudMapNamespace()
      Getter for namespace added to cluster.
      Specified by:
      getDefaultCloudMapNamespace in interface ICluster

    • getExecuteCommandConfiguration

      @Stability(Stable) @Nullable public ExecuteCommandConfiguration getExecuteCommandConfiguration()
      Getter for execute command configuration associated with the cluster.
      Specified by:
      getExecuteCommandConfiguration in interface ICluster