Service
Reference doc for the `sst.aws.Service` component.
The Service
component is internally used by the Cluster
component to deploy services to
Amazon ECS. It uses AWS Fargate.
This component is returned by the addService
method of the Cluster
component.
Constructor
Parameters
-
name
string
-
args
ServiceArgs
-
opts?
ComponentResourceOptions
ServiceArgs
architecture?
Type Input
<
“
x86_64
”
|
“
arm64
”
>
Default “x86_64”
The CPU architecture of the container in this service.
cluster
cluster.arn
Type Input
<
string
>
The ARN of the cluster.
cluster.name
Type Input
<
string
>
The name of the cluster.
command?
Type Input
<
Input
<
string
>
[]
>
The command to override the default command in the container.
containers?
Type Input
<
Object
>
[]
The containers to run in the service.
By default this starts a single container. To add multiple containers in the service, pass in an array of containers args.
If you sepcify containers
, you cannot list the above args at the top-level. For example,
you cannot pass in image
at the top level.
You will need to pass in image
as a part of the containers
.
containers[].command?
Type Input
<
string
[]
>
The command to override the default command in the container. Same as the top-level
command
.
containers[].dev?
Type Object
Configure how this container works in sst dev
. Same as the top-level
dev
.
containers[].dev.autostart?
Type Input
<
boolean
>
Configure if you want to automatically start this when sst dev
starts. Same as the
top-level dev.autostart
.
containers[].dev.command?
Type Input
<
string
>
The command that sst dev
runs to start this in dev mode. Same as the top-level
dev.command
.
containers[].dev.directory?
Type Input
<
string
>
Change the directory from where the command
is run. Same as the top-level
dev.directory
.
containers[].entrypoint?
Type Input
<
string
[]
>
The entrypoint to override the default entrypoint in the container. Same as the top-level
entrypoint
.
containers[].environment?
Type Input
<
Record
<
string
, Input
<
string
>
>
>
Key-value pairs of values that are set as container environment variables. Same as the
top-level environment
.
containers[].health?
Type Input
<
Object
>
Configure the health check for the container. Same as the top-level
health
.
containers[].health.command
Type Input
<
string
[]
>
A string array representing the command that the container runs to determine if it is healthy.
The string array must start with CMD
to run the command arguments directly, or
CMD-SHELL
to run the command with the container’s default shell.
containers[].health.interval?
Type Input
<
“
${number} minute
”
|
“
${number} minutes
”
|
“
${number} second
”
|
“
${number} seconds
”
>
Default “30 seconds”
The time between running the check. Must be between 5 seconds
and 300 seconds
.
containers[].health.retries?
Type Input
<
number
>
Default 3
The number of consecutive failures required to consider the check to have failed. Must
be between 1
and 10
.
containers[].health.startPeriod?
Type Input
<
“
${number} minute
”
|
“
${number} minutes
”
|
“
${number} second
”
|
“
${number} seconds
”
>
Default “0 seconds”
The grace period to provide containers time to bootstrap before failed health checks
count towards the maximum number of retries. Must be between 0 seconds
and
300 seconds
.
containers[].health.timeout?
Type Input
<
“
${number} minute
”
|
“
${number} minutes
”
|
“
${number} second
”
|
“
${number} seconds
”
>
Default “5 seconds”
The time to wait before considering the check to have hung. Must be between 2 seconds
and 60 seconds
.
containers[].image?
Type Input
<
string
|
Object
>
Configure the Docker image for the container. Same as the top-level image
.
containers[].image.args?
Type Input
<
Record
<
string
, Input
<
string
>
>
>
Key-value pairs of build args. Same as the top-level image.args
.
containers[].image.context?
Type Input
<
string
>
The path to the Docker build context. Same as the top-level
image.context
.
containers[].image.dockerfile?
Type Input
<
string
>
The path to the Dockerfile. Same as the top-level
image.dockerfile
.
containers[].logging?
Type Input
<
Object
>
Configure the service’s logs in CloudWatch. Same as the top-level logging
.
containers[].logging.retention?
Type Input
<
“
1 day
”
|
“
3 days
”
|
“
5 days
”
|
“
1 week
”
|
“
2 weeks
”
|
“
1 month
”
|
“
2 months
”
|
“
3 months
”
|
“
4 months
”
|
“
5 months
”
|
“
6 months
”
|
“
1 year
”
|
“
13 months
”
|
“
18 months
”
|
“
2 years
”
|
“
3 years
”
|
“
5 years
”
|
“
6 years
”
|
“
7 years
”
|
“
8 years
”
|
“
9 years
”
|
“
10 years
”
|
“
forever
”
>
The duration the logs are kept in CloudWatch. Same as the top-level
logging.retention
.
containers[].name
Type Input
<
string
>
The name of the container.
This is used as the --name
option in the Docker run command.
containers[].ssm?
Type Input
<
Record
<
string
, Input
<
string
>
>
>
Key-value pairs of AWS Systems Manager Parameter Store parameter ARNs or AWS Secrets
Manager secret ARNs. The values will be loaded into the container as environment
variables. Same as the top-level ssm
.
containers[].volumes?
Type Input
<
Object
>
[]
Mount Amazon EFS file systems into the container. Same as the top-level
efs
.
containers[].volumes[].efs
Type Input
<
Efs
|
Object
>
The Amazon EFS file system to mount.
containers[].volumes[].efs.accessPoint
Type Input
<
string
>
The ID of the EFS access point.
containers[].volumes[].efs.fileSystem
Type Input
<
string
>
The ID of the EFS file system.
containers[].volumes[].path
Type Input
<
string
>
The path to mount the volume.
cpu?
Type “
0.25 vCPU
”
|
“
0.5 vCPU
”
|
“
1 vCPU
”
|
“
2 vCPU
”
|
“
4 vCPU
”
|
“
8 vCPU
”
|
“
16 vCPU
”
Default “0.25 vCPU”
The amount of CPU allocated to the container in this service.
dev?
Type false
|
Object
Configure how this component works in sst dev
.
By default, your service in not deployed in sst dev
. Instead, you can use the
dev.command
to start your app locally. It’ll be run as a separate process in the
sst dev
multiplexer. Read more about sst dev
.
To disable dev mode and deploy your service, pass in false
.
dev.autostart?
Type Input
<
boolean
>
Default true
Configure if you want to automatically start this when sst dev
starts. You can still
start it manually later.
dev.command?
Type Input
<
string
>
The command that sst dev
runs to start this in dev mode. This is the command you run
when you want to run your service locally.
dev.directory?
Type Input
<
string
>
Default Uses the image.dockerfile
path
Change the directory from where the command
is run.
dev.url?
Type Input
<
string
>
Default “http://url-unavailable-in-dev.mode”
The url
when this is running in dev mode.
Since this component is not deployed in sst dev
, there is no real URL. But if you are
using this component’s url
or linking to this component’s url
, it can be useful to
have a placeholder URL. It avoids having to handle it being undefined
.
entrypoint?
Type Input
<
string
[]
>
The entrypoint to override the default entrypoint in the container.
environment?
Type Input
<
Record
<
string
, Input
<
string
>
>
>
Key-value pairs of values that are set as container environment variables. The keys need to:
- Start with a letter
- Be at least 2 characters long
- Contain only letters, numbers, or underscores
executionRole?
Type Input
<
string
>
Default Creates a new role
Assigns the given IAM role name to AWS ECS to launch and manage the containers in the service. This allows you to pass in a previously created role.
By default, the service creates a new IAM role when it’s created.
health?
Type Input
<
Object
>
Default No container health check
Configure the health check for the container. This configuration maps to the
HEALTHCHECK
parameter of docker run.
Learn more about container health checks.
health.command
Type Input
<
string
[]
>
A string array representing the command that the container runs to determine if it is healthy.
The string array must start with CMD
to run the command arguments directly, or
CMD-SHELL
to run the command with the container’s default shell.
health.interval?
Type Input
<
“
${number} minute
”
|
“
${number} minutes
”
|
“
${number} second
”
|
“
${number} seconds
”
>
Default “30 seconds”
The time between running the check. Must be between 5 seconds
and 300 seconds
.
health.retries?
Type Input
<
number
>
Default 3
The number of consecutive failures required to consider the check to have failed. Must
be between 1
and 10
.
health.startPeriod?
Type Input
<
“
${number} minute
”
|
“
${number} minutes
”
|
“
${number} second
”
|
“
${number} seconds
”
>
Default “0 seconds”
The grace period to provide containers time to bootstrap before failed health checks
count towards the maximum number of retries. Must be between 0 seconds
and
300 seconds
.
health.timeout?
Type Input
<
“
${number} minute
”
|
“
${number} minutes
”
|
“
${number} second
”
|
“
${number} seconds
”
>
Default “5 seconds”
The time to wait before considering the check to have hung. Must be between 2 seconds
and 60 seconds
.
image?
Type Input
<
string
|
Object
>
Default Build a Docker image from the Dockerfile in the root directory.
Configure the Docker build command for building the image or specify a pre-built image.
Building a Docker image.
Prior to building the image, SST will automatically add the .sst
directory
to the .dockerignore
if not already present.
Alternatively, you can pass in a pre-built image.
image.args?
Type Input
<
Record
<
string
, Input
<
string
>
>
>
Key-value pairs of build args to pass to the Docker build command.
image.context?
Type Input
<
string
>
Default ”.”
The path to the Docker build context. The path is relative to your project’s sst.config.ts
.
To change where the Docker build context is located.
image.dockerfile?
Type Input
<
string
>
Default “Dockerfile”
The path to the Dockerfile.
The path is relative to the build context
.
To use a different Dockerfile.
link?
Type Input
<
any
[]
>
Link resources to your service. This will:
- Grant the permissions needed to access the resources.
- Allow you to access it in your app using the SDK.
Takes a list of components to link to the service.
loadBalancer?
Type Input
<
Object
>
Default Load balancer is not created
Configure a load balancer to route traffic to the containers.
While you can expose a service through API Gateway, it’s better to use a load balancer for most traditional web applications. It is more expensive to start but at higher levels of traffic it ends up being more cost effective.
Also, if you need to listen on network layer protocols like tcp
or udp
, you have to
expose it through a load balancer.
By default, the endpoint is an autogenerated load balancer URL. You can also add a custom domain for the endpoint.
loadBalancer.domain?
Type Input
<
string
|
Object
>
Set a custom domain for your load balancer endpoint.
Automatically manages domains hosted on AWS Route 53, Cloudflare, and Vercel. For other
providers, you’ll need to pass in a cert
that validates domain ownership and add the
DNS records.
By default this assumes the domain is hosted on Route 53.
For domains hosted on Cloudflare.
loadBalancer.domain.cert?
Type Input
<
string
>
The ARN of an ACM (AWS Certificate Manager) certificate that proves ownership of the domain. By default, a certificate is created and validated automatically.
To manually set up a domain on an unsupported provider, you’ll need to:
- Validate that you own the domain by creating an ACM certificate. You can either validate it by setting a DNS record or by verifying an email sent to the domain owner.
- Once validated, set the certificate ARN as the
cert
and setdns
tofalse
. - Add the DNS records in your provider to point to the load balancer endpoint.
loadBalancer.domain.dns?
Type Input
<
false
|
sst.aws.dns
|
sst.cloudflare.dns
|
sst.vercel.dns
>
Default sst.aws.dns
The DNS provider to use for the domain. Defaults to the AWS.
Takes an adapter that can create the DNS records on the provider. This can automate validating the domain and setting up the DNS routing.
Supports Route 53, Cloudflare, and Vercel adapters. For other providers, you’ll need
to set dns
to false
and pass in a certificate validating ownership via cert
.
Specify the hosted zone ID for the Route 53 domain.
Use a domain hosted on Cloudflare, needs the Cloudflare provider.
Use a domain hosted on Vercel, needs the Vercel provider.
loadBalancer.domain.name
Type Input
<
string
>
The custom domain you want to use.
Can also include subdomains based on the current stage.
loadBalancer.health?
Type Input
<
Record
<
“
${number}/https
”
|
“
${number}/http
”
|
“
${number}/tcp
”
|
“
${number}/udp
”
|
“
${number}/tcp_udp
”
|
“
${number}/tls
”
, Input
<
Object
>
>
>
Configure the health check for the load balancer.
Health checks are used to ensure that only healthy containers receive traffic. The load balancer checks each target container at the specified health check path and only routes traffic to containers that pass these checks.
The health check cannot be disabled.
- The default for “http” protocols is
{ path: "/", interval: "30 seconds", timeout: "5 seconds", healthyThreshold: 5, unhealthyThreshold: 2, successCodes: "200" }
. - The default for “tcp” and “udp” protocols is
{ interval: "30 seconds", timeout: "6 seconds", healthyThreshold: 5, unhealthyThreshold: 2 }
Here we are configuring a health check that pings the /health
path on port 8080
every 10 seconds.
loadBalancer.health[].healthyThreshold?
Type Input
<
number
>
Default 5
The number of consecutive successful health checks required to consider the target healthy. Must be between 2 and 10.
loadBalancer.health[].interval?
Type Input
<
“
${number} minute
”
|
“
${number} minutes
”
|
“
${number} second
”
|
“
${number} seconds
”
>
Default “30 seconds”
The time period between each health check. Must be between 5 and 300 seconds.
loadBalancer.health[].path?
Type Input
<
string
>
Default ”/”
The URL path to ping on the service for health checks. Only applicable to “http” protocols.
loadBalancer.health[].successCodes?
Type Input
<
string
>
Default “200”
One or more HTTP response codes the health check treats as successful. Only applicable to “http” protocols.
loadBalancer.health[].timeout?
Type Input
<
“
${number} minute
”
|
“
${number} minutes
”
|
“
${number} second
”
|
“
${number} seconds
”
>
Default “5 seconds”
The timeout for each health check. If no response is received within this time, the health check is considered failed. Must be between 2 and 120 seconds.
loadBalancer.health[].unhealthyThreshold?
Type Input
<
number
>
Default 2
The number of consecutive failed health checks required to consider the target unhealthy. Must be between 2 and 10.
loadBalancer.ports
Type Input
<
Object
[]
>
Configure the mapping for the ports the load balancer listens to and forwards to the service. This supports two types of protocols:
- Application Layer Protocols:
http
andhttps
. This’ll create an Application Load Balancer. - Network Layer Protocols:
tcp
,udp
,tcp_udp
, andtls
. This’ll create a Network Load Balancer.
You can not configure both application and network layer protocols for the same service.
Here we are listening on port 80
and forwarding it to the service on port 8080
.
The forward
port and protocol defaults to the listen
port and protocol. So in this
case both are 80/http
.
If multiple containers are configured via the containers
argument, you need to
specify which container the traffic should be forwarded to.
loadBalancer.ports[].container?
Type Input
<
string
>
The name of the container to forward the traffic to.
You need this if there’s more than one container.
If there is only one container, the traffic is automatically forwarded to that container.
loadBalancer.ports[].forward?
Type Input
<
“
${number}/https
”
|
“
${number}/http
”
|
“
${number}/tcp
”
|
“
${number}/udp
”
|
“
${number}/tcp_udp
”
|
“
${number}/tls
”
>
Default The same port and protocol as listen
.
The port and protocol of the container the service forwards the traffic to. Uses the
format {port}/{protocol}
.
loadBalancer.ports[].listen
Type Input
<
“
${number}/https
”
|
“
${number}/http
”
|
“
${number}/tcp
”
|
“
${number}/udp
”
|
“
${number}/tcp_udp
”
|
“
${number}/tls
”
>
The port and protocol the service listens on. Uses the format {port}/{protocol}
.
loadBalancer.public?
Type Input
<
boolean
>
Default true
Configure if the load balancer should be public or private.
When set to false
, the load balancer enpoint will only be accessible within the
VPC.
logging?
Type Input
<
Object
>
Default { retention: “1 month” }
Configure the service’s logs in CloudWatch.
logging.retention?
Type Input
<
“
1 day
”
|
“
3 days
”
|
“
5 days
”
|
“
1 week
”
|
“
2 weeks
”
|
“
1 month
”
|
“
2 months
”
|
“
3 months
”
|
“
4 months
”
|
“
5 months
”
|
“
6 months
”
|
“
1 year
”
|
“
13 months
”
|
“
18 months
”
|
“
2 years
”
|
“
3 years
”
|
“
5 years
”
|
“
6 years
”
|
“
7 years
”
|
“
8 years
”
|
“
9 years
”
|
“
10 years
”
|
“
forever
”
>
Default “1 month”
The duration the logs are kept in CloudWatch.
memory?
Type “
${number} GB
”
Default “0.5 GB”
The amount of memory allocated to the container in this service.
permissions?
Type Input
<
Object
[]
>
Permissions and the resources that the service needs to access. These permissions are used to create the service’s task role.
Allow the service to read and write to an S3 bucket called my-bucket
.
Allow the service to perform all actions on an S3 bucket called my-bucket
.
Granting the service permissions to access all resources.
permissions[].actions
Type string
[]
The IAM actions that can be performed.
permissions[].resources
Type Input
<
string
>
[]
The resourcess specified using the IAM ARN format.
scaling?
Type Input
<
Object
>
Default { min: 1, max: 1 }
Configure the service to automatically scale up or down based on the CPU or memory utilization of a container. By default, scaling is disabled and the service will run in a single container.
scaling.cpuUtilization?
Type Input
<
number
|
false
>
Default 70
The target CPU utilization percentage to scale up or down. It’ll scale up when the CPU utilization is above the target and scale down when it’s below the target.
scaling.max?
Type Input
<
number
>
Default 1
The maximum number of containers to scale up to.
scaling.memoryUtilization?
Type Input
<
number
|
false
>
Default 70
The target memory utilization percentage to scale up or down. It’ll scale up when the memory utilization is above the target and scale down when it’s below the target.
scaling.min?
Type Input
<
number
>
Default 1
The minimum number of containers to scale down to.
serviceRegistry?
Type Input
<
Object
>
Configure the CloudMap service registry for the service.
This creates an srv
record in the CloudMap service. This is needed if you want to connect
an ApiGatewayV2
VPC link to the service.
API Gateway will forward requests to the given port on the service.
serviceRegistry.port
Type number
The port in the service to forward requests to.
ssm?
Type Input
<
Record
<
string
, Input
<
string
>
>
>
Key-value pairs of AWS Systems Manager Parameter Store parameter ARNs or AWS Secrets Manager secret ARNs. The values will be loaded into the container as environment variables.
storage?
Type “
${number} GB
”
Default “20 GB”
The amount of ephemeral storage (in GB) allocated to the container in this service.
taskRole?
Type Input
<
string
>
Default Creates a new role
Assigns the given IAM role name to the containers running in the service. This allows you to pass in a previously created role.
By default, the service creates a new IAM role when it’s created. It’ll update this role if you add permissions
or link
resources.
However, if you pass in a role, you’ll need to update it manually if you add permissions
or link
resources.
transform?
Type Object
Transform how this component creates its underlying resources.
transform.autoScalingTarget?
Type TargetArgs
|
(
args
:
TargetArgs
,
opts
:
ComponentResourceOptions
,
name
:
string
)
=>
void
Transform the AWS Application Auto Scaling target resource.
transform.executionRole?
Type RoleArgs
|
(
args
:
RoleArgs
,
opts
:
ComponentResourceOptions
,
name
:
string
)
=>
void
Transform the ECS Execution IAM Role resource.
transform.image?
Type ImageArgs
|
(
args
:
ImageArgs
,
opts
:
ComponentResourceOptions
,
name
:
string
)
=>
void
Transform the Docker Image resource.
transform.listener?
Type ListenerArgs
|
(
args
:
ListenerArgs
,
opts
:
ComponentResourceOptions
,
name
:
string
)
=>
void
Transform the AWS Load Balancer listener resource.
transform.loadBalancer?
Type LoadBalancerArgs
|
(
args
:
LoadBalancerArgs
,
opts
:
ComponentResourceOptions
,
name
:
string
)
=>
void
Transform the AWS Load Balancer resource.
transform.loadBalancerSecurityGroup?
Type SecurityGroupArgs
|
(
args
:
SecurityGroupArgs
,
opts
:
ComponentResourceOptions
,
name
:
string
)
=>
void
Transform the AWS Security Group resource for the Load Balancer.
transform.logGroup?
Type LogGroupArgs
|
(
args
:
LogGroupArgs
,
opts
:
ComponentResourceOptions
,
name
:
string
)
=>
void
Transform the CloudWatch log group resource.
transform.service?
Type ServiceArgs
|
(
args
:
ServiceArgs
,
opts
:
ComponentResourceOptions
,
name
:
string
)
=>
void
Transform the ECS Service resource.
transform.target?
Type TargetGroupArgs
|
(
args
:
TargetGroupArgs
,
opts
:
ComponentResourceOptions
,
name
:
string
)
=>
void
Transform the AWS Load Balancer target group resource.
transform.taskDefinition?
Type TaskDefinitionArgs
|
(
args
:
TaskDefinitionArgs
,
opts
:
ComponentResourceOptions
,
name
:
string
)
=>
void
Transform the ECS Task Definition resource.
transform.taskRole?
Type RoleArgs
|
(
args
:
RoleArgs
,
opts
:
ComponentResourceOptions
,
name
:
string
)
=>
void
Transform the ECS Task IAM Role resource.
volumes?
Type Input
<
Object
>
[]
Mount Amazon EFS file systems into the container.
Create an EFS file system.
And pass it in.
Or pass in a the EFS file system ID.
volumes[].efs
Type Input
<
Efs
|
Object
>
The Amazon EFS file system to mount.
volumes[].efs.accessPoint
Type Input
<
string
>
The ID of the EFS access point.
volumes[].efs.fileSystem
Type Input
<
string
>
The ID of the EFS file system.
volumes[].path
Type Input
<
string
>
The path to mount the volume.
vpc
Type Input
<
Vpc
|
Object
>
The VPC to use for the cluster.
vpc.cloudmapNamespaceId
Type Input
<
string
>
The ID of the Cloud Map namespace to use for the service.
vpc.cloudmapNamespaceName
Type Input
<
string
>
The name of the Cloud Map namespace to use for the service.
vpc.id
Type Input
<
string
>
The ID of the VPC.
vpc.loadBalancerSubnets
Type Input
<
Input
<
string
>
[]
>
A list of subnet IDs in the VPC to place the load balancer in.
vpc.securityGroups
Type Input
<
Input
<
string
>
[]
>
A list of VPC security group IDs for the service.
vpc.serviceSubnets
Type Input
<
Input
<
string
>
[]
>
A list of private subnet IDs in the VPC to place the services in.
Properties
nodes
Type Object
The underlying resources this component creates.
nodes.executionRole
Type undefined
|
Role
The Amazon ECS Execution Role.
nodes.taskRole
Type Role
The Amazon ECS Task Role.
nodes.autoScalingTarget
Type Target
The Amazon Application Auto Scaling target.
nodes.cloudmapService
Type Service
The Amazon Cloud Map service.
nodes.loadBalancer
Type LoadBalancer
The Amazon Elastic Load Balancer.
nodes.service
Type Service
The Amazon ECS Service.
nodes.taskDefinition
Type Output
<
TaskDefinition
>
The Amazon ECS Task Definition.
service
Type Output
<
string
>
The name of the Cloud Map service.
url
Type Output
<
string
>
The URL of the service.
If public.domain
is set, this is the URL with the custom domain.
Otherwise, it’s the autogenerated load balancer URL.
SDK
Use the SDK in your runtime to interact with your infrastructure.
Links
This is accessible through the Resource
object in the SDK.
-
service
string
The name of the Cloud Map service.
-
url
undefined
|
string
The URL of the service.
If
public.domain
is set, this is the URL with the custom domain. Otherwise, it’s the autogenerated load balancer URL.