Backend Service
List of all available properties for a 'Backend Service'
manifest.
# Your service name will be used in naming your resources like log groups, ECS services, etc.
name: api
# Your service is reachable at "http://{{.Name}}.${COPILOT_SERVICE_DISCOVERY_ENDPOINT}:{{.Image.Port}}" but is not public.
type: Backend App
image:
# Path to your service's Dockerfile.
build: ./api/Dockerfile
# Or instead of building, you can specify an existing image name.
location: aws_account_id.dkr.ecr.region.amazonaws.com/my-svc:tag
# Optional. Port exposed through your container to route traffic to it.
port: 8080
#Optional. Configuration for your container healthcheck.
healthcheck:
# The command the container runs to determine if it's healthy.
command: ["CMD-SHELL", "curl -f http://localhost:8080 || exit 1"]
interval: 10s # Time period between healthchecks. Default is 10s if omitted.
retries: 2 # Number of times to retry before container is deemed unhealthy. Default is 2 if omitted.
timeout: 5s # How long to wait before considering the healthcheck failed. Default is 5s if omitted.
start_period: 0s # Grace period within which to provide containers time to bootstrap before failed health checks count towards the maximum number of retries. Default is 0s if omitted.
# Number of CPU units for the task.
cpu: 256
# Amount of memory in MiB used by the task.
memory: 512
# Number of tasks that should be running in your service.
count: 1
variables: # Optional. Pass environment variables as key value pairs.
LOG_LEVEL: info
secrets: # Optional. Pass secrets from AWS Systems Manager (SSM) Parameter Store.
GITHUB_TOKEN: GITHUB_TOKEN # The key is the name of the environment variable, the value is the name of the SSM parameter.
# Optional. You can override any of the values defined above by environment.
environments:
prod:
count: 2 # Number of tasks to run for the "prod" environment.
name
String
The name of your service.
type
String
The architecture type for your service. Backend services is not reachable from the internet, but can be reached with service discovery from your other services.
image
Map
The image section contains parameters relating to the Docker build configuration and exposed port.
image.build
String or Map
If you specify a string, Copilot interprets it as the path to your Dockerfile. It will assume that the dirname of the string you specify should be the build context. The manifest:
image:
build: path/to/dockerfile
$ docker build --file path/to/dockerfile path/to
You can also specify build as a map:
image:
build:
dockerfile: path/to/dockerfile
context: context/dir
target: build-stage
cache_from:
- image:tag
args:
key: value
$ docker build --file path/to/dockerfile --target build-stage --cache-from image:tag --build-arg key=value context/dir
.
You can omit fields and Copilot will do its best to understand what you mean. For example, if you specify context
but not dockerfile
, Copilot will run Docker in the context directory and assume that your Dockerfile is named "Dockerfile." If you specify dockerfile
but no context
, Copilot assumes you want to run Docker in the directory that contains dockerfile
.
All paths are relative to your workspace root.
image.location
String
Instead of building a container from a Dockerfile, you can specify an existing image name. Mutually exclusive with image.build
.
The location
field follows the same definition as the image
parameter in the Amazon ECS task definition.
image.port
Integer
The port exposed in your Dockerfile. Copilot should parse this value for you from your EXPOSE
instruction.
If you don't need your backend service to accept requests from other services you can omit this field.
image.healthcheck
Map
Optional configuration for container health checks.
image.healthcheck.command
Array of Strings
The command to run to determine if the container is healthy.
The string array can start with CMD
to execute the command arguments directly, or CMD-SHELL
to run the command with the container's default shell.
image.healthcheck.interval
Duration
Time period between healthchecks in seconds. Default is 10s.
image.healthcheck.retries
Integer
Number of times to retry before container is deemed unhealthy. Default is 2.
image.healthcheck.timeout
Duration
How long to wait before considering the healthcheck failed in seconds. Default is 5s.
image.healthcheck.start_period
Duration
Grace period within which to provide containers time to bootstrap before failed health checks count towards the maximum number of retries. Default is 0s.
cpu
Integer
Number of CPU units for the task. See the Amazon ECS docs for valid CPU values.
memory
Integer
Amount of memory in MiB used by the task. See the Amazon ECS docs for valid memory values.
count
Integer or Map
If you specify a number:
count: 5
Alternatively, you can specify a map for setting up autoscaling:
count:
range: 1-10
cpu_percentage: 70
memory_percentage: 80
count.range
String
Specify a minimum and maximum bound for the number of tasks your service should maintain.
count.cpu_percentage
Integer
Scale up or down based on the average CPU your service should maintain.
count.memory_percentage
Integer
Scale up or down based on the average memory your service should maintain.
variables
Map
Key-value pairs that represents environment variables that will be passed to your service. Copilot will include a number of environment variables by default for you.
secrets
Map
Key-value pairs that represents secret values from AWS Systems Manager Parameter Store that will passed to your service as environment variables securely.
environments
Map
The environment section lets you overwrite any value in your manifest based on the environment you're in. In the example manifest above, we're overriding the count parameter so that we can run 2 copies of our service in our prod environment.