Load Balanced Web Service

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

frontend Service のサンプル Manifest
# Service 名はロググループや ECS サービスなどのリソースの命名に利用されます。
name: frontend
type: Load Balanced Web Service

# Serviceのトラフィックを分散します。
http:
  path: '/'
  healthcheck:
    path: '/_healthcheck'
    healthy_threshold: 3
    unhealthy_threshold: 2
    interval: 15s
    timeout: 10s
    grace_period: 45s
  deregistration_delay: 5s
  stickiness: false
  allowed_source_ips: ["10.24.34.0/23"]

# コンテナと Service の構成
image:
  build:
    dockerfile: ./frontend/Dockerfile
    context: ./frontend
  port: 80

cpu: 256
memory: 512
count:
  range: 1-10
  cpu_percentage: 70
  memory_percentage: 80
  requests: 10000
  response_time: 2s
exec: true

variables:
  LOG_LEVEL: info
secrets:
  GITHUB_TOKEN: GITHUB_TOKEN

# 上記すべての値は Environment ごとにオーバーライド可能です。
environments:
  test:
    count:
      range:
        min: 1
        max: 10
        spot_from: 2
  staging:
    count:
      spot: 2
  production:
    count: 2

name String
Service の名前。

type String
Service のアーキテクチャタイプ。 Load Balanced Web Service は、ロードバランサー及び AWS Fargate 上の Amazon ECS によって構成される、インターネットに公開するための Service です。

http Map
http セクションは Service と Application Load Balancer の連携に関するパラメーターを含みます。

http.path String
このパスに対するリクエストが Service に転送されます。各 Load Balanced Web Service は、ユニークなパスでリッスンする必要があります。

http.healthcheck String or Map
文字列を指定した場合、Copilot は、ターゲットグループからのヘルスチェックリクエストを処理するためにコンテナが公開しているパスと解釈します。デフォルトは "/" です。

http:
  healthcheck: '/'
あるいは以下のように Map によるヘルスチェックも指定可能です。
http:
  healthcheck:
    path: '/'
    success_codes: '200'
    healthy_threshold: 3
    unhealthy_threshold: 2
    interval: 15s
    timeout: 10s
    grace_period: 60s

http.healthcheck.path String
ヘルスチェックリクエスト送信先。

http.healthcheck.success_codes String
healthy なターゲットがヘルスチェックに対して返す HTTP ステータスコードを指定します。200 から 499 の範囲で指定可能です。また、"200,202" のように複数の値を指定することや "200-299" のような値の範囲指定も可能です。デフォルト値は 200 です。

http.healthcheck.healthy_threshold Integer
unhealthy なターゲットを healthy とみなすために必要な、連続したヘルスチェックの成功回数を指定します。デフォルト値は 5 で、設定可能な範囲は、2 〜 10 です。

http.healthcheck.unhealthy_threshold Integer
ターゲットが unhealthy であると判断するまでに必要な、連続したヘルスチェックの失敗回数を指定します。デフォルト値は 2 で、設定可能な範囲は、2 〜 10 です。

http.healthcheck.interval Duration
個々のターゲットへのヘルスチェックを行う際の、おおよその間隔を秒単位で指定します。デフォルト値は 30 秒で、設定可能な範囲は、5 〜 300 です。

http.healthcheck.timeout Duration
ターゲットからの応答がない場合、ヘルスチェックが失敗したとみなすまでの時間を秒単位で指定します。デフォルト値は 5 秒で、設定可能な範囲は、5 〜 300 です。

http.healthcheck.grace_period Duration
コンテナ起動時にターゲットグループのヘルスチェックが失敗した場合の、それを無視する時間を指定します。デフォルトは 60 秒です。これは、healthy であることを担保しながら着信を待機するまでに時間がかかるコンテナのデプロイ時の問題を修正したり、迅速な起動が保証されているコンテナのデプロイを高速化したりするのに役立ちます。

http.deregistration_delay Duration
登録解除時にターゲットがクライアントとの接続を閉じるのを待つ時間を指定します。デフォルトでは 60 秒です。この値を大きくするとターゲットが安全に接続を閉じるための時間を確保できますが、新バージョンのデプロイに必要となる時間が長くなります。範囲は 0 〜 3600 です。

http.target_container String
サイドカーコンテナを指定することで、Service のメインコンテナの代わりにサイドカーでロードバランサからのリクエストを受け取れます。

http.stickiness Boolean
スティッキーセッションの有効化、あるいは無効化を指定します。

http.allowed_source_ips Array of Strings
Service へのアクセスを許可する CIDR IP アドレスのリストを指定します。

http:
  allowed_source_ips: ["192.0.2.0/24", "198.51.100.10/32"]

http.alias String or Array of Strings
サービスの HTTPS ドメインエイリアス

# 文字列で指定する場合
http:
  alias: example.com
# 別の方法として、文字列配列の場合
http:
  alias: ["example.com", "v1.example.com"]

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

image.build String or Map
このフィールドに 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 パラメータのそれに従います。

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

image.port Integer
公開するポート番号。Dockerfile 内に EXPOSE インストラクションが記述されている場合、Copilot はそれをパースした値をここに挿入します。

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

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

Note

サイドカーのコンテナヘルスチェックは、現在 Copilot ではサポートされていません。つまり、healthy はサイドカーの有効な依存条件ではありません。

設定例:

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

image.healthcheck Map
コンテナヘルスチェックの設定。この設定はオプションです。

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

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

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

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

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

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

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

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

platform String
docker build --platform で渡すオペレーティングシステムとアーキテクチャ。([os]/[arch] の形式で指定)

count Integer or Map
数値を指定する例。

count: 5

Service が保つべきタスク数を5に指定します。

count.spot Integer

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

count:
  spot: 5

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

count:
  range: 1-10
  cpu_percentage: 70
  memory_percentage: 80
  requests: 10000
  response_time: 2s

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.requests Integer
タスク当たりのリクエスト数を指定し、それによってスケールアップ・ダウンします。

count.response_time Duration
Service の平均レスポンスタイムを指定し、それによってスケールアップ・ダウンします。

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

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

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

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

Info

Copilot が生成した VPC を利用して private サブネットにタスクを配置する場合、Copilot は Environment に NAT ゲートウェイを作成します。既存の VPC を copilot env init コマンドでインポートする場合、タスクからのインターネット接続を確保できるよう、その VPC 内に NAT ゲートウェイが作成済みであることを確認してください。

network.vpc.security_groups Array of Strings
Copilot は、Service が Environment 内の他の Service と通信できるようにするためのセキュリティグループを常にタスクに対して設定します。本フィールドでは、同セキュリティグループ以外に追加で紐づけたい1つ以上のセキュリティグループ ID を指定します。

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

secrets Map
AWS Systems Manager (SSM) パラメータストアから取得する秘密情報を、キーに環境変数名、バリューに SSM パラメータ名をペアで指定します。秘密情報はタスク実行時に安全に取得され、環境変数として設定されます。

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 サブフィールドのみを指定した場合は、Copilot 管理の EFS ファイルシステムと Service 専用の EFS アクセスポイントが作成されます。

// Simple managed EFS
efs: true

// Managed EFS with custom POSIX info
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 となっている必要があります。

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

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

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

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

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

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

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 に設定します。

publish Map
publish セクションを使用すると、サービスは 1 つまたは複数の SNS トピックにメッセージをパブリッシュできます。デフォルトでは、作成されたトピックにサブスクライブできる Worker Service はありません。Environment 内の Worker Serivce は、各トピックの allowed_workers フィールドを使って許可リストに登録できます。

publish:
  topics:
    - name: order-events
      allowed_workers: [database-worker, receipts-worker]

上記の例では、この Manifest は、order-events という名前の SNS トピックを定義しています。Copilot の Environment にデプロイされた database-worker または receipts-worker という名前の Worker Service がこのトピックをサブスクライブすることを許可します。

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

publish.topics.topic Map
1 つの SNS トピックの名前とパーミッションを保持します。

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

topic.allowed_workers Array of strings
この SNS トピックをサブスクライブすることが許可されている Worker Service の名前を含む配列です。このフィールドが指定されていない場合、どの Worker もこの SNS トピックへのサブスクリプションを作成することはできません。