Worker Service

以下は 'Worker Service' Manifest で利用できるすべてのプロパティのリストです。Service の概念説明のページも合わせてご覧ください。

Worker Service の Manifest のサンプル
    # Service 名は、ロググループや ECS サービスなどのリソースの命名に使用されます。
    name: orders-worker
    type: Worker Service

    image:
      build: ./orders/Dockerfile

    subscribe:
      topics:
        - name: events
          service: api
          filter_policy:
            event:
            - anything-but: order_cancelled
        - name: events
          service: fe
      queue:
        retention: 96h
        timeout: 30s
        dead_letter:
          tries: 10

    cpu: 256
    memory: 512
    count: 1
    exec: true

    variables:
      LOG_LEVEL: info
    env_file: log.env
    secrets:
      GITHUB_TOKEN: GITHUB_TOKEN

    # 上記で定義された値は、environment で上書きすることができます。
    environments:
      production:
        count:
          range:
            min: 1
            max: 50
            spot_from: 26
          queue_delay:
            acceptable_latency: 1m
            msg_processing_time: 250ms

name String
Service の名前。

type String

Service のアーキテクチャタイプ。Worker Service は、インターネットや VPC 外からはアクセスできません。Worker Service は関連する SQS キューからメッセージをプルするように設計されています。SQS キューは、他の Copilot Service の publish フィールドで作成された SNS トピックへのサブスクリプションによって生成されます。

subscribe Map
subscribe セクションでは、Worker Service が、同じ Application や Environment にある他の Copilot Service が公開する SNS トピックへのサブスクリプションを作成できるようにします。各トピックは独自の SQS キューを定義できますが、デフォルトではすべてのトピックが Worker Service のデフォルトキューにサブスクライブされます。

subscribe:
  topics:
    - name: events
      service: api
      queue: # api-events トピックの固有のキューを定義します。
        timeout: 20s 
    - name: events
      service: fe
  queue: # デフォルトでは、すべてのトピックからのメッセージは、共有キューに入ります。
    timeout: 45s
    retention: 96h
    delay: 30s

subscribe.queue Map
デフォルトでは、サービスレベルのキューが常に作成されます。queue では、そのデフォルトキューの特定の属性をカスタマイズできます。

subscribe.queue.delay Duration
キュー内のすべてのメッセージの配信を遅延させる時間を秒単位で指定します。デフォルトは 0 秒です。指定できる範囲は 0 秒 - 15 分です。

subscribe.queue.retention Duration
Retention はメッセージが削除される前にキューに残っている時間を指定します。デフォルトは 4 日です。指定できる範囲は 60 秒 - 336 時間です。

subscribe.queue.timeout Duration
Timeout はメッセージが配信された後に利用できない時間の長さを定義します。デフォルトは 30 秒です。範囲は 0 秒 - 12 時間です。

subscribe.queue.dead_letter.tries Integer
指定された場合、DLQ(デッドレターキュー)を作成し、メッセージを tries 回試行した後に DLQ にルーティングするリドライブポリシーを設定します。つまり、Worker Service がメッセージの処理に tries 回成功しなかった場合、メッセージ送信はリトライされません。 メッセージは DLQ にルーティングされるため、あとからメッセージの内容を確認して失敗の原因分析に役立てることができます。

subscribe.topics Array of topics
Worker Service がサブスクライブすべき SNS トピックの情報が含まれています。

topic.name String
必須項目。サブスクライブする SNS トピックの名前。

topic.service String
必須項目。この SNS トピックが公開されているサービスです。トピック名と合わせて、Copilot Environment 内で SNS トピックを一意に識別します。

topic.filter_policy Map
任意項目。SNS サブスクリプションフィルターポリシーを指定します。このポリシーは、着信メッセージの属性を評価します。フィルターポリシーは JSON で指定します。例えば以下の様になります。

filter_policy: {"store":["example_corp"],"event":[{"anything-but":"order_cancelled"}],"customer_interests":["rugby","football","baseball"],"price_usd":[{"numeric":[">=",100]}]}
または、YAML の MAP を利用して記述します。

filter_policy:
  store:
    - example_corp
  event:
    - anything-but: order_cancelled
  cutomer_interests:
    - rugby
    - football
    - baseball
  price_usd:
    - numeric:
      - ">="
      - 100
フィルターポリシーの書き方に関するさらに詳しい情報については、SNS documentationを確認してください。

topic.queue Boolean or Map 任意項目。トピックに対する SQS キューの設定です。true を指定した場合、キューはデフォルト設定で作成されます。トピックに対応したキューに関する特性の属性についてカスタマイズする場合は、このフィールドを Map で指定します。

image Map
image セクションは、Docker ビルドに関する設定や公開するポートについてのパラメータを含みます。

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.locationimage.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 は依存関係を表す値 (依存条件) として starthealthycompletesuccess のいずれかを指定できます。なお、必須コンテナに completesuccess の依存条件を指定することはできません。

設定例:

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

cpu Integer タスクに割り当てる CPU ユニット数。指定可能な値については Amazon ECS ドキュメントをご覧ください。

memory Integer
タスクに割り当てるメモリ量(MiB)。指定可能な値については Amazon ECS ドキュメントをご覧ください。

platform String or Map
docker build --platform で渡すオペレーティングシステムとアーキテクチャ。([os]/[arch] の形式で指定)
例えば linux/arm64windows/x86_64 などが指定できます。デフォルトは linux/x86_64 です。

異なる osfamilyarchitecture を明示的に指定することもできます。 例えば、Windows では以下の設定はデフォルトで WINDOWS_SERVER_2019_CORE が利用されますが

platform: windows/x86_64

Map を使って WINDOWS_SERVER_2019_FULL を明示的に指定できます。

platform:
  osfamily: windows_server_2019_full
  architecture: x86_64

count Integer or Map 次の様に指定すると、

count: 5
Service は、希望するタスク数を 5 に設定し、Service 内に 5 つのタスクが起動している様に保ちます。

count.spot Integer

spot サブフィールドに数値を指定することで、Service の実行に Fargate Spot キャパシティを利用できます。

count:
  spot: 5

Info

ARM アーキテクチャで動作するコンテナでは、Fargate Spot はサポートされていません。

あるいは、Map を指定してオートスケーリングの設定も可能です。

count:
  range: 1-10
  cpu_percentage: 70
  memory_percentage: 80
  queue_delay:
    acceptable_latency: 10m
    msg_processing_time: 250ms

count.range String or Map メトリクスで指定した値に基づいて、Service が保つべきタスク数の最小と最大を範囲指定できます。

count:
  range: n-m
これにより Application Auto Scaling がセットアップされ、MinCapacityn が、MaxCapacitym が設定されます。

あるいは次の例に挙げるように range フィールド以下に minmax を指定し、加えて spot_from フィールドを利用することで、一定数以上のタスクを実行する場合に Fargate Spot キャパシティを利用する設定が可能です。

count:
  range:
    min: 1
    max: 10
    spot_from: 3

上記の例では Application Auto Scaling は 1-10 の範囲で設定されますが、最初の2タスクはオンデマンド Fargate キャパシティに配置されます。Service が3つ以上のタスクを実行するようにスケールした場合、3つ目以降のタスクは最大タスク数に達するまで Fargate Spot に配置されます。

range.min Integer Service がオートスケーリングを利用する場合の最小タスク数。

range.max Integer Service がオートスケーリングを利用する場合の最大タスク数。

range.spot_from Integer Service の何個目のタスクから Fargate Spot キャパシティプロバイダーを利用するか。

count.cpu_percentage Integer Service が保つべき平均 CPU 使用率を指定し、それによってスケールアップ・ダウンします。

count.memory_percentage Integer Service が保つべき平均メモリ使用率を指定し、それによってスケールアップ・ダウンします。

count.queue_delay Integer タスク単位の許容可能なバックログをトラッキングし、許容可能なキュー遅延を維持するようにスケールアップ・ダウンします。 タスク単位の許容可能なバックログとは、acceptable_latencymsg_processing_time で割って計算されます。例えば、メッセージが到着後、10 分以内に処理できれば良いとします。またメッセージを処理するのに平均 250 ミリ秒かかるとすると、この時、acceptableBacklogPerTask = 10 * 60 / 0.25 = 2400 となります。各タスクは 2,400 件のメッセージを処理することになります。 ターゲットトラッキングポリシーはタスクあたり 2400 メッセージ以下の処理となる様に Service をスケールアップ・ダウンします。詳細については、docsを確認してください。

count.queue_delay.acceptable_latency Duration メッセージがキューに格納されている許容可能な時間。例えば、"45s""5m"10h を指定します。

count.queue_delay.msg_processing_time Duration SQS メッセージ 1 件あたりの平均処理時間。例えば、"250ms""1s" を指定します。

exec Boolean
コンテナ内部でのインタラクティブなコマンド実行機能を有効化します。デフォルト値は false です。$ copilot svc exec コマンドの利用には、この値に true を指定しておく必要があります。

deployment Map
deployment セクションには、デプロイ中に実行されるタスクの数や、タスクの停止と開始の順序を制御するためのパラメータが含まれています。

deployment.rolling String
ローリングデプロイ戦略。有効な値は以下の通りです。

  • "default": 古いタスクを停止する前に、更新されたタスク定義で必要な数だけ新しいタスクを作成します。内部的には、minimumHealthyPercent を 100 に、maximumPercent を 200 に設定することになります。
  • "recreate": 実行中のタスクをすべて停止し、新しいタスクを起動します。内部的には、minimumHealthyPercent を 0 に、maximumPercent を 100 に設定します。

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"]

network Map
network セクションは VPC 内の AWS リソースに接続するための設定です。

network.vpc Map
タスクを配置するサブネットとアタッチされるセキュリティグループの設定です。

network.vpc.placement String or Map
String として利用する場合、public あるいは private のどちらかを指定します。デフォルトではタスクはパブリックサブネットに配置されます。

Info

Copilot が生成した VPC を利用して private サブネットにタスクを配置する場合、Copilot は Environment にインターネット接続用の NAT ゲートウェイを作成します。(価格はこちら。)あるいは copilot env init コマンドで既存の VPC をインポートして利用することや、分離されたワークロード用に VPC エンドポイントが構成された VPC を構成ができます。詳細は、custom environment resourcesを確認してください。

Map として利用する場合、 Copilot が ECS タスクを起動するサブネットを指定します。例:

network:
  vpc:
    placement:
      subnets: ["SubnetID1", "SubnetID2"]

network.vpc.placement.subnets Array of Strings
Copilot が ECS タスクを起動するサブネット ID のリスト

network.vpc.security_groups Array of Strings Copilot がタスクに対して自動で設定するセキュリティグループ以外に追加で設定したいセキュリティグループがある場合にそれらの ID を指定します。複数のセキュリティグループ ID を指定可能です。(Copilot が自動設定するセキュリティグループは、同一 Environment 内の Service 間通信を可能にする目的で設定されます。)

variables Map
Copilot は Service 名などを常に環境変数としてタスクに対して渡します。本フィールドではそれら以外に追加で渡したい環境変数をキーバーリューのペアで指定します。

env_file String
ワークスペースのルートから、メインコンテナに引き渡す環境変数を含むファイルへのパスを指定します。環境変数ファイルの詳細については、環境変数ファイルの指定に関する考慮事項を参照してください。

secrets Map
AWS Systems Manager (SSM) パラメータストアまたは AWS Secrets Managerから環境変数として、Service に安全に渡される秘密値を表すキー・値ペアを指定します。

storage Map
storage セクションでは、コンテナやサイドカーでマウントしたい EFS ボリュームを指定できます。これにより、リージョン内のアベイラビリティゾーンにまたがって永続化ストレージへのアクセスが必要となるデータ処理や CMS のようなワークロードの実行が可能となります。詳細はストレージページもご覧ください。また、タスクレベルのエフェメラルストレージの拡張を設定もできます。

storage.ephemeral Int タスクに割り当てたいエフェメラルストレージのサイズを GiB で指定します。デフォルトかつ最小値は 20 GiB で、最大値は 200 GiB です。20 GiB を超えるサイズを指定した場合、サイズに応じた追加の料金が発生します。

タスクのメインコンテナとサイドカーでファイルシステムを共有したい場合、例えば次のように空ボリュームを使う方法が検討できます。

storage:
  ephemeral: 100
  volumes:
    scratch:
      path: /var/data
      read_only: false

sidecars:
  mySidecar:
    image: public.ecr.aws/my-image:latest
    mount_points:
      - source_volume: scratch
        path: /var/data
        read_only: false
この例ではサイドカーとメインコンテナで共有されるボリュームとして、100 GiB のストレージがプロビジョンされます。例えば大きなサイズのデータセットを利用したい場合、あるいはディスク I/O の要求が高いワークロードにおいてサイドカーを利用して EFS からデータをコピーするような場合に有効な方法と言えます。

storage.volumes Map
マウントしたい EFS ボリュームの名前や設定を指定します。volumes フィールドでは次のように Map を利用して指定します。

volumes:
  <volume name>:
    path: "/etc/mountpath"
    efs:
      ...

storage.volumes.volume Map
ボリュームの設定を指定します。

volume.path String
必須設定項目です。ボリュームをマウントするコンテナ内のパスを指定します。指定する値は242文字未満かつ a-zA-Z0-9.-_/ の文字種である必要があります。

volume.read_only Boolean
任意設定項目で、デフォルト値は true です。ボリュームを読み取り専用とするかどうかを指定します。false に設定した場合、コンテナにファイルシステムへの elasticfilesystem:ClientWrite 権限が付与され、それによりボリュームへ書き込めるようになります。

volume.efs Boolean or Map
詳細な EFS 設定を指定します。Boolean 値による指定、あるいは uidgid サブフィールドのみを指定した場合に、EFS ファイルシステムと Service 専用の EFS アクセスポイントが作成されます。

// Boolean 値を指定する場合
efs: true

// POSIX uid/gid を指定する場合
efs:
  uid: 10000
  gid: 110000

volume.efs.id String
必須設定項目です。マウントする EFS ファイルシステムの ID を指定します。

volume.efs.root_dir String 任意設定項目で、デフォルト値は / です。EFS ファイルシステム内のどのパスをマウントするボリュームのルートとするのかを指定します。指定する値は 255 文字未満かつ a-zA-Z0-9.-_/ の文字種である必要があります。EFS アクセスポイントを利用する場合、本設定値に空もしくは / を指定し、かつ auth.iam の設定値が true となっている必要があります。

volume.efs.uid Uint32 任意設定項目で、gid とともに指定する必要があります。また、root_dirauthid とともに指定することはできません. Copilot 管理の EFS ファイルシステムに対する EFS アクセスポイントを作成する際の POSIX UID として利用されます。

volume.efs.gid Uint32 任意設定項目で、uid とともに指定する必要があります。また、root_dirauthid とともに指定することはできません. Copilot 管理の EFS ファイルシステムに対する EFS アクセスポイントを作成する際の POSIX GID として利用されます。

volume.efs.auth Map
EFS に関連する認可設定を指定します。

volume.efs.auth.iam Boolean
任意設定項目で、デフォルトは true です。EFS リソースへのアクセスに IAM による認可を利用するかどうかを指定します。

volume.efs.auth.access_point_id String
任意設定項目で、デフォルトは "" です。利用する EFS アクセスポイントの ID を指定します。EFS アクセスポイントを利用する場合、root_dir の設定値に空もしくは / を指定しており、かつ本設定値が true となっている必要があります。

publish Map
publish セクションを使用すると、サービスは 1 つまたは複数の SNS トピックにメッセージをパブリッシュできます。

publish:
  topics:
    - name: orderEvents

上記の例では、この Manifest は、Copilot の Environment にデプロイされた他の Worker Service がサブスクライブできる orderEvents という名前の SNS トピックを定義しています。COPILOT_SNS_TOPIC_ARNS という名前の環境変数が、JSON 文字列としてワークロードに設定されます。

JavaScriptでは、次のように記述できます。

const {orderEvents} = JSON.parse(process.env.COPILOT_SNS_TOPIC_ARNS)
詳しくは、パブリッシュ / サブスクライブのページをご覧ください。

publish.topics Array of topics
topic オブジェクトのリスト。

publish.topics.topic Map
1 つの SNS トピックの設定を保持します。

topic.name String
必須項目。SNS トピックの名前です。大文字、小文字、数字、ハイフン、アンダースコアのみを含む必要があります。

logging Map
logging セクションには、ログ設定を含みます。このセクションでは、コンテナの FireLens ログドライバ用のパラメータを設定できます。(設定例はこちら)

logging.retention Integer
任意項目。 ログイベントを保持する日数。設定可能な値については、こちらを確認してください。省略した場合、デフォルトの 30 が設定されます。

logging.image Map
任意項目。使用する Fluent Bit のイメージ。デフォルト値は public.ecr.aws/aws-observability/aws-for-fluent-bit:stable

logging.destination Map
任意項目。FireLens ログドライバーにログを送信するときの設定。

logging.enableMetadata Map
任意項目。ログに ECS メタデータを含めるかどうか。デフォルトは true

logging.secretOptions Map
任意項目。ログの設定に渡す秘密情報です。

logging.configFilePath Map
任意項目。カスタムの Fluent Bit イメージ内の設定ファイルのフルパス。

observability Map
observability セクションは、Service の現在の状態を測定する方法を設定することができます。現在のところ、トレース設定のみサポートされています。

詳細については、observability のページを参照してください。

observability.tracing String
トレースに使用するベンダー。現在、awsxray のみサポートしています。

taskdef_overrides Array of Rules
taskdef_overrides セクションでは、ECS のタスク定義のオーバーライドルールを適用できます (例はこちら)。

taskdef_overrides.path String 必須設定項目です。オーバーライドするタスク定義のフィールドのパス。

taskdef_overrides.value Any 必須設定項目です。オーバーライドするタスク定義のフィールドの値。

environments Map
environments セクションでは、Manifest 内の任意の設定値を Environment ごとにオーバーライドできます。上部記載の Manifest 例では count パラメータをオーバーライドすることで 'prod' Environment で実行されるタスク数を 2 に設定し、'staging' Environment で実行される Fargate Spot capacity によるタスク数を 2 に設定します。