メニュー
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 がサポートされています。デフォルトでは、このコマンドは現在のディレクトリで 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 パラメータの使用」を参照してください。

  • dns

  • dns_search

  • entrypoint

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

    重要

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

  • env_file

    重要

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

  • extra_hosts

  • 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: integer mem_reservation: integer 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_modenetworkMode - ECS タスク定義の に対応します。サポートされている値は 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 フィールドを指定しない場合、その値はデフォルトで true になります。Docker Compose バージョン 3 を使用している場合、cpu_sharesmem_limit、および mem_reservation フィールドはオプションであり、compose ファイルではなく ECS params ファイルで指定する必要があります。Docker Compose バージョン 2 では、cpu_sharesmem_limit、および mem_reservation フィールドを compose または ECS params ファイルで指定できます。それらのフィールドを ECS params ファイルで指定する場合、それらの値は compose ファイル内の値を上書きします。

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

  • network_configuration - ecs_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

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