サイドカー

サイドカーは主となるコンテナと共に実行され補助的な役割を担うコンテナのことです。サイドカーの役割はロギングや設定ファイルの取得、リクエストのプロキシ処理などの周辺的なタスクを実行することです。

Attention

Request-Driven Web Service はサイドカーの利用をサポートしていません。

Attention

メインコンテナに Windows イメージを使用している場合、FireLens, AWS X-Ray, AWS App Mesh はサポートされていません。利用しようとしているサイドカーコンテナが Windows 環境での実行をサポートしているか確認してください。

AWS はまた ECS サービスとシームレスに組み合わせられるいくつかのプラグインを提供しており、FireLens や AWS X-Ray、AWS App Mesh など多岐に渡ります。

Manifest の中で storage フィールドを使って主となるコンテナ用の EFS ボリュームを定義した場合、定義した任意のサイドカーコンテナはそのボリュームをマウントできます。

Copilot でサイドカーを追加するには？

Copilot の Manifest でサイドカーを追加したい場合、サイドカーコンテナを直接定義するあるいはサイドカーパターンを利用する方法があります。

サイドカーコンテナを直接定義する

サイドカーコンテナイメージの URL を指定する必要があります。オプションで公開するポートやプライベートレジストリの認証パラメータを指定できます。

port Integer
コンテナの公開するポート番号。(任意項目)

image String or Map サイドカーコンテナのイメージ URL。(必須項目)

image.build String or Map
オプションの引数で指定した Dockerfile からコンテナをビルドします。後述の image.location フィールドとは排他的な使用となります。

このフィールドに String（文字列）を指定した場合、Copilot はそれを Dockerfile の場所を示すパスと解釈します。その際、指定したパスのディレクトリ部が Docker のビルドコンテキストであると仮定します。以下は build フィールドに文字列を指定する例です。

image:
  build: path/to/dockerfile

これにより、イメージビルドの際に次のようなコマンドが実行されることになります: $ docker build --file path/to/dockerfile path/to

build フィールドには Map も利用できます。

image:
  build:
    dockerfile: path/to/dockerfile
    context: context/dir
    target: build-stage
    cache_from:
      - image:tag
    args:
      key: value

この例は、Copilot は Docker ビルドコンテキストに context フィールドの値が示すディレクトリを利用し、args 以下のキーバリューのペアをイメージビルド時の --build-args 引数として渡します。上記例と同等の docker build コマンドは次のようになります:
$ docker build --file path/to/dockerfile --target build-stage --cache-from image:tag --build-arg key=value context/dir.

Copilot はあなたの意図を理解するために最善を尽くしますので、記述する情報の省略も可能です。例えば、context は指定しているが dockerfile は未指定の場合、Copilot は Dockerfile が "Dockerfile" という名前で存在すると仮定しつつ、docker コマンドを context ディレクトリ以下で実行します。逆に dockerfile は指定しているが context が未指定の場合は、Copilot はあなたが dockerfile で指定されたディレクトリをビルドコンテキストディレクトリとして利用したいのだと仮定します。

すべてのパスはワークスペースのルートディレクトリからの相対パスと解釈されます。

image.location String
Dockerfile からコンテナイメージをビルドする代わりに、既存のコンテナイメージ名の指定も可能です。image.location と image.build の同時利用はできません。 location フィールドの制約を含む指定方法は Amazon ECS タスク定義の image パラメータのそれに従います。

Warning

Windows コンテナイメージを指定する場合、Manifest に platform: windows/amd64 を指定する必要があります。
ARM アーキテクチャベースのコンテナイメージを指定する場合、Manifest に platform: linux/arm64 を指定する必要があります。

image.credentials String
任意項目です。プライベートリポジトリの認証情報の ARN。credentials フィールドは、Amazon ECS タスク定義の credentialsParameter と同じです。

image.labels Map
コンテナに付与したい Docker ラベルを key/value の Map で指定できます。これは任意設定項目です。

image.depends_on Map
任意項目。コンテナに追加する Container Dependencies の任意の key/value の Map。Map の key はコンテナ名で、value は依存関係を表す値 (依存条件) として start、healthy、complete、success のいずれかを指定できます。なお、必須コンテナに complete や success の依存条件を指定することはできません。

設定例:

image:
  build: ./Dockerfile
  depends_on:
    nginx: start
    startup: success

上記の例では、タスクのメインコンテナは nginx サイドカーが起動し、startup コンテナが正常に完了してから起動します。

essential Bool サイドカーコンテナが必須のコンテナかどうか。(任意項目。デフォルトでは true)

credentialsParameter String
プライベートレジストリの認証情報を保存している秘密情報の ARN。(任意項目)

variables Map
サイドカーコンテナの環境変数。(任意項目)

secrets Map
サイドカーコンテナで用いる秘密情報。(任意項目)

env_file String
サイドカーコンテナに設定する環境変数を含むファイルのワークスペースのルートからのパス。環境変数ファイルに関する詳細については、環境変数ファイルの指定に関する考慮事項を確認してください。

mount_points Array of Maps
サービスレベルで指定する EFS ボリュームのマウントパス。(任意項目)

mount_points.source_volume String
サイドカーからマウントするときのソースボリューム。(必須項目)

mount_points.path String
サイドカーからボリュームをマウントするときのパス。(必須項目)

mount_points.read_only Boolean
サイドカーにボリュームに対する読み込みのみを許可するかどうか。(デフォルトでは true)

labels Map
コンテナに付与する Docker ラベル。(任意項目)

depends_on Map
このコンテナに適用するコンテナの依存関係。(任意項目)

entrypoint String or Array of Strings
サイドカーのデフォルトのエントリポイントをオーバーライドします。

# 文字列で指定する場合
entrypoint: "/bin/entrypoint --p1 --p2"
# 別の方法として、文字列配列の場合
entrypoint: ["/bin/entrypoint", "--p1", "--p2"]

command String or Array of Strings
サイドカーのデフォルトコマンドを上書きします。

# 文字列で指定する場合
command: ps au
# 別の方法として、文字列配列の場合
command: ["ps", "au"]

healthcheck Map サイドカーコンテナヘルスチェックの設定。この設定はオプションです。

healthcheck.command Array of Strings サイドカーコンテナが healthy であると判断するためのコマンド。 このフィールドに設定する文字列配列の最初のアイテムには、コマンド引数を直接実行するための CMD、あるいはコンテナのデフォルトシェルでコマンドを実行する CMD-SHELL が利用できます。

healthcheck.interval Duration 各ヘルスチェックの実行間の秒単位の間隔です。デフォルト値は１０秒です。

healthcheck.retries Integer コンテナが unhealthy と見なされるまでに、失敗したヘルスチェックを再試行する回数です。デフォルト値は２です。

healthcheck.timeout Duration ヘルスチェックの実行開始から失敗とみなすまでに待機する秒単位の期間です。デフォルト値は５秒です。

healthcheck.start_period Duration ヘルスチェックの実行と失敗がリトライ回数としてカウントされ始める前に、コンテナに対して起動処理を済ませる猶予期間の長さです。秒単位で指定し、デフォルト値は０秒です。

実行例

サイドカーでの Environment オーバーライド

他の Service / Job の Manifest と同様に、サイドカー設定も environments フィールドを利用して環境ごとにオーバーライドできます。 次の例では、datadog サイドカーの環境変数 DD_APM_ENABLED の値を、dev Environment かどうかによって設定しています。

name: api
type: Load Balanced Web Service

sidecars:
  datadog:
    port: 80
    image:
      build: src/reverseproxy/Dockerfile
    variables:
      DD_APM_ENABLED: true

environments:
  dev:
    sidecars:
      datadog:
        variables:
          DD_APM_ENABLED: false

nginx サイドカーコンテナ

以下は Load Balanced Web Service の Manifest で nginx サイドカーコンテナを指定する例です。

name: api
type: Load Balanced Web Service

image:
  build: api/Dockerfile
  port: 3000

http:
  path: 'api'
  healthcheck: '/api/health-check'
  # ロードバランサーのターゲットコンテナは Service のコンテナの代わりにサイドカーの'nginx'を指定しています。
  target_container: 'nginx'

cpu: 256
memory: 512
count: 1

sidecars:
  nginx:
    port: 80
    image:
      build: src/reverseproxy/Dockerfile
    variables:
      NGINX_PORT: 80

Service とサイドカーコンテナ両方で EFS ボリュームを利用

storage:
  volumes:
    myEFSVolume:
      path: '/etc/mount1'
      read_only: false
      efs:
        id: fs-1234567

sidecars:
  nginx:
    port: 80
    image: 1234567890.dkr.ecr.us-west-2.amazonaws.com/reverse-proxy:revision_1
    variables:
      NGINX_PORT: 80
    mount_points:
      - source_volume: myEFSVolume
        path: '/etc/mount1'

AWS Distro for OpenTelemetry サイドカー

以下は、AWS Distro for OpenTelemetry のサイドカーをカスタム構成で実行した例です。このカスタム構成例では、X-Ray トレースデータを収集するだけでなく、ECS メトリクスをサードパーティに送信することができます。この例では、SSM シークレットと追加の IAM 権限が必要になります。

OpenTelemetry サイドカーを使用するには、まず有効な設定ファイルを作成します。次に、設定ファイルのサイズを確認します。標準的なパラメータは 4KB に制限されています。設定ファイルが 4K より大きい場合、高度な SSM パラメータを使用する必要があります。

高度なパラメータが必要な場合は、手動で作成してタグ付けする必要があります。設定が標準パラメータに収まっている場合は、secret init を使用して SSM シークレットを作成します。以下の YAML ドキュメントは、"YOUR-API-KEY-HERE" と書かれた API キーを更新した後、そのまま New Relic で使用することができます。

サンプル YAML では、空のキーが含まれているのは意図的なものです。サイドカーは、これらのキーに対してコレクターのデフォルトを使用します。

receivers:
  awsxray:
    transport: udp
  awsecscontainermetrics:

processors:
  batch:

exporters:
  awsxray:
    region: us-west-2
  otlp:
    endpoint: otlp.nr-data.net:4317
    headers: 
      api-key: YOUR-API-KEY-HERE

service:
  pipelines:
    traces:
      receivers: [awsxray]
      processors: [batch]
      exporters: [awsxray]
    metrics:
      receivers: [awsecscontainermetrics]
      exporters: [otlp]

X-Ray トレースの書き込みには、以下のような追加の IAM 権限が必要です。公開されているドキュメントに従ってこれを Addon に含めてください。

Resources:
  XrayWritePolicy:
    Type: AWS::IAM::ManagedPolicy
    Properties:
      PolicyDocument:
        Version: '2012-10-17'
        Statement:
          - Sid: CopyOfAWSXRayDaemonWriteAccess
            Effect: Allow
            Action:
              - xray:PutTraceSegments
              - xray:PutTelemetryRecords
              - xray:GetSamplingRules
              - xray:GetSamplingTargets
              - xray:GetSamplingStatisticSummaries
            Resource: "*"

Outputs:
  XrayAccessPolicyArn:
    Description: "The ARN of the ManagedPolicy to attach to the task role."
    Value: !Ref XrayWritePolicy

OpenTelemetry コレクターの設定は、環境変数としてサイドカーに渡されます。

sidecars:
  otel_sidecar:
    image: 'public.ecr.aws/aws-observability/aws-otel-collector:latest'
    secrets:
      AOT_CONFIG_CONTENT: /copilot/${COPILOT_APPLICATION_NAME}/${COPILOT_ENVIRONMENT_NAME}/secrets/otel_config

サイドカーパターン

サイドカーパターンは Copilot であらかじめ定義されたサイドカーの構成です。現在サポートされているパターンは FireLens だけですが将来的にさらにパターンを追加していく予定です！

logging:
  # Fluent Bitのイメージ (オプション。デフォルトでは "public.ecr.aws/aws-observability/aws-for-fluent-bit:stable" を使用)
  image: <image URL>
  # Firelens ログドライバーにログを送信するときの設定 (オプション)
  destination:
    <config key>: <config value>
  # ログに ECS メタデータを含むかどうか (オプション。デフォルトでは true )
  enableMetadata: <true|false>
  # ログの設定に渡すシークレット (オプション)
  secretOptions:
    <key>: <value>
  # カスタムの Fluent Bit イメージ内の設定ファイルのフルパス
  configFilePath: <config file path>
  # サイドカーコンテナに対する環境変数 (オプション)
  variables:
    <key>: <value>
  # サイドカーコンテナに公開するシークレット (オプション)
  secrets:
    <key>: <value>

例えば以下のように設定できます。

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

FireLens がログを転送するためにタスクロールに対して必要なアクセス許可を追加で与える必要があるかもしれません。Addon のなかで許可を追加できます。例えば以下のように設定できます。

Resources:
  FireLensPolicy:
    Type: AWS::IAM::ManagedPolicy
    Properties:
      PolicyDocument:
        Version: '2012-10-17'
        Statement:
        - Effect: Allow
          Action:
          - logs:CreateLogStream
          - logs:CreateLogGroup
          - logs:DescribeLogStreams
          - logs:PutLogEvents
          Resource: "<resource ARN>"
Outputs:
  FireLensPolicyArn:
    Description: An addon ManagedPolicy gets used by the ECS task role
    Value: !Ref FireLensPolicy

Info

FireLens ログドライバーは主となるコンテナのログを様々な宛先へルーティングできる一方で、 svc logs コマンドは CloudWatch Logs で Copilot Service のために作成したロググループに送信された場合のみログをトラックできます。