AWS CloudFormation 部署動作參考 - AWS CodePipeline
動作類型組態參數 Input artifacts (輸入成品)輸出成品輸出變數動作宣告另請參閱

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

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 是IAM服務角色ARN的 ， AWS CloudFormation 其在指定堆疊中的資源上操作時擔任 。 RoleArn 會在執行變更集時套用。如果您不使用 CodePipeline 建立變更集，請確定變更集或堆疊具有相關聯的角色。

注意

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

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

  • CREATE_UPDATE

  • REPLACE_ON_FAILURE

  • DELETE_ONLY

  • CHANGE_SET_REPLACE

注意

AWS CloudFormation 為URL範本提供 S3-signed；因此，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 物件）。

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

注意

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

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 偽影 。

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

輸出成品

  • 成品數量： 0 to 1

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

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

輸出變數

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

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

  • CHANGE_SET_EXECUTE

  • CHANGE_SET_REPLACE

  • CREATE_UPDATE

  • REPLACE_ON_FAILURE

如需詳細資訊，請參閱變數參考。如需教學課程，說明如何在使用輸出變數的管道中建立具有 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"
        }
    ]
},

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