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

サービス定義パラメータ

サービス定義は、サービスで使用するタスク定義、実行するタスクのインスタンス化数、タスクに関連付けるロードバランサー (ある場合)、およびその他のサービスパラメータ を定義します。

{ "cluster": "", "serviceName": "", "taskDefinition": "", "loadBalancers": [ { "targetGroupArn": "", "loadBalancerName": "", "containerName": "", "containerPort": 0 } ], "serviceRegistries": [ { "registryArn": "", "port": 0, "containerName": "", "containerPort": 0 } ], "desiredCount": 0, "clientToken": "", "launchType": "EC2", "platformVersion": "", "role": "", "deploymentConfiguration": { "maximumPercent": 0, "minimumHealthyPercent": 0 }, "placementConstraints": [ { "type": "distinctInstance", "expression": "" } ], "placementStrategy": [ { "type": "binpack", "field": "" } ], "networkConfiguration": { "awsvpcConfiguration": { "subnets": [ "" ], "securityGroups": [ "" ], "assignPublicIp": "ENABLED" } }, "healthCheckGracePeriodSeconds": 0, "schedulingStrategy": "REPLICA", "deploymentController": { "type": "ECS" }, "tags": [ { "key": "", "value": "" } ], "enableECSManagedTags": true, "propagateTags": "TASK_DEFINITION" }

注記

上記のサービス定義テンプレートは、以下の AWS CLI コマンドで作成できます。

aws ecs create-service --generate-cli-skeleton

サービス定義では、以下のパラメータを指定できます。

cluster

サービスを実行するクラスターの短い名前または完全な Amazon リソースネーム (ARN)。クラスターを指定しない場合は、default クラスターが使用されます。

serviceName

サービスの名前。最大 255 文字の英字 (大文字と小文字)、数字、ハイフン、アンダースコアを使用できます。 サービス名は同じクラスター内で一意になるようにしてください。ただし、リージョン内のクラスター間や複数のリージョンにまたがるクラスター間では、同様の名前のサービスがあっても構いません。

必須: はい

taskDefinition

familyrevision (family:revision)、またはサービスで実行されるタスク定義の完全な Amazon リソースネーム (ARN)。revision を指定しない場合、最新の ACTIVE リビジョンが使用されます。

loadBalancers

サービスで使用するロードバランサーを表すロードバランサーオブジェクト。Application Load Balancer または Network Load Balancer を使用するサービスの場合、サービスにアタッチできる 5 つのターゲットグループの制限があります。

.サービスを作成した後、サービス定義で指定されているロードバランサー名、ターゲットグループ ARN、コンテナ名、コンテナポートはイミュータブルです。

Classic Load Balancer では、このオブジェクトには、ロードバランサー名、コンテナ名 (コンテナの定義に表示)、ロードバランサーからアクセスされるコンテナポートが含まれる必要があります。このサービスのタスクがコンテナインスタンスに配置されると、コンテナインスタンスはここで指定したロードバランサーに登録されます。

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

targetGroupArn

サービスに関連付ける Elastic Load Balancing ターゲットグループの完全な Amazon リソースネーム (ARN)。

loadBalancerName

ロードバランサーの名前。

containerName

ロードバランサーに関連付けるコンテナの名前 (コンテナ定義に表示)。

containerPort

ロードバランサーに関連付けるコンテナのポート。このポートは、サービスのタスク定義の containerPort に対応する必要があります。コンテナインスタンスでは、ポートマッピングの hostPort で入力トラフィックが許可される必要があります。

serviceRegistries

サービスのサービス検出設定の詳細。詳細については、「サービス検出」を参照してください。

registryArn

サービスレジストリの Amazon リソースネーム (ARN)。現在サポートされているサービスレジストリは Amazon Route 53 Auto Naming です。詳細については、「サービス」を参照してください。

port

サービス検出サービスが SRV レコードを指定した場合に使用されるポート値。このフィールドは、awsvpc ネットワークモードと SRV レコードの両方が使用されている場合に必要です。

containerName

タスク定義にすでに指定されているコンテナ名の値。サービス検出サービスに使用されます。サービスタスクが指定するタスク定義に bridge または host ネットワークモードが使用されている場合は、タスク定義からの containerNamecontainerPort の組み合わせを指定する必要があります。サービスタスクが指定するタスク定義に awsvpcネットワークモードが使用され、SRV DNS タイプのレコードが使用されている場合は、containerNamecontainerPort の組み合わせを指定するか、port 値を指定する必要があります (両方は指定しないでください)。

containerPort

タスク定義にすでに指定されているポートの値。サービス検出サービスに使用されます。サービスタスクが指定するタスク定義に bridge または host ネットワークモードが使用されている場合は、タスク定義からの containerNamecontainerPort の組み合わせを指定する必要があります。サービスタスクが指定するタスク定義に awsvpc ネットワークモードが使用され、SRV DNS タイプのレコードが使用されている場合は、containerNamecontainerPort の組み合わせを指定するか、port 値を指定する必要があります (両方は指定しないでください)。

desiredCount

指定したタスク定義のインスタンスをクラスターに配置して実行状態に保つ数。

clientToken

リクエストのべき等のために割り当てる一意の識別子 (大文字と小文字を区別)。最大 32 文字の ASCII 文字を使用できます。

launchType

サービスを実行する起動タイプ。有効な値は、「FARGATE」と「EC2」です。指定しない場合は、デフォルトで EC2 が使用されます。詳細については、「Amazon ECS 起動タイプ」を参照してください。

platformVersion

サービス内のタスクが実行されているプラットフォームのバージョン。プラットフォームのバージョンは、Fargate 起動タイプを使用するタスクにのみ指定されます。指定されない場合、デフォルトで最新バージョン (LATEST) が使用されます。

AWS Fargate プラットフォームのバージョンを使って、Fargate タスクインフラストラクチャの特定のランタイム環境を参照できます。プラットフォームのバージョンに LATEST を指定してタスクを実行またはサービスを作成すると、プラットフォームの最新バージョンをタスクで利用できるようになります。サービスをスケールアップする場合は、これらのタスクには、サービスの最新のデプロイで指定されたプラットフォームのバージョンが提供されます。詳細については、「AWS Fargate プラットフォームのバージョン」を参照してください。

注記

プラットフォームのバージョンは、EC2 起動タイプを使用するタスクには指定されません。

role

Amazon ECS によるロードバランサーの呼び出しを許可する IAM ロールの短縮名または完全な ARN。このパラメータは、サービスでロードバランサーを使用していて、タスク定義が awsvpc ネットワークモードを使用していない場合にのみ許可されます。role パラメータを指定する場合、loadBalancers パラメータでロードバランサーのオブジェクトも指定する必要があります。

指定したロールに / 以外のパスがある場合は、完全なロール ARN を指定するか (推奨)、ロール名の前にパスを付ける必要があります。たとえば、ロールの名前が bar で、パスが /foo/ の場合、ロール名として /foo/bar を指定します。詳細については、IAM ユーザーガイド の「わかりやすい名前とパス」を参照してください。

重要

アカウントが既に Amazon ECS サービスリンクロールを作成している場合は、ここでロールを指定しない限り、そのロールがサービスにデフォルトで使用されます。タスク定義で awsvpc ネットワークモードを使用している場合はサービスにリンクされたロールが必要です。詳細については、「Amazon ECS のサービスにリンクされたロールの使用」を参照してください。

deploymentConfiguration

デプロイ時に実行されるタスクの数と、タスクの停止および開始の順序を制御するオプションのデプロイパラメータ。

maximumPercent

サービスでローリング更新 (ECS) のデプロイタイプが使用されている場合、maximumPercent パラメータは、デプロイ時に RUNNING または PENDING 状態で使用できるサービスのタスクの上限数を desiredCount のパーセント値 (最も近い整数に切り下げ) で表します。このパラメータを使用すると、デプロイのバッチサイズを定義できます。たとえば、サービスで REPLICA サービススケジューラを使用して、desiredCount が 4 タスク、maximumPercent の値が 200% とすると、スケジューラは 4 つの古いタスクを停止する前に、4 つの新しいタスクを開始できます (そのために必要なクラスターリソースを使用できることが前提)。REPLICA サービススケジューラを使用するサービスのデフォルトの maximumPercent 値は 200% です。

サービスで DAEMON サービススケジューラタイプを使用している場合、maximumPercent はデフォルト値の 100% のままにする必要があります。

デプロイ時のタスクの最大数は、desiredCountmaximumPercent/100 を乗算したもので、最も近い整数値に切り下げられます。

サービスが Blue/Green (CODE_DEPLOY) または EXTERNAL デプロイのタイプと EC2 起動タイプを使用するタスクのいずれかを使用している場合、maximum percent 値はデフォルト値に設定され、コンテナインスタンスが DRAINING 状態のとき RUNNING 状態のままのタスクの上限数を定義するために使用されます。サービス内のタスクが Fargate 起動タイプを使用する場合、最大ヘルス率の値はサービスを記述するときに返されますが、使用されません。

minimumHealthyPercent

サービスでローリング更新 (ECS) のデプロイタイプが使用されている場合、minimumHealthyPercent は、デプロイ時に RUNNING 状態に留まる必要があるサービスのタスクの下限数を desiredCount のパーセント値 (最も近い整数に切り上げ) で表します。このパラメータにより、追加のクラスターキャパシティーを使用せずにデプロイできます。たとえば、サービスで desiredCount が 4 タスク、minimumHealthyPercent が 50% とすると、サービススケジューラは 2 つの新しいタスクを開始する前に、2 つの既存のタスクを停止してクラスターの容量を解放できます。

ロードバランサーを使用しないサービスのタスクは、RUNNING 状態にある場合、正常と見なされます。

ロードバランサーを使用するサービスのタスクは、RUNNING 状態にあり、定義されたすべてのヘルスチェックを通過し、ロードバランサーまたはターゲットグループで正常と報告された場合に、正常であると見なされます。

レプリカサービスの minimumHealthyPercent のデフォルト値は、AWS マネジメントコンソール では 50%、AWS CLI、AWS SDK、API では 100% です。DAEMON サービススケジュールを使用しているデフォルトの minimumHealthyPercent 値は、AWS CLI、AWS SDK、API では 0%、AWS マネジメントコンソール では 50% です。

デプロイ時の正常なタスクの最小数は、desiredCountminimumHealthyPercent/100 を乗算したもので、最も近い整数値に切り上げられます。

サービスが Blue/Green (CODE_DEPLOY) または EXTERNAL デプロイのタイプと EC2 起動タイプを使用するタスクのいずれかを使用している場合、最小ヘルス率のデフォルト値はデフォルト値に設定され、コンテナインスタンスが DRAINING 状態のとき RUNNING 状態のままのタスクの下限数を定義するために使用されます。サービス内のタスクが Fargate 起動タイプを使用する場合、最小ヘルス率の値はサービスを記述するときに返されますが、使用されません。

placementConstraints

サービスのタスクに使用する、配置制約オブジェクトの配列。タスクごとに最大 10 個の制約を指定できます (この制限数には、タスク定義内の制約と、実行時に指定される制約が含まれます)。Fargate 起動タイプを使用している場合、タスク配置の制約事項はサポートされません。

type

制約事項のタイプ。特定のグループの各タスクが確実に別のコンテナインスタンスで実行されるようにするには、distinctInstance を使用します。選択対象を有効な候補グループに制約するには、memberOf を使用します。値 distinctInstance はタスク定義ではサポートされていません。

expression

制約に適用されるクラスタークエリ言語式。制約タイプが distinctInstance である場合は、式を指定できないことに注意してください。詳細については、「クラスタークエリ言語」を参照してください。

placementStrategy

サービスのタスクで使用する配置戦略オブジェクト。サービスごとに最大 4 つの戦略ルールを指定できます。

type

配置戦略のタイプ。random 配置戦略は、タスクを利用可能な候補にランダムに配置します。spread 配置戦略は、field パラメータに基づいて、利用可能候補間で均等にタスクを分散して配置します。binpack 戦略は、field パラメータで指定したリソースの利用可能量が最も少ない利用可能候補にタスクを配置します。たとえば、メモリの binpack 戦略を使用する場合、タスクは残りのメモリの量が最も少ない (ただし、タスクを実行するのに十分な) インスタンスに配置されます。

field

配置戦略を適用するフィールド。spread 配置戦略では、有効な値は instanceId (または同じ効果を持つ host)、または attribute:ecs.availability-zone などのコンテナインスタンスに適用される任意のプラットフォームまたはカスタム属性です。binpack 配置戦略では、有効な値は、cpu および memory です。random 配置戦略では、このフィールドは使用されません。

networkConfiguration

サービスのネットワーク構成。awsvpc ネットワークモードを使用して独自の Elastic Network Interface を受け取るタスク定義の場合に必要です。その他のネットワークモードではサポートされていません。Fargate 起動タイプを使用している場合、awsvpc ネットワークモードが必要です。詳細については、「タスクネットワーキングと awsvpc ネットワークモード」を参照してください。

awsvpcConfiguration

タスクまたはサービスのサブネットとセキュリティグループを表すオブジェクト。

subnets

タスクまたはサービスに関連付けられたサブネット。

securityGroups

タスクまたはサービスに関連付けられたセキュリティグループ。セキュリティグループを指定しないと、VPC のデフォルトのセキュリティグループが関連付けられます。

assignPublicIP

タスクの Elastic Network Interface がパブリック IP アドレスを受信するかどうか。

healthCheckGracePeriodSeconds

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

schedulingStrategy

使用するスケジュール戦略。詳細については、「サービススケジューラの概念」を参照してください。

利用できる 2 つのサービススケジューラ戦略があります。

  • REPLICA — レプリカスケジュール戦略では、クラスター全体で必要数のタスクを配置して維持します。デフォルトでは、サービススケジューラによってタスクはアベイラビリティーゾーン間で分散されます。タスク配置の戦略と制約を使用すると、タスク配置の決定をカスタマイズできます。詳細については、「レプリカ」を参照してください。

  • DAEMON — デーモンのスケジュール戦略では、指定したすべてのタスク配置制約を満たすクラスター内のアクティブなコンテナインスタンスごとに、1 つのタスクのみをデプロイします。この戦略を使用する場合、タスクの必要数や配置戦略、サービスの Auto Scaling ポリシーを指定する必要はありません。詳細については、「デーモン」を参照してください。

    注記

    Fargate タスクは DAEMON スケジューリング戦略をサポートしていません。

deploymentController

サービスで使用するデプロイコントローラータイプ。詳細については、「Amazon ECS デプロイタイプ」を参照してください。

type

使用するデプロイコントローラータイプ。次の 3 つのデプロイコントローラータイプを使用できます。

ECS

ローリング更新 (ECS) デプロイタイプでは、コンテナの現在実行されているバージョンを最新バージョンに置き換えられます。ローリング更新中に Amazon ECS がサービスに追加または削除するコンテナの数は、deploymentConfiguration で指定されるように、サービスのデプロイ中に許可される正常なタスクの最小数と最大数を調整することで制御されます。

CODE_DEPLOY

Blue/Green (CODE_DEPLOY) デプロイタイプは、CodeDeploy による Blue/Green デプロイモデルを使用することにより、本稼働トラフィックを送信する前に、サービスの新しいデプロイを確認できます。

EXTERNAL

外部デプロイタイプでは、Amazon ECS サービスのデプロイプロセスを完全に制御するためのサードパーティーのデプロイコントローラーを使用できます。

tags

サービスに適用し、サービスの分類と整理に役立つメタデータ。タグはそれぞれ、1 つのキーとオプションの 1 つの値で構成されており、どちらもお客様側が定義します。サービスが削除されると、タグも削除されます。タグキーの最大文字数は 128 文字、タグ値の最大長は 256 文字です。詳細については、「Amazon ECS リソースのタグ付け」を参照してください。

key

タグを構成するキーと値のペアの一部。キーは、より具体的なタグ値のカテゴリのように動作する、一般的なラベルです。

value

タグを構成するキーと値のペアのオプションの一部。値はタグカテゴリ (キー) の記述子として機能します。

enableECSManagedTags

サービスでタスクの Amazon ECS マネージドタグを有効にするかどうかを指定します。詳細については、「請求用のリソースにタグを付ける」を参照してください。

propagateTags

タグをタスク定義またはサービスからサービスのタスクへコピーするかどうかを指定します。値を指定しない場合、タグはコピーされません。タグは、サービス作成中のサービス内のタスクにのみコピーすることができます。タグをサービス作成後のタスクに追加するには、TagResource API アクションを使用します。