AWS Copilot CLI Documentation

AWS Copilot CLI is a developer tool designed to build, release, and operate production-ready containerized applications on AWS App Runner and Amazon ECS on AWS Fargate. It manages the entire application lifecycle, including:

• Getting started with new applications
• Pushing code to staging environments
• Releasing applications to production

An AWS Copilot Pipeline automates the build and deployment process using AWS CodePipeline. It consists of three main stages:

1. Source Stage: Triggers the pipeline when code is pushed to a configured GitHub, Bitbucket, or AWS CodeCommit repository.
2. Build Stage: Downloads code from the repository, builds the container image for the Service, and pushes it to the Amazon ECR repositories for all Environments. It also uploads input files (such as Addon templates, Lambda function zip files, and environment variable files) to Amazon S3.
3. Deploy Stages: Deploys the built artifacts to one or more Environments. You can optionally include manual approval steps for actions or test commands before or after deployment.

Note: Because the Build Stage uses Linux-based AWS CodeBuild, Copilot Pipelines currently do not support building Windows-based containers.

A Scheduled Job in Copilot is composed of several AWS resources managed via CloudFormation:

• Amazon ECS Task Definition
• Task Role
• Task Execution Role
• AWS Step Function State Machine (used for retrying on failures)
• Amazon EventBridge Event Rule (used to trigger the state machine)

AWS Copilot CLI uses a consistent "noun verb" or "verb" command structure. Commands are lowercase and do not use hyphens, colons, or underscores. Command nesting is limited to a single level; if you need to perform an action on a sub-resource, use flags instead of deeper nesting.

Common patterns include:

• Showing a resource: copilot [entity] show [identifier] [options]
• Listing resources: copilot [entity] ls [options]
• Creating a resource: copilot [entity] init [identifier] [options]
• Updating a resource: copilot [entity] update [options]
• Deleting a resource: copilot [entity] delete [identifier...] [options]

The AWS Copilot CLI manifest is an infrastructure-as-code representation of a service, job, pipeline, or environment's architecture. It is generated during initialization commands (such as copilot init, copilot svc init, copilot job init, copilot pipeline init, or copilot env init) and is subsequently converted into an AWS CloudFormation template by Copilot.

Using a manifest allows you to define high-level architectural settings rather than managing individual AWS resources manually.

Copilot provisions several application-wide resources that support multi-region and multi-account deployments:

ECR Repositories

Each service in your application gets its own ECR Repository per region. These repositories live in the application account (not the environment accounts) and have policies allowing environment accounts to pull images. This setup maintains region isolation and reduces cross-region data transfer costs.

Release Infrastructure

For every region in your app, Copilot creates a KMS Key and an S3 bucket. These are used by CodePipeline to enable cross-region and cross-account deployments. All pipelines in your application share these resources. Policies are configured to allow environments (even in other accounts) to read encrypted deployment artifacts.

Before starting, ensure you have the AWS CLI installed and configured via aws configure.

You can deploy a sample application to AWS App Runner or Amazon ECS on AWS Fargate using the copilot init command. This command automates the creation of a VPC, Application Load Balancer, and an Amazon ECS Service.

Follow these steps to run a sample service:

1. Clone the sample repository.
2. Navigate to the directory.
3. Run copilot init with the required flags.

git clone git@github.com:aws-samples/aws-copilot-sample-service.git demo-app
cd demo-app
copilot init --app demo                \
  --name api                             \
  --type 'Load Balanced Web Service'     \
  --dockerfile './Dockerfile'            \
  --deploy

To verify that your taskdef_overrides are being applied correctly to the generated CloudFormation template, run the following commands to preview the output:

copilot svc package
# OR
copilot job package

You can pass values to your Copilot Manifest by using shell environment variables with the ${VARIABLE_NAME} syntax.

Copilot supports substituting variables in:

• String fields (e.g., image.location)
• Array of Strings fields (e.g., security_groups)
• Map fields where the value type is String or Array of Strings (e.g., secrets).

Example: String substitution If your shell has TAG=version01:

image:
  location: id.dkr.ecr.zone.amazonaws.com/project-name:${TAG}

It is interpreted as:

image:
  location: id.dkr.ecr.zone.amazonaws.com/project-name:version01

Example: Array of Strings substitution If your shell has SECURITY_GROUPS=["sg-123","sg-456"]:

network:
  vpc:
    security_groups: ${SECURITY_GROUPS}

It is interpreted as:

network:
  vpc:
    security_groups:
      - sg-123
      - sg-456