Backend Service

List of all available properties for a 'Backend Service' manifest.

Sample manifest for an api service
# Your service name will be used in naming your resources like log groups, ECS services, etc.
name: api
type: Backend Service

# Your service is reachable at "http://api.${COPILOT_SERVICE_DISCOVERY_ENDPOINT}:8080" but is not public.

# Configuration for your containers and service.
  build: ./api/Dockerfile
  port: 8080
    command: ["CMD-SHELL", "curl -f http://localhost:8080 || exit 1"]
    interval: 10s
    retries: 2
    timeout: 5s
    start_period: 0s

cpu: 256
memory: 512
count: 1
exec: true

      path: '/etc/mount1'
      read_only: true
        id: fs-12345678
        root_dir: '/'
          iam: true
          access_point_id: fsap-12345678

    placement: 'private'
    security_groups: ['sg-05d7cd12cceeb9a6e']

  LOG_LEVEL: info

# You can override any of the values defined above by environment.
    count: 2

name String
The name of your service.

type String
The architecture type for your service. Backend Services are 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. 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:

  build: path/to/dockerfile
will result in the following call to docker build: $ docker build --file path/to/dockerfile path/to

You can also specify build as a map:

    dockerfile: path/to/dockerfile
    context: context/dir
    target: build-stage
      - image:tag
      key: value
In this case, copilot will use the context directory you specified and convert the key-value pairs under args to --build-arg overrides. The equivalent docker build call will be:
$ 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
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 health checks, 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 health check 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.

entrypoint String or Array of Strings
Override the default entrypoint in the image.

# String version.
entrypoint: "/bin/entrypoint --p1 --p2"
# Alteratively, as an array of strings.
entrypoint: ["/bin/entrypoint", "--p1", "--p2"]

command String or Array of Strings
Override the default command in the image.

# String version.
command: ps au
# Alteratively, as an array of strings.
command: ["ps", "au"]

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
The service will set the desired count to 5 and maintain 5 tasks in your service.

Alternatively, you can specify a map for setting up autoscaling:

  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.

exec Boolean
Enable running commands in your container. The default is false. Required for $ copilot svc exec. Please note that this will update the service's Fargate Platform Version to 1.4.0.

network Map
The network section contains parameters for connecting to AWS resources in a VPC.

network.vpc Map
Subnets and security groups attached to your tasks.

network.vpc.placement String
Must be one of 'public' or 'private'. Defaults to launching your tasks in public subnets.


If you launch tasks in 'private' subnets and use a Copilot-generated VPC, Copilot will add NAT Gateways to your environment. Alternatively, you can import a VPC with NAT Gateways when running copilot env init for internet connectivity.

network.vpc.security_groups Array of Strings
Additional security group IDs associated with your tasks. Copilot always includes a security group so containers within your environment can communicate with each other.

variables Map
Key-value pairs that represent 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 represent secret values from AWS Systems Manager Parameter Store that will be securely passed to your service as environment variables.

storage Map
The Storage section lets you specify external EFS volumes for your containers and sidecars to mount. This allows you to access persistent storage across regions for data processing or CMS workloads. For more detail, see the storage page.

storage.volumes Map
Specify the name and configuration of any EFS volumes you would like to attach. The volumes field is specified as a map of the form:

  {{ volume name }}:
    path: "/etc/mountpath"

storage.volumes.volume Map
Specify the configuration of a volume.

volume.path String
Required. Specify the location in the container where you would like your volume to be mounted. Must be fewer than 242 characters and must consist only of the characters a-zA-Z0-9.-_/.

volume.read_only Bool
Optional. Defaults to true. Defines whether the volume is read-only or not. If false, the container is granted elasticfilesystem:ClientWrite permissions to the filesystem and the volume is writable.

volume.efs Map
Specify more detailed EFS configuration. String
Required. The ID of the filesystem you would like to mount.

volume.efs.root_dir String
Optional. Defaults to /. Specify the location in the EFS filesystem you would like to use as the root of your volume. Must be fewer than 255 characters and must consist only of the characters a-zA-Z0-9.-_/. If using an access point, root_dir must be either empty or / and auth.iam must be true.

volume.efs.auth Map
Specify advanced authorization configuration for EFS.

volume.efs.auth.iam Bool
Optional. Defaults to true. Whether or not to use IAM authorization to determine whether the volume is allowed to connect to EFS.

volume.efs.auth.access_point_id String
Optional. Defaults to "". The ID of the EFS access point to connect to. If using an access point, root_dir must be either empty or / and auth.iam must be true.

environments Map
The environment section lets you override 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.