AWS CloudFormation StackSets - AWS CodePipeline
AWS CloudFormation StackSets アクションの機能 パイプラインで StackSets アクションを構成する方法CloudFormationStackSet アクションCloudFormationStackInstances アクションスタックセットオペレーションのアクセス許可モデルテンプレートパラメータのデータタイプ以下も参照してください。

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

AWS CloudFormation StackSets

CodePipeline は、AWS CloudFormation StackSets オペレーションを CI/CD プロセスの一部として実行する機能を提供します。スタックセットを使用して、1 つの AWS テンプレートを使用して、AWS リージョンの AWS CloudFormation アカウントにスタックを作成します。各スタックに含まれるリソースはすべて、スタックセットの AWS CloudFormation テンプレートで定義されます。スタックセットを作成する際、使用するテンプレートに加え、そのテンプレートで必要なパラメータや機能を指定します。

注記

AWS CloudFormation StackSet をデプロイするには、AWS Organizations 管理アカウントを使用する必要があります。このアクションには委任された管理アカウントを使用することはできません。

AWS CloudFormation StackSets の概念の詳細については、AWS CloudFormation ユーザーガイドの「StackSets の概念」を参照してください。

パイプラインと AWS CloudFormation StackSets を統合するには、次の 2 つの異なるアクションタイプを使用します。

  • CloudFormationStackSet アクションはスタックセット、またはパイプラインのソース場所に保存されているテンプレートからのスタックインスタンスを作成または更新します。スタックセットが作成または更新されるたびに、指定したインスタンスへの変更のデプロイが開始されます。コンソールでは、パイプラインを作成または編集するとき、[ CloudFormation スタックセット ] アクションプロバイダーを選択します。

  • CloudFormationStackInstances アクションは、指定したインスタンスへの CloudFormationStackSet アクションからの変更のデプロイ、新しいスタックインスタンスの作成、および指定されたインスタンスに対するパラメータの上書きを定義します。コンソールでは、パイプラインを作成または編集するとき、[ CloudFormation スタックインスタンス ] アクションプロバイダーを選択します。

注記

CloudFormationStackSet および CloudFormationStackInstances アクションは、アジアパシフィック (香港)、欧州 (チューリッヒ)、欧州 (ミラノ)、アフリカ (ケープタウン) および中東 (バーレーン) リージョンでは利用できません。利用可能なその他のアクションについては、「との製品とサービスの統合 CodePipeline」を参照してください。

これらのアクションを使用して、AWS アカウントまたは AWS Organizations の組織単位 ID をターゲットにデプロイします。

注記

AWS Organizations のアカウントまたは組織単位 ID をターゲットにデプロイし、サービスマネージドアクセス許可モデルを使用する場合は、AWS CloudFormation StackSets と AWS Organizations の間で信頼されたアクセスを有効にする必要があります。詳細については、「AWS CloudFormation Stacksets で信頼されたアクセスを有効にする」を参照してください。

AWS CloudFormation StackSets アクションの機能

CloudFormationStackSet アクションは、アクションが初めて実行されているかどうかに応じて、リソースを作成または更新します。

CloudFormationStackSet アクションはスタックセットを 作成 または 更新 して、指定されたインスタンスに変更をデプロイします。

注記

このアクションを使用してスタックインスタンスの追加を含む更新を行う場合、新しいインスタンスが最初にデプロイされ、更新は最後に完了します。新しいインスタンスは最初に古いバージョンを受け取り、次に更新がすべてのインスタンスに適用されます。

  • 作成: インスタンスが指定されておらず、スタックセットが存在しない場合は、 CloudFormationsStackSet アクション は、インスタンスを作成せずにスタックセットを作成します。

  • 更新 : CloudFormationsStackSet アクションがすでに作成されたスタックセットに対して実行されているとき、アクションはスタックセットを更新します。インスタンスが指定されておらず、スタックセットがすでに存在する場合は、すべてのインスタンスが更新されます。このアクションが 特定の インスタンスの更新に使用されている場合、残りのすべてのインスタンスが OUTDATED ステータスに移行します。

    CloudFormationsStackSet アクションを使用して、次の方法でスタックセットを更新します。

    • 一部またはすべてのインスタンスでテンプレートを更新します。

    • 一部またはすべてのインスタンスのパラメータを更新します。

    • スタックセット の実行ロールを更新します。(これは、管理者ロールで指定された 実行 ロールと一致しなければなりません)。

    • アクセス許可 モデルを変更します (インスタンスが作成されていない場合のみ)。

    • スタックセットのアクセス許可モデルが Service Managed の場合、AutoDeployment を有効または無効にします。

    • 管理者ロール を更新します。

    • スタックセット の説明を更新します。

    • デプロイターゲットをスタックセットの更新に追加して、新しいスタックインスタンスを作成します。

CloudFormationStackInstances アクションは、新しいスタックインスタンスを作成するか、古いスタックインスタンスを更新します。スタックセットが更新されると、インスタンスは古くなりますが、その中のすべてのインスタンスが更新されるわけではありません。

  • 作成: スタックがすでに存在する場合には、CloudFormationStackInstances アクションはインスタンスの更新のみを行い、スタックインスタンスは作成しません。

  • 更新: CloudFormationStackSet アクションが実行された後に、テンプレートまたはパラメータが一部のインスタンスでのみ更新された場合、残りは OUTDATED とマークされます。後期のパイプラインのステージでは、CloudFormationStackInstances は断続的にスタックセット内の残りのインスタンスを更新して、すべてのインスタンスが CURRENT とマークされるようにします。このアクションは、インスタンスを追加、または新しいインスタンスまたは既存のインスタンスでパラメータをオーバーライドするために使用できます。

アップデートの一環として、CloudFormationStackSet そして CloudFormationStackInstances アクションは、新しいデプロイターゲットを指定して、新しいスタックインスタンスを作成します。

アップデートの一環として、CloudFormationStackSet そして CloudFormationStackInstances アクションは、スタックセット、インスタンス、またはリソースを削除しません。アクションがスタックを更新する一方、すべてのインスタンスが更新されないよう指定する場合、更新を指定しなかったインスタンスは更新から除外され、ステータスが OUTDATED に設定されます。

デプロイ中、インスタンスへのデプロイが失敗した場合、スタックインスタンスは、OUTDATED のステータスを表示することもできます。

パイプラインで StackSets アクションを構成する方法

ベストプラクティスとして、スタックセットが作成され、最初にサブセットまたは単一のインスタンスにデプロイされるようにパイプラインを構築する必要があります。デプロイをテストし、生成されたスタックセットを表示したら、CloudFormationStackInstances アクションを追加し、残りのインスタンスが作成および更新されるようにします。

コンソールまたは CLI を使用して、次のように推奨されるパイプライン構造を作成します。

  1. ソースアクションを持つパイプラインを作成し (必須)、CloudFormationStackSet アクションをデプロイアクションとして指定します。パイプラインを実行します。

  2. パイプラインが最初に実行されると、CloudFormationStackSet アクションがスタックセットと少なくとも 1 つの初期インスタンスを作成します。スタックセットの作成を確認し、初期インスタンスへのデプロイを確認します。例えば、us-east-1 が指定されたリージョンであるアカウント Account-A のスタックセットの初期作成では、スタックインスタンスは次のスタックセットで作成されます。

    スタックインスタンス リージョン [ステータス]
    StackInstanceID-1 us-east-1 CURRENT

  3. パイプラインを編集して、指定したターゲットのスタックインスタンスを作成または更新する 2 番目のデプロイアクションとして CloudFormationStackInstances を追加します。例えば、us-east-2 およびeu-central-1 リージョンが指定されるアカウント Account-A のスタックインスタンスの作成の場合、残りのスタックインスタンスが作成され、初期インスタンスは次のように更新されます。

    スタックインスタンス リージョン [ステータス]
    StackInstanceID-1 us-east-1 CURRENT
    StackInstanceID-2 us-east-2 CURRENT
    StackInstanceID-3 eu-central-1 CURRENT

  4. 必要に応じてパイプラインを実行して、スタックセットを更新し、スタックインスタンスを更新または作成します。

アクション設定からデプロイターゲットを削除したスタックの更新を開始すると、更新用に指定されていなかったスタックインスタンスがデプロイから削除され、OUTDATED ステータスに移行します。たとえば、Account-A リージョンがアクション設定から削除されたアカウント us-east-2 のスタックインスタンスの更新の場合、残りのスタックインスタンスが作成され、削除されたインスタンスは OUTDATED に設定されます。

スタックインスタンス リージョン [ステータス]
StackInstanceID-1 us-east-1 CURRENT
StackInstanceID-2 us-east-2 OUTDATED
StackInstanceID-3 eu-central-1 CURRENT

スタックセットのデプロイのベストプラクティスの詳細については、AWS CloudFormation ユーザーガイドで StackSets のベストプラクティスを参照してください。

CloudFormationStackSet アクション

アクションはパイプラインのソース場所に保存されているテンプレートからのスタックセットを作成または更新します。

スタックセットを定義したら、設定パラメータに指定されたターゲットアカウントや リージョンでスタックを作成、更新、削除できるようになります。スタックの作成、更新、削除の際に、オペレーションを実行するリージョンの順序、スタックオペレーションを停止するフォールトトレランスパーセンテージ、スタックでオペレーションを同時に実行するアカウント数など、その他の環境設定を指定することができます。

スタックセットはリージョンのリソースです。1 つの AWS リージョンでスタックを作成した場合、他のリージョンからそのスタックにアクセスすることはできません。

このアクションをスタックセットに対する更新アクションとして使用する場合、少なくとも 1 つの スタック インスタンスにデプロイがないと、スタックの更新は許可されません。

アクションタイプ

  • カテゴリ:Deploy

  • 所有者: AWS

  • プロバイダー: CloudFormationStackSet

  • バージョン: 1

設定パラメータ

StackSetName

必須: はい

スタックセットに関連付ける名前。この名前は作成されるリージョンで一意であることが必要です。

名前には、英数字とハイフンのみを使用することができます。アルファベットで始まり、また 128 文字以下である必要があります。

説明

必須: いいえ

スタックセットの説明。これを使用して、スタックセットの目的やその他の関連情報を記述できます。

TemplatePath

必須: はい

スタックセット内のリソースを定義するテンプレートのロケーション。これは、最大サイズ 460,800 byte のテンプレートを指定する必要があります。

フォーマット "InputArtifactName::TemplateFileName" で、ソースアーティファクト名とテンプレートファイルへのパスを次の例に示すように入力します。

SourceArtifact::template.txt
パラメータ

必須: いいえ

デプロイ中に更新されるスタックセットのテンプレートパラメータのリスト。

パラメータはリテラルリストまたはファイルパスとして提供できます。

  • パラメータは、次の ParameterKey=string,ParameterValue=string,UsePreviousValue=boolean,ResolvedValue=string ParameterKey=string,ParameterValue=string,UsePreviousValue=boolean,ResolvedValue=string のような省略構文のフォーマットで入力できます。これらのデータタイプの詳細については、「テンプレートパラメータのデータタイプ」を参照してください。

    次の例は、my- BucketName の値を持つ bucket という名前のパラメータを示しています。

    ParameterKey=BucketName,ParameterValue=my-bucket

    次の例は、複数のパラメータを持つエントリを示しています。

                                                                                                          
  ParameterKey=BucketName,ParameterValue=my-bucket
  ParameterKey=Asset1,ParameterValue=true              
  ParameterKey=Asset2,ParameterValue=true

  • 次の例で示すように、フォーマット "InputArtifactName::ParametersFileName" で入力されたテンプレートパラメータのオーバーライドのリストを含むファイルのロケーションを入力できます。

    SourceArtifact::parameters.txt

    次の例では、parameters.txt のファイルの内容を示します。

    [
    {
        "ParameterKey": "KeyName",
        "ParameterValue": "true"
    },
    {
        "ParameterKey": "KeyName",
        "ParameterValue": "true"
    }
]
機能

必須: いいえ

テンプレート内のリソースのタイプに応じて、テンプレートがリソースを作成および更新できることを示します。

このプロパティは、スタックテンプレートに IAM リソースがある場合、またはマクロを含むテンプレートから直接スタックを作成する場合に使用する必要があります。AWS CloudFormation アクションがこの方法で正常に動作するためには、以下のいずれかの機能を使用する必要があります。

  • CAPABILITY_IAM

  • CAPABILITY_NAMED_IAM

機能間にカンマ (スペースなし) を使用して、複数の機能を指定できます。例 CloudFormationStackSet アクションの設定 の例は、複数の機能を持つエントリを示しています。

PermissionModel

必須: いいえ

IAM ロールの作成および管理方法を決定します。フィールドを指定しない場合、デフォルトが使用されます。詳細については、スタックセットオペレーションのアクセス許可モデルを参照してください。

有効な 値は次のとおりです。

  • SELF_MANAGED (デフォルト): ターゲットアカウントにデプロイするには、管理者ロールと実行ロールを作成する必要があります。

  • SERVICE_MANAGED: AWS CloudFormation Organizations が管理するアカウントへのデプロイに必要な IAM ロールが AWS StackSets によって自動的に作成されます。これには、アカウントが組織のメンバーである必要があります。

注記

このパラメータは、スタックセットにスタックインスタンスが存在しない場合にのみ変更できます。

AdministrationRoleARN
注記

AWS CloudFormation スタックセットでは複数のアカウントでオペレーションが実行されるため、スタックセットを作成する前に、それらのアカウントで必要なアクセス許可を定義しなければなりません。

必須: いいえ

注記

このパラメータは SELF_MANAGED アクセス許可モデルの場合はオプションで、SERVICE_MANAGED アクセス許可モデルには使用されません。

スタックセットオペレーションの実行に使用される管理者アカウントの IAM ロールの ARN。

名前には、英数字と記号 _+=,.@-, を使用できます。スペースは使用できません。名前では、大文字と小文字は区別されません。このロール名は、最小 20 文字、最大 2048 文字の長さでなければなりません。ロール名はアカウント内で一意である必要があります。ここで指定するロール名は、既存のロール名である必要があります。ロール名を指定しない場合は、AWSCloudFormationStackSetAdministrationRole に設定されます。ServiceManaged を指定する場合は、ロール名を定義してはいけません。

ExecutionRolenName
注記

AWS CloudFormation スタックセットでは複数のアカウントでオペレーションが実行されるため、スタックセットを作成する前に、それらのアカウントで必要なアクセス許可を定義しなければなりません。

必須: いいえ

注記

このパラメータは SELF_MANAGED アクセス許可モデルの場合はオプションで、SERVICE_MANAGED アクセス許可モデルには使用されません。

スタックセットオペレーションの実行に使用されるターゲットアカウントの IAM ロールの名前。名前には、英数字と記号 _+=,.@-, を使用できます。スペースは使用できません。名前では、大文字と小文字は区別されません。このロール名は、最小 1 文字、最大 64 文字の長さでなければなりません。ロール名はアカウント内で一意である必要があります。ここで指定するロール名は、既存のロール名である必要があります。カスタマイズされた実行ロールを使用している場合は、このロールを指定しないでください。ロール名を指定しない場合は、AWSCloudFormationStackSetExecutionRole に設定されます。Service_Managed を true に設定する場合は、ロール名を定義してはいけません。

OrganizationsAutoDeployment

必須: いいえ

注記

このパラメータは SERVICE_MANAGED アクセス許可モデルの場合はオプションで、SELF_MANAGED アクセス許可モデルには使用されません。

ターゲットの組織または組織単位 (OU) に追加した AWS CloudFormation Organizations アカウントに AWS StackSets が自動的にデプロイされるかどうかを示します。もし OrganizationsAutoDeployment が指定されている場合は、DeploymentTargets そして Regions を指定しないでください。

注記

OrganizationsAutoDeployment に入力が指定されていない場合、デフォルト値は Disabled です。

有効な 値は次のとおりです。

  • Enabled。必須: いいえ

    StackSets は、指定したリージョンのターゲット組織または組織単位 (OU) に追加した AWS Organizations アカウントに追加のスタックインスタンスを自動的にデプロイします。ターゲット組織または OU からアカウントを削除すると、AWS CloudFormation StackSets は指定したリージョンのアカウントからスタックインスタンスを削除します。

  • Disabled。必須: いいえ

    StackSets は、指定したリージョンのターゲット組織または組織単位 (OU) に追加した AWS Organizations アカウントに追加のスタックインスタンスを自動的にデプロイしません。

  • EnabledWithStackRetention。必須: いいえ

    ターゲット組織または OU からアカウントを削除したときに スタックリソースは保持されます。

DeploymentTargets

必須: いいえ

注記

SERVICE_MANAGED アクセス許可モデルの場合、デプロイターゲットに組織ルート ID または組織単位 ID を提供できます。SELF_MANAGED アクセス許可モデルの場合、アカウントのみを提供できます。

注記

このパラメータを選択する場合は、リージョン も選択する必要があります。

スタックセットインスタンスを作成および更新する必要がある AWS アカウントまたは組織単位 IDのリスト。

  • Accounts:

    アカウントは、リテラルリストまたはファイルパスとして指定できます。

    • リテラル: 次の例に示すように、パラメータを省略構文のフォーマット account_ID,account_ID で入力します。

      111111222222,333333444444

    • ファイルパス: フォーマット InputArtifactName::AccountsFileName で入力された、スタックセットインスタンスを作成および更新する必要がある AWS アカウントのリストを含むファイルのロケーション。ファイルパスを使用して accounts または OrganizationalUnitIds のいずれかを指定する場合、以下の例に示すように、ファイル形式は JSON であることが必要です。

      SourceArtifact::accounts.txt

      次の例では、accounts.txt のファイルの内容を示します。

      [
    "111111222222"
]

      以下の例では、複数のアカウントを一覧表示したときの accounts.txt のファイルの内容を示しています。

      [
    "111111222222","333333444444"
]

  • OrganizationalUnitIds

    注記

    このパラメータは SERVICE_MANAGED アクセス許可モデルの場合はオプションで、SELF_MANAGED アクセス許可モデルには使用されません。OrganizationsAutoDeployment を選択した場合は、これを使用しないでください。

    関連するスタックインスタンスを更新する AWS 組織単位。

    組織単位 ID は、リテラルリストまたはファイルパスとして提供できます。

    • リテラル: 次の例に示すように、カンマで区切って文字列の配列を入力します。

      ou-examplerootid111-exampleouid111,ou-examplerootid222-exampleouid222

    • ファイルパス: スタックセットインスタンスを作成または更新する OrganizationalUnitIds のリストを含むファイルの場所。ファイルパスを使用して accounts または OrganizationalUnitIds のいずれかを指定する場合、以下の例に示すように、ファイル形式は JSON であることが必要です。

      ファイルのパスをフォーマット InputArtifactName::OrganizationalUnitIdsFileName で入力します。

      SourceArtifact::OU-IDs.txt

      次の例では、OU-IDs.txt のファイルの内容を示します。

      [
    "ou-examplerootid111-exampleouid111","ou-examplerootid222-exampleouid222"
]
リージョン

必須: いいえ

注記

このパラメータを選択する場合は、DeploymentTargets も選択する必要があります。

スタックセットインスタンスが作成または更新される AWS リージョンのリスト。リージョンは、入力された順序で更新されます。

次の例に示すように、AWS フォーマットに有効な Region1,Region2 リージョンのリストを入力してください。

us-west-2,us-east-1
FailureTolerancePercentage

必須: いいえ

AWS CloudFormation がリージョンでのオペレーションを停止するまでに、このスタックオペレーションの失敗を許容する、リージョンあたりのアカウントの割合 (%)。リージョンでのオペレーションが停止すると、AWS CloudFormation は以降のリージョンでオペレーションを試行しません。指定した割合に基づいてアカウント数を計算する際に、AWS CloudFormation は最も近い整数に 切り捨てます。

MaxConcurrentPercentage

必須: いいえ

このオペレーションを一度に実行するアカウントの最大の割合。指定した割合に基づいてアカウント数を計算する際に、AWS CloudFormation は最も近い整数に 切り捨てます。四捨五入すると 0 になる場合、代わりに AWS CloudFormation によって数字は 1 に設定されます。この設定で 最大値 を指定する場合でも、大規模なデプロイでは、同時に処理される実際のアカウント数はサービスのスロットリングのために低くなる可能性があります。

RegionConcurrencyType

必須: いいえ

リージョン同時デプロイパラメータを設定することで、スタックセットを AWS リージョン 全体に順次デプロイするか、並列デプロイするかを指定できます。複数の AWS リージョン にスタックを並列デプロイするようにリージョンの同時実行数を指定している場合は、全体のデプロイ時間が短縮される可能性があります。

  • 並列: スタックセットのデプロイは、指定された失敗許容回数をリージョンのデプロイ失敗が超えない限り、同時に行われます。

  • 順次: スタックセットのデプロイは、リージョンのデプロイ失敗が指定された失敗許容回数を超えない限り、一度に 1 つずつ行われます。デフォルトでは、順次デプロイが選択されています。

ConcurrencyMode

必須: いいえ

同時実行モードでは、スタックセットオペレーション時の同時実行レベルの動作を、厳密な耐障害性またはソフトな耐障害性のいずれかを選択できます。厳密な障害耐性では、障害が発生するたびに同時実行性が低下するため、スタックセットの操作に障害が発生するため、デプロイ速度が低下します。ソフト障害耐性は、AWS CloudFormation 安全機能を活用しながらデプロイ速度を優先させます。

  • STRICT_FAILURE_TOLERANCE: このオプションでは、失敗したアカウントの数が特定の耐障害性を超えないように、同時実行レベルを動的に下げます。これがデフォルトの動作です。

  • SOFT_FAILURE_TOLERANCE: このオプションは実際の同時実行性から耐障害性を切り離します。これにより、障害の数に関係なく、スタックセットの操作を設定された同時実行レベルで実行できます。

入力アーティファクト

CloudFormationStackSet アクションでスタックセットのテンプレートを含む入力アーティファクトを少なくとも 1 つ含める必要があります。デプロイターゲット、アカウント、およびパラメータのリストには、より多くの入力アーティファクトを含めることができます。

  • アーティファクトの数: 1 to 3

  • 説明: アーティファクトを含めて、以下を提供できます。

    • スタックテンプレートファイル （TemplatePath パラメータを参照。）

    • パラメータファイル （Parameters パラメータを参照。）

    • アカウントファイル （DeploymentTargets パラメータを参照。）

出力アーティファクト

  • アーティファクトの数: 0

  • 説明: 入力アーティファクトは、このアクションタイプには適用されません。

出力変数

このアクションを設定すると、パイプライン内のダウンストリームアクションのアクション設定によって参照できる変数が生成されます。名前空間を使用してアクションを設定し、これらの変数をダウンストリームアクションの設定で使用できるようにします。

  • StackSetId: スタックセットの ID。

  • OperationId: スタックセットオペレーションの ID。

詳細については、「可変」を参照してください。

例 CloudFormationStackSet アクションの設定

次の例は、CloudFormationStackSet アクションのアクション設定を示しています。

自己管理型のアクセス許可モデルの例

次の例は CloudFormationStackSet アクションで、入力されたデプロイターゲットが AWS アカウント ID であることを示しています。

YAML
Name: CreateStackSet
ActionTypeId:
  Category: Deploy
  Owner: AWS
  Provider: CloudFormationStackSet
  Version: '1'
RunOrder: 1
Configuration:
  DeploymentTargets: '111111222222'
  FailureTolerancePercentage: '20'
  MaxConcurrentPercentage: '25'
  PermissionModel: SELF_MANAGED
  Regions: us-east-1
  StackSetName: my-stackset
  TemplatePath: 'SourceArtifact::template.json'
OutputArtifacts: []
InputArtifacts:
  - Name: SourceArtifact
Region: us-west-2
Namespace: DeployVariables
JSON
{
    "Name": "CreateStackSet",
    "ActionTypeId": {
        "Category": "Deploy",
        "Owner": "AWS",
        "Provider": "CloudFormationStackSet",
        "Version": "1"
    },
    "RunOrder": 1,
    "Configuration": {
        "DeploymentTargets": "111111222222",
        "FailureTolerancePercentage": "20",
        "MaxConcurrentPercentage": "25",
        "PermissionModel": "SELF_MANAGED",
        "Regions": "us-east-1",
        "StackSetName": "my-stackset",
        "TemplatePath": "SourceArtifact::template.json"
    },
    "OutputArtifacts": [],
    "InputArtifacts": [
        {
            "Name": "SourceArtifact"
        }
    ],
    "Region": "us-west-2",
    "Namespace": "DeployVariables"
}

サービス管理型のアクセス許可モデルの例

次の例は、サービス管理アクセス許可モデルの CloudFormationStackSet アクションで、AWS Organizations の自動デプロイのオプションがスタックリテンションによって有効になっていることを示しています。

YAML
Name: Deploy
ActionTypeId:
  Category: Deploy
  Owner: AWS
  Provider: CloudFormationStackSet
  Version: '1'
RunOrder: 1
Configuration:
  Capabilities: 'CAPABILITY_IAM,CAPABILITY_NAMED_IAM'
  OrganizationsAutoDeployment: EnabledWithStackRetention
  PermissionModel: SERVICE_MANAGED
  StackSetName: stacks-orgs
  TemplatePath: 'SourceArtifact::template.json'
OutputArtifacts: []
InputArtifacts:
  - Name: SourceArtifact
Region: eu-central-1
Namespace: DeployVariables
JSON
{
    "Name": "Deploy",
    "ActionTypeId": {
        "Category": "Deploy",
        "Owner": "AWS",
        "Provider": "CloudFormationStackSet",
        "Version": "1"
    },
    "RunOrder": 1,
    "Configuration": {
        "Capabilities": "CAPABILITY_IAM,CAPABILITY_NAMED_IAM",
        "OrganizationsAutoDeployment": "EnabledWithStackRetention",
        "PermissionModel": "SERVICE_MANAGED",
        "StackSetName": "stacks-orgs",
        "TemplatePath": "SourceArtifact::template.json"
    },
    "OutputArtifacts": [],
    "InputArtifacts": [
        {
            "Name": "SourceArtifact"
        }
    ],
    "Region": "eu-central-1",
    "Namespace": "DeployVariables"
}

CloudFormationStackInstances アクション

このアクションは 新しいインスタンスを作成し、指定されたインスタンスに スタックセットをデプロイします。スタックインスタンスは、リージョン内のターゲットアカウントのスタックへのリファレンスです。スタックインスタンスは、スタックがなくても存在することができます。たとえば、スタックの作成が失敗した場合は、スタック作成の失敗理由がスタックインスタンスに表示されます。スタックインスタンスに関連付けられるスタックセットは、1 つのみです。

スタックセットの最初の作成後、CloudFormationStackInstances を使用して新しいスタックインスタンスを追加できます。テンプレートパラメータ値は、スタックセットインスタンスの作成または更新オペレーション中にスタックインスタンスレベルでオーバーライドできます。

各スタックセットには、1 つのテンプレートとテンプレートパラメータのセットがあります。テンプレートまたはテンプレートパラメータを更新すると、セット全体のパラメータが更新されます。次に、変更がそのインスタンスにデプロイされるまですべてのインスタンスステータスが OUTDATED に設定されます。

特定のインスタンスのパラメータ値をオーバーライドするには、たとえばテンプレートに stage のパラメータが prod の値で含まれている場合、そのパラメータ値を beta または gamma にオーバーライドできます。

アクションタイプ

  • カテゴリ:Deploy

  • 所有者: AWS

  • プロバイダー: CloudFormationStackInstances

  • バージョン: 1

設定パラメータ

StackSetName

必須: はい

スタックセットに関連付ける名前。この名前は作成されるリージョンで一意であることが必要です。

名前には、英数字とハイフンのみを使用することができます。アルファベットで始まり、また 128 文字以下である必要があります。

DeploymentTargets

必須: いいえ

注記

SERVICE_MANAGED アクセス許可モデルの場合、デプロイターゲットに組織ルート ID または組織単位 ID を提供できます。SELF_MANAGED アクセス許可モデルの場合、アカウントのみを提供できます。

注記

このパラメータを選択する場合は、リージョン も選択する必要があります。

スタックセットインスタンスを作成および更新する必要がある AWS アカウントまたは組織単位 IDのリスト。

  • Accounts:

    アカウントは、リテラルリストまたはファイルパスとして指定できます。

    • リテラル: 次の例に示すように、パラメータを省略構文のフォーマット account_ID,account_ID で入力します。

      111111222222,333333444444

    • ファイルパス: フォーマット InputArtifactName::AccountsFileName で入力された、スタックセットインスタンスを作成および更新する必要がある AWS アカウントのリストを含むファイルのロケーション。ファイルパスを使用して accounts または OrganizationalUnitIds のいずれかを指定する場合、以下の例に示すように、ファイル形式は JSON であることが必要です。

      SourceArtifact::accounts.txt

      次の例では、accounts.txt のファイルの内容を示します。

      [
    "111111222222"
]

      以下の例では、複数のアカウントを一覧表示したときの accounts.txt のファイルの内容を示しています。

      [
    "111111222222","333333444444"
]

  • OrganizationalUnitIds

    注記

    このパラメータは SERVICE_MANAGED アクセス許可モデルの場合はオプションで、SELF_MANAGED アクセス許可モデルには使用されません。OrganizationsAutoDeployment を選択した場合は、これを使用しないでください。

    関連するスタックインスタンスを更新する AWS 組織単位。

    組織単位 ID は、リテラルリストまたはファイルパスとして提供できます。

    • リテラル: 次の例に示すように、カンマで区切って文字列の配列を入力します。

      ou-examplerootid111-exampleouid111,ou-examplerootid222-exampleouid222

    • ファイルパス: スタックセットインスタンスを作成または更新する OrganizationalUnitIds のリストを含むファイルの場所。ファイルパスを使用して accounts または OrganizationalUnitIds のいずれかを指定する場合、以下の例に示すように、ファイル形式は JSON であることが必要です。

      ファイルのパスをフォーマット InputArtifactName::OrganizationalUnitIdsFileName で入力します。

      SourceArtifact::OU-IDs.txt

      次の例では、OU-IDs.txt のファイルの内容を示します。

      [
    "ou-examplerootid111-exampleouid111","ou-examplerootid222-exampleouid222"
]
リージョン

必須: はい

注記

このパラメータを選択する場合は、DeploymentTargets も選択する必要があります。

スタックセットインスタンスが作成または更新される AWS リージョンのリスト。リージョンは、入力された順序で更新されます。

次の例に示すように、AWS のフォーマットに有効な Region1,Region2 リージョンのリストを入力します。

us-west-2,us-east-1
ParameterOverrides

必須: いいえ

選択したスタックインスタンスでオーバーライドしたいスタックセットパラメータのリスト。オーバーライドされたパラメータ値は、指定されたアカウントおよびリージョン内のすべてのスタックインスタンスに適用されます。

パラメータはリテラルリストまたはファイルパスとして提供できます。

  • パラメータは、次の ParameterKey=string,ParameterValue=string,UsePreviousValue=boolean,ResolvedValue=string ParameterKey=string,ParameterValue=string,UsePreviousValue=boolean,ResolvedValue=string のような省略構文のフォーマットで入力できます。これらのデータタイプの詳細については、「テンプレートパラメータのデータタイプ」を参照してください。

    次の例は、my- BucketName の値を持つ bucket という名前のパラメータを示しています。

    ParameterKey=BucketName,ParameterValue=my-bucket

    次の例は、複数のパラメータを持つエントリを示しています。

                                                                                                          
  ParameterKey=BucketName,ParameterValue=my-bucket
  ParameterKey=Asset1,ParameterValue=true              
  ParameterKey=Asset2,ParameterValue=true

  • 次の例で示すように、フォーマット InputArtifactName::ParameterOverridessFileName で入力されたテンプレートパラメータのオーバーライドのリストを含むファイルのロケーションを入力できます。

    SourceArtifact::parameter-overrides.txt

    次の例では、parameter-overrides.txt のファイルの内容を示します。

    [
    {
        "ParameterKey": "KeyName",
        "ParameterValue": "true"
    },
    {
        "ParameterKey": "KeyName",
        "ParameterValue": "true"
    }
]
FailureTolerancePercentage

必須: いいえ

AWS CloudFormation がリージョンでのオペレーションを停止するまでに、このスタックオペレーションの失敗を許容する、リージョンあたりのアカウントの割合 (%)。リージョンでのオペレーションが停止すると、AWS CloudFormation は以降のリージョンでオペレーションを試行しません。指定した割合に基づいてアカウント数を計算する際に、AWS CloudFormation は最も近い整数に 切り捨てます。

MaxConcurrentPercentage

必須: いいえ

このオペレーションを一度に実行するアカウントの最大の割合。指定した割合に基づいてアカウント数を計算する際に、AWS CloudFormation は最も近い整数に 切り捨てます。四捨五入すると 0 になる場合、代わりに AWS CloudFormation によって数字は 1 に設定されます。最大値 を指定する場合でも、大規模なデプロイでは、同時に処理される実際のアカウント数はサービスのスロットリングのために低くなる可能性があります。

RegionConcurrencyType

必須: いいえ

リージョン同時デプロイパラメータを設定することで、スタックセットを AWS リージョン 全体に順次デプロイするか、並列デプロイするかを指定できます。複数の AWS リージョン にスタックを並列デプロイするようにリージョンの同時実行数を指定している場合は、全体のデプロイ時間が短縮される可能性があります。

  • 並列: スタックセットのデプロイは、指定された失敗許容回数をリージョンのデプロイ失敗が超えない限り、同時に行われます。

  • 順次: スタックセットのデプロイは、リージョンのデプロイ失敗が指定された失敗許容回数を超えない限り、一度に 1 つずつ行われます。デフォルトでは、順次デプロイが選択されています。

ConcurrencyMode

必須: いいえ

同時実行モードでは、スタックセットオペレーション時の同時実行レベルの動作を、厳密な耐障害性またはソフトな耐障害性のいずれかを選択できます。厳密な障害耐性では、障害が発生するたびに同時実行性が低下するため、スタックセットの操作に障害が発生するため、デプロイ速度が低下します。ソフト障害耐性は、AWS CloudFormation 安全機能を活用しながらデプロイ速度を優先させます。

  • STRICT_FAILURE_TOLERANCE: このオプションでは、失敗したアカウントの数が特定の耐障害性を超えないように、同時実行レベルを動的に下げます。これがデフォルトの動作です。

  • SOFT_FAILURE_TOLERANCE: このオプションは実際の同時実行性から耐障害性を切り離します。これにより、障害の数に関係なく、スタックセットの操作を設定された同時実行レベルで実行できます。

入力アーティファクト

CloudFormationStackInstances にデプロイターゲットとパラメータをリストするアーティファクトを含めることができます。

  • アーティファクトの数: 0 to 2

  • 説明: 入力として、 スタックセットアクションはオプションでこれらの目的でアーティファクトを受け入れます。

    • 使用するパラメータファイルを提供するには （ParameterOverrides パラメータを参照。）

    • 使用するターゲットアカウントファイルを提供するには （DeploymentTargets パラメータを参照。）

出力アーティファクト

  • アーティファクトの数: 0

  • 説明: 入力アーティファクトは、このアクションタイプには適用されません。

出力変数

このアクションを設定すると、パイプライン内のダウンストリームアクションのアクション設定によって参照できる変数が生成されます。名前空間を使用してアクションを設定し、これらの変数をダウンストリームアクションの設定で使用できるようにします。

  • StackSetId: スタックセットの ID。

  • OperationId: スタックセットオペレーションの ID。

詳細については、「可変」を参照してください。

アクション設定の例

次の例は、CloudFormationStackInstances アクションのアクション設定を示しています。

自己管理型のアクセス許可モデルの例

次の例は CloudFormationStackInstances アクションで、入力されたデプロイターゲットが AWS アカウント ID 111111222222 であることを示しています。

YAML
Name: my-instances
ActionTypeId:
  Category: Deploy
  Owner: AWS
  Provider: CloudFormationStackInstances
  Version: '1'
RunOrder: 2
Configuration:
  DeploymentTargets: '111111222222'
  Regions: 'us-east-1,us-east-2,us-west-1,us-west-2'
  StackSetName: my-stackset
OutputArtifacts: []
InputArtifacts:
  - Name: SourceArtifact
Region: us-west-2
JSON
{
    "Name": "my-instances",
    "ActionTypeId": {
        "Category": "Deploy",
        "Owner": "AWS",
        "Provider": "CloudFormationStackInstances",
        "Version": "1"
    },
    "RunOrder": 2,
    "Configuration": {
        "DeploymentTargets": "111111222222",
        "Regions": "us-east-1,us-east-2,us-west-1,us-west-2",
        "StackSetName": "my-stackset"
    },
    "OutputArtifacts": [],
    "InputArtifacts": [
        {
            "Name": "SourceArtifact"
        }
    ],
    "Region": "us-west-2"
}

サービス管理型のアクセス許可モデルの例

次の例は、サービスマネージドアクセス許可モデルの CloudFormationStackInstances アクションで、デプロイターゲットが AWS Organizations の組織単位 ID ou-1111-1example であることを示しています。

YAML
Name: Instances
ActionTypeId:
  Category: Deploy
  Owner: AWS
  Provider: CloudFormationStackInstances
  Version: '1'
RunOrder: 2
Configuration:
  DeploymentTargets: ou-1111-1example
  Regions: us-east-1
  StackSetName: my-stackset
OutputArtifacts: []
InputArtifacts:
  - Name: SourceArtifact
Region: eu-central-1
JSON
{
    "Name": "Instances",
    "ActionTypeId": {
        "Category": "Deploy",
        "Owner": "AWS",
        "Provider": "CloudFormationStackInstances",
        "Version": "1"
    },
    "RunOrder": 2,
    "Configuration": {
        "DeploymentTargets": "ou-1111-1example",
        "Regions": "us-east-1",
        "StackSetName": "my-stackset"
    },
    "OutputArtifacts": [],
    "InputArtifacts": [
        {
            "Name": "SourceArtifact"
        }
    ],
    "Region": "eu-central-1"
}

スタックセットオペレーションのアクセス許可モデル

AWS CloudFormation スタックセットでは複数のアカウントでオペレーションが実行されるため、スタックセットを作成する前に、それらのアカウントで必要なアクセス許可を定義しなければなりません。アクセス許可は、自己管理型のアクセス許可またはサービス管理型のアクセス許可を使用して定義できます。

自己管理アクセス許可を使用して、StackSets で必要な 2 つの IAM ロールを作成します。これは、スタックセットを定義するアカウント内の AWSCloudFormationStackSetAdministrationRole などの管理者ロールと、スタックセットインスタンスをデプロイする各アカウントの AWSCloudFormationStackSetExecutionRole などの実行ロールです。このアクセス許可モデルを使用すると、StackSets は、IAM ロールを作成するアクセス許可を持つ任意の AWS アカウントにデプロイできます。詳細については、[AWS CloudFormation ユーザーガイド ] の「自己管理型のアクセス許可の承認」を参照してください。

注記

AWS CloudFormation スタックセットでは複数のアカウントでオペレーションが実行されるため、スタックセットを作成する前に、それらのアカウントで必要なアクセス許可を定義しなければなりません。

サービス管理型のアクセス許可を使用する場合、AWS Organizations が管理するアカウントにスタックインスタンスをデプロイできます。このアクセス許可モデルを使用すると、必要な IAM ロールを作成する必要はありません。ユーザーに代わって StackSets が IAM ロールを作成します。このモデルでは、将来組織に追加されるアカウントへの自動デプロイを有効にすることもできます。[AWS ユーザーガイド ] の「AWS CloudFormation Organizations で信頼されたアクセスを有効にする」を参照してください。

テンプレートパラメータのデータタイプ

スタックセットオペレーションで使用されるテンプレートパラメータには、次のデータタイプが含まれます。詳細については、「DescribeStackset」を参照してください。

ParameterKey

  • 説明: パラメータに関連付けられたキー。特定のパラメータにキーと値が指定されていない場合、AWS CloudFormation はテンプレートに指定されているデフォルト値を使用します。

  • 例：

    "ParameterKey=BucketName,ParameterValue=my-bucket"
ParameterValue

  • 説明: パラメータに関連付けられた入力値。

  • 例：

    "ParameterKey=BucketName,ParameterValue=my-bucket"
UsePreviousValue

  • スタックの更新中に、スタックが特定のパラメータキーに使用している既存のパラメータ値を使用します。true を指定した場合は、パラメータ値を指定しないでください。

  • 例：

    "ParameterKey=Asset1,UsePreviousValue=true"

各スタックセットには、1 つのテンプレートとテンプレートパラメータのセットがあります。テンプレートまたはテンプレートパラメータを更新すると、セット全体のパラメータが更新されます。次に、変更がそのインスタンスにデプロイされるまですべてのインスタンスステータスが OUTDATED に設定されます。

特定のインスタンスのパラメータ値をオーバーライドするには、たとえばテンプレートに stage のパラメータが prod の値で含まれている場合、そのパラメータ値を beta または gamma にオーバーライドできます。

このアクションを利用する際に役立つ関連リソースは以下の通りです。

  • パラメータタイプ - [AWS CloudFormation ユーザーガイド ] 内のこのリファレンスチャプターでは、CloudFormation テンプレートパラメータの詳細と例をより詳しく提供します。

  • ベストプラクティス - スタックセットのデプロイのベストプラクティスの詳細については、AWS CloudFormation ユーザーガイドの「https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-bestpractices.html」を参照してください。

  • AWS CloudFormation API リファレンス - スタックセットオペレーションで使用されるパラメータの詳細については、[AWS CloudFormation API リファレンス] の次の CloudFormation アクションを参照できます。

    • CreateStackSet アクションでスタックセットを作成します。

    • UpdateStackSet アクションで、指定されたアカウントおよびリージョン内のスタックセットおよび関連するスタックインスタンスを更新します。スタックセットの更新で作成されたスタックセットオペレーションが (完全または部分的に、指定されたフォルトトレランス値以下または以上となり) 失敗しても、スタックセットはこれらの変更で更新されます。指定されたスタックセットに対する後続の CreateStackInstances 呼び出しでは、更新されたスタックセットが使用されます。

    • CreateStackInstances アクションで、自己管理アクセス許可モデルで指定されたすべてのアカウント内、またはサービス管理アクセス許可モデルで指定されたすべてのデプロイターゲット内に、指定されたすべてのリージョンのスタックインスタンスを作成します。このアクションによって作成されたインスタンスのパラメータをオーバーライドできます。インスタンスがすでに存在する場合、CreateStackInstances は同じ入力パラメータで UpdateStackInstances を呼び出します。このアクションを使用してインスタンスを作成しても、他のスタックインスタンスのステータスは変更されません。

    • UpdateStackInstances アクションで、自己管理アクセス許可モデルで指定されたすべてのアカウント内、またはサービス管理アクセス許可モデルで指定されたすべてのデプロイターゲット内で、指定されたすべてのリージョンのスタックセットによってスタックインスタンスを最新にします。このアクションによって更新されたインスタンスのパラメータをオーバーライドできます。このアクションを使用してインスタンスのサブセットを更新しても、他のスタックインスタンスのステータスは変更されません。

    • DescribeStackSetOperation アクションで、指定されたスタックセットオペレーションの説明を返します。

    • DescribeStackSet アクションで、指定されたスタックセットの説明を返します。