CloudFormation 組態屬性參考

建置 CodePipeline 管道時，您可以將 Deploy 動作新增至管道，並將 CloudFormation 作為提供者。您接著必須指定管道要呼叫的 CloudFormation 動作以及動作的設定。本主題說明 CloudFormation 組態屬性。若要指定屬性，可以使用 CodePipeline 主控台，也可以建立用於 AWS CLI、CodePipeline API 或 CloudFormation 範本的 JSON 物件。

組態屬性 (主控台)

CodePipeline 主控台會顯示組態屬性，根據您選擇的動作模式指示哪些屬性為必要項目。

注意

當您建立管道時，您只能指定 Create or update a stack (建立或更新堆疊) 或 Create or replace a change set (建立或取代變更組) 動作模式。Advanced (進階) 區段中的屬性只有在您編輯管道時才可使用。

Action mode (動作模式

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 個字元。

Change set name (變更組合名稱

現有變更組或您希望為指定堆疊建立之新變更組的名稱。

範本

CloudFormation 範本檔案的位置，其格式為 ArtifactName::TemplateFileName。

Template configuration (範本組態

範本組態檔案的位置，其格式為 ArtifactName::TemplateConfigurationFileName。範本組態檔案可包含範本參數值、堆疊政策和標籤。若您在其中包含敏感資訊 (例如密碼)，請限制此檔案的存取。如需更多詳細資訊，請參閱 CloudFormation 成品。

功能

針對包含特定資源的堆疊，請明確確認 CloudFormation 可能會建立或更新那些資源。例如，若您的堆疊範本包含 AWS Identity and Access Management (IAM) 資源，您必須指定 CAPABILITY_IAM。如需詳細資訊，請參閱 CreateStack API 操作請求參數。

若您在您的堆疊範本中具有 IAM 資源，您必須指定此屬性。

您可以指定多個功能。

角色名稱 - 。

CloudFormation 在指定堆疊中的資源上操作時擔任之 IAM 服務角色名稱。

Output file name (輸出檔案名稱

在 Advanced (進階) 區段中，您可以指定輸出檔案名稱 (例如 CreateStackOutput.json)，CodePipeline 會在執行指定動作之後將其新增至輸出成品。輸出成品包含 JSON 檔案，其中包含 Outputs 範本的 CloudFormation 區段內容。

若您沒有指定名稱，CodePipeline 便不會產生輸出成品。

Parameter overrides (參數覆寫

參數是在您的範本中定義，而且可讓您在建立或更新堆疊時輸入自訂值。您可以指定覆寫範本組態檔案中範本參數值的 JSON 物件。所有參數名稱都必須在堆疊範本中存在。如需更多詳細資訊，請參閱 CloudFormation 範本 Parameters 語法。

注意

能存放在 ParameterOverrides 屬性的 JSON 物件具有 1 KB 的最大大小限制。

我們建議您使用範本組態檔案來指定您大多數的參數值。僅使用參數覆寫來指定動態參數值。除非您執行管道，否則動態參數是未知的。

下列範例會使用參數覆寫函數定義 ParameterName 參數的值。函數會從 CodePipeline 輸入成品擷取值。如需參數覆寫函數的詳細資訊，請參閱搭配 CodePipeline 管道使用參數覆寫函數。

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

組態屬性 (JSON 物件)

當您指定 CloudFormation 作為階段動作的提供者時，請在 Configuration 屬性中定義以下屬性。將 JSON 物件用於 AWS CLI、CodePipeline API 或 CloudFormation 範本。如需範例，請參閱 逐步解說：建置管線以用於測試和生產堆疊 和 CloudFormation 組態屬性參考。

ActionMode

CodePipeline 在處理相關聯階段時叫用的 CloudFormation 動作。僅指定下列其中一個動作模式：

• 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。如需詳細資訊，請參閱 CreateStack API 操作請求參數。

此屬性為條件式。若您在您的堆疊範本中具有 IAM 資源，您必須指定此屬性。

您可以指定多個功能。下列範例會將 CAPABILITY_IAM 和 CAPABILITY_AUTO_EXPAND 屬性新增至範本：

YAML

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'

JSON

 "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 會在執行指定動作之後將檔案新增至輸出成品。輸出成品包含 JSON 檔案，其中包含 Outputs 範本的 CloudFormation 區段內容。

此屬性為選擇性。若您沒有指定名稱，CodePipeline 便不會產生輸出成品。

ParameterOverrides

參數是在您的範本中定義，而且可讓您在建立或更新堆疊時輸入自訂值。您可以指定覆寫範本組態檔案中範本參數值的 JSON 物件。所有參數名稱都必須在堆疊範本中存在。如需更多詳細資訊，請參閱 CloudFormation 範本 Parameters 語法。

下列範例會將 InstanceType 和 KeyName 參數覆寫新增至範本：

YAML

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'

JSON

"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 管道使用參數覆寫函數。

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

此屬性為選擇性。

RoleArn

CloudFormation 在堆疊中的資源上操作時擔任之 IAM 服務角色 Amazon Resource Name (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 成品

此屬性為選擇性。

TemplatePath

TemplatePath 代表 CloudFormation 範本檔案。您將檔案包含在此動作的輸入成品中。該檔案名稱遵循此格式：

Artifactname::TemplateFileName

Artifactname 是出現在 CodePipeline 中的輸入成品名稱。例如，來源階段的成品名稱為 SourceArtifact 且 template.yaml 檔案名稱建立 TemplatePath 名稱，如此範例所顯示：

"TemplatePath": "SourceArtifact::template.yaml"

針對下列動作模式，此屬性為必要：CREATE_UPDATE、REPLACE_ON_FAILURE 和 CHANGE_SET_REPLACE。針對其他所有動作模式，可忽略此屬性。

另請參閱

以下相關資源可協助您使用這些參數。

• 如需有關 CodePipeline 中 CloudFormation 動作參數的詳細資訊，請參閱《AWS CodePipeline 使用者指南》中的 CloudFormation 部署動作組態參考。

• 如需動作提供者的範例範本值 (例如 Owner 欄位或 configuration 欄位)，請參閱 AWS CodePipeline User Guide (《 使用者指南》) 中的 Action structure reference (動作結構參考)。

• 若要下載 YAML 或 JSON 格式的管道堆疊範本範例，請參閱《AWS CodePipeline 使用者指南》中的教學課程：使用 CloudFormation 建立管道。