AWS Copilot CLI

AWS Copilot CLI cheatsheet — deploy containers to ECS/Fargate. copilot init, copilot svc deploy, copilot env deploy, copilot pipeline. Simplified AWS container deployments.

7 min read

What it is

AWS Copilot CLI is a command-line interface for building, releasing, and operating containerized applications on AWS, simplifying the deployment of microservices and web applications.

Installation

Linux:

sudo curl -Lo /usr/local/bin/copilot https://github.com/aws/copilot-cli/releases/latest/download/copilot-linux-amd64
sudo chmod +x /usr/local/bin/copilot

Mac:

brew tap aws/tap
brew install copilot

Alternatively, download the binary:

curl -Lo copilot https://github.com/aws/copilot-cli/releases/latest/download/copilot-macos
chmod +x copilot
sudo mv copilot /usr/local/bin/copilot

Windows: Download the latest release from the Copilot CLI GitHub releases page and add the executable to your system’s PATH.

Core Concepts

Application: A logical grouping of services. You deploy an application to an environment.
Environment: A deployment target (e.g., test, staging, prod) that contains a set of AWS resources managed by Copilot. Environments can be linked, allowing for progressive rollouts.
Service: A specific containerized application (e.g., a web frontend, a backend API). A service can be deployed to multiple environments.
Manifest File: A YAML file (e.g., copilot.yml, Dockerfile) that defines the configuration for a service or an environment.

Commands / Usage

Application Management

Initialize a new application:
```
copilot app init --name my-app
```
Creates a new Copilot application named my-app.
List applications:
```
copilot app ls
```
Lists all Copilot applications in your AWS account and region.
Show application details:
```
copilot app show --name my-app
```
Displays details about the specified application.
Delete an application:
```
copilot app delete --name my-app
```
Deletes the specified application and all its associated environments and services.

Environment Management

Initialize a new environment:
```
copilot env init --name test --profile default
```
Initializes a new environment named test using your AWS default profile. You can specify a different profile with --profile <profile-name>.
Deploy an environment:
```
copilot env deploy --name test
```
Deploys or updates the specified environment.
List environments:
```
copilot env ls --name my-app
```
Lists all environments for the specified application.
Show environment details:
```
copilot env show --name my-app --env test
```
Displays details about the specified environment.
Delete an environment:
```
copilot env delete --name my-app --env test
```
Deletes the specified environment and all services deployed within it.

Service Management

Initialize a new service:
```
copilot svc init --name api --app my-app --profile default
```
Initializes a new service named api within the my-app application. You’ll be prompted to choose a service type (e.g., Load Balanced Web Service, Backend Service, Worker Service). This command creates a copilot.yml file for your service.
Deploy a service:
```
copilot svc deploy --name api --app my-app --env test
```
Deploys or updates the api service to the test environment for the my-app application.
List services:
```
copilot svc ls --name my-app --env test
```
Lists all services deployed in the specified environment for the application.
Show service details:
```
copilot svc show --name my-app --svc api --env test
```
Displays details about the specified service in the environment.
View service logs:
```
copilot svc logs --name my-app --svc api --env test
```
Fetches and displays logs for the specified service in the environment. Use --follow to stream logs.
Delete a service:
```
copilot svc delete --name my-app --svc api --env test
```
Deletes the specified service from the environment.

Pipeline Management

Initialize a new pipeline:
```
copilot pipeline init --name my-pipeline --app my-app
```
Initializes a new CI/CD pipeline for your application. You’ll be prompted to choose a source provider (e.g., GitHub, CodeCommit).
Deploy a pipeline:
```
copilot pipeline deploy --name my-pipeline --app my-app
```
Deploys or updates the specified pipeline.
Show pipeline details:
```
copilot pipeline show --name my-pipeline --app my-app
```
Displays details about the specified pipeline, including its stages and associated environments.
Execute a pipeline:
```
copilot pipeline execute --name my-pipeline --app my-app --branch main
```
Manually triggers a pipeline execution for a specific branch.

Delete a pipeline:

copilot pipeline delete --name my-pipeline --app my-app

Deletes the specified pipeline.

Workspace Management

Initialize a new workspace:
```
copilot workspace init
```
Initializes a new Copilot workspace if you’re not already in an application directory.
Show workspace status:
```
copilot workspace status
```
Displays the current status of your Copilot workspace, including the application and environment context.

Other Commands

Check Copilot version:
```
copilot version
```
Displays the installed version of the Copilot CLI.

Help:

copilot --help
copilot app --help
copilot svc deploy --help

Provides help information for commands and subcommands.

Common Patterns

Deploying a service to all environments:
```
copilot svc deploy --name api --app my-app --all-envs
```
Deploys the api service to every environment configured for the my-app application.
Viewing logs for a service in the current environment:
```
copilot svc logs --svc api --follow
```
Streams logs for the api service in the environment currently configured in your Copilot workspace.
Creating a new service from a Dockerfile: When initializing a service (copilot svc init), choose the "Load Balanced Web Service" or "Backend Service" type, and Copilot will prompt you to specify the path to your Dockerfile.
Troubleshooting a failed deployment: Check the output of copilot svc deploy for error messages. If the issue persists, examine CloudFormation stack events for the environment or service in the AWS console. Use copilot svc logs to inspect application logs.
Adding a new environment to an existing application:
1. Initialize the environment: copilot env init --name staging --app my-app
2. Deploy the environment: copilot env deploy --name staging --app my-app
3. Deploy your services to the new environment: copilot svc deploy --name <service-name> --app my-app --env staging
Configuring environment variables for a service: Edit the copilot.yml file for your service. Under the variables section, add key-value pairs. For secrets, use AWS Secrets Manager.
```
# copilot.yml
name: my-api-service
type: Backend Service

variables:
  MY_VARIABLE: "some_value"
```

{% raw %} MY_SECRET: "{{secrets.my-app/my-secret-name}}" # Refers to a secret in AWS Secrets Manager {% endraw %} ```

Setting up health checks for a Load Balanced Web Service: In your copilot.yml, configure the healthcheck block:

# copilot.yml
name: my-web-frontend
type: Load Balanced Web Service

healthcheck:
  path: /health
  interval: 30s
  timeout: 5s
  healthy_threshold: 2
  unhealthy_threshold: 3

Gotchas

Resource Naming: Copilot automatically generates AWS resource names based on your application, environment, and service names. Avoid using special characters or excessively long names, as this can sometimes lead to naming conflicts or errors.
Permissions: Ensure your AWS credentials have the necessary permissions to create and manage AWS resources (ECS, ECR, ALB, CloudFormation, etc.). Copilot uses IAM roles, but the initial setup of your AWS environment might require specific permissions.
Environment Linking: When linking environments (e.g., test to staging), the linked environment’s resources are created within the same VPC as the source environment. This can simplify networking but also means they share the same network infrastructure.
copilot.yml Location: The copilot.yml file must be in the root directory of your service’s codebase.
Implicit Resource Creation: Copilot abstracts away much of the underlying AWS infrastructure. While convenient, it means you might not always be aware of every resource being created. Understand the service types and their default configurations.
State Management: Copilot manages your infrastructure through CloudFormation. Direct modifications to resources managed by Copilot outside of the CLI can lead to drift and deployment issues. Always use Copilot commands to manage your infrastructure.
Service Discovery: For backend services communicating with each other, Copilot automatically configures Service Discovery using AWS Cloud Map. Ensure your service names are unique within the application.
Docker Image Building: By default, Copilot builds Docker images using docker build in your local environment. If you need more advanced build steps or want to build directly on AWS, consider using custom build configurations or AWS CodeBuild within your pipeline.