コンソールにサインインする
Amazon Elastic Container Service
開発者ガイド (API バージョン 2014-11-13)

AWS ドキュメント » Amazon EC2 Container Service » 開発者ガイド » Amazon ECS コマンドラインインターフェイスの使用 » Amazon ECS コマンドラインリファレンス » Amazon ECS パラメータの使用

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: string
  ipc: string
  services:
    <service_name>:
      essential: boolean
      repository_credentials:
        credentials_parameter: string
      cpu_shares: integer
      mem_limit: string
      mem_reservation: string
      healthcheck:
        test: ["CMD", "curl -f http://localhost"]
        interval: string
        timeout: string
        retries: integer
        start_period: string
      secrets:
        - value_from: string
          name: string
  docker_volumes:
      name: string
      scope: string
      autoprovision: 
      driver: string
      driver_opts: boolean
         string: string
      labels:
         string: 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 – タスクのコンテナで使用するプロセス名前空間。有効な値は host または task です。host が指定されている場合、同じコンテナインスタンスで host PID モードを指定したタスク内のすべてのコンテナは、ホスト Amazon EC2 インスタンスと同じ IPC リソースを共有します。task が指定されている場合、指定したタスク内のすべてのコンテナは同じプロセス名前空間を共有します。値が指定されていない場合、デフォルトはプライベート名前空間です。詳細については、Docker run reference の「PID settings」を参照してください。

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

    注記

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

  • ipc – タスクのコンテナで使用する 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 つの必須のコンテナが必要です。アプリケーションが複数のコンテナで構成される場合は、用途が共通するコンテナをコンポーネントにグループ化し、それらのコンポーネントを複数のタスク定義に分ける必要があります。

    • 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 ファイル内にある値を上書きします。

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

      注記

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

    • 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 キーを使用して定義されたボリュームは、構成ファイルで設定されていない場合であっても、構成ファイルで名前で参照可能です。

run_params の下に示されているフィールドは、API 呼び出しのオプションとして必要な値であり、タスク定義には特に関係ありません。たとえば、compose up (RunTask) や compose service up (CreateService) です。現在、run_params でサポートされている唯一のパラメータは network_configuration です。これは、タスクネットワーキングを使用するために、そして Fargate 起動タイプと共にタスクを使用する場合に必要なパラメータです。

  • 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 です。

    • constraint – 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 サービスを作成する」を参照してください。