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

ecs-cli compose service

説明

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

注記

サービスを作成する代わりに Amazon ECS CLI でタスクを実行する場合は、「ecs-cli compose」を参照してください。

ecs-cli compose service コマンドは、Docker 構成ファイルと使用されて、サービスを作成し、タスクを管理します。現時点で、Amazon ECS CLI では、Docker Compose ファイル構文のバージョン 1、2、3 がサポートされています。デフォルトでは、コマンドは現在のディレクトリ内で docker-compose.yml という名前の構成ファイルを探します。ただし、--file オプションを使用して、構成ファイルに別のファイル名またはパスを指定できます。これは、Amazon ECS CLI を使用して複数の構成ファイルからタスクとサービスを一度に管理するために特に便利です。

ecs-cli compose service コマンドは、作成するタスク定義とサービスでプロジェクト名を使用します。CLI によって構成ファイルからタスク定義とサービスが作成されるとき、タスク定義とサービスには 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 のインストール」を参照してください。

構文

[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 service コマンドでは、以下のサブコマンドと引数を使用できます。

create [--deployment-max-percent n] [--deployment-min-healthy-percent n] [--load-balancer-name value|--target-group-arn value] [--container-name value] [--container-port value] [--role value] [--launch-type launch_type] [--health-check-grace-period integer] [--create-log-groups]

構成ファイルから ECS サービスを作成します。サービスは必要数を 0 として作成されるため、このコマンドによってコンテナは開始されません。

--deployment-max-percent オプションは、デプロイ中にサービスで実行できる、実行中のタスクの数の上限を (サービスの desiredCount の割合として) 指定します (デフォルト値は 200 です)。--deployment-min-healthy-percent オプションは、デプロイ中にサービスで実行されていて、正常である必要がある実行中のタスクの数の下限を (サービスの desiredCount の割合として) 指定します (デフォルト値は 100 です)。詳細については、「maximumPercent」および「minimumHealthyPercent」を参照してください。

オプションで、ロードバランサーの背後でサービスを実行できます。ロードバランサーは、サービスに関連付けられたタスク間でトラフィックを分散させます。詳細については、「サービスロードバランシング」を参照してください。サービスを作成した後、サービス定義で指定されているロードバランサー名、ターゲットグループ ARN、コンテナ名、コンテナポートはイミュータブルです。

注記

それらを使用するようサービスを設定する前に、ロードバランサーリソースを作成する必要があります。ロードバランサーリソースはコンテナインスタンスと同じ VPC にあり、同じサブネットを使用するよう設定する必要があります。また、ロードバランサーからの着信トラフィックを許可するコンテナインスタンスのセキュリティグループに、セキュリティグループルールを追加する必要があります。詳細については、「ロードバランサーの作成」を参照してください。

  • 既存の Elastic Load Balancing Classic Load Balancer を使用するようサービスを設定するには、ロードバランサー名、(コンテナの定義に表示されるとおりの) コンテナ名、およびロードバランサーからアクセスするコンテナポートを指定する必要があります。このサービスのタスクがコンテナインスタンスに配置されると、コンテナインスタンスはここで指定したロードバランサーに登録されます。

  • 既存の Elastic Load Balancing Application Load Balancer を使用するようサービスを設定するには、ロードバランサーのターゲットグループ ARN、(コンテナの定義に表示されるとおりの) コンテナ名、およびロードバランサーからアクセスするコンテナポートを指定する必要があります。このサービスのタスクがコンテナインスタンスに配置されると、コンテナインスタンスとポートの組み合わせは、ここで指定したターゲットグループのターゲットとして登録されます。

--health-check-grace-period オプションは、Amazon ECS サービススケジューラが、タスクが最初に開始された後で異常な Elastic Load Balancing ターゲットのヘルスチェックを無視する期間 (秒単位) を指定します。これが有効であるのは、ロードバランサーを使用するようにサービスが設定されている場合のみです。タスクで、ELB ヘルスチェックを開始して応答するまでに時間がかかる場合は、ヘルスチェックの猶予期間として最大 1,800 秒まで指定できます。この間は、ECS サービススケジューラは Elastic Load Balancing ヘルスチェックのステータスを無視します。この猶予期間により、Amazon ECS サービススケジューラがタスクを異常とマークして時間より前に停止することがなくなります。

start [--timeout value] [--create-log-groups] [--force-deployment]

作成された ECS サービスで各コンテナの 1 つのコピーを開始します。このコマンドはサービスの必要数を 1 に更新します。

--timeout オプションでは、実行中のタスクの数の変更を待機するタイムアウト値を分単位で指定します (小数点以下の指定も可能)。実行中のタスク数が指定した期間変更されていない場合、CLI はタイムアウトし、エラーを返します。タイムアウトを 0 に設定すると、コマンドは、結果に関係なく返ります。デフォルトのタイムアウト値は 5 分です。

--create-log-groups オプションは、構成ファイルで指定される CloudWatch ロググループを作成します。

--force-deployment オプションが含まれる場合は、サービスの新しいデプロイが強制されます。

up [--deployment-max-percent n] [--deployment-min-healthy-percent n] [--load-balancer-name value|--target-group-arn value] [--container-name value] [--container-port value] [--role value] [--timeout value] [--launch-type launch_type] [--health-check-grace-period integer] [--create-log-groups] [--force-deployment]

構成ファイルからサービスを作成し (存在しない場合)、クラスターでそのタスクの 1 つのインスタンスを実行します (作成開始の組み合わせ)。このコマンドはサービスの必要数を 1 に更新します。

--deployment-max-percent オプションは、デプロイ中にサービスで実行できる、実行中のタスクの数の上限を (サービスの desiredCount の割合として) 指定します (デフォルト値は 200 です)。--deployment-min-healthy-percent オプションは、デプロイ中にサービスで実行されていて、正常である必要がある実行中のタスクの数の下限を (サービスの desiredCount の割合として) 指定します (デフォルト値は 100 です)。詳細については、「maximumPercent」および「minimumHealthyPercent」を参照してください。

--timeout オプションでは、実行中のタスクの数の変更を待機するタイムアウト値を分単位で指定します (小数点以下の指定も可能)。実行中のタスク数が指定した期間変更されていない場合、CLI はタイムアウトし、エラーを返します。タイムアウトを 0 に設定すると、コマンドは、結果に関係なく返ります。デフォルトのタイムアウト値は 5 分です。

--health-check-grace-period オプションは、Amazon ECS サービススケジューラが、タスクが最初に開始された後で異常な Elastic Load Balancing ターゲットのヘルスチェックを無視する期間 (秒単位) を指定します。これが有効であるのは、ロードバランサーを使用するようにサービスが設定されている場合のみです。タスクで、ELB ヘルスチェックを開始して応答するまでに時間がかかる場合は、ヘルスチェックの猶予期間として最大 1,800 秒まで指定できます。この間は、ECS サービススケジューラは Elastic Load Balancing ヘルスチェックのステータスを無視します。この猶予期間により、Amazon ECS サービススケジューラがタスクを異常とマークして時間より前に停止することがなくなります。

--create-log-groups オプションは、構成ファイルで指定される CloudWatch ロググループを作成します。

--force-deployment オプションが含まれる場合は、サービスの新しいデプロイが強制されます。

オプションで、ロードバランサーの背後でサービスを実行できます。ロードバランサーは、サービスに関連付けられたタスク間でトラフィックを分散させます。詳細については、「サービスロードバランシング」を参照してください。サービスを作成した後、サービス定義で指定されているロードバランサー名、ターゲットグループ ARN、コンテナ名、コンテナポートはイミュータブルです。

注記

それらを使用するようサービスを設定する前に、ロードバランサーリソースを作成する必要があります。ロードバランサーリソースはコンテナインスタンスと同じ VPC にあり、同じサブネットを使用するよう設定する必要があります。また、ロードバランサーからの着信トラフィックを許可するコンテナインスタンスのセキュリティグループに、セキュリティグループルールを追加する必要があります。詳細については、「ロードバランサーの作成」を参照してください。

  • 既存の Elastic Load Balancing Classic Load Balancer を使用するようサービスを設定するには、ロードバランサー名、(コンテナの定義に表示されるとおりの) コンテナ名、およびロードバランサーからアクセスするコンテナポートを指定する必要があります。このサービスのタスクがコンテナインスタンスに配置されると、コンテナインスタンスはここで指定したロードバランサーに登録されます。

  • 既存の Elastic Load Balancing Application Load Balancer を使用するようサービスを設定するには、ロードバランサーのターゲットグループ ARN、(コンテナの定義に表示されるとおりの) コンテナ名、およびロードバランサーからアクセスするコンテナポートを指定する必要があります。このサービスのタスクがコンテナインスタンスに配置されると、コンテナインスタンスとポートの組み合わせは、ここで指定したターゲットグループのターゲットとして登録されます。

pslist

構成プロジェクトで作成されたサービスに属する、クラスター内のすべてのコンテナを一覧表示します。

scale [--deployment-max-percent n] [--deployment-min-healthy-percent n] [--timeout value] n

サービスの必要数を、指定した数にスケーリングします。

--deployment-max-percent オプションは、デプロイ中にサービスで実行できる、実行中のタスクの数の上限を (サービスの desiredCount の割合として) 指定します (デフォルト値は 200 です)。--deployment-min-healthy-percent オプションは、デプロイ中にサービスで実行されていて、正常である必要がある実行中のタスクの数の下限を (サービスの desiredCount の割合として) 指定します (デフォルト値は 100 です)。詳細については、「maximumPercent」および「minimumHealthyPercent」を参照してください。

--timeout オプションでは、実行中のタスクの数の変更を待機するタイムアウト値を分単位で指定します (小数点以下の指定も可能)。実行中のタスク数が指定した期間変更されていない場合、CLI はタイムアウトし、エラーを返します。タイムアウトを 0 に設定すると、コマンドは、結果に関係なく返ります。デフォルトのタイムアウト値は 5 分です。

stop [--timeout value]

構成プロジェクトで作成されたサービスに属する、実行中のタスクを停止します。このコマンドはサービスの必要数を 0 に更新します。

--timeout オプションでは、実行中のタスクの数の変更を待機するタイムアウト値を分単位で指定します (小数点以下の指定も可能)。実行中のタスク数が指定した期間変更されていない場合、CLI はタイムアウトし、エラーを返します。タイムアウトを 0 に設定すると、コマンドは、結果に関係なく返ります。デフォルトのタイムアウト値は 5 分です。

rmdeletedown [--timeout value]

サービスの必要数を 0 に更新してから、サービスを削除します。

--timeout オプションでは、実行中のタスクの数の変更を待機するタイムアウト値を分単位で指定します (小数点以下の指定も可能)。実行中のタスク数が指定した期間変更されていない場合、CLI はタイムアウトし、エラーを返します。タイムアウトを 0 に設定すると、コマンドは、結果に関係なく返ります。デフォルトのタイムアウト値は 5 分です。

help

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

例 1

この例では、hello-world 構成ファイルからプロジェクト名 hello-world.yml で ECS サービスを作成します。

ecs-cli compose --project-name hello-world --file hello-world.yml service up

出力:

INFO[0000] Using ECS task definition TaskDefinition="ecscompose-hello-world:7" INFO[0000] Created an ECS service service=ecscompose-service-hello-world taskDefinition="ecscompose-hello-world:7" INFO[0000] Updated ECS service successfully desiredCount=1 serviceName=ecscompose-service-hello-world INFO[0015] (service ecscompose-service-hello-world) has started 1 tasks: (task 682dc22f-8bfa-4c28-b6f8-3a916bd8f86a). timestamp=2017-08-18 21:16:00 +0000 UTC INFO[0060] Service status desiredCount=1 runningCount=1 serviceName=ecscompose-service-hello-world INFO[0060] ECS Service has reached a stable state desiredCount=1 runningCount=1 serviceName=ecscompose-service-hello-world

例 2

この例では、hello-world プロジェクトによって作成されたサービスを必要数 2 にスケーリングしています。

ecs-cli compose --project-name hello-world --file hello-world.yml service scale 2

出力:

INFO[0000] Updated ECS service successfully desiredCount=2 serviceName=ecscompose-service-hello-world INFO[0000] Service status desiredCount=2 runningCount=1 serviceName=ecscompose-service-hello-world INFO[0030] (service ecscompose-service-hello-world) has started 1 tasks: (task 80602da8-442c-48ea-a8a9-80328c302b89). timestamp=2017-08-18 21:17:44 +0000 UTC INFO[0075] Service status desiredCount=2 runningCount=2 serviceName=ecscompose-service-hello-world INFO[0075] ECS Service has reached a stable state desiredCount=2 runningCount=2 serviceName=ecscompose-service-hello-world

例 3

この例では、hello-world プロジェクトによって作成されたサービスを必要数 にスケーリングしてから、サービスを削除しています。0

ecs-cli compose --project-name hello-world --file hello-world.yml service rm

出力:

INFO[0000] Updated ECS service successfully desiredCount=0 serviceName=ecscompose-service-hello-world INFO[0000] Service status desiredCount=0 runningCount=2 serviceName=ecscompose-service-hello-world INFO[0015] Service status desiredCount=0 runningCount=0 serviceName=ecscompose-service-hello-world INFO[0015] (service ecscompose-service-hello-world) has stopped 2 running tasks: (task 682dc22f-8bfa-4c28-b6f8-3a916bd8f86a) (task 80602da8-442c-48ea-a8a9-80328c302b89). timestamp=2017-08-18 21:25:28 +0000 UTC INFO[0015] ECS Service has reached a stable state desiredCount=0 runningCount=0 serviceName=ecscompose-service-hello-world INFO[0015] Deleted ECS service service=ecscompose-service-hello-world INFO[0015] ECS Service has reached a stable state desiredCount=0 runningCount=0 serviceName=ecscompose-service-hello-world

例 4

この例では nginx-compose.yml 構成ファイルからサービスを作成し、既存の Application Load Balancer を使用してそれを設定します。

ecs-cli compose -f nginx-compose.yml service up --target-group-arn arn:aws:elasticloadbalancing:us-east-1:aws_account_id:targetgroup/ecs-cli-alb/9856106fcc5d4be8 --container-name nginx --container-port 80 --role ecsServiceRole

例 5

この例では、nginx-compose.yml 構成ファイルからサービスを作成し、ヘルスチェックの猶予期間を 25 秒に設定した既存の Application Load Balancer を使用するように設定します。

ecs-cli compose -f nginx-compose.yml service up --target-group-arn arn:aws:elasticloadbalancing:us-east-1:aws_account_id:targetgroup/ecs-cli-alb/9856106fcc5d4be8 --container-name nginx --container-port 80 --role ecsServiceRole --health-check-grace-period 25