Amazon ECS パラメータの使用 - Amazon Elastic Container Service

Amazon ECS パラメータの使用

ecs-cli compose またはecs-cli compose service コマンドを、Amazon ECS タスクおよびサービスを管理するために使用する場合、Amazon ECS タスク定義には、Docker Compose ファイルに対応しないフィールドがあります。これらの値は、--ecs-params フラグで ECS パラメータファイルを使用して指定できます。デフォルトでは、このコマンドは現在のディレクトリで ecs-params.yml という名前の ECS parameters ファイルを検索します。ただし、--ecs-params オプションを使用して、ECS parameters ファイルに別のファイル名またはパスを指定することもできます。

現在、このファイルは以下のスキーマをサポートしています。

version: 1
task_definition:
  ecs_network_mode: string
  task_role_arn: string
  task_execution_role: string
  task_size:
    cpu_limit: string
    mem_limit: string
  pid_mode: string
  ipc_mode: string
  services:
    <service_name>:
      essential: boolean
      depends_on:
        - container_name: string
          condition: string
      repository_credentials:
        credentials_parameter: string
      cpu_shares: integer
      mem_limit: string
      mem_reservation: string
      gpu: string
      init_process_enabled: boolean
      healthcheck:
        test: ["CMD", "curl -f http://localhost"]
        interval: string
        timeout: string
        retries: integer
        start_period: string
      firelens_configuration:
        type: string
        options:
          enable-ecs-log-metadata: boolean
      secrets:
        - value_from: string
          name: string
  docker_volumes:
      - name: string
        scope: string
        autoprovision: 
        driver: string
        driver_opts: boolean
           string: string
        labels:
           string: string
  efs_volumes:
      - name: string
        filesystem_id: string
        root_directory: string
        transit_encryption: string
        transit_encryption_port: int64
        access_point: string
        iam: string
  placement_constraints:
      - type: string
        expression: string
run_params:
  network_configuration:
    awsvpc_configuration:
      subnets: 
        - subnet_id1 
        - subnet_id2
      security_groups: 
        - secgroup_id1
        - secgroup_id2
      assign_public_ip: ENABLED
  task_placement:
    strategy:
      - type: string
        field: string
    constraints:
      - type: string
        expression: string
  service_discovery:
    container_name: string
    container_port: integer
    private_dns_namespace:
        vpc: string
        id: string
        name: string
        description: string
    public_dns_namespace:
        id: string
        name: string
    service_discovery_service:
        name: string
        description: string
        dns_config:
          type: string
          ttl: integer
        healthcheck_custom_config:
          failure_threshold: integer

task_definition に示されているフィールドは、Amazon ECS タスク定義に含まれるフィールドに対応しています。

  • ecs_network_mode – ECS タスク定義の networkMode に対応します。サポートされている値は none、bridge、host、または awsvpc です。デフォルト値は bridge です。タスクネットワーキングを使用する場合、このフィールドは awsvpc に設定する必要があります。詳細については、「ネットワークモード」を参照してください。

  • task_role_arn – タスクに関連付ける IAM ロールの名前または完全な ARN。詳細については、「タスクロール」を参照してください。

  • task_execution_role – タスク実行ロールの名前または完全な ARN。これは、タスクでコンテナアプリケーションログを CloudWatch に保存する場合や、Amazon ECR からコンテナイメージを取得する場合に必要なフィールドです。詳細については、「Amazon ECS タスク実行 IAM ロール」を参照してください。

  • task_size – タスク用の CPU とメモリの値。EC2 起動タイプを使用する場合、このフィールドはオプションであり、任意の値を使用できます。Fargate 起動タイプを使用する場合、このフィールドは必須であり、cpu および memory パラメータに以下のいずれかの値を使用する必要があります。

    CPU の値 メモリの値 (MiB)
    256 (.25 vCPU) 512 (0.5 GB)、1024 (1 GB)、2048 (2 GB)
    512 (.5 vCPU) 1024 (1 GB)、2048 (2 GB)、3072 (3 GB)、4096 (4 GB)
    1024 (1 vCPU) 2048 (2 GB)、3072 (3 GB)、4096 (4 GB)、5120 (5 GB)、6144 (6 GB)、7168 (7 GB)、8192 (8 GB)
    2048 (2 vCPU) 4096 (4 GB) ～ 16384 (16 GB) (1024 (1 GB) のインクリメント)
    4096 (4 vCPU) 8192 (8 GB) ～ 30720 (30 GB) (1024 (1 GB) のインクリメント)

    詳細については、「タスクサイズ」を参照してください。

  • pid_mode – タスクのコンテナで使用するプロセス名前空間。有効な値は host または task です。host が指定されている場合、同じコンテナインスタンスで host PID モードを指定したタスク内のすべてのコンテナは、ホスト Amazon EC2 インスタンスと同じ IPC リソースを共有します。task が指定されている場合、指定したタスク内のすべてのコンテナは同じプロセス名前空間を共有します。値が指定されていない場合、デフォルトはプライベート名前空間です。詳細については、Docker run reference の「PID settings」を参照してください。

    host PID モードを使用する場合は、意図せずプロセス名前空間が公開されるリスクが高いことに注意してください。詳細については、「Docker security」を参照してください。

    注記

    このパラメータは、Fargate 起動タイプを使用する Windows コンテナまたはタスクではサポートされていません。

  • ipc_mode – タスクのコンテナで使用する IPC リソースの名前空間。有効な値は host、task または none です。host が指定されている場合、同じコンテナインスタンスで host IPC モードを指定したタスク内のすべてのコンテナは、ホスト Amazon EC2 インスタンスと同じ IPC リソースを共有します。task が指定されている場合、指定したタスク内のすべてのコンテナは同じ IPC リソースを共有します。none が指定されている場合、タスクのコンテナ内の IPC リソースはプライベートです。タスク内またはコンテナインスタンスの他のコンテナと共有されることはありません。値を指定しない場合、IPC リソース名前空間の共有はコンテナインスタンスの Docker デーモンの設定によって異なります。詳細については、Docker run reference の「IPC settings」を参照してください。

    host IPC モードを使用する場合は、意図せず IPC 名前空間が公開されるリスクが高いことに注意してください。詳細については、「Docker security」を参照してください。

    タスクのコンテナに systemControls を使用して名前空間のカーネルパラメータを設定している場合は、次のように IPC リソース名前空間に適用されます。詳細については、Amazon Elastic Container Service Developer Guide の「システムコントロール」を参照してください。

    • host IPC モードを使用するタスクの場合、systemControls に関連する IPC 名前空間はサポートされていません。

    • task IPC モードを使用するタスクでは、systemControls に関連する IPC 名前空間はタスク内のすべてのコンテナに適用されます。

    注記

    このパラメータは、Fargate 起動タイプを使用する Windows コンテナまたはタスクではサポートされていません。

  • services – Docker 構成ファイルに示されているサービスに対応します。service_name は実行するコンテナの名前と一致します。そのフィールドはコンテナ定義にマージされます。

    • essential – コンテナの essential パラメータが true とマークされている場合、そのコンテナが何らかの理由で失敗または停止すると、タスクに含まれる他のすべてのコンテナは停止します。コンテナの essential パラメータが false とマークされている場合、その失敗はタスクに含まれる残りのコンテナに影響を与えません。デフォルト値は true です。

      すべてのタスクには少なくとも 1 つの必須のコンテナが必要です。アプリケーションが複数のコンテナで構成される場合は、用途が共通するコンテナをコンポーネントにグループ化し、それらのコンポーネントを複数のタスク定義に分ける必要があります。

    • depends_on – このパラメータは、dependsOn タスク定義のパラメータにマッピングします。このパラメータは、コンテナ依存関係のリストを指定するために使用します。これを使って、依存するコンテナの条件付き起動や、複数のコンテナを使用するときの起動順序を保証することができます。タスク定義の例については、「例: コンテナの依存関係」を参照してください。

    • repository_credentials – イメージをプルするためにプライベートリポジトリを使用している場合、repository_credentials により、プライベートリポジトリの認証情報を含むシークレットの名前として AWS Secrets Manager シークレットの ARN を credential_parameter で指定できます。詳細については、「タスクのプライベートレジストリの認証」を参照してください。

    • cpu_shares – このパラメータは、Docker 構成ファイルのリファレンスの cpu_shares にマッピングされます。Docker Compose バージョン 3 を使用している場合、このフィールドはオプションであり、compose ファイルではなく ECS params ファイルで指定する必要があります。Docker Compose バージョン 2 では、このフィールドを compose または ECS params ファイルで指定できます。ECS params ファイルで指定する場合、その値は compose ファイル内にある値を上書きします。

    • mem_limit – このパラメータは、Docker 構成ファイルのリファレンスの mem_limit にマッピングされます。Docker Compose バージョン 3 を使用している場合、このフィールドはオプションであり、compose ファイルではなく ECS params ファイルで指定する必要があります。Docker Compose バージョン 2 では、このフィールドを compose または ECS params ファイルで指定できます。ECS params ファイルで指定する場合、その値は compose ファイル内にある値を上書きします。

    • mem_reservation – このパラメータは、Docker 構成ファイルのリファレンスの mem_reservation にマッピングされます。Docker Compose バージョン 3 を使用している場合、このフィールドはオプションであり、compose ファイルではなく ECS params ファイルで指定する必要があります。Docker Compose バージョン 2 では、このフィールドを compose または ECS params ファイルで指定できます。ECS params ファイルで指定する場合、その値は compose ファイル内にある値を上書きします。

    • gpu – Amazon ECS コンテナエージェントがコンテナ用に予約した物理 GPU の数です。このパラメータは、タスク定義の resourceRequirements フィールドにマッピングします。詳細については、「Amazon ECS での GPU の使用」を参照してください。

    • init_process_enabled – このパラメータを使用して、コンテナ内でinit プロセスを実行し信号を転送してプロセスをできます。このパラメータは、docker run の --init オプションにマッピングされます。

      このパラメータは、コンテナインスタンスで Docker Remote API バージョン 1.25 以上を使用する必要があります。

    • healthcheck – このパラメータは、Docker 構成ファイルのリファレンスの healthcheck にマッピングされます。test フィールドは command として指定することもでき、文字列またはリストである必要があります。リストである場合、最初の項目は NONE、CMD、CMD-SHELL のいずれかにする必要があります。文字列の場合は、CMD-SHELL を指定した場合と同等で、その後にその文字列が続きます。interval、timeout、および start_period フィールドは、文字列形式で期間として指定されます。たとえば、2.5s、10s、1m30s、2h23m、5h34m56s です。

      注記

      単位が指定されていない場合には、秒が指定されたと見なされます。たとえば、10s または 10 と指定することができます。

    • firelens_configuration – このパラメータを使用すると、awsfirelens ログドライバを使用してログ設定を定義できます。これを使用して、AWS のサービスやパートナーの宛先にログをルーティングして保存および分析します。詳細については、「カスタムログルーティング」を参照してください。

      • type – 使用するログルーターのタイプ。サポートされているオプションは fluentbit と fluentd です。

      • options – 使用するログルーターのオプション。これは、ログをルーティングする宛先によって異なります。詳細については、「カスタムログルーティング」を参照してください。

    • secrets – このパラメータを使用すると、AWS Systems Manager パラメータストアに機密データを保存し、コンテナの定義でそれらを参照することにより、コンテナに機密データを挿入できます。詳細については、「機密データの指定」を参照してください。

      • value_from – これは、コンテナに公開する AWS Systems Manager パラメータストア ARN または名前です。起動しているタスクと同じリージョンに Systems Manager パラメータストアパラメータが存在する場合は、シークレットの完全な ARN または名前のどちらも使用できます。別のリージョンにパラメータが存在する場合は、完全な ARN を指定する必要があります。

      • name – コンテナの環境変数として設定する値。

  • docker_volumes – このパラメータで、Docker ボリュームを作成することができます。name キーは必須で、scope、autoprovision、driver、driver_opts および Docker ボリューム設定に対応する labels フィールドは、タスク定義のフィールドです。詳細については、『Amazon Elastic Container Service API Reference』の「DockerVolumeConfiguration」を参照してください。docker_volumes キーを使用して定義されたボリュームは、構成ファイルで設定されていない場合であっても、構成ファイルで名前で参照可能です。

  • efs_volumes – このパラメータを使用すると、Amazon EFS ファイルシステムをマウントできます。name キーと filesystem_id キーが必要です。

    • name – ボリュームの名前。最大 255 文字の英字 (大文字と小文字)、数字、ハイフン、アンダースコアを使用できます。この名前は、コンテナ定義 mountPoints の SourceEvolume パラメータで参照されます。

    • filesystem_id – マウントターゲットを作成するファイルシステムの ID。

    • root_directory – ホスト内にルートディレクトリとしてマウントする Amazon EFS ファイルシステム内のディレクトリ。このパラメータを省略すると、Amazon EFS ボリュームのルートが使用されます。/ を指定すると、このパラメータを省略した場合と同じ結果になります。

    • transit_encryption – Amazon ECS ホストと Amazon EFS サーバーの間で転送される Amazon EFS データの暗号化を有効にするかどうかを指定します。このパラメータは、IAM が有効になっているか、アクセスポイント ID が指定されている場合に必要です。有効な値は ENABLED or DISABLED. DISABLED がデフォルトです。

    • transit_encryption_port – Amazon ECS ホストと Amazon EFS サーバーの間で暗号化されたデータを送信するときに使用するポート。転送中の暗号化ポートを指定しないと、Amazon EFS マウントヘルパーが使用するポート選択方法が使用されます。このパラメータは、transit_encryption を有効した場合に必須です。

    • access_point – 使用する Amazon EFS アクセスポイントの ID。アクセスポイントを指定した場合、ルートディレクトリの値は、アクセスポイントとして設定したディレクトリからの相対値になります。指定する場合は、transit_encryption を有効にする必要があります。

    • iam – Amazon EFS ファイルシステムのマウント時に定義した Amazon ECS タスクの IAM ロールを使用するかどうかを指定します。有効にする場合は、EFSVolumeConfiguration で transit encryption を有効にする必要があります。有効な値は ENABLED or DISABLED. DISABLED がデフォルトです。

  • placement_constraints – このパラメータを使用すると、タスク定義内のタスク配置に対する制約のリストを指定できます。詳細については、Amazon Elastic Container Service API Referenceの「TaskDefinitionPlacementConstraint」を参照してください。EC2 起動タイプを使用する場合、このフィールドはオプションです。Fargate 起動タイプを使用する場合はサポートされません。

run_params の下に示されているフィールドは、API 呼び出しのオプションとして必要な値であり、タスク定義には特に関係ありません。たとえば、compose up (RunTask) や compose service up (CreateService) です。

  • network_configuration – ecs_network_mode に awsvpc を指定した場合、必須です。1 つの入れ子になっているパラメータ awsvpc_configuration を使用します。このパラメータには、以下のサブフィールドがあります。

    • subnets – タスクに関連付けるのに使用されるサブネット ID のリスト。リストにあるサブネットは、タスクを起動するインスタンスと同じ VPC およびアベイラビリティーゾーンにあることが必要です。

    • security_groups – タスクに関連付けるセキュリティグループ ID のリスト。リストにあるセキュリティは、タスクを起動するインスタンスと同じ VPC にあることが必要です。

    • assign_public_ip – このフィールドでサポートされている値は ENABLED または DISABLED です。このフィールドは、Fargate 起動タイプを使用するタスクでのみ使用されます。EC2 起動タイプを使用するタスクでタスクネットワーキングを使用する場合、このフィールドがタスクにあると、リクエストは失敗します。

  • task_placement – このパラメータでタスク配置オプションを指定することができます。EC2 起動タイプを使用する場合、このフィールドはオプションです。Fargate 起動タイプを使用する場合はサポートされません。詳細については、「Amazon ECS タスクの配置」を参照してください。

    以下のサブフィールドがあります。

    • strategy – 2 つのキーがあるオブジェクトのリスト。有効なキーは、type および field です。

      • type – 有効な値は random、binpack または spread です。random を指定した場合、field キーを指定しません。

      • field – 有効な値は、戦略タイプに依存します。

        • spreadの場合、有効な値は instanceId、host、または属性キーと値のペアです。例: attribute:ecs.instance-type =~ t2.*。

        • binpackの場合、有効な値は cpu または memory です。

    • constraints – 2 つのキーがあるオブジェクトのリスト。有効なキーは、type および expression です。

      • type – 有効な値は distinctInstance および memberOf です。distinctInstance を指定した場合、expression キーを指定しません。

      • expression – タイプが memberOf の場合、有効な値は属性またはタスクグループのキーと値のペアです。例: task:group == databases または attribute:color =~ green。

  • service_discovery – このパラメータを使用すると、Amazon Route 53 自動命名 API アクションを使用して Amazon ECS サービス検出 を構成し、サービスのタスクの DNS エントリを管理できます。詳細については、「チュートリアル : Amazon ECS CLI を使用して サービス検出 を使用する Amazon ECS サービスを作成する」を参照してください。