サービス定義パラメーター - Amazon Elastic Container Service

サービス定義パラメーター

サービス定義は、Amazon ECS サービスの実行方法を定義します。サービス定義では、次のパラメータを指定できます。

起動タイプ

launchType

型: 文字列

有効な値: EC2 | FARGATE

必須: いいえ

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

launchType を指定した場合、capacityProviderStrategy パラメータを省略する必要があります。

キャパシティープロバイダー戦略

capacityProviderStrategy

タイプ: オブジェクトの配列

必須: いいえ

サービスに使用するキャパシティープロバイダー戦略。

キャパシティープロバイダー戦略は、1 つ以上のキャパシティープロバイダーと、それらに割り当てる baseweight で構成されます。キャパシティープロバイダーは、キャパシティープロバイダー戦略で使用するクラスターに関連付ける必要があります。PutClusterCapacityProviders API は、キャパシティープロバイダーをクラスターに関連付けるために使用されます。ACTIVE または UPDATING ステータスのキャパシティープロバイダーのみを使用できます。

capacityProviderStrategy を指定した場合、launchType パラメータを省略する必要があります。capacityProviderStrategy または launchType を指定しない場合は、クラスターの defaultCapacityProviderStrategy が使用されます。

Auto Scaling グループを使用するキャパシティープロバイダーを指定する場合は、キャパシティープロバイダーがすでに作成されている必要があります。新しいキャパシティープロバイダーは、CreateCapacityProvider API オペレーションで作成できます。

AWS Fargate キャパシティープロバイダーを使用するには、キャパシティープロバイダー FARGATE または FARGATE_SPOT を指定します。AWS Fargate キャパシティープロバイダーはすべてのアカウントで使用でき、クラスターに関連付けるだけで使用できるようになります。

PutClusterCapacityProviders API オペレーションは、クラスターの作成後にクラスターで使用可能なキャパシティープロバイダーのリストを更新するために使用されます。

capacityProvider

型: 文字列

必須: はい

キャパシティープロバイダーの短縮名または完全な ARN。

weight

タイプ: 整数

有効な範囲: 0~1,000 の整数。

必須: いいえ

ウエイト値は、指定したキャパシティープロバイダーを使用する起動済みタスクの総数に対する相対的な割合を示します。

たとえば、2 つのキャパシティープロバイダーを含む戦略があり、両方のウェイトが 1 である場合、ベースが満たされると、タスクは 2 つのキャパシティープロバイダー間で均等に分割されます。同じロジックを使用して、キャパシティープロバイダーcapacityProviderA に 1 のウエイトを指定し、capacityProviderB に 4 のウエイトを指定すると、capacityProviderA を使用して実行されるタスクごとに、4 つのタスクが capacityProviderB を使用します。

base

タイプ: 整数

有効な範囲: 0~100,000 の整数。

必須: いいえ

ベース値は、指定されたキャパシティープロバイダーで実行するタスクの最小限の数を指定します。キャパシティープロバイダー戦略では、ベースを定義できるキャパシティープロバイダーは 1 つだけです。

タスク定義

taskDefinition

型: 文字列

必須: いいえ

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

ローリングアップデート (ECS) デプロイメントコントローラーを使用する場合は、タスク定義を指定する必要があります。

プラットフォームのバージョン

platformVersion

型: 文字列

必須: いいえ

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

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

注記

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

クラスター

cluster

型: 文字列

必須: いいえ

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

サービス名

serviceName

型: 文字列

必須: はい

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

スケジュール戦略

schedulingStrategy

型: 文字列

有効な値: REPLICA | DAEMON

必須: いいえ

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

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

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

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

    注記

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

必要数

desiredCount

タイプ: 整数

必須: いいえ

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

このパラメータは、REPLICA スケジュール戦略を使用する場合に必要です。サービスが DAEMON スケジュール戦略を使用する場合、このパラメータはオプションです。

デプロイ設定

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 状態に達した後 40 秒間待ってから、正常性の最小割合の合計にカウントします。

  • タスクに、ヘルスチェックが定義された必須コンテナが 1 つ以上ある場合、サービススケジューラは、タスクが正常ステータスに達するのを待ってから、正常性の最小割合の合計にカウントします。タスク内のすべての必須コンテナがヘルスチェックに合格すると、タスクは正常と見なされます。サービススケジューラが待つことができる時間は、コンテナのヘルスチェックの設定によって決まります。詳細については、「ヘルスチェック」を参照してください。

ロードバランサーを使用するサービスについては、次の点に注意してください。

  • タスクにヘルスチェックが定義されている必須コンテナがない場合、サービススケジューラは、ロードバランサーターゲットグループのヘルスチェックが正常ステータスを返すのを待ってから、正常性の最小割合の合計にカウントします。

  • タスクにヘルスチェックが定義されている必須コンテナがない場合、サービススケジューラは、両方のタスクが正常なステータスになり、ロードバランサーターゲットグループのヘルスチェックが正常ステータスを返すのを待機し、その後でタスクを正常性の最小割の合計にカウントします。

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

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

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

デプロイメントコントローラー

deploymentController

型: オブジェクト

必須: いいえ

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

type

型: 文字列

有効な値: ECS | CODE_DEPLOY | EXTERNAL

必須: はい

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

ECS

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

CODE_DEPLOY

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

EXTERNAL

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

タスクの配置

placementConstraints

タイプ: オブジェクトの配列

必須: いいえ

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

type

型: 文字列

必須: いいえ

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

expression

型: 文字列

必須: いいえ

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

placementStrategy

タイプ: オブジェクトの配列

必須: いいえ

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

type

型: 文字列

有効な値: random | spread | binpack

必須: いいえ

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

field

型: 文字列

必須: いいえ

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

Tags

tags

タイプ: オブジェクトの配列

必須: いいえ

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

key

型: 文字列

長さの制限: 最小長は 1 です。最大長は 128 です。

必須: いいえ

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

value

型: 文字列

長さの制限: 最小長は 0 です。最大長は 256 です。

必須: いいえ

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

enableECSManagedTags

タイプ: ブール値

有効な値: true | false

必須: いいえ

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

propagateTags

型: 文字列

有効な値: TASK_DEFINITION | SERVICE

必須: いいえ

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

ネットワーク構成

networkConfiguration

型: オブジェクト

必須: いいえ

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

awsvpcConfiguration

型: オブジェクト

必須: いいえ

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

subnets

タイプ: 文字列の配列

必須: はい

タスクまたはサービスに関連付けられたサブネット。awsvpcConfiguration ごとに指定できるサブネットは 16 個に制限されています。

securityGroups

タイプ: 文字列の配列

必須: いいえ

タスクまたはサービスに関連付けられたセキュリティグループ。セキュリティグループを指定しないと、VPC のデフォルトのセキュリティグループが使用されます。awsvpcConfiguration ごとに指定できるセキュリティグループは 5 つに制限されています。

assignPublicIP

型: 文字列

有効な値: ENABLED | DISABLED

必須: いいえ

タスクの Elastic Network Interface がパブリック IP アドレスを受け取るかどうか。値を指定しない場合は、デフォルト値の DISABLED が使用されます。

healthCheckGracePeriodSeconds

タイプ: 整数

必須: いいえ

Amazon ECS サービススケジューラが、タスクが RUNNING 状態になった後で異常な Elastic Load Balancing ターゲットのヘルスチェック、コンテナのヘルスチェック、Route 53 のヘルスチェックを無視する期間 (秒単位)。これが有効であるのは、ロードバランサーを使用するようにサービスが設定されている場合のみです。サービスにロードバランサーを定義している場合、ヘルスチェックの猶予期間値を指定しないと、デフォルト値の 0 が使用されます。

サービスのタスクで、ヘルスチェックを開始して応答するまでに時間がかかる場合は、ヘルスチェックの猶予期間として最大 2,147,483,647 秒まで指定できます。この間は、ECS サービススケジューラはヘルスチェックのステータスを無視します。この猶予期間により、ECS サービススケジューラがタスクを異常とマークして時間より前に停止することがなくなります。

loadBalancers

タイプ: オブジェクトの配列

必須: いいえ

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

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

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

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

targetGroupArn

型: 文字列

必須: いいえ

サービスに関連付けられた Elastic Load Balancing ターゲットグループの完全な ARN。

ターゲットグループ ARN は、Application Load Balancer または Network Load Balancer を使用する場合にのみ指定します。Classic Load Balancer を使用する場合は、ターゲットグループ ARN を省略してください。

loadBalancerName

型: 文字列

必須: いいえ

サービスに関連付けるロードバランサーの名前。

ロードバランサー名は、Classic Load Balancer を使用する場合にのみ指定します。 Application Load Balancer または Network Load Balancer を使用する場合は、ロードバランサー名パラメータを省略してください。

containerName

型: 文字列

必須: いいえ

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

containerPort

タイプ: 整数

必須: いいえ

ロードバランサーに関連付けるコンテナのポート。このポートは、サービスのタスクが使用しているタスク定義の containerPort に対応する必要があります。EC2 起動タイプを使用するタスクの場合、コンテナインスタンスは、ポートマッピングの hostPort で進入トラフィックを許可する必要があります。

role

型: 文字列

必須: いいえ

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

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

重要

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

serviceRegistries

タイプ: オブジェクトの配列

必須: いいえ

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

registryArn

型: 文字列

必須: いいえ

サービスレジストリの ARN。現在サポートされているサービスレジストリは AWS Cloud Map です。詳細については、AWS Cloud Map 開発者ガイドの「サービスの使用」を参照してください。

port

タイプ: 整数

必須: いいえ

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

containerName

型: 文字列

必須: いいえ

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

containerPort

タイプ: 整数

必須: いいえ

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

クライアントトークン

clientToken

型: 文字列

必須: いいえ

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

サービス定義テンプレート

以下に、Amazon ECS サービス定義の JSON 表現を示します。

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

このサービス定義テンプレートは、次の AWS CLI コマンドを使用して作成できます。

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