Manifests

The AWS Copilot CLI manifests describe a service’s architecture as infrastructure-as-code.

It is a file generated from copilot init or copilot svc init that gets converted to a AWS CloudFormation template. Unlike raw CloudFormation templates, the manifest allows you to focus on the most common settings for the architecture of your service and not the individual resources.

Manifest files are stored under the copilot/<your service name>/ directory.

Load Balanced Web Service

List of all available properties for a 'Load Balanced Web Service' manifest.

# Your service name will be used in naming your resources like log groups, ECS services, etc.
name: frontend
# The "architecture" of the service you're running.
type: Load Balanced Web Service

image:
  # Path to your service's Dockerfile.
  build: ./Dockerfile
  # Port exposed through your container to route traffic to it.
  port: 80

http:
  # Requests to this path will be forwarded to your service. 
  # To match all requests you can use the "/" path. 
  path: '/'
  # You can specify a custom health check path. The default is "/"
  # healthcheck: "/"

# 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:
  test:
    count: 2               # Number of tasks to run for the "test" environment.

image

The image section contains parameters relating to the Docker build configuration and exposed port.

build

build can be specified either as a string or a map. If you specify a simple 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

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:

image:
  build:
    dockerfile: path/to/dockerfile
    context: context/dir
    args:
      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 --build-arg key=value context/dir

In this case, you can see that Copilot will default to building your Docker image in the context directory you specify.

You can also 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.

port

For a Load Balanced Web Service, the port is where traffic is forwarded to. Copilot will auto-populate this field if there's an EXPOSE command in your Dockerfile.

http

The HTTP section is unique to the Load Balanced Web Service type. When a request comes to the load balancer, traffic will be fowraded to this service if the path matches '/' - meaning any traffic will be forwarded to this service. You could update this so that only traffic to the front-end path would be routed to this service by updating the path to be path: 'front-end'.

There's also an optional health check path. This path is invoked every couple of seconds so that the load balancer can ensure your service is healthy. By default the health check path is / - but this can be changed to anything.

count

memory

cpu

variables

The variable section includes environment variables that will be passed to your service. There are a number of environment variables that are passed in by default.

secrets

The secrets section lets you pass in secret values to your service as environment variables, securely. In this example, the environment variable GITHUB_TOKEN will be set in your service and the value will be extracted from an AWS SSM Parameter named GH_SECRET_TOKEN.

environments

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 coppies of our service in or prod environment.

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
  # 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 10 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:
  test:
    count: 2               # Number of tasks to run for the "test" environment.