AWS CloudFormation StackSets デプロイアクションリファレンス

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

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

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

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

AWS CloudFormation StackSets アクションの機能

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

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

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

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

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

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

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

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

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

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

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

CloudFormationStackSet アクション

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

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

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

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

アクションタイプ

設定パラメータ

入力アーティファクト

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

出力アーティファクト

出力変数

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

詳細については、「変数リファレンス」を参照してください。

例 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 にオーバーライドできます。

アクションタイプ

設定パラメータ

入力アーティファクト

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

出力アーティファクト

出力変数

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

詳細については、「変数リファレンス」を参照してください。

アクション設定の例

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

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

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

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

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

以下も参照してください。

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