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

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

起動タイプ

launchType

タイプ: 文字列

有効な値: EC2 | FARGATE | EXTERNAL

必須: いいえ

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

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

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

capacityProviderStrategy

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

必須: いいえ

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

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

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

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

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

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

capacityProvider

タイプ: 文字列

必須: はい

キャパシティープロバイダーの短縮名または完全な Amazon リソースネーム (ARN)。

weight

タイプ: 整数

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

必須: いいえ

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

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

base

タイプ: 整数

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

必須: いいえ

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

タスク定義

taskDefinition

タイプ: 文字列

必須: いいえ

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

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

プラットフォームオペレーティングシステム

platformFamily

タイプ: 文字列

必須: 条件による

デフォルト: Linux

このパラメータは Fargate でホストされている Amazon ECS サービスに必要です。

このパラメータは、Amazon EC2 でホストされている Amazon ECS サービスでは無視されます。

サービスを実行するコンテナ上のオペレーティングシステム。有効な値は、LINUX、WINDOWS_SERVER_2019_FULL、WINDOWS_SERVER_2019_CORE、WINDOWS_SERVER_2022_FULL、および WINDOWS_SERVER_2022_CORE です。

サービスに指定するすべてのタスクの platformFamily 値は、サービス platformFamily 値と一致する必要があります。例えば、platformFamily を WINDOWS_SERVER_2019_FULL に設定すると、すべてのタスクの platformFamily 値は WINDOWS_SERVER_2019_FULL でなければなりません。

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

platformVersion

タイプ: 文字列

必須: いいえ

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

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

注記

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

クラスター

cluster

タイプ: 文字列

必須: いいえ

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

サービス名

serviceName

タイプ: 文字列

必須: はい

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

スケジュール戦略

schedulingStrategy

タイプ: 文字列

有効な値: REPLICA | DAEMON

必須: いいえ

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

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

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

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

  注記

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

必要数

desiredCount

タイプ: 整数

必須: いいえ

指定されたタスク定義のインスタンスをサービス内に配置し、実行し続ける数です。

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

デプロイ設定

deploymentConfiguration

タイプ: オブジェクト

必須: いいえ

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

maximumPercent

タイプ: 整数

必須: いいえ

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

Amazon ECS スケジューラはこのパラメータを使用して、置き換えタスクを開始するためのクラスターリソースが使用可能である限り、最初に置き換えタスクを開始してから、異常なタスクを停止することで、異常なタスクを置き換えます。スケジューラが異常なタスクを置き換える仕組みの詳細については、「Amazon ECS サービス」を参照してください。

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

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

サービスで Blue/Green (CODE_DEPLOY) または EXTERNAL のいずれかのデプロイタイプと EC2 起動タイプを使用するタスクが使用されている場合、最大パーセントの値はデフォルト値に設定されます。この値は、コンテナインスタンスが DRAINING 状態にある間、サービス内で RUNNING 状態を保つタスクの数の上限を定義する目的で使用されます。

注記

Blue/Green (CODE_DEPLOY) または EXTERNAL デプロイタイプのいずれかを使用し、EC2 起動タイプを使用するタスクがあるサービスのカスタム maximumPercent 値を指定することはできません。

サービス内のタスクが Fargate 起動タイプを使用する場合、maximum percent 値はサービスを記述するときに返されますが、使用されません。

minimumHealthyPercent

タイプ: 整数

必須: いいえ

サービスでローリング更新 (ECS) のデプロイタイプが使用されている場合、minimumHealthyPercent は、デプロイ時に RUNNING 状態に留まる必要があるサービスのタスクの下限数を表します。これは、最も近い整数に切り上げられた desiredCount のパーセンテージ (%) として表されます。このパラメータを使用して、追加のクラスターキャパシティーを使用せずにデプロイできます。

例えば、サービスで desiredCount が 4 タスク、minimumHealthyPercent が 50%、maximumPercent が 100% とすると、サービススケジューラは 2 つの新しいタスクを開始する前に、2 つの既存のタスクを停止してクラスターのキャパシティを解放できます。

いずれかのタスクに異常があり、maximumPercent が Amazon ECS スケジューラによる置き換えタスクの開始を許可しない場合、スケジューラは minimumHealthyPercent を制約として使用して、置き換えタスクを起動するためのキャパシティを解放するために、異常なタスクを 1 つずつ停止します。スケジューラが異常なタスクを置き換える仕組みの詳細については、「Amazon ECS サービス」を参照してください。

ロードバランサーを使用しないサービスの場合は、次のことを考慮してください。

• サービスのタスク内のすべての必須コンテナがヘルスチェックに合格すると、サービスは正常と見なされます。

• タスクにヘルスチェックが定義された必須コンテナがない場合、サービススケジューラは、タスクが RUNNING 状態に達した後 40 秒間待ってから、正常性の最小割合の合計にカウントします。

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

ロードバランサーを使用するサービスについては、次のことを考慮してください。

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

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

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

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

サービスで Blue/Green (CODE_DEPLOY) または EXTERNAL のデプロイタイプとタスクが使用されていて、EC2 起動タイプを使用するタスクが実行されている場合、最小ヘルス率の値はデフォルト値に設定されます。この値は、コンテナインスタンスが DRAINING 状態にある間、サービス内で RUNNING 状態を保つタスクの数の下限を定義する目的で使用されます。

注記

Blue/Green (CODE_DEPLOY) または EXTERNAL デプロイタイプのいずれかを使用し、EC2 起動タイプを使用するタスクがあるサービスのカスタム maximumPercent 値を指定することはできません。

サービスが Blue/Green (CODE_DEPLOY) または EXTERNAL デプロイタイプのいずれかを使用していて、Fargate 起動タイプを使用するタスクを実行している場合、最小ヘルス率の値は使用されませんが、サービスの説明時に値が返されます。

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

deploymentController

タイプ: オブジェクト

必須: いいえ

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

type

タイプ: 文字列

有効な値: ECS | CODE_DEPLOY | EXTERNAL

必須: はい

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

ECS

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

CODE_DEPLOY

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

EXTERNAL

サードパーティーのデプロイコントローラーを使用して Amazon ECS サービスのデプロイプロセスを完全に制御することが必要な場合は、外部デプロイタイプを使用します。

タスクの配置

placementConstraints

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

必須: いいえ

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

type

タイプ: 文字列

必須: いいえ

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

expression

タイプ: 文字列

必須: いいえ

制約に適用されるクラスタークエリ言語表現。制約タイプが distinctInstance である場合は、式を指定できません。詳細については、「Amazon ECS タスク用のコンテナインスタンスを定義する式を作成する」を参照してください。

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

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

必須: いいえ

サービスに適用し、サービスの分類と整理に役立つメタデータ。タグはそれぞれ、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 ネットワークモードが必要です。Amazon EC2 起動タイプのネットワークの詳細については、「EC2 起動タイプの Amazon ECS タスクネットワークオプション」を参照してください。Fargate 起動タイプのネットワークの詳細については、「Fargate 起動タイプの Amazon ECS タスクのネットワークオプション」を参照してください。

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 サービススケジューラがタスクを異常とマークして時間より前に停止することがなくなります。

Elastic Load Balancing を使用しない場合、タスク定義のヘルスチェックパラメータの startPeriod を使用することをお勧めします。コンテナのヘルスチェックを使用して Amazon ECS タスク状態を判定する

loadBalancers

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

必須: いいえ

サービスで使用するロードバランサーを表すロードバランサーオブジェクト。Application Load Balancer または Network Load Balancer を使,用するサービスの場合、6 個以上のターゲットグループはアタッチできません。

サービスの作成後にロードバランサーの設定を AWS Management Console から変更することはできません。AWS Copilot、AWS CloudFormation、AWS CLI、SDK のいずれかを使用して、AWS CodeDeploy ブルー/グリーンまたは外部ではなく、ECS ローリングデプロイコントローラのみのロードバランサー設定を変更できます。ロードバランサー設定を追加、更新、削除すると、Amazon ECS は、更新された Elastic Load Balancing 設定で新しいデプロイを開始します。これにより、タスクがロードバランサーに登録およびロードバランサーから登録解除されます。Elastic Load Balancing 設定を更新する前に、テスト環境でこれを検証することをお勧めします。設定の変更方法の詳細については、「Amazon Elastic Containers サービス API リファレンス」の UpdateService を参照してください。

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

targetGroupArn

タイプ: 文字列

必須: いいえ

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

ターゲットグループ ARN は、Application Load Balancer または Network Load Balancer を使用する場合にのみ指定します。

loadBalancerName

タイプ: 文字列

必須: いいえ

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

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 のサービスリンクロールの使用」を参照してください。

serviceConnectConfiguration

タイプ: オブジェクト

必須: いいえ

このサービスがサービスを検出して接続し、名前空間内の他のサービスによって検出され接続されるための設定。

詳細については、「Service Connect を使用して Amazon ECS サービスを短縮名で接続する」を参照してください。

enabled

型: ブール値

必須: はい

このサービスで Service Connect を使用するかどうかを指定します。

namespace

タイプ: 文字列

必須: いいえ

Service Connect で使用する AWS Cloud Map 名前空間の短縮名または完全な Amazon リソースネーム (ARN)。名前空間は、Amazon ECS サービスおよびクラスターと同じ AWS リージョンにある必要があります。名前空間のタイプは Service Connect に影響しません。AWS Cloud Map の詳細については、「AWS Cloud Map デベロッパーガイド」の「Working with Services」(サービスの使用) を参照してください。

services

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

必須: いいえ

Service Connect サービスオブジェクトの配列。これらは、他の Amazon ECS サービスがこのサービスに接続するために使用する名前とエイリアスです (エンドポイントとも呼ばれます)。

名前空間のメンバーである「クライアント」 Amazon ECS サービスが名前空間内の他のサービスに接続するだけであれば、このフィールドは必要ありません。その一例が、サービスに接続されているロードバランサーまたは他の方法で受信リクエストを受け入れるフロントエンドアプリケーションです。

オブジェクトは、タスク定義からポートを選択し、AWS Cloud Map サービスの名前や、クライアントアプリケーションがこのサービスを参照するためのエイリアス (エンドポイントとも呼ばれます) とポートの配列を割り当てます。

portName

タイプ: 文字列

必須: はい

portName は、この Amazon ECS サービスのタスク定義内のすべてのコンテナからの、portMappings のいずれかの name と一致する必要があります。

discoveryName

タイプ: 文字列

必須: いいえ

discoveryName は、この Amazon ECS サービス用に Amazon ECS が作成する新しい AWS Cloud Map サービスの名前です。これは AWS Cloud Map 名前空間内で一意である必要があります。

このフィールドを指定しない場合、portName が使用されます。

clientAliases

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

必須: いいえ

このサービス接続サービスのクライアントエイリアスのリストです。これらを使用して、クライアントアプリケーションで使用できる名前を割り当てます。このリストで使用できるクライアントエイリアスの最大数は 1 です。

各エイリアス (「エンドポイント」) は、他の Amazon ECS サービス (「クライアント」) がこのサービスに接続するために使用できる DNS 名とポート番号です。

名前とポートの組み合わせは、名前空間内で一意である必要があります。

これらの名前は、クライアントサービスの各タスク内で設定され、AWS Cloud Map では設定されません。これらの名前を解決するための DNS リクエストはタスクから離れることはなく、Elastic Network Interface ごとの 1 秒あたりの DNS リクエストの割り当てにもカウントされません。

port

タイプ: 整数

必須: はい

サービス接続プロキシのリスニングポート番号です。このポートは、同じ名前空間内のすべてのタスク内で使用できます。

クライアント Amazon ECS サービスのアプリケーションが変更されないようにするには、クライアントアプリケーションがデフォルトで使用するのと同じポートを設定します。

dnsName

タイプ: 文字列

必須: いいえ

dnsName は、このサービスに接続するためにクライアントタスクのアプリケーションで使用する名前です。この名前は有効な DNS ラベルでなければなりません。

このフィールドが指定されない場合、デフォルト値は discoveryName.namespace になります。discoveryName が指定されない場合、タスク定義から portName が使用されます。

クライアント Amazon ECS サービスのアプリケーションが変更されないようにするには、クライアントアプリケーションがデフォルトで使用するのと同じ名前を設定します。例えば、一般的な名前として database や db、または mysql や redis などのデータベース名の小文字表記が挙げられます。

ingressPortOverride

タイプ: 整数

必須: いいえ

(オプション) Service Connect プロキシがリッスンするポート番号です。

このフィールドの値を使用して、このアプリケーションのタスク定義で portMapping という名称で指定されているポート番号のトラフィックに対してプロキシをバイパスしてから、Amazon VPC セキュリティグループでそのポート番号を使用して、この Amazon ECS サービスのプロキシへのトラフィックを許可します。

awsvpc モードでは、このアプリケーションのタスク定義で portMapping という名称で指定されているコンテナポート番号がデフォルト値になります。bridge モードでは、Service Connect プロキシの動的エフェメラルポートがデフォルト値になります。

logConfiguration

タイプ: LogConfiguration オブジェクト

必須: いいえ

これにより、Service Connect プロキシログの公開場所が定義されます。このログは、予期しないイベント発生時のデバッグに使用します。この設定は、この Amazon ECS サービスの各タスクの Service Connect プロキシコンテナに logConfiguration パラメータを設定します。タスク定義でプロキシコンテナが指定されていません。

この Amazon ECS サービスのタスク定義のアプリケーションコンテナと同じログ設定を使用することをお勧めします。FireLens では、これはアプリケーションコンテナのログ設定です。fluent-bit または fluentd コンテナイメージを使用するのは FireLens ログルーターコンテナではありません。

serviceRegistries

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

必須: いいえ

サービスのサービス検出設定の詳細。詳細については、「サービス検出を使用して Amazon ECS サービスを DNS 名で接続する」を参照してください。

registryArn

型: 文字列

必須: いいえ

サービスレジストリの Amazon リソースネーム (ARN)。現在サポートされているサービスレジストリは AWS Cloud Map です。詳細については、AWS Cloud Map デベロッパーガイドの「サービスの使用」を参照してください。

port

タイプ: 整数

必須: いいえ

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

containerName

タイプ: 文字列

必須: いいえ

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

containerPort

タイプ: 整数

必須: いいえ

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

クライアントトークン

clientToken

タイプ: 文字列

必須: いいえ

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

ボリューム設定

volumeConfigurations

タイプ: オブジェクト

必須: いいえ

サービスによって管理されるタスク用のボリュームを作成するのに使用される設定。サービス内のタスクごとに 1 つのボリュームが作成されます。このオブジェクトを使用して設定できるのは、タスク定義で「configuredAtLaunch」とマークされているボリュームだけです。このオブジェクトは、サービスによって管理されるタスクに Amazon EBS データボリュームをアタッチするのに必要です。詳細については、「Amazon EBS ボリューム」を参照してください。

name

タイプ: 文字列

必須: はい

サービスを作成または更新するときに設定されるボリュームの名前。最大 255 文字の英字 (大文字と小文字)、数字、アンダースコア (_)、ハイフン (-) が可能です。この値は、タスク定義で指定されたボリューム名と一致する必要があります。

managedEBSVolume

タイプ: オブジェクト

必須: いいえ

サービスの作成または更新時にサービスによって管理されるタスクにアタッチされる Amazon EBS ボリュームのボリューム設定。

encrypted

型: ブール値

必須: いいえ

有効な値: true|false

サービスによって管理されるタスクにアタッチされる Amazon EBS ボリュームを暗号化するかどうかを指定します。アカウントのデフォルトで Amazon EBS 暗号化を有効にしている場合、この設定は無効になり、ボリュームは暗号化されます。デフォルトでの EBS 暗号化の詳細については、「Amazon EBS ユーザーガイド」の「Amazon EBS暗号化をデフォルトで有効にする」を参照してください。

kmsKeyId

タイプ: 文字列

必須: いいえ

Amazon EBS 暗号化に使用する AWS Key Management Service (AWS KMS) キーの識別子。このパラメータが指定されなかった場合は、Amazon EBS 用の AWS KMS key が使用されます。KmsKeyId を指定する場合、暗号化された状態は true である必要があります。

以下のいずれかを使用して KMS キーを指定できます。

• キー ID – 1234abcd-12ab-34cd-56ef-1234567890ab など。

• キーエイリアス – alias/ExampleAlias など。

• キー ARN – arn:aws:kms:us-east-1:012345678910:key/1234abcd-12ab-34cd-56ef-1234567890ab など。

• エイリアス ARN – arn:aws:kms:us-east-1:012345678910:alias/ExampleAlias など。

重要

AWS では、KMS キーを非同期で認証します。したがって、無効な ID、エイリアス、または ARN を指定すると、アクションは正常に行われているように見える場合がありますが、最終的には失敗します。詳細については、「Troubleshooting Amazon EBS volume attachment issues」を参照してください。

volumeType

タイプ: 文字列

必須: いいえ

有効な値: gp2|gp3|io1|io2|sc1|st1|standard

EBS ボリュームタイプ。詳細については、「Amazon EBS ユーザーガイド」の「Amazon EBS ボリュームタイプ」を参照してください。デフォルトのボリュームタイプは gp3 です。

注記

standard ボリュームタイプは、Fargate タスクにアタッチするように設定された Amazon EBS ボリュームではサポートされていません。

sizeInGiB

タイプ: 整数

必須: いいえ

有効な範囲: 1～16,384 の整数。

EBS ボリュームのギビバイト (GiB) でのサイズ。アタッチするボリュームを設定するスナップショット ID を指定しない場合は、サイズ値を指定する必要があります。スナップショットを使用してボリュームをアタッチするように設定した場合、デフォルト値はスナップショットサイズです。スナップショットサイズ以上のサイズを指定できます。

gp2 および gp3 ボリュームタイプでは、有効範囲は 1～16,384 です。

io1 および io2 ボリュームタイプでは、有効範囲は 4～16,384 です。

st1 および sc1 ボリュームタイプでは、有効範囲は 125～16,384 です。

standard ボリュームタイプでは、有効範囲は 1～1,024 です。

snapshotId

タイプ: 文字列

必須: いいえ

ECS タスクにアタッチされた新しいボリュームの作成に使用される既存の EBS ボリュームのスナップショットの ID。

iops

タイプ: 整数

必須: いいえ

1 秒あたりの I/O 操作の数 (IOPS)。gp3、io1、io2 ボリュームの場合、これはボリュームでプロビジョニングされている IOPS の数を表します。gp2 ボリュームの場合、この値はボリュームのベースラインパフォーマンスと、バースト用の I/O クレジットがこのボリュームに蓄積されるレートを表します。このパラメータは、io1 と io2 のボリュームに必須です。このパラメータは、gp2、st1、sc1、standard ボリュームではサポートされていません。

gp3 ボリュームでは、値の有効範囲は 3,000～16,000 です。

io1 ボリュームでは、値の有効範囲は 100～64,000 です。

io2 ボリュームでは、値の有効範囲は 100～64,000 です。

throughput

タイプ: 整数

必須: いいえ

サービスによって管理されるタスクにアタッチされたボリュームにプロビジョニングするスループット。

重要

このパラメータは、gp3 ボリュームのみでサポートされています。

roleArn

タイプ: 文字列

必須: はい

タスク用の Amazon EBS リソースを管理するための Amazon ECS アクセス許可を提供するインフラストラクチャ AWS Identity and Access Management (IAM) ロールの Amazon リソース ARN (ARN)。詳細については、「Amazon ECS インフラストラクチャ IAM ロール」を参照してください。

tagSpecifications

タイプ: オブジェクト

必須: いいえ

サービス管理型の Amazon EBS ボリュームに適用されるタグの指定。

resourceType

タイプ: 文字列

必須: はい

有効な値: volume

作成時にタグ付けするリソースのタイプ。

tags

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

必須: いいえ

分類と整理に役立つようにボリュームに適用するメタデータ。タグはそれぞれ、1 つのキーとオプションの 1 つの値で構成されており、どちらもユーザーが定義します。AmazonECSCreated と AmazonECSManaged は Amazon ECS がユーザーに代わって追加する予約済みのタグなので、独自のタグを最大 48 個指定できます。ボリュームが削除されると、タグも削除されます。詳細については、「Amazon ECS リソースにタグ付けする」を参照してください。

key

タイプ: 文字列

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

必須: いいえ

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

value

タイプ: 文字列

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

必須: いいえ

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

propagateTags

タイプ: 文字列

有効な値: TASK_DEFINITION | SERVICE | NONE

必須: いいえ

タグをタスク定義またはサービスからボリュームにコピーするかどうかを指定します。NONE を指定した場合、または値を指定しない場合、タグはコピーされません。

fileSystemType

タイプ: 文字列

必須: いいえ

有効な値: xfs|ext3|ext4|NTFS

ボリューム上のファイルシステムのタイプ。ボリュームのファイルシステムタイプによって、ボリューム内でのデータの格納方法と取得方法が決まります。スナップショットから作成されたボリュームでは、スナップショットの作成時にボリュームが使用していたのと同じファイルシステムタイプを指定する必要があります。ファイルシステムのタイプが一致しない場合、タスクは開始できません。

Linux の有効な値は xfs、ext3, and ext4 です。Linux タスクにアタッチされているボリュームのデフォルトは XFS です。

Windows の有効な値は NTFS です。TWindows タスクにアタッチされるボリュームのデフォルトは NTFS です。

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

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

Amazon EC2 起動タイプ

{
    "cluster": "", 
    "serviceName": "", 
    "taskDefinition": "", 
    "loadBalancers": [
        {
            "targetGroupArn": "", 
            "loadBalancerName": "", 
            "containerName": "", 
            "containerPort": 0
        }
    ], 
    "serviceRegistries": [
        {
            "registryArn": "", 
            "port": 0, 
            "containerName": "", 
            "containerPort": 0
        }
    ], 
    "desiredCount": 0, 
    "clientToken": "", 
    "launchType": "EC2", 
    "capacityProviderStrategy": [
        {
            "capacityProvider": "", 
            "weight": 0, 
            "base": 0
        }
    ], 
    "platformVersion": "", 
    "role": "", 
    "deploymentConfiguration": {
        "deploymentCircuitBreaker": {
            "enable": true, 
            "rollback": true
        }, 
        "maximumPercent": 0, 
        "minimumHealthyPercent": 0, 
        "alarms": {
            "alarmNames": [
                ""
            ], 
            "enable": true, 
            "rollback": true
        }
    }, 
    "placementConstraints": [
        {
            "type": "distinctInstance", 
            "expression": ""
        }
    ], 
    "placementStrategy": [
        {
            "type": "binpack", 
            "field": ""
        }
    ], 
    "networkConfiguration": {
        "awsvpcConfiguration": {
            "subnets": [
                ""
            ], 
            "securityGroups": [
                ""
            ], 
            "assignPublicIp": "DISABLED"
        }
    }, 
    "healthCheckGracePeriodSeconds": 0, 
    "schedulingStrategy": "REPLICA", 
    "deploymentController": {
        "type": "EXTERNAL"
    }, 
    "tags": [
        {
            "key": "", 
            "value": ""
        }
    ], 
    "enableECSManagedTags": true, 
    "propagateTags": "TASK_DEFINITION", 
    "enableExecuteCommand": true, 
    "serviceConnectConfiguration": {
        "enabled": true, 
        "namespace": "", 
        "services": [
            {
                "portName": "", 
                "discoveryName": "", 
                "clientAliases": [
                    {
                        "port": 0, 
                        "dnsName": ""
                    }
                ], 
                "ingressPortOverride": 0
            }
        ], 
        "logConfiguration": {
            "logDriver": "journald", 
            "options": {
                "KeyName": ""
            }, 
            "secretOptions": [
                {
                    "name": "", 
                    "valueFrom": ""
                }
            ]
        }
    }, 
    "volumeConfigurations": [
        {
            "name": "", 
            "managedEBSVolume": {
                "encrypted": true, 
                "kmsKeyId": "", 
                "volumeType": "", 
                "sizeInGiB": 0, 
                "snapshotId": "", 
                "iops": 0, 
                "throughput": 0, 
                "tagSpecifications": [
                    {
                        "resourceType": "volume", 
                        "tags": [
                            {
                                "key": "", 
                                "value": ""
                            }
                        ], 
                        "propagateTags": "NONE"
                    }
                ], 
                "roleArn": "", 
                "filesystemType": ""
            }
        }
    ]
}

Fargate 起動タイプ

{
    "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": "", 
    "platformFamily": "",
    "role": "", 
    "deploymentConfiguration": {
        "deploymentCircuitBreaker": {
            "enable": true, 
            "rollback": true
        }, 
        "maximumPercent": 0, 
        "minimumHealthyPercent": 0, 
        "alarms": {
            "alarmNames": [
                ""
            ], 
            "enable": true, 
            "rollback": true
        }
    }, 
    "placementStrategy": [
        {
            "type": "binpack", 
            "field": ""
        }
    ], 
    "networkConfiguration": {
        "awsvpcConfiguration": {
            "subnets": [
                ""
            ], 
            "securityGroups": [
                ""
            ], 
            "assignPublicIp": "DISABLED"
        }
    }, 
    "healthCheckGracePeriodSeconds": 0, 
    "schedulingStrategy": "REPLICA", 
    "deploymentController": {
        "type": "EXTERNAL"
    }, 
    "tags": [
        {
            "key": "", 
            "value": ""
        }
    ], 
    "enableECSManagedTags": true, 
    "propagateTags": "TASK_DEFINITION", 
    "enableExecuteCommand": true, 
    "serviceConnectConfiguration": {
        "enabled": true, 
        "namespace": "", 
        "services": [
            {
                "portName": "", 
                "discoveryName": "", 
                "clientAliases": [
                    {
                        "port": 0, 
                        "dnsName": ""
                    }
                ], 
                "ingressPortOverride": 0   
            }
        ], 
        "logConfiguration": {
            "logDriver": "journald", 
            "options": {
                "KeyName": ""
            }, 
            "secretOptions": [
                {
                    "name": "", 
                    "valueFrom": ""
                }
            ]
        }
    }, 
    "volumeConfigurations": [
        {
            "name": "", 
            "managedEBSVolume": {
                "encrypted": true, 
                "kmsKeyId": "", 
                "volumeType": "", 
                "sizeInGiB": 0, 
                "snapshotId": "", 
                "iops": 0, 
                "throughput": 0, 
                "tagSpecifications": [
                    {
                        "resourceType": "volume", 
                        "tags": [
                            {
                                "key": "", 
                                "value": ""
                            }
                        ], 
                        "propagateTags": "NONE"
                    }
                ], 
                "roleArn": "", 
                "filesystemType": ""
            }
        }
    ]
}

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

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