AWS CloudFormation

Mengeksekusi operasi pada AWS CloudFormation tumpukan. Tumpukan adalah kumpulan sumber daya AWS yang dapat Anda kelola sebagai unit tunggal. Sumber daya dalam tumpukan ditentukan oleh AWS CloudFormation template tumpukan. Sebuah set perubahan menciptakan perbandingan yang dapat dilihat tanpa mengubah tumpukan asli. Untuk informasi tentang jenis AWS CloudFormation tindakan yang dapat dilakukan pada tumpukan dan set perubahan, lihat ActionMode parameter.

Untuk membuat pesan kesalahan untuk AWS CloudFormation tindakan di mana operasi tumpukan gagal, CodePipeline panggil AWS CloudFormation DescribeStackEvents API. Jika peran IAM tindakan memiliki izin untuk mengakses API tersebut, detail tentang sumber daya pertama yang gagal akan disertakan dalam pesan CodePipeline kesalahan. Jika tidak, jika kebijakan peran tidak memiliki izin yang sesuai, CodePipeline akan mengabaikan mengakses API dan menampilkan pesan kesalahan umum sebagai gantinya. Untuk melakukan ini, cloudformation:DescribeStackEvents izin harus ditambahkan ke peran layanan atau peran IAM lainnya untuk pipeline.

Jika Anda tidak ingin detail sumber daya muncul dalam pesan kesalahan pipeline, Anda dapat mencabut izin ini untuk peran IAM tindakan dengan menghapus izin. cloudformation:DescribeStackEvents

Tipe tindakan

• Kategori: Deploy

• Pemilik: AWS

• Penyedia: CloudFormation

• Versi: 1

Parameter konfigurasi

ActionMode

Diperlukan: Ya

ActionModeadalah nama tindakan yang AWS CloudFormation dilakukan pada tumpukan atau set perubahan. Mode aksi berikut tersedia:

• CHANGE_SET_EXECUTEmengeksekusi set perubahan untuk tumpukan sumber daya yang didasarkan pada serangkaian pembaruan sumber daya yang ditentukan. Dengan tindakan ini, AWS CloudFormation mulai mengubah tumpukan.

• CHANGE_SET_REPLACE membuat set perubahan, jika tidak ada, berdasarkan nama tumpukan dan templat yang Anda kirimkan. Jika set perubahan ada, AWS CloudFormation menghapusnya, lalu membuat yang baru.

• CREATE_UPDATEmembuat tumpukan jika tidak ada. Jika tumpukan ada, AWS CloudFormation akan memperbarui tumpukan. Gunakan tindakan ini untuk memperbarui tumpukan yang ada. Tidak sepertiREPLACE_ON_FAILURE, jika tumpukan ada dan dalam keadaan gagal, CodePipeline tidak akan menghapus dan mengganti tumpukan.

• DELETE_ONLY akan menghapus tumpukan. Jika Anda menentukan tumpukan yang tidak ada, tindakan berhasil diselesaikan tanpa menghapus tumpukan.

• REPLACE_ON_FAILUREmembuat tumpukan, jika tidak ada. Jika tumpukan ada dan dalam keadaan gagal, AWS CloudFormation hapus tumpukan, lalu buat tumpukan baru. Jika tumpukan tidak dalam keadaan gagal, AWS CloudFormation akan memperbaruinya.

  Tumpukan dalam keadaan gagal ketika salah satu jenis status berikut ditampilkan diAWS CloudFormation:

  • ROLLBACK_FAILED

  • CREATE_FAILED

  • DELETE_FAILED

  • UPDATE_ROLLBACK_FAILED

  Gunakan tindakan ini untuk secara otomatis mengganti tumpukan yang gagal tanpa memulihkan atau memecahkan masalahnya.

  penting

  Kami menyarankan Anda menggunakan REPLACE_ON_FAILURE untuk tujuan pengujian hanya karena mungkin menghapus tumpukan Anda.

StackName

Diperlukan: Ya

StackNameadalah nama tumpukan yang ada atau tumpukan yang ingin Anda buat.

Kemampuan

Diperlukan: Kondisional

Penggunaan Capabilities mengakui bahwa template mungkin memiliki kemampuan untuk membuat dan memperbarui beberapa sumber daya sendiri, dan bahwa kemampuan ini ditentukan berdasarkan jenis sumber daya dalam template.

Properti ini diperlukan jika Anda memiliki sumber daya IAM di template tumpukan Anda atau Anda membuat tumpukan langsung dari template yang berisi makro. Agar AWS CloudFormation tindakan berhasil beroperasi dengan cara ini, Anda harus secara eksplisit mengakui bahwa Anda ingin melakukannya dengan salah satu kemampuan berikut:

• CAPABILITY_IAM

• CAPABILITY_NAMED_IAM

• CAPABILITY_AUTO_EXPAND

Anda dapat menentukan lebih dari satu kemampuan dengan menggunakan koma (tanpa spasi) di antara kemampuan. Contoh di Deklarasi tindakan menunjukkan entri dengan properti CAPABILITY_IAM dan CAPABILITY_AUTO_EXPAND.

Untuk informasi selengkapnyaCapabilities, lihat properti UpdateStackdi bawah Referensi AWS CloudFormation API.

ChangeSetName

Diperlukan: Kondisional

ChangeSetNameadalah nama set perubahan yang ada atau set perubahan baru yang ingin Anda buat untuk tumpukan yang ditentukan.

Properti ini diperlukan untuk mode tindakan berikut: CHANGE_SET_REPLACE dan CHANGE_SET_EXECUTE. Untuk semua mode tindakan lainnya, properti ini diabaikan.

RoleArn

Diperlukan: Kondisional

RoleArnIni adalah ARN dari peran layanan IAM yang AWS CloudFormation mengasumsikan ketika beroperasi pada sumber daya di tumpukan yang ditentukan. RoleArntidak diterapkan saat menjalankan set perubahan. Jika Anda tidak menggunakan CodePipeline untuk membuat set perubahan, pastikan bahwa set perubahan atau tumpukan memiliki peran terkait.

catatan

Peran ini harus dalam akun yang sama dengan peran untuk tindakan yang sedang berjalan, seperti yang dikonfigurasi dalam deklarasi tindakanRoleArn.

Properti ini diperlukan untuk mode tindakan berikut:

• CREATE_UPDATE

• REPLACE_ON_FAILURE

• DELETE_ONLY

• CHANGE_SET_REPLACE

catatan

AWS CloudFormationdiberikan URL bertanda S3 ke template; oleh karena itu, ini RoleArn tidak memerlukan izin untuk mengakses bucket artefak. Namun, tindakan tersebut RoleArn memang memerlukan izin untuk mengakses bucket artefak, untuk menghasilkan URL yang ditandatangani.

TemplatePath

Diperlukan: Kondisional

TemplatePath mewakili file templat AWS CloudFormation. Anda menyertakan file dalam artefak input untuk tindakan ini. Nama file mengikuti format ini:

Artifactname::TemplateFileName

Artifactname adalah nama artefak input seperti yang muncul di CodePipeline. Sebagai contoh, tahap sumber dengan nama artefak SourceArtifact dan nama file template-export.json membuat nama TemplatePath seperti yang ditunjukkan dalam contoh ini:

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

Properti ini diperlukan untuk mode tindakan berikut:

• CREATE_UPDATE

• REPLACE_ON_FAILURE

• CHANGE_SET_REPLACE

Untuk semua mode tindakan lainnya, properti ini diabaikan.

catatan

File AWS CloudFormation template yang berisi badan template memiliki panjang minimal 1 byte dan panjang maksimum 1 MB. Untuk tindakan AWS CloudFormation penerapan di CodePipeline, ukuran artefak input maksimum selalu 256 MB. Untuk informasi selengkapnya, lihat Kuota di AWS CodePipeline dan AWS CloudFormationBatas.

OutputFileName

Diperlukan: Tidak

Gunakan OutputFileName untuk menentukan nama file keluaran, sepertiCreateStackOutput.json, yang CodePipeline menambah artefak keluaran pipeline untuk tindakan ini. File JSON berisi isi Outputs bagian dari AWS CloudFormation tumpukan.

Jika Anda tidak menentukan nama, CodePipeline tidak menghasilkan file keluaran atau artefak.

ParameterOverrides

Diperlukan: Tidak

Parameter didefinisikan dalam template tumpukan Anda dan memungkinkan Anda untuk memberikan nilai untuk mereka pada saat pembuatan tumpukan atau pembaruan. Anda dapat menggunakan objek JSON untuk mengatur nilai parameter dalam template Anda. (Nilai-nilai ini mengesampingkan yang ditetapkan dalam file konfigurasi template.) Untuk informasi selengkapnya tentang penggunaan penggantian parameter, lihat Properti Konfigurasi (Objek JSON).

Kami menyarankan Anda menggunakan file konfigurasi template untuk sebagian besar nilai parameter Anda. Gunakan penggantian parameter hanya untuk nilai yang tidak diketahui sampai pipeline berjalan. Untuk informasi selengkapnya, lihat Menggunakan Fungsi Ganti Parameter dengan CodePipeline Pipelines di AWS CloudFormationPanduan Pengguna.

catatan

Semua nama parameter harus ada dalam templat tumpukan.

TemplateConfiguration

Diperlukan: Tidak

TemplateConfiguration adalah file konfigurasi templat. Anda menyertakan file dalam artefak input untuk tindakan ini. Ini dapat berisi nilai parameter template dan kebijakan tumpukan. Untuk informasi selengkapnya tentang format file konfigurasi templat, lihat AWS CloudFormationArtefak.

Nama file konfigurasi template mengikuti format ini:

Artifactname::TemplateConfigurationFileName

Artifactname adalah nama artefak input seperti yang muncul di CodePipeline. Sebagai contoh, tahap sumber dengan nama artefak SourceArtifact dan nama file test-configuration.json membuat nama TemplateConfiguration seperti yang ditunjukkan dalam contoh ini:

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

Artefak masukan

• Jumlah artefak: 0 to 10

• Deskripsi: Sebagai masukan, AWS CloudFormation tindakan secara opsional menerima artefak untuk tujuan ini:

  • Untuk menyediakan file template stack untuk dieksekusi. (Lihat TemplatePath parameternya.)

  • Untuk menyediakan file konfigurasi template yang akan digunakan. (Lihat TemplateConfiguration parameternya.) Untuk informasi selengkapnya tentang format file konfigurasi templat, lihat AWS CloudFormationArtefak.

  • Untuk menyediakan artefak untuk fungsi Lambda yang akan digunakan sebagai bagian dari tumpukan. AWS CloudFormation

Artefak keluaran

• Jumlah artefak: 0 to 1

• Deskripsi: Jika OutputFileName parameter ditentukan, ada artefak keluaran yang dihasilkan oleh tindakan ini yang berisi file JSON dengan nama yang ditentukan. File JSON berisi isi bagian Output dari tumpukan. AWS CloudFormation

  Untuk informasi selengkapnya tentang bagian output yang dapat Anda buat untuk AWS CloudFormation tindakan Anda, lihat Keluaran.

Variabel keluaran

Ketika dikonfigurasi, tindakan ini menghasilkan variabel yang dapat direferensikan oleh konfigurasi tindakan tindakan hilir dalam pipeline. Anda mengonfigurasi tindakan dengan namespace untuk membuat variabel-variabel tersebut tersedia untuk konfigurasi tindakan hilir.

Untuk AWS CloudFormation tindakan, variabel dihasilkan dari nilai apa pun yang ditunjuk di Outputs bagian template tumpukan. Perhatikan bahwa satu-satunya mode CloudFormation tindakan yang menghasilkan output adalah mode yang menghasilkan atau memperbarui tumpukan, seperti pembuatan tumpukan, pembaruan tumpukan, dan eksekusi set perubahan. Mode tindakan terkait yang menghasilkan variabel adalah:

• CHANGE_SET_EXECUTE

• CHANGE_SET_REPLACE

• CREATE_UPDATE

• REPLACE_ON_FAILURE

Untuk informasi selengkapnya, lihat Variabel. Untuk tutorial yang menunjukkan cara membuat pipeline dengan tindakan CloudFormation penerapan dalam pipeline yang menggunakan variabel CloudFormation keluaran, lihatTutorial: Buat pipeline yang menggunakan variabel dari AWS CloudFormation tindakan penerapan.

Deklarasi tindakan

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"
        }
    ]
},

Lihat juga

Sumber daya terkait berikut dapat membantu Anda saat Anda bekerja dengan tindakan ini.

• Referensi Properti Konfigurasi - Bab referensi ini dalam Panduan AWS CloudFormation Pengguna memberikan lebih banyak deskripsi dan contoh untuk CodePipeline parameter ini.

• AWS CloudFormationReferensi API — CreateStackParameter dalam Referensi AWS CloudFormation API menjelaskan parameter tumpukan untuk AWS CloudFormation template.