Amazon Elastic Container Service
開発者ガイド (API バージョン 2014-11-13)

ecs-cli compose

説明

ECS クラスターで docker-compose スタイルのコマンドを使用して、Amazon ECS タスクを管理します。

注記

Amazon ECS CLI を使用して Amazon ECS サービスを作成するには、「ecs-cli compose service」を参照してください。

ecs-cli compose コマンドは、Docker 構成ファイルと使用されて、タスク定義を作成し、タスクを管理します。現時点で、Amazon ECS CLI の最新バージョンでは、Docker Compose ファイル構文のバージョン 1、2、3 がサポートされています。

注記

Amazon ECS CLI では、Docker 構成ファイル構文のメジャーバージョンのみがサポートされています。したがって、構成ファイルで指定されたバージョンは、文字列 "1""1.0""2""2.0""3"、または "3.0" である必要があります。

デフォルトでは、このコマンドは現在のディレクトリで docker-compose.yml という名前の compose ファイルを検索します。ただし、--file オプションを使用して、構成ファイルに別のファイル名またはパスを指定できます。これは、Amazon ECS CLI を使用して複数の構成ファイルからタスクとサービスを一度に管理するために特に便利です。

ecs-cli compose コマンドは、作成するタスク定義とサービスで、プロジェクト名を使用します。CLI によって構成ファイルからタスク定義が作成されるとき、タスク定義には project-name という名前が付けられます。CLI によって構成ファイルからサービスが作成されるとき、サービスには service-project-name という名前が付けられます。デフォルトでは、プロジェクト名は現在の作業ディレクトリの名前です。ただし、--project-name オプションを使用して独自のプロジェクト名を指定することもできます。

注記

Amazon ECS CLI は、CLI で作成されたタスク、サービス、およびコンテナインスタンスのみを管理できます。Amazon ECS CLI で作成されていないタスク、サービス、およびコンテナインスタンスを管理するには、AWS Command Line Interface または AWS マネジメントコンソールを使用します。

以下のパラメーターが、Amazon ECS CLI 用の構成ファイルでサポートされています。

  • cap_add (Fargate 起動タイプを使用するタスクでは無効)

  • cap_drop (Fargate 起動タイプを使用するタスクでは無効)

  • command

  • cpu_shares

    注記

    Compose バージョン 3 形式を使用している場合、cpu_shares は、ecs-params.yml で指定する必要があります。file. 詳細については、「Amazon ECS パラメータの使用」を参照してください。

  • devices (Fargate 起動タイプを使用するタスクでは無効)

  • dns

  • dns_search

  • entrypoint

  • environment: 構成ファイルで環境変数値が指定されていないが、シェル環境に存在する場合、シェル環境変数値が、関連付けられたタスクまたはサービス用に作成されたタスク定義に渡されます。

    重要

    認証情報データなどの機密情報にプレーンテキストの環境変数を使用することはお勧めしません。

  • env_file

    重要

    認証情報データなどの機密情報にプレーンテキストの環境変数を使用することはお勧めしません。

  • extra_hosts

  • healthcheck (構成ファイルバージョン 3 のみ)

    注記

    start_period フィールドは構成ファイルの使用をサポートしていません。start_period を指定するには、ecs-params.yml を使用します。file. 詳細については、「Amazon ECS パラメータの使用」を参照してください。

  • hostname

  • image

  • labels

  • links (Fargate 起動タイプを使用するタスクでは無効)

  • log_driver (構成ファイルバージョン 1 のみ)

  • log_opt (構成ファイルバージョン 1 のみ)

  • logging (構成ファイルバージョン 2 および 3)

    • driver

    • options

  • mem_limit (バイト単位)

    注記

    Compose バージョン 3 形式を使用している場合、mem_limit は、ecs-params.yml で指定する必要があります。file. 詳細については、「Amazon ECS パラメータの使用」を参照してください。

  • mem_reservation (バイト単位)

    注記

    Compose バージョン 3 形式を使用している場合、mem_reservation は、ecs-params.yml で指定する必要があります。file. 詳細については、「Amazon ECS パラメータの使用」を参照してください。

  • ports

  • privileged (Fargate 起動タイプを使用するタスクでは無効)

  • read_only

  • security_opt

  • shm_size (構成ファイルバージョン 1 および 2 のみで、Fargate 起動タイプを使用するタスクには無効です)

  • tmpfs (Fargate 起動タイプを使用するタスクでは無効)

  • ulimits

  • user

  • volumes

  • volumes_from (構成ファイルバージョン 1 および 2 のみ)

  • working_dir

重要

build ディレクティブは現在サポートされていません。

Docker 構成ファイル構文の詳細については、Docker ドキュメントの構成ファイルのリファレンスを参照してください。

重要

記載されている機能の一部は、ECS CLI の最新バージョンでのみ使用可能です。最新バージョンを取得するには、「Amazon ECS CLI のインストール」を参照してください。

Amazon ECS パラメータの使用

Amazon ECS タスク定義には、Docker 構成ファイルのフィールドに対応しないフィールドがあるため、これらの値を指定するには --ecs-params フラグを使用します。デフォルトでは、このコマンドは現在のディレクトリで 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 services: <service_name>: essential: boolean 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 run_params: network_configuration: awsvpc_configuration: subnets: - subnet_id1 - subnet_id2 security_groups: - secgroup_id1 - secgroup_id2 assign_public_ip: ENABLED

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

  • ecs_network_mode – ECS タスク定義の networkMode に対応します。サポートされている値は nonebridgehost、または 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) のインクリメント)

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

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

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

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

    • 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 として指定することもでき、文字列またはリストである必要があります。リストである場合、最初の項目は NONECMDCMD-SHELL のいずれかにする必要があります。文字列の場合は、CMD-SHELL を指定した場合と同等で、その後にその文字列が続きます。intervaltimeout、および start_period フィールドは、文字列形式で期間として指定されます。たとえば、2.5s10s1m30s2h23m5h34m56s です。

      注記

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

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

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

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

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

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

構文

ecs-cli compose [--verbose] [--file compose-file] [--project-name project-name] [--task-role-arn role_value] [--cluster cluster_name] [--region region] [--ecs-params ecs-params.yml] [subcommand] [arguments] [--help]

オプション

名前 説明

--verbose, --debug

コマンド出力の詳細を増やし、診断に役立てます。

必須: いいえ

--file, -f compose-file

使用する Docker 構成ファイルを指定します。現時点で、Amazon ECS CLI の最新バージョンでは、Docker 構成ファイル構文のバージョン 1 と 2 がサポートされています。 ecs-cli compose の実行時に COMPOSE_FILE 環境変数が設定されている場合、Docker 構成ファイルは、その環境変数の値に設定されます。

型: 文字列

デフォルト: ./docker-compose.yml

必須: いいえ

--project-name, -p project-name

使用するプロジェクト名を指定します。ecs-cli compose の実行時に COMPOSE_PROJECT_NAME 環境変数を設定する場合、プロジェクト名はその環境変数の値に設定されます。

型: 文字列

デフォルト: 現在のディレクトリ名。

必須: いいえ

--task-role-arn role_value

このタスクでコンテナが引き受けることのできる IAM ロールの略称または Amazon リソースネーム (ARN) 全体を指定します。このタスクのすべてのコンテナには、このロールに指定されているアクセス許可が付与されます。

型: 文字列

必須: いいえ

--ecs-params

Docker 構成ファイルでネイティブではない ECS パラメータが指定されます。詳細については、「Amazon ECS パラメータの使用」を参照してください。

デフォルト: ./ecs-params.yml

必須: いいえ

--cluster, -c cluster_name

使用する ECS クラスター名を指定します。デフォルトは、configure コマンドを使用して設定したクラスターになります。

型: 文字列

必須: いいえ

--region, -r region

使用する AWS リージョンを指定します。デフォルトは、configure コマンドを使用して設定したクラスターになります。

型: 文字列

必須: いいえ

--ecs-profile ecs_profile

使用する ECS プロファイル設定の名前が指定されます。デフォルトは、configure profile コマンドを使用して設定したプロファイルになります。

型: 文字列

必須: いいえ

--aws-profile aws_profile

使用する AWS プロファイルが指定されます。~/.aws/credentials という名前の既存のプロファイルから、AWS 認証情報を使用することができます。

型: 文字列

必須: いいえ

--cluster-config cluster_config_name

使用する ECS クラスター設定の名前が指定されます。デフォルトでは、デフォルトとして設定するクラスター設定が指定されます。

型: 文字列

必須: いいえ

--help, -h

指定したコマンドのヘルプテキストを表示します。

タイプ: ブール値

必須: いいえ

使用できるサブコマンド

ecs-cli compose コマンドは以下のサブコマンドをサポートしています。これらの各サブコマンドには、関連付けられた独自のフラグがあり、--help フラグを使用して表示できます。

create

構成ファイルから Amazon ECS タスク定義を作成します。詳細については、「ecs-cli compose create」を参照してください。

pslist

構成プロジェクトによって開始されたクラスター内のすべてのコンテナを一覧表示します。

run [containerName] ["command ..."] ...

指定した 1 回限りのコマンドでコマンドを上書きして、すべてのコンテナを開始します。

scale n

実行中のタスクの数を、指定した数にスケーリングします。

start

構成ファイルから作成されたタスク定義から 1 つのタスクを開始します。詳細については、「ecs-cli compose start」を参照してください。

stopdown

構成プロジェクトによって作成されたすべての実行中のタスクを停止します。

up

構成ファイルから ECS タスク定義を作成し (まだない場合)、そのタスクの 1 つのインスタンスをクラスターで実行します (createstart の組み合わせ)。詳細については、「ecs-cli compose up」を参照してください。

service [subcommand]

構成ファイルから ECS サービスを作成します。詳細については、「ecs-cli compose service」を参照してください。

help

指定したコマンドのヘルプテキストを表示します。