Sidecars

What are Copilot sidecars?

Copilot sidecars are containers that run in the same ECS service as the main container. They are usually used to help the main container to perform certain tasks or improve the main container's performance since they share the same resources.

When to use sidecars?

It really depends on your need. For example, you might want to add a log router sidecar to help you route your service's log else where so as to centralize logs for an application; Or you might want to make your application safer or more effective by adding a reverse proxy sidecar.

AWS also provides some plugin options that can be seamlessly incorporated with your ECS service, including but not limited to Firelens, X-ray, and App Mesh.

How to add sidecars in Copilot?

There are two ways of adding sidecars using Copilot manifest: specify general sidecars or sidecar patterns.

General sidecars

By specifying a general sidecar, you'll need to at least provide the URL for the sidecar image and potentially the port you'd like to expose and the credential parameter for private registry.

sidecars:
  {{ sidecar name }}:
    # Port of the container to expose. (Optional)
    port: {{ port number }}
    # Image URL for sidecar container. (Required)
    image: {{ image url }}
    # ARN of the secret containing the private repository credentials. (Optional)
    credentialParameter: {{ credential }}

Below is an example of adding nginx as a sidecar container.

# The manifest for the "hello" service.
# Read the full specification for the "Load Balanced Web Service" type at:
#  https://github.com/aws/amazon-ecs-cli-v2/wiki/Manifests#load-balanced-web-svc

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

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

http:
  # Requests to this path will be forwarded to your service. 
  # To match all requests you can use the "/" path. 
  path: 'api'
  # You can specify a custom health check path. The default is "/"
  healthcheck: '/api/health-check'
  # Target container for Load Balancer to route your traffic to.
  targetContainer: 'nginx'

# 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

sidecars:
  nginx:
    port: 80
    image: 1234567890.dkr.ecr.us-west-2.amazonaws.com/reverse-proxy:revision_1

Sidecar patterns

Sidecar patterns are pre-defined patterns for configuring specific sidecars very easily. The only supported pattern is Firelens for now but we'll add more in the future!

logging:
  # The fluent bit image. (Optional, we'll use "amazon/aws-for-fluent-bit:latest" by default)
  image: {{ image URL }}
  # The configuration options to send to the Firelens log driver. (Optional)
  destination:
    {{ config key }}: {{ config value}}
  # Whether to include ECS metadata in logs. (Optional, default to true)
  enableMetadata: {{ true|false }}
  # Secret to pass to the log configuration. (Optional)
  secretOptions:
    {{ key }}: {{ value}
  # The full config file path in your custom fluent bit image.
  configFile: {{ config file path }}

Also, you might need to add necessary permissions to the task role so that Firelens can perform certain actions. You can add permissions by specifying them with your addons.

Since Firelens log driver can route your main container's logs to various destinations, our svc logs can only track them when they are sent to the log group we create for Copilot service in CloudWatch. Below is an example for it.

# The manifest for the "hello" service.
# Read the full specification for the "Load Balanced Web Service" type at:
#  https://github.com/aws/amazon-ecs-cli-v2/wiki/Manifests#load-balanced-web-svc

# Your service name will be used in naming your resources like log groups, ECS services, etc.
name: hello
# 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: 3000

http:
  # Requests to this path will be forwarded to your service. 
  # To match all requests you can use the "/" path. 
  path: 'hello'
  # 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

logging:
  destination:
    Name: cloudwatch
    region: us-west-2
    log_group_name: /copilot/sidecar-test-hello
    log_stream_prefix: copilot/

And the addons permission file:

AdditionalResourcesPolicy:
  Type: AWS::IAM::ManagedPolicy
  Properties:
    PolicyDocument:
      Version: 2012-10-17
      Statement:
      - Effect: Allow
        Action:
        - logs:CreateLogStream
        - logs:CreateLogGroup
        - logs:DescribeLogStreams
        - logs:PutLogEvents
        Resource: "*"

❇️ We're going to make this easier and more powerful!

Currently we only support using remote images for sidecars which means users need to build and push their local sidecar image. But, we are planning to support using local image or Dockerfile. Additionally, Firelens will be able to route logs for the other sidecars (not just the main container).