class BaseService

Language	Type name
.NET	Amazon.CDK.AWS.ECS.BaseService
Go	github.com/aws/aws-cdk-go/awscdk/v2/awsecs#BaseService
Java	software.amazon.awscdk.services.ecs.BaseService
Python	aws_cdk.aws_ecs.BaseService
TypeScript (source)	aws-cdk-lib » aws_ecs » BaseService

Implements IConstruct, IDependable, IResource, IBaseService, IService, IApplicationLoadBalancerTarget, INetworkLoadBalancerTarget, ILoadBalancerTarget, IConnectable

Extends Resource

Implemented by Ec2Service, ExternalService, FargateService

The base class for Ec2Service and FargateService services.

Example

import * as ecs from 'aws-cdk-lib/aws-ecs';

const service = ecs.BaseService.fromServiceArnWithCluster(this, 'EcsService',
  'arn:aws:ecs:us-east-1:123456789012:service/myClusterName/myServiceName'
);
const pipeline = new codepipeline.Pipeline(this, 'MyPipeline');
const buildOutput = new codepipeline.Artifact();
// add source and build stages to the pipeline as usual...
const deployStage = pipeline.addStage({
  stageName: 'Deploy',
  actions: [
    new codepipeline_actions.EcsDeployAction({
      actionName: 'DeployAction',
      service: service,
      input: buildOutput,
    }),
  ],
});

Initializer

new BaseService(scope: Construct, id: string, props: BaseServiceProps, additionalProps: any, taskDefinition: TaskDefinition)

Parameters

• scope Construct
• id string
• props BaseServiceProps
• additionalProps any
• taskDefinition TaskDefinition

Constructs a new instance of the BaseService class.

Properties

Name	Type	Description
cluster	ICluster	The cluster that hosts the service.
connections	Connections	The security groups which manage the allowed network traffic for the service.
env	ResourceEnvironment	The environment this resource belongs to.
loadBalancers	LoadBalancerProperty[]	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.
node	Node	The tree node.
serviceArn	string	The Amazon Resource Name (ARN) of the service.
serviceName	string	The name of the service.
serviceRegistries	ServiceRegistryProperty[]	The details of the service discovery registries to assign to this service.
stack	Stack	The stack in which this resource is defined.
taskDefinition	TaskDefinition	The task definition to use for tasks in the service.
cloudMapService?	IService	The CloudMap service created for this service, if any.
cloudmapService?	Service	The details of the AWS Cloud Map service.
deploymentAlarms?	DeploymentAlarmsProperty	The deployment alarms property - this will be rendered directly and lazily as the CfnService.alarms property.
networkConfiguration?	NetworkConfigurationProperty	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.

---

cluster

Type: ICluster

The cluster that hosts the service.

---

connections

Type: Connections

The security groups which manage the allowed network traffic for the service.

---

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.

---

loadBalancers

Type: LoadBalancerProperty[]

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.

---

node

Type: Node

The tree node.

---

serviceArn

Type: string

The Amazon Resource Name (ARN) of the service.

---

serviceName

Type: string

The name of the service.

---

serviceRegistries

Type: ServiceRegistryProperty[]

The details of the service discovery registries to assign to this service.

For more information, see Service Discovery.

---

stack

Type: Stack

The stack in which this resource is defined.

---

taskDefinition

Type: TaskDefinition

The task definition to use for tasks in the service.

---

cloudMapService?

Type: IService (optional)

The CloudMap service created for this service, if any.

---

cloudmapService?

Type: Service (optional)

The details of the AWS Cloud Map service.

---

deploymentAlarms?

Type: DeploymentAlarmsProperty (optional)

The deployment alarms property - this will be rendered directly and lazily as the CfnService.alarms property.

---

networkConfiguration?

Type: NetworkConfigurationProperty (optional)

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.

Methods

Name	Description
addVolume(volume)	Adds a volume to the Service.
applyRemovalPolicy(policy)	Apply the given removal policy to this resource.
associateCloudMapService(options)	Associates this service with a CloudMap service.
attachToApplicationTargetGroup(targetGroup)	This method is called to attach this service to an Application Load Balancer.
attachToClassicLB(loadBalancer)	Registers the service as a target of a Classic Load Balancer (CLB).
attachToNetworkTargetGroup(targetGroup)	This method is called to attach this service to a Network Load Balancer.
autoScaleTaskCount(props)	An attribute representing the minimum and maximum task count for an AutoScalingGroup.
enableCloudMap(options)	Enable CloudMap service discovery for the service.
enableDeploymentAlarms(alarmNames, options?)	Enable Deployment Alarms which take advantage of arbitrary alarms and configure them after service initialization.
enableServiceConnect(config?)	Enable Service Connect on this service.
loadBalancerTarget(options)	Return a load balancing target for a specific container and port.
metric(metricName, props?)	This method returns the specified CloudWatch metric name for this service.
metricCpuUtilization(props?)	This method returns the CloudWatch metric for this service's CPU utilization.
metricMemoryUtilization(props?)	This method returns the CloudWatch metric for this service's memory utilization.
registerLoadBalancerTargets(...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.
toString()	Returns a string representation of this construct.
protected configureAwsVpcNetworkingWithSecurityGroups(vpc, assignPublicIp?, vpcSubnets?, securityGroups?)	This method is called to create a networkConfiguration.
static fromServiceArnWithCluster(scope, id, serviceArn)	Import an existing ECS/Fargate Service using the service cluster format.

---

addVolume(volume)

public addVolume(volume: ServiceManagedVolume): void

Parameters

• volume ServiceManagedVolume

Adds a volume to the 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).

---

associateCloudMapService(options)

public associateCloudMapService(options: AssociateCloudMapServiceOptions): void

Parameters

• options AssociateCloudMapServiceOptions

Associates this service with a CloudMap service.

---

attachToApplicationTargetGroup(targetGroup)

public attachToApplicationTargetGroup(targetGroup: IApplicationTargetGroup): LoadBalancerTargetProps

Parameters

• targetGroup IApplicationTargetGroup

Returns

• LoadBalancerTargetProps

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.

---

attachToClassicLB(loadBalancer)

public attachToClassicLB(loadBalancer: LoadBalancer): void

Parameters

• loadBalancer LoadBalancer

Registers the service as a target of a Classic Load Balancer (CLB).

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

---

attachToNetworkTargetGroup(targetGroup)

public attachToNetworkTargetGroup(targetGroup: INetworkTargetGroup): LoadBalancerTargetProps

Parameters

• targetGroup INetworkTargetGroup

Returns

• LoadBalancerTargetProps

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.

---

autoScaleTaskCount(props)

public autoScaleTaskCount(props: EnableScalingProps): ScalableTaskCount

Parameters

• props EnableScalingProps

Returns

• ScalableTaskCount

An attribute representing the minimum and maximum task count for an AutoScalingGroup.

---

enableCloudMap(options)

public enableCloudMap(options: CloudMapOptions): Service

Parameters

• options CloudMapOptions

Returns

• Service

Enable CloudMap service discovery for the service.

---

enableDeploymentAlarms(alarmNames, options?)

public enableDeploymentAlarms(alarmNames: string[], options?: DeploymentAlarmOptions): void

Parameters

• alarmNames string[]
• options DeploymentAlarmOptions

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.

---

enableServiceConnect(config?)

public enableServiceConnect(config?: ServiceConnectProps): void

Parameters

• config ServiceConnectProps

Enable Service Connect on this service.

---

loadBalancerTarget(options)

public loadBalancerTarget(options: LoadBalancerTargetOptions): IEcsLoadBalancerTarget

Parameters

• options LoadBalancerTargetOptions

Returns

• IEcsLoadBalancerTarget

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

declare const listener: elbv2.ApplicationListener;
declare const service: ecs.BaseService;
listener.addTargets('ECS', {
  port: 80,
  targets: [service.loadBalancerTarget({
    containerName: 'MyContainer',
    containerPort: 1234,
  })],
});

---

metric(metricName, props?)

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

Parameters

• metricName string
• props MetricOptions

Returns

• Metric

This method returns the specified CloudWatch metric name for this service.

---

metricCpuUtilization(props?)

public metricCpuUtilization(props?: MetricOptions): Metric

Parameters

• props MetricOptions

Returns

• Metric

This method returns the CloudWatch metric for this service's CPU utilization.

---

metricMemoryUtilization(props?)

public metricMemoryUtilization(props?: MetricOptions): Metric

Parameters

• props MetricOptions

Returns

• Metric

This method returns the CloudWatch metric for this service's memory utilization.

---

registerLoadBalancerTargets(...targets)

public registerLoadBalancerTargets(...targets: EcsTarget[]): void

Parameters

• targets EcsTarget

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

declare const listener: elbv2.ApplicationListener;
declare const service: ecs.BaseService;
service.registerLoadBalancerTargets(
  {
    containerName: 'web',
    containerPort: 80,
    newTargetGroupId: 'ECS',
    listener: ecs.ListenerConfig.applicationListener(listener, {
      protocol: elbv2.ApplicationProtocol.HTTPS
    }),
  },
)

---

toString()

public toString(): string

Returns

• string

Returns a string representation of this construct.

---

protected configureAwsVpcNetworkingWithSecurityGroups(vpc, assignPublicIp?, vpcSubnets?, securityGroups?)

protected configureAwsVpcNetworkingWithSecurityGroups(vpc: IVpc, assignPublicIp?: boolean, vpcSubnets?: SubnetSelection, securityGroups?: ISecurityGroup[]): void

Parameters

• vpc IVpc
• assignPublicIp boolean
• vpcSubnets SubnetSelection
• securityGroups ISecurityGroup[]

This method is called to create a networkConfiguration.

---

static fromServiceArnWithCluster(scope, id, serviceArn)

public static fromServiceArnWithCluster(scope: Construct, id: string, serviceArn: string): IBaseService

Parameters

• scope Construct
• id string
• serviceArn string

Returns

• IBaseService

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".

See also: https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-account-settings.html#ecs-resource-ids