Package software.amazon.awscdk.services.ecs

Class BaseService

java.lang.Object
software.amazon.jsii.JsiiObject
software.constructs.Construct
software.amazon.awscdk.Resource
software.amazon.awscdk.services.ecs.BaseService
All Implemented Interfaces:
IResource, IConnectable, IBaseService, IService, ILoadBalancerTarget, IApplicationLoadBalancerTarget, INetworkLoadBalancerTarget, software.amazon.jsii.JsiiSerializable, software.constructs.IConstruct, software.constructs.IDependable
Direct Known Subclasses:
Ec2Service, ExternalService, FargateService
@Generated(value="jsii-pacmak/1.116.0 (build 0eddcff)", date="2025-10-24T13:34:37.645Z") @Stability(Stable) public abstract class BaseService extends Resource implements IBaseService, IApplicationLoadBalancerTarget, INetworkLoadBalancerTarget, ILoadBalancerTarget
The base class for Ec2Service and FargateService services.

Example: 

 import software.amazon.awscdk.services.ecs.*;
 IBaseService service = BaseService.fromServiceArnWithCluster(this, "EcsService", "arn:aws:ecs:us-east-1:123456789012:service/myClusterName/myServiceName");
 Pipeline pipeline = new Pipeline(this, "MyPipeline");
 Artifact buildOutput = new Artifact();
 // add source and build stages to the pipeline as usual...
 IStage deployStage = pipeline.addStage(StageOptions.builder()
         .stageName("Deploy")
         .actions(List.of(
             EcsDeployAction.Builder.create()
                     .actionName("DeployAction")
                     .service(service)
                     .input(buildOutput)
                     .build()))
         .build());

  • Constructor Details

    • BaseService

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

    • BaseService

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

    • BaseService

      @Stability(Stable) protected BaseService(@NotNull software.constructs.Construct scope, @NotNull String id, @NotNull BaseServiceProps props, @NotNull Object additionalProps, @NotNull TaskDefinition taskDefinition)
      Constructs a new instance of the BaseService class.

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

  • Method Details

    • fromServiceArnWithCluster

      @Stability(Stable) @NotNull public static IBaseService fromServiceArnWithCluster(@NotNull software.constructs.Construct scope, @NotNull String id, @NotNull String serviceArn)
      Import an existing ECS/Fargate Service using the service cluster format.

      The format is the "new" format "arn:aws:ecs:region:aws_account_id:service/cluster-name/service-name".

      Parameters:
      scope - This parameter is required.
      id - This parameter is required.
      serviceArn - This parameter is required.
      See Also:

    • addLifecycleHook

      @Stability(Stable) public void addLifecycleHook(@NotNull IDeploymentLifecycleHookTarget target)
      Add a deployment lifecycle hook target.

      Parameters:
      target - The lifecycle hook target to add. This parameter is required.

    • addVolume

      @Stability(Stable) public void addVolume(@NotNull ServiceManagedVolume volume)
      Adds a volume to the Service.

      Parameters:
      volume - This parameter is required.

    • associateCloudMapService

      @Stability(Stable) public void associateCloudMapService(@NotNull AssociateCloudMapServiceOptions options)
      Associates this service with a CloudMap service.

      Parameters:
      options - This parameter is required.

    • attachToApplicationTargetGroup

      @Stability(Stable) @NotNull public LoadBalancerTargetProps attachToApplicationTargetGroup(@NotNull IApplicationTargetGroup targetGroup)
      This method is called to attach this service to an Application Load Balancer.

      Don't call this function directly. Instead, call listener.addTargets() to add this service to a load balancer.

      Specified by:
      attachToApplicationTargetGroup in interface IApplicationLoadBalancerTarget
      Parameters:
      targetGroup - This parameter is required.

    • attachToClassicLB

      @Stability(Stable) public void attachToClassicLB(@NotNull LoadBalancer loadBalancer)
      Registers the service as a target of a Classic Load Balancer (CLB).

      Don't call this. Call loadBalancer.addTarget() instead.

      Specified by:
      attachToClassicLB in interface ILoadBalancerTarget
      Parameters:
      loadBalancer - [disable-awslint:ref-via-interface]. This parameter is required.

    • attachToNetworkTargetGroup

      @Stability(Stable) @NotNull public LoadBalancerTargetProps attachToNetworkTargetGroup(@NotNull INetworkTargetGroup targetGroup)
      This method is called to attach this service to a Network Load Balancer.

      Don't call this function directly. Instead, call listener.addTargets() to add this service to a load balancer.

      Specified by:
      attachToNetworkTargetGroup in interface INetworkLoadBalancerTarget
      Parameters:
      targetGroup - This parameter is required.

    • autoScaleTaskCount

      @Stability(Stable) @NotNull public ScalableTaskCount autoScaleTaskCount(@NotNull EnableScalingProps props)
      An attribute representing the minimum and maximum task count for an AutoScalingGroup.

      Parameters:
      props - This parameter is required.

    • configureAwsVpcNetworkingWithSecurityGroups

      @Stability(Stable) protected void configureAwsVpcNetworkingWithSecurityGroups(@NotNull IVpc vpc, @Nullable Boolean assignPublicIp, @Nullable SubnetSelection vpcSubnets, @Nullable List<ISecurityGroup> securityGroups)
      This method is called to create a networkConfiguration.

      Parameters:
      vpc - This parameter is required.
      assignPublicIp -
      vpcSubnets -
      securityGroups -

    • configureAwsVpcNetworkingWithSecurityGroups

      @Stability(Stable) protected void configureAwsVpcNetworkingWithSecurityGroups(@NotNull IVpc vpc, @Nullable Boolean assignPublicIp, @Nullable SubnetSelection vpcSubnets)
      This method is called to create a networkConfiguration.

      Parameters:
      vpc - This parameter is required.
      assignPublicIp -
      vpcSubnets -

    • configureAwsVpcNetworkingWithSecurityGroups

      @Stability(Stable) protected void configureAwsVpcNetworkingWithSecurityGroups(@NotNull IVpc vpc, @Nullable Boolean assignPublicIp)
      This method is called to create a networkConfiguration.

      Parameters:
      vpc - This parameter is required.
      assignPublicIp -

    • configureAwsVpcNetworkingWithSecurityGroups

      @Stability(Stable) protected void configureAwsVpcNetworkingWithSecurityGroups(@NotNull IVpc vpc)
      This method is called to create a networkConfiguration.

      Parameters:
      vpc - This parameter is required.

    • enableCloudMap

      @Stability(Stable) @NotNull public Service enableCloudMap(@NotNull CloudMapOptions options)
      Enable CloudMap service discovery for the service.

      Parameters:
      options - This parameter is required.
      Returns:
      The created CloudMap service

    • enableDeploymentAlarms

      @Stability(Stable) public void enableDeploymentAlarms(@NotNull List<String> alarmNames, @Nullable DeploymentAlarmOptions options)
      Enable Deployment Alarms which take advantage of arbitrary alarms and configure them after service initialization.

      If you have already enabled deployment alarms, this function can be used to tell ECS about additional alarms that should interrupt a deployment.

      New alarms specified in subsequent calls of this function will be appended to the existing list of alarms.

      The same Alarm Behavior must be used on all deployment alarms. If you specify different AlarmBehavior values in multiple calls to this function, or the Alarm Behavior used here doesn't match the one used in the service constructor, an error will be thrown.

      If the alarm's metric references the service, you cannot pass Alarm.alarmName here. That will cause a circular dependency between the service and its deployment alarm. See this package's README for options to alarm on service metrics, and avoid this circular dependency.

      Parameters:
      alarmNames - This parameter is required.
      options -

    • enableDeploymentAlarms

      @Stability(Stable) public void enableDeploymentAlarms(@NotNull List<String> alarmNames)
      Enable Deployment Alarms which take advantage of arbitrary alarms and configure them after service initialization.

      If you have already enabled deployment alarms, this function can be used to tell ECS about additional alarms that should interrupt a deployment.

      New alarms specified in subsequent calls of this function will be appended to the existing list of alarms.

      The same Alarm Behavior must be used on all deployment alarms. If you specify different AlarmBehavior values in multiple calls to this function, or the Alarm Behavior used here doesn't match the one used in the service constructor, an error will be thrown.

      If the alarm's metric references the service, you cannot pass Alarm.alarmName here. That will cause a circular dependency between the service and its deployment alarm. See this package's README for options to alarm on service metrics, and avoid this circular dependency.

      Parameters:
      alarmNames - This parameter is required.

    • enableServiceConnect

      @Stability(Stable) public void enableServiceConnect(@Nullable ServiceConnectProps config)
      Enable Service Connect on this service.

      Parameters:
      config -

    • enableServiceConnect

      @Stability(Stable) public void enableServiceConnect()
      Enable Service Connect on this service.

    • isUsingECSDeploymentController

      @Stability(Stable) @NotNull public Boolean isUsingECSDeploymentController()
      Checks if the service is using the ECS deployment controller.

      Returns:
      true if the service is using the ECS deployment controller or if no deployment controller is specified (defaults to ECS)

    • loadBalancerTarget

      @Stability(Stable) @NotNull public IEcsLoadBalancerTarget loadBalancerTarget(@NotNull LoadBalancerTargetOptions options)
      Return a load balancing target for a specific container and port.

      Use this function to create a load balancer target if you want to load balance to another container than the first essential container or the first mapped port on the container.

      Use the return value of this function where you would normally use a load balancer target, instead of the Service object itself.

      Example: 

       ApplicationListener listener;
 BaseService service;
 listener.addTargets("ECS", AddApplicationTargetsProps.builder()
         .port(80)
         .targets(List.of(service.loadBalancerTarget(LoadBalancerTargetOptions.builder()
                 .containerName("MyContainer")
                 .containerPort(1234)
                 .build())))
         .build());

      Parameters:
      options - This parameter is required.

    • metric

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

      Parameters:
      metricName - This parameter is required.
      props -

    • metric

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

      Parameters:
      metricName - This parameter is required.

    • metricCpuUtilization

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

      Default: average over 5 minutes

      Parameters:
      props -

    • metricCpuUtilization

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

      Default: average over 5 minutes

    • metricMemoryUtilization

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

      Default: average over 5 minutes

      Parameters:
      props -

    • metricMemoryUtilization

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

      Default: average over 5 minutes

    • registerLoadBalancerTargets

      @Stability(Stable) public void registerLoadBalancerTargets(@NotNull EcsTarget... targets)
      Use this function to create all load balancer targets to be registered in this service, add them to target groups, and attach target groups to listeners accordingly.

      Alternatively, you can use listener.addTargets() to create targets and add them to target groups.

      Example: 

       ApplicationListener listener;
 BaseService service;
 service.registerLoadBalancerTargets(EcsTarget.builder()
         .containerName("web")
         .containerPort(80)
         .newTargetGroupId("ECS")
         .listener(ListenerConfig.applicationListener(listener, AddApplicationTargetsProps.builder()
                 .protocol(ApplicationProtocol.HTTPS)
                 .build()))
         .build());

      Parameters:
      targets - This parameter is required.

    • getCluster

      @Stability(Stable) @NotNull public ICluster getCluster()
      The cluster that hosts the service.
      Specified by:
      getCluster in interface IBaseService

    • getConnections

      @Stability(Stable) @NotNull public Connections getConnections()
      The security groups which manage the allowed network traffic for the service.
      Specified by:
      getConnections in interface IConnectable

    • getServiceArn

      @Stability(Stable) @NotNull public String getServiceArn()
      The Amazon Resource Name (ARN) of the service.
      Specified by:
      getServiceArn in interface IService

    • getServiceName

      @Stability(Stable) @NotNull public String getServiceName()
      The name of the service.
      Specified by:
      getServiceName in interface IService

    • getTaskDefinition

      @Stability(Stable) @NotNull public TaskDefinition getTaskDefinition()
      The task definition to use for tasks in the service.

    • getCloudMapService

      @Stability(Stable) @Nullable public IService getCloudMapService()
      The CloudMap service created for this service, if any.

    • getLoadBalancers

      @Stability(Stable) @NotNull protected List<CfnService.LoadBalancerProperty> getLoadBalancers()
      A list of Elastic Load Balancing load balancer objects, containing the load balancer name, the container name (as it appears in a container definition), and the container port to access from the load balancer.

    • setLoadBalancers

      @Stability(Stable) protected void setLoadBalancers(@NotNull List<CfnService.LoadBalancerProperty> value)
      A list of Elastic Load Balancing load balancer objects, containing the load balancer name, the container name (as it appears in a container definition), and the container port to access from the load balancer.

    • getServiceRegistries

      @Stability(Stable) @NotNull protected List<CfnService.ServiceRegistryProperty> getServiceRegistries()
      The details of the service discovery registries to assign to this service.

      For more information, see Service Discovery.

    • setServiceRegistries

      @Stability(Stable) protected void setServiceRegistries(@NotNull List<CfnService.ServiceRegistryProperty> value)
      The details of the service discovery registries to assign to this service.

      For more information, see Service Discovery.

    • getCloudmapService

      @Stability(Stable) @Nullable protected Service getCloudmapService()
      The details of the AWS Cloud Map service.

    • setCloudmapService

      @Stability(Stable) protected void setCloudmapService(@Nullable Service value)
      The details of the AWS Cloud Map service.

    • getDeploymentAlarms

      @Stability(Stable) @Nullable protected CfnService.DeploymentAlarmsProperty getDeploymentAlarms()
      The deployment alarms property - this will be rendered directly and lazily as the CfnService.alarms property.

    • setDeploymentAlarms

      @Stability(Stable) protected void setDeploymentAlarms(@Nullable CfnService.DeploymentAlarmsProperty value)
      The deployment alarms property - this will be rendered directly and lazily as the CfnService.alarms property.

    • getNetworkConfiguration

      @Stability(Stable) @Nullable protected CfnService.NetworkConfigurationProperty getNetworkConfiguration()
      A list of Elastic Load Balancing load balancer objects, containing the load balancer name, the container name (as it appears in a container definition), and the container port to access from the load balancer.

    • setNetworkConfiguration

      @Stability(Stable) protected void setNetworkConfiguration(@Nullable CfnService.NetworkConfigurationProperty value)
      A list of Elastic Load Balancing load balancer objects, containing the load balancer name, the container name (as it appears in a container definition), and the container port to access from the load balancer.