# CloudFormation 構成プロパティのリファレンス
<a name="continuous-delivery-codepipeline-action-reference"></a>

CodePipeline パイプラインを構築する際、CloudFormation をプロバイダーとして `Deploy` アクションをパイプラインに追加します。その後、パイプラインが起動する CloudFormation アクションと、そのアクションの設定を指定する必要があります。このトピックでは、CloudFormation 構成プロパティについて説明します。プロパティを指定するには、CodePipeline コンソールを使用、あるいは JSON オブジェクトを作成して、AWS CLI、CodePipeline API、CloudFormation テンプレートを使用できます。

**Topics**
+ [構成プロパティ (コンソール)](#continuous-delivery-codepipeline-action-reference-console)
+ [構成プロパティ (JSON オブジェクト)](#continuous-delivery-codepipeline-action-reference-json)
+ [関連情報](#continuous-delivery-codepipeline-action-reference-see-also)

## 構成プロパティ (コンソール)
<a name="continuous-delivery-codepipeline-action-reference-console"></a>

CodePipeline [コンソール](https://console.aws.amazon.com/codepipeline/)に構成プロパティが表示され、選択したアクションモードに基づいて必須プロパティが示されます。

**注記**  
新しいパイプラインを作成するときは、[**Create or update a stack (スタックの作成または更新)**] または [**Create or replace a change set (変更セットの作成または置換)**] のアクションモードのみを指定できます。また、[**Advanced**] セクションのプロパティは、既存のパイプラインを編集するときにのみ使用できます。

**アクションモード**  
CodePipeline が関連ステージを処理する際に呼び出す CloudFormation アクション。以下のいずれかのアクションモードを選択します。  
+ [**Create or replace a change set (変更セットの作成または置換)**] は、変更セットが存在しない場合は送信したスタック名とテンプレートに基づいて作成します。変更セットがある場合は、CloudFormation それを削除して新しいものを作成します。
+ [**Create or update a stack (スタックの作成または更新)**] は、指定されたスタックが存在しない場合、スタックを作成します。スタックが存在する場合、CloudFormation はそのスタックを更新します。既存のスタックを更新するには、このアクションを使用します。CodePipeline はスタックを置き換えません。
+ [**Delete a stack (スタックの削除)**] は、スタックを削除します。存在しないスタックを指定した場合は、アクションはスタックを削除せずに正常に終了します。
+ [**Execute a change set (変更セットの実行)**] は、変更セットを実行します。
+ [**Replace a failed stack (失敗したスタックの置換)**] は、指定されたスタックが存在しない場合、スタックを作成します。スタックが存在しており、失敗状態の場合 (`ROLLBACK_COMPLETE`、`ROLLBACK_FAILED`、`CREATE_FAILED`、`DELETE_FAILED` または `UPDATE_ROLLBACK_FAILED` として報告されている場合)、CloudFormation はそのスタックを削除して新しいスタックを作成します。スタックが失敗状態ではない場合は、CloudFormation はそれを更新します。失敗したスタックをリカバリーまたはトラブルシューティングせずに置き換えるには、このアクションを使用します。通常、このモードはテスト用に選択されます。

**スタック名**  
既存のスタックまたは作成するスタックに関連付けられている名前のことを指します。この名前は、作成しているスタックの AWS リージョン内で一意であることが必要です。  
スタック名には、英数字 (大文字と小文字が区別されます) とハイフンのみを使用できます。先頭の文字はアルファベット文字である必要があります。また、128 文字より長くすることはできません。

**変更セット名**  
既存の変更セットの名前、または指定されたスタック用に作成する新しい変更セットの名前です。

**テンプレート**  
CloudFormation テンプレートファイルの場所です。形式は `ArtifactName::TemplateFileName` です。

**テンプレート構成**  
テンプレート構成ファイルの場所です。形式は `ArtifactName::TemplateConfigurationFileName` です。テンプレート構成ファイルには、テンプレートのパラメータ値、スタックポリシー、およびタグを含めることができます。機密情報 (パスワードなど) を含める場合は、このファイルへのアクセスを制限します。詳細については、「[CloudFormation アーティファクト](continuous-delivery-codepipeline-cfn-artifacts.md)」を参照してください。

**機能**  
特定のリソースを含むスタックの場合、CloudFormation がそれらのリソースを作成または更新する場合があることの明示的に承認。例えば、スタックテンプレートに AWS Identity and Access Management (IAM) リソースが含まれている場合、`CAPABILITY_IAM` を指定する必要があります。詳しくは、「[https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html) API 操作リクエストパラメータ」を参照してください。  
スタックテンプレートに IAM リソースがある場合は、このプロパティを指定する必要があります。  
複数のキャパシティーを指定できます。

**ロール名**  
CloudFormation が指定されたスタックのリソースで操作する際に引き受ける IAM サービスロールの名前。

**出力ファイル名**  
[**Advanced**] セクションで、CodePipeline が指定されたアクションを実行した後に[出力アーティファクト](https://docs.aws.amazon.com/codepipeline/latest/userguide/concepts.html#concepts-artifacts)に追加する出力ファイル名 (`CreateStackOutput.json` など) を指定できます。出力アーティファクトには、CloudFormation テンプレートの `Outputs` セクションの内容を含む JSON ファイルが含まれています。  
名前を指定しない場合、CodePipeline は出力アーティファクトを生成しません。

**パラメータの上書き**  
パラメータはテンプレートで定義されます。パラメータを使用すると、スタックの作成時または更新時にカスタム値を入力できます。テンプレート構成ファイルのテンプレートパラメータ値を上書きする JSON オブジェクトを指定できます。すべてのパラメータ名がスタックテンプレートに存在する必要があります。詳細については、「[CloudFormation テンプレートの Parameters 構文](parameters-section-structure.md)」を参照してください。  
`ParameterOverrides` プロパティに保存することができる JSON オブジェクトのサイズは、最大 1 キロバイトに制限されています。
パラメータ値のほとんどは、テンプレート構成ファイルを使用して指定することをお勧めします。パラメータの上書き機能を使用して、動的パラメータ値のみを指定します。動的パラメータは、パイプラインを実行するまでは不明です。  
次の例では、パラメータオーバーライド関数を使用して `ParameterName` パラメータの値を定義します。この関数は、CodePipeline 入力アーティファクトから値を取得します。パラメータオーバーライド関数の詳細については、「[CodePipeline パイプラインでのパラメーターオーバーライド関数の使用](continuous-delivery-codepipeline-parameter-override-functions.md)」を参照してください。  

```
{
  "ParameterName" : { "Fn::GetParam" : ["ArtifactName", "config-file-name.json", "ParamName"]}
}
```

## 構成プロパティ (JSON オブジェクト)
<a name="continuous-delivery-codepipeline-action-reference-json"></a>

ステージのアクションで `CloudFormation` をプロバイダーとして指定する場合は、`Configuration` プロパティ内で次のプロパティを定義します。AWS CLI、CodePipeline API、CloudFormation テンプレートに JSON オブジェクトを使用します。例については、「[チュートリアル: テストおよび本稼働スタック用のパイプラインを構築する](continuous-delivery-codepipeline-basic-walkthrough.md)」および「[CloudFormation 構成プロパティのリファレンス](#continuous-delivery-codepipeline-action-reference)」を参照してください。

`ActionMode`  
CodePipeline が関連ステージを処理する際に呼び出す CloudFormation アクション。次のアクションモードのいずれか 1 つのみを指定します。  
+ `CHANGE_SET_EXECUTE` は変更セットを実行します。
+ `CHANGE_SET_REPLACE` は、変更セットが存在しない場合、指定されたスタック名とテンプレートに基づいて変更セットを作成します。変更セットがある場合は、CloudFormation それを削除して新しいものを作成します。
+ `CREATE_UPDATE` は、指定されたスタックが存在しない場合、そのスタックを作成します。スタックが存在する場合、CloudFormation はそのスタックを更新します。既存のスタックを更新するには、このアクションを使用します。CodePipeline はスタックを置き換えません。
+ `DELETE_ONLY` は、スタックを削除します。存在しないスタックを指定した場合は、アクションはスタックを削除せずに正常に終了します。
+ `REPLACE_ON_FAILURE` は、指定されたスタックが存在しない場合、スタックを作成します。スタックが存在しており、失敗状態の場合 (`ROLLBACK_COMPLETE`、`ROLLBACK_FAILED`、`CREATE_FAILED`、`DELETE_FAILED` または `UPDATE_ROLLBACK_FAILED` として報告されている場合)、CloudFormation はそのスタックを削除して新しいスタックを作成します。スタックが失敗状態ではない場合は、CloudFormation はそれを更新します。失敗したスタックをリカバリーまたはトラブルシューティングせずに自動的に置き換えるには、このアクションを使用します。通常、このモードはテスト用に選択されます。
このプロパティは必須です。

`Capabilities`  
特定のリソースを含むスタックの場合、CloudFormation がそれらのリソースを作成または更新する場合があることの明示的に承認。例えば、スタックテンプレートに AWS Identity and Access Management (IAM) リソースが含まれている場合、`CAPABILITY_IAM` を指定する必要があります。詳しくは、「[https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html) API 操作リクエストパラメータ」を参照してください。  
このプロパティは条件付きです。スタックテンプレートに IAM リソースがある場合は、このプロパティを指定する必要があります。  
複数の機能を指定できます。次の例では、`CAPABILITY_IAM` および `CAPABILITY_AUTO_EXPAND` プロパティをテンプレートに追加します。  

```
configuration:
  ActionMode: CHANGE_SET_REPLACE
  Capabilities: CAPABILITY_IAM,CAPABILITY_AUTO_EXPAND
  ChangeSetName: pipeline-changeset
  RoleArn: CloudFormation_Role_ARN
  StackName: my-pipeline-stack
  TemplateConfiguration: 'my-pipeline-stack::template-configuration.json'
  TemplatePath: 'my-pipeline-stack::template-export.yml'
```

```
 "configuration": {
        "ActionMode": "CHANGE_SET_REPLACE",
        "Capabilities": "CAPABILITY_IAM,CAPABILITY_AUTO_EXPAND",
        "ChangeSetName": "pipeline-changeset",
        "RoleArn": "CloudFormation_Role_ARN",
        "StackName": "my-pipeline-stack",
        "TemplateConfiguration": "my-pipeline-stack::template-configuration.json",
        "TemplatePath": "my-pipeline-stack::template-export.yml"
    }
```

`ChangeSetName`  
既存の変更セットの名前、または指定されたスタック用に作成する新しい変更セットの名前です。  
このプロパティは `CHANGE_SET_REPLACE` および `CHANGE_SET_EXECUTE` アクションモードでは必須です。他のすべてのアクションモードでは、このプロパティは無視されます。

`OutputFileName`  
`CreateStackOutput.json` など、出力ファイルの名前。CodePipeline は指定されたアクションを実行した後、[出力アーティファクト](https://docs.aws.amazon.com/codepipeline/latest/userguide/concepts.html#concepts-artifacts)にファイルを追加します。出力アーティファクトには、CloudFormation テンプレートの `Outputs` セクションの内容を含む JSON ファイルが含まれています。  
このプロパティはオプションです。名前を指定しない場合、CodePipeline は出力アーティファクトを生成しません。

`ParameterOverrides`  
パラメータはテンプレートで定義されます。パラメータを使用すると、スタックの作成時または更新時にカスタム値を入力できます。テンプレート構成ファイルのテンプレートパラメータ値を上書きする JSON オブジェクトを指定できます。すべてのパラメータ名がスタックテンプレートに存在する必要があります。詳細については、「[CloudFormation テンプレートの Parameters 構文](parameters-section-structure.md)」を参照してください。  
次の例では、 `InstanceType` および `KeyName` パラメータの上書きをテンプレートに追加します。  

```
configuration:
  ActionMode: CHANGE_SET_REPLACE
  Capabilities: CAPABILITY_NAMED_IAM
  ChangeSetName: pipeline-changeset
  ParameterOverrides: '{"InstanceType": "t2.small","KeyName": "my-keypair"}'
  RoleArn: CloudFormation_Role_ARN
  StackName: my-pipeline-stack
  TemplateConfiguration: 'my-pipeline-stack::template-configuration.json'
  TemplatePath: 'my-pipeline-stack::template-export.yml'
```

```
"configuration": {
        "ActionMode": "CHANGE_SET_REPLACE",
        "Capabilities": "CAPABILITY_NAMED_IAM",
        "ChangeSetName": "pipeline-changeset",
        "ParameterOverrides": "{\"InstanceType\": \"t2.small\",\"KeyName\": \"my-keypair\"}",
        "RoleArn": "CloudFormation_Role_ARN",
        "StackName": "my-pipeline-stack",
        "TemplateConfiguration": "my-pipeline-stack::template-configuration.json",
        "TemplatePath": "my-pipeline-stack::template-export.yml"
    }
```
`ParameterOverrides` プロパティに保存できる JSON オブジェクトの最大サイズは 1 KB です。
パラメータ値のほとんどは、テンプレート構成ファイルを使用して指定することをお勧めします。パラメータの上書き機能を使用して、動的パラメータ値のみを指定します。動的パラメータ値は、パイプラインを実行するまでは不明です。  
次の例では、パラメータオーバーライド関数を使用して `ParameterName` パラメータの値を定義します。この関数は、CodePipeline 入力アーティファクトから値を取得します。パラメータオーバーライド関数の詳細については、「[CodePipeline パイプラインでのパラメーターオーバーライド関数の使用](continuous-delivery-codepipeline-parameter-override-functions.md)」を参照してください。  

```
{
  "ParameterName" : { "Fn::GetParam" : ["ArtifactName", "config-file-name.json", "ParamName"]}
}
```
このプロパティはオプションです。

`RoleArn`  
CloudFormation がスタックのリソースを操作する際に引き受ける IAM サービスロールの Amazon リソースネーム (ARN) です。  
このプロパティは、`CREATE_UPDATE`、`REPLACE_ON_FAILURE`、`DELETE_ONLY`、および `CHANGE_SET_REPLACE` アクションモードに必要です。`RoleArn` は、変更セットを実行するときには適用されません。変更セットの作成に CodePipeline を使用しない場合は、変更セットまたはスタックにロールが関連付けられていることを確認します。

`StackName`  
既存のスタックの名前、または作成するスタックの名前です。  
このプロパティはすべてのアクションモードで必須です。

`TemplateConfiguration`  
`TemplateConfiguration` はテンプレート構成ファイルです。このアクションへの入力アーティファクトにファイルを含めます。テンプレート構成ファイル名は以下の形式に従います。  
`Artifactname::TemplateConfigurationFileName`  
`Artifactname` は、CodePipeline に表示される入力アーティファクト名です。たとえば、アーティファクト名 `SourceArtifact` と `test-configuration.json` ファイル名を持つソースステージでは、次の例に示すような `TemplateConfiguration` の名前が作成されます。  

```
"TemplateConfiguration": "SourceArtifact::test-configuration.json"
```
テンプレート構成ファイルには、テンプレートのパラメーター値およびスタックポリシーを含めることができます。機密情報 (パスワードなど) を含める場合は、このファイルへのアクセスを制限します。設定ファイルのテンプレートの例については、「[CloudFormation アーティファクト](continuous-delivery-codepipeline-cfn-artifacts.md)」を参照してください。  
このプロパティはオプションです。

`TemplatePath`  
`TemplatePath` は CloudFormation テンプレートファイルを表します。このアクションへの入力アーティファクトにファイルを含めます。ファイル名の形式は次のとおりです:   
`Artifactname::TemplateFileName`  
`Artifactname` は、CodePipeline に表示される入力アーティファクト名です。たとえば、アーティファクト名 `SourceArtifact` と `template.yaml` ファイル名を持つソースステージでは、次の例に示すような `TemplatePath` の名前が作成されます。  

```
"TemplatePath": "SourceArtifact::template.yaml"
```
このプロパティは `CREATE_UPDATE`、`REPLACE_ON_FAILURE` および `CHANGE_SET_REPLACE` アクションモードでは必須です。他のすべてのアクションモードでは、このプロパティは無視されます。

## 関連情報
<a name="continuous-delivery-codepipeline-action-reference-see-also"></a>

これらのパラメータを利用する際に役立つ関連リソースは以下の通りです。
+ CodePipeline の CloudFormation アクションパラメータの詳細については、「*AWS CodePipeline ユーザーガイド*」の「[アクション設定リファレンスの CloudFormation デプロイ](https://docs.aws.amazon.com/codepipeline/latest/userguide/action-reference-CloudFormation.html)」を参照してください。
+ アクションプロバイダーごとのテンプレート値における例の場合 (`Owner` フィールドまたは `configuration` フィールドなど)、「*AWS CodePipeline ユーザーガイド*」の「[アクション構造リファレンス](https://docs.aws.amazon.com/codepipeline/latest/userguide/action-reference.html)」を参照してください。
+ サンプルのパイプラインスタックテンプレートを YAML または JSON 形式でダウンロードするには、「*AWS CodePipeline ユーザーガイド*」の「[Tutorial: Create a pipeline with CloudFormation](https://docs.aws.amazon.com/codepipeline/latest/userguide/tutorials-cloudformation.html)」を参照してください。