AWS CloudFormation

在 AWS CloudFormation 堆棧上執行操作。堆疊是您可以作為單一單元來管理的 AWS 資源集合。堆疊中的資源都是由堆疊的 AWS CloudFormation 範本定義。變更集會建立比較，無須變更原始堆疊即可檢視。如需可在堆疊和變更集上執行之 AWS CloudFormation 動作類型的相關資訊，請參閱ActionMode參數。

若要針對堆疊作業失敗的 AWS CloudFormation 動作建構錯誤訊息，請 CodePipeline 呼叫 AWS CloudFormation DescribeStackEvents API。如果動作 IAM 角色具有存取該 API 的權限，則有關第一個失敗資源的詳細資訊將包含在 CodePipeline 錯誤訊息中。否則，如果角色原則沒有適當的權限， CodePipeline 將忽略存取 API 並改為顯示一般錯誤訊息。若要這麼做，必須將cloudformation:DescribeStackEvents權限新增至管道的服務角色或其他 IAM 角色。

如果您不希望資源詳細資訊顯示在管道錯誤訊息中，可以移除權限來撤銷此動作 IAM 角色的cloudformation:DescribeStackEvents權限。

動作類型

• 類別：Deploy

• 擁有者：AWS

• 提供者：CloudFormation

• 版本：1

組態參數

ActionMode

必要：是

ActionMode是在堆疊或變更集上 AWS CloudFormation 執行的動作名稱。以下是可用的動作模式：

• CHANGE_SET_EXECUTE 根據一組指定的資源更新，為資源堆疊執行變更集。使用此操作， AWS CloudFormation 開始改變堆棧。

• CHANGE_SET_REPLACE 根據您提交的堆疊名稱和範本建立變更組 (若不存在的話)。如果變更集存在，請將其 AWS CloudFormation 刪除，然後建立新的變更集。

• CREATE_UPDATE 建立堆疊 (如果堆疊不存在)。如果堆疊存在，則 AWS CloudFormation 會更新堆疊。使用此動作來更新現有堆疊。不同的是REPLACE_ON_FAILURE，如果堆棧存在並處於失敗狀態，則 CodePipeline 不會刪除並替換堆棧。

• DELETE_ONLY 刪除堆疊。若您指定不存在的堆疊，動作會成功完成，而不會刪除任何堆疊。

• REPLACE_ON_FAILURE 建立堆疊 (若堆疊不存在)。如果堆疊存在且處於失敗狀態，請 AWS CloudFormation 刪除堆疊，然後建立新堆疊。如果堆疊不是處於失敗狀態，請 AWS CloudFormation 更新它。

  若在 AWS CloudFormation中顯示下列任何狀態類型，堆疊會處於故障狀態：

  • ROLLBACK_FAILED

  • CREATE_FAILED

  • DELETE_FAILED

  • UPDATE_ROLLBACK_FAILED

  使用此動作來自動取代故障的堆疊，無須復原或故障診斷。

  重要

  建議您使用 REPLACE_ON_FAILURE 僅作為測試目的，因為它可能會刪除您的堆疊。

StackName

必要：是

StackName 是現有堆疊或您希望建立之堆疊的名稱。

功能

必要：有條件

使用 Capabilities 可確認範本具有自行建立和更新一些資源的功能，而且這些功能是根據範本中的資源類型來決定。

如果您的堆疊範本中有 IAM 資源，或您直接從包含巨集的範本建立堆疊，則此屬性為必要。為了讓 AWS CloudFormation 動作以這種方式成功操作，您必須明確確認您希望它使用以下功能之一來執行此操作：

• CAPABILITY_IAM

• CAPABILITY_NAMED_IAM

• CAPABILITY_AUTO_EXPAND

您可以透過在功能間使用逗號 (無空格) 來指定多個功能。動作宣告 中的範例顯示具有 CAPABILITY_IAM 和 CAPABILITY_AUTO_EXPAND 屬性的項目。

有關更多信息Capabilities，請參閱 AWS CloudFormation API 參考UpdateStack中的屬性。

ChangeSetName

必要：有條件

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

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

RoleArn

必要：有條件

RoleArn 是在指定堆疊中的資源上操作時 AWS CloudFormation 所假設 IAM 服務角色的 ARN。執行變更集時，不會套用 RoleArn。如果您不使用 CodePipeline 來建立變更集，請確定變更集或堆疊具有相關聯的角色。

注意

此角色必須與正在執行之動作的角色位於相同的帳戶中，如動作宣告中所配置RoleArn。

針對下列動作模式，此屬性為必要：

• CREATE_UPDATE

• REPLACE_ON_FAILURE

• DELETE_ONLY

• CHANGE_SET_REPLACE

注意

AWS CloudFormation 會為範本提供 S3 簽署的 URL；因此，這RoleArn不需要存取成品值區的權限。不過，動作RoleArn確實需要存取成品值區的權限，才能產生已簽署的 URL。

TemplatePath

必要：有條件

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

Artifactname::TemplateFileName

Artifactname是顯示在中的輸入人工因素名稱 CodePipeline。例如，來源階段的成品名稱為 SourceArtifact 且 template-export.json 檔案名稱建立 TemplatePath 名稱，如此範例所顯示：

"TemplatePath": "SourceArtifact::template-export.json"

針對下列動作模式，此屬性為必要：

• CREATE_UPDATE

• REPLACE_ON_FAILURE

• CHANGE_SET_REPLACE

針對其他所有動作模式，可忽略此屬性。

注意

包含 AWS CloudFormation 模板主體的模板文件的最小長度為 1 個字節，最大長度為 1 MB。對於中的 AWS CloudFormation 部署動作 CodePipeline，輸入人工因素大小上限一律為 256 MB。如需詳細資訊，請參閱配額 AWS CodePipeline和 AWS CloudFormation 的限制。

OutputFileName

必要：否

用OutputFileName於指定輸出檔案名稱，例如CreateStackOutput.json，為此動作 CodePipeline 新增至管線輸出人工因素。JSON 檔案包含 AWS CloudFormation 堆疊中Outputs區段的內容。

如果未指定名稱，則不 CodePipeline 會產生輸出檔案或成品。

ParameterOverrides

必要：否

參數會定義於您的堆疊範本中，並可讓您在建立或更新堆疊時為其提供值。您可以使用 JSON 物件在您的範本中設定參數值。(這些值會覆寫範本組態檔案中設定的值。) 如需使用參數覆寫的詳細資訊，請參閱 組態屬性 (JSON 物件)。

我們建議您大多數的參數值都使用範本組態檔案。僅對管道執行前未知的值使用參數覆寫。如需詳細資訊，請參閱《使用指南》中的〈搭 CodePipeline 配管線使用參數覆寫函數〉。AWS CloudFormation

注意

所有參數名稱都必須在堆疊範本中存在。

TemplateConfiguration

必要：否

TemplateConfiguration 是範本組態檔案。您將檔案包含在此動作的輸入成品中。它可以包含範本參數值和堆疊政策。如需範本組態檔案格式的詳細資訊，請參閱AWS CloudFormation 人工因素。

範本組態檔案名稱遵循此格式：

Artifactname::TemplateConfigurationFileName

Artifactname是顯示在中的輸入人工因素名稱 CodePipeline。例如，來源階段的成品名稱為 SourceArtifact 且 test-configuration.json 檔案名稱建立 TemplateConfiguration 名稱，如此範例所顯示：

"TemplateConfiguration": "SourceArtifact::test-configuration.json"

Input artifacts (輸入成品)

• 人工因素數目：0 to 10

• 描述：作為輸入， AWS CloudFormation 動作可選擇性地接受人工因素以達到下列目的：

  • 提供要執行的堆疊範本檔案。(請參閱 TemplatePath 參數。)

  • 提供要使用的範本組態檔案。(請參閱 TemplateConfiguration 參數。) 如需範本組態檔案格式的詳細資訊，請參閱AWS CloudFormation 人工因素。

  • 提供作為 AWS CloudFormation 堆疊一部分部署的 Lambda 函數的成品。

輸出成品

• 人工因素數目：0 to 1

• Description: (描述：) 如果指定 OutputFileName 參數，則此動作會產生一個包含具有指定名稱的 JSON 檔案的輸出成品。JSON 檔案包含 AWS CloudFormation 堆疊中 Outputs (輸出) 區段的內容。

  如需您可為 AWS CloudFormation 動作建立輸出區段的詳細資訊，請參閱 Outputs (輸出)。

輸出變數

設定時，此動作會產生變數，供管道中的下游動作的動作組態所參考。您可以設定動作的命名空間，讓這些變數可供下游動作的組態使用。

對於 AWS CloudFormation 動作，變數是從堆疊範本Outputs區段中指定的任何值產生的。請注意，生成輸出的唯一 CloudFormation動作模式是導致創建或更新堆棧的操作模式，例如堆棧創建，堆棧更新和更改集執行。產生變數的相應動作模式如下：

• CHANGE_SET_EXECUTE

• CHANGE_SET_REPLACE

• CREATE_UPDATE

• REPLACE_ON_FAILURE

如需詳細資訊，請參閱 Variables。如需說明如何在使用 CloudFormation輸出變數的管線中使用 CloudFormation 部署動作建立管線的教學課程，請參閱教學課程：建立使用 AWS CloudFormation 部署動作變數的管道。

動作宣告

YAML

Name: ExecuteChangeSet
ActionTypeId:
  Category: Deploy
  Owner: AWS
  Provider: CloudFormation
  Version: '1'
RunOrder: 2
Configuration:
  ActionMode: CHANGE_SET_EXECUTE
  Capabilities: CAPABILITY_NAMED_IAM,CAPABILITY_AUTO_EXPAND
  ChangeSetName: pipeline-changeset
  ParameterOverrides: '{"ProjectId": "my-project","CodeDeployRole": "CodeDeploy_Role_ARN"}'
  RoleArn: CloudFormation_Role_ARN
  StackName: my-project--lambda
  TemplateConfiguration: 'my-project--BuildArtifact::template-configuration.json'
  TemplatePath: 'my-project--BuildArtifact::template-export.yml'
OutputArtifacts: []
InputArtifacts:
  - Name: my-project-BuildArtifact

JSON

{
    "Name": "ExecuteChangeSet",
    "ActionTypeId": {
        "Category": "Deploy",
        "Owner": "AWS",
        "Provider": "CloudFormation",
        "Version": "1"
    },
    "RunOrder": 2,
    "Configuration": {
        "ActionMode": "CHANGE_SET_EXECUTE",
        "Capabilities": "CAPABILITY_NAMED_IAM,CAPABILITY_AUTO_EXPAND",
        "ChangeSetName": "pipeline-changeset",
        "ParameterOverrides": "{\"ProjectId\": \"my-project\",\"CodeDeployRole\": \"CodeDeploy_Role_ARN\"}",
        "RoleArn": "CloudFormation_Role_ARN",
        "StackName": "my-project--lambda",
        "TemplateConfiguration": "my-project--BuildArtifact::template-configuration.json",
        "TemplatePath": "my-project--BuildArtifact::template-export.yml"
    },
    "OutputArtifacts": [],
    "InputArtifacts": [
        {
             "Name": "my-project-BuildArtifact"
        }
    ]
},

另請參閱

以下相關資源可協助您使用此動作。

• 配置屬性參考 — 《AWS CloudFormation 使用指南》中的本參考章節提供了這些 CodePipeline 參數的更多描述和範例。

• AWS CloudFormation API 參考 — AWS CloudFormation API CreateStack參考中的參數描述了 AWS CloudFormation 範本的堆疊參數。