CloudFormationをAWS CLIで操作｜deployと変更セット

CloudFormation を AWS CLI で操作するときの基本は、「aws cloudformation deploy でスタックの作成と更新を1つのコマンドにまとめ、中身を先に確かめたいときだけ変更セット（change set）を挟む」ことです。スタックとは、テンプレートから作られたリソースのまとまりのことです。

この記事では、deploy / create-stack / update-stack / create-change-set の違いを比較表にしたうえで、検証 → 作成 → 変更セットの確認 → 実行 → 削除を、コマンドと出力つきで順番に通します。あわせて、スタックの状態ごとに「次に打つコマンド」を一覧にし、よく出会う3つのエラー文への対処もまとめます。

確認環境：Ubuntu 24.04、AWS CLI 1.46.1（Python 3.11）。AWS の API をローカルで再現するツール（moto 5.2.3）で実行しました。掲載するコマンドは、接続先の指定を外して、AWS でそのまま使える形にしています。

CloudFormation CLI の早見表

4つのコマンドの違い

迷ったら deploy、差分を見てから反映したいときは deploy --no-execute-changeset か create-change-set と覚えておくと選びやすくなります。

やりたいこと別のコマンド

一連の流れを図で見る

flowchart LR
  A[validate-template<br>文法を確かめる] --> B[deploy<br>スタックを作る]
  B --> C[create-change-set<br>変更の下書き]
  C --> D[describe-change-set<br>中身を確かめる]
  D --> E[execute-change-set<br>反映する]
  E --> F[delete-stack<br>片付ける]

以降は、この順番で実際に動かしていきます。

準備：サンプルのテンプレート

SQS のキューを1つ作るテンプレートです。queue.yaml という名前で保存します。パラメータは環境名（Env）と可視性タイムアウト（Timeout）の2つです。

AWSTemplateFormatVersion: "2010-09-09"
Description: Task queue sample
Parameters:
  Env:
    Type: String
    Default: dev
  Timeout:
    Type: Number
    Default: 30
Resources:
  TaskQueue:
    Type: AWS::SQS::Queue
    Properties:
      QueueName: !Sub "task-queue-${Env}"
      VisibilityTimeout: !Ref Timeout
Outputs:
  QueueUrl:
    Value: !Ref TaskQueue

手順1：validate-template でテンプレートを検証する

スタックを作る前に、テンプレートが読み取れる形になっているかを確かめます。--query Description を付けると、説明文だけが返るので、通ったことがひと目で分かります。

aws cloudformation validate-template --template-body file://queue.yaml --query Description

"Task queue sample"

ローカルのファイルを渡すときは file:// を付けます。付け忘れると、ファイル名そのものがテンプレートの中身として送られます。

validate-template が確かめるのは、テンプレートの書式です。リソースのプロパティの値が受け付けられるかどうかは、実際に作成するときに決まります。

手順2：deploy でスタックを作成する

aws cloudformation deploy \
  --template-file queue.yaml \
  --stack-name task-stack \
  --parameter-overrides Env=dev \
  --tags Team=platform

Waiting for changeset to be created..
Waiting for stack create/update to complete
Successfully created/updated stack - task-stack

出力から分かるとおり、deploy は内部で変更セットを作り、それを実行し、完了まで待ちます。スタックが無ければ作成、有れば更新になるので、同じコマンドを何度でも使えます。

deploy でよく使うオプション

作成された内容を確かめる

aws cloudformation describe-stacks --stack-name task-stack \
  --query "Stacks[0].{Status:StackStatus,Params:Parameters,Tags:Tags}"

{
    "Status": "CREATE_COMPLETE",
    "Params": [
        {
            "ParameterKey": "Env",
            "ParameterValue": "dev"
        },
        {
            "ParameterKey": "Timeout",
            "ParameterValue": "30"
        }
    ],
    "Tags": [
        {
            "Key": "Team",
            "Value": "platform"
        }
    ]
}

スタックに含まれるリソースは list-stack-resources で一覧にできます。

aws cloudformation list-stack-resources --stack-name task-stack --output text \
  --query "StackResourceSummaries[].[LogicalResourceId,ResourceType,PhysicalResourceId,ResourceStatus]"

TaskQueue   AWS::SQS::Queue https://sqs.ap-northeast-1.amazonaws.com/123456789012/task-queue-dev    CREATE_COMPLETE

手順3：変更セットを作って中身を確かめる

変更セットは、「この内容で更新すると、どのリソースがどう変わるか」をまとめた下書きです。作っただけではリソースは変わりません。ここでは Timeout を 30 から 60 に変える下書きを作ります。

aws cloudformation create-change-set \
  --stack-name task-stack \
  --change-set-name timeout-60 \
  --change-set-type UPDATE \
  --template-body file://queue.yaml \
  --parameters ParameterKey=Env,ParameterValue=dev ParameterKey=Timeout,ParameterValue=60

{
    "Id": "arn:aws:cloudformation:ap-northeast-1:123456789012:changeSet/timeout-60/c491a6bd-b096-4a6c-8174-ff7c64a07d46",
    "StackId": "arn:aws:cloudformation:ap-northeast-1:123456789012:stack/task-stack/6c7c592c-11f3-4bf5-ac27-de54e3f83120"
}

--change-set-type は CREATE（新規作成用）、UPDATE（更新用）、IMPORT（既存リソースの取り込み用）から選びます。

変更セットの作成は少し時間がかかるので、wait で待ってから中身を見ます。

aws cloudformation wait change-set-create-complete \
  --stack-name task-stack --change-set-name timeout-60

aws cloudformation describe-change-set \
  --stack-name task-stack --change-set-name timeout-60 \
  --query "{Status:Status,ExecutionStatus:ExecutionStatus,Parameters:Parameters}"

{
    "Status": "CREATE_COMPLETE",
    "ExecutionStatus": "AVAILABLE",
    "Parameters": [
        {
            "ParameterKey": "Env",
            "ParameterValue": "dev"
        },
        {
            "ParameterKey": "Timeout",
            "ParameterValue": "60"
        }
    ]
}

Status が CREATE_COMPLETE、ExecutionStatus が AVAILABLE になっていれば実行できます。

Changes の読み方

describe-change-set の出力には Changes という配列があり、リソースごとの変更が入ります。AWS CLI のリファレンスに載っている例は次の形です。

{
    "Type": "Resource",
    "ResourceChange": {
        "Action": "Modify",
        "LogicalResourceId": "function",
        "PhysicalResourceId": "my-function-SEZV4XMPL4S5",
        "ResourceType": "AWS::Lambda::Function",
        "Replacement": "False",
        "Scope": [
            "Properties"
        ],
        "Details": [
            {
                "Target": {
                    "Attribute": "Properties",
                    "Name": "Timeout",
                    "RequiresRecreation": "Never"
                },
                "Evaluation": "Static",
                "ChangeSource": "DirectModification"
            }
        ]
    }
}

実行前に必ず見たいのは Action が Remove の行と、Replacement が True の行です。どちらも既存のリソースが無くなる変更なので、データを持つリソースでは特に確認します。この2つだけを抜き出す式は次のとおりです。

aws cloudformation describe-change-set \
  --stack-name task-stack --change-set-name timeout-60 \
  --query "Changes[?ResourceChange.Action=='Remove' || ResourceChange.Replacement=='True'].ResourceChange.[Action,LogicalResourceId,ResourceType,Replacement]" \
  --output text

Status と ExecutionStatus の値

手順4：execute-change-set で反映する

aws cloudformation execute-change-set \
  --stack-name task-stack --change-set-name timeout-60

aws cloudformation wait stack-update-complete --stack-name task-stack

どちらも、うまくいくと何も表示せずに終わります。状態とパラメータを1行で確かめます。

aws cloudformation describe-stacks --stack-name task-stack --output text \
  --query "Stacks[0].[StackStatus,Parameters[?ParameterKey=='Timeout'].ParameterValue|[0]]"

UPDATE_COMPLETE 60

キューの設定も変わっています。

aws sqs get-queue-attributes \
  --queue-url https://sqs.ap-northeast-1.amazonaws.com/123456789012/task-queue-dev \
  --attribute-names VisibilityTimeout

{
    "Attributes": {
        "VisibilityTimeout": "60"
    }
}

deploy で変更セットだけを作る

deploy に --no-execute-changeset を付けると、変更セットを作ったところで止まり、確認用のコマンドを表示してくれます。次の出力は、新しいスタック名に対して実行したときのものです。

aws cloudformation deploy --template-file queue.yaml --stack-name task-stack --no-execute-changeset

Waiting for changeset to be created..
Changeset created successfully. Run the following command to review changes:
aws cloudformation describe-change-set --change-set-name arn:aws:cloudformation:ap-northeast-1:123456789012:changeSet/awscli-cloudformation-package-deploy-1791180361/c0a7dce9-0ffa-45ec-96f5-bde445fe16e2

表示された describe-change-set で中身を確かめ、同じ ARN を execute-change-set --change-set-name に渡せば反映できます。新しいスタックに対してこの形で止めると、スタックは REVIEW_IN_PROGRESS という状態で残ります。使わないと決めたら delete-stack で片付けます。

update-stack で更新する場合

変更セットを挟まずに、すぐ更新する方法です。テンプレートを変えないときは --use-previous-template、値を変えないパラメータには UsePreviousValue=true が使えます。

aws cloudformation update-stack \
  --stack-name task-stack \
  --use-previous-template \
  --parameters ParameterKey=Env,UsePreviousValue=true ParameterKey=Timeout,ParameterValue=45

{
    "StackId": "arn:aws:cloudformation:ap-northeast-1:123456789012:stack/task-stack/6c7c592c-11f3-4bf5-ac27-de54e3f83120"
}

update-stack は StackId を返してすぐ戻るので、完了は wait で待ちます。

aws cloudformation wait stack-update-complete --stack-name task-stack
aws cloudformation describe-stacks --stack-name task-stack --output text \
  --query "Stacks[0].[StackStatus,Parameters[?ParameterKey=='Timeout'].ParameterValue|[0]]"

UPDATE_COMPLETE 45

create-stack で作成する場合

create-stack は、同じ名前のスタックがすでに有るとエラーになります。「新規作成のつもりが既存のスタックを更新していた」という取り違えを避けたいときに向いています。

aws cloudformation create-stack \
  --stack-name task-stack-stg \
  --template-body file://queue.yaml \
  --parameters ParameterKey=Env,ParameterValue=stg

aws cloudformation wait stack-create-complete --stack-name task-stack-stg

{
    "StackId": "arn:aws:cloudformation:ap-northeast-1:123456789012:stack/task-stack-stg/ce2e4ca9-3c76-4d1a-ad8c-47c09d57dbda"
}

テンプレートの Outputs に書いた値は、describe-stacks で取り出せます。

aws cloudformation describe-stacks --stack-name task-stack-stg --query "Stacks[0].Outputs"

[
    {
        "OutputKey": "QueueUrl",
        "OutputValue": "https://sqs.ap-northeast-1.amazonaws.com/123456789012/task-queue-stg"
    }
]

スタックの一覧は list-stacks です。--stack-status-filter で状態を絞れます。

aws cloudformation list-stacks \
  --stack-status-filter CREATE_COMPLETE UPDATE_COMPLETE \
  --query "StackSummaries[].[StackName,StackStatus]" --output text

task-stack  UPDATE_COMPLETE
task-stack-stg  CREATE_COMPLETE

手順5：delete-stack で削除する

aws cloudformation delete-stack --stack-name task-stack
aws cloudformation wait stack-delete-complete --stack-name task-stack

どちらも出力はありません。削除が終わると、スタック名での describe-stacks は次のエラーを返します。これは削除できたことの確認になります。

aws cloudformation describe-stacks --stack-name task-stack

An error occurred (ValidationError) when calling the DescribeStacks operation: Stack with id task-stack does not exist

削除済みのスタックは、list-stacks に状態を指定すると見られます。

aws cloudformation list-stacks --stack-status-filter DELETE_COMPLETE \
  --query "StackSummaries[].[StackName,StackStatus]" --output text

task-stack  DELETE_COMPLETE
task-stack-stg  DELETE_COMPLETE

delete-stack は確認を求めずに受け付けられます。打つ前に、スタック名と、接続先のアカウント・リージョンを見直す習慣を付けておくと安心です。

スタック状態の一覧と「次に打つコマンド」

状態名は、AWS CloudFormation ユーザーガイドの状態コード一覧に沿っています。

作成まわり

更新まわり

削除・取り込みまわり

名前に ROLLBACK が付く状態のうち、スタックをそのまま使えるのは UPDATE_ROLLBACK_COMPLETE だけです。ROLLBACK_COMPLETE（先頭に UPDATE が付かないほう）は、最初の作成が通らなかったことを表すので、削除して作り直します。

describe-stack-events から理由だけを抜く1行

スタックの出来事は describe-stack-events に時刻の新しい順で並びます。うまくいかなかった理由は、ResourceStatus が _FAILED で終わる行の ResourceStatusReason に入っています。そこで、その行だけを --query で抜きます。

aws cloudformation describe-stack-events --stack-name task-stack \
  --query "StackEvents[?ends_with(ResourceStatus,'_FAILED')].[LogicalResourceId,ResourceStatus,ResourceStatusReason]" \
  --output text

式の働きが分かるように、説明用に用意したイベントのデータ（events.json）に同じ式を当ててみます。キューは作れたものの、ロールの作成で止まり、取り消された、という並びです。

{"StackEvents":[
 {"Timestamp":"2026-10-05T06:10:09Z","LogicalResourceId":"task-stack","ResourceStatus":"ROLLBACK_COMPLETE"},
 {"Timestamp":"2026-10-05T06:10:07Z","LogicalResourceId":"TaskQueue","ResourceStatus":"DELETE_COMPLETE"},
 {"Timestamp":"2026-10-05T06:10:05Z","LogicalResourceId":"task-stack","ResourceStatus":"ROLLBACK_IN_PROGRESS","ResourceStatusReason":"The following resource(s) failed to create: [AppRole]."},
 {"Timestamp":"2026-10-05T06:10:04Z","LogicalResourceId":"AppRole","ResourceStatus":"CREATE_FAILED","ResourceStatusReason":"(sample) role name app-role is already in use"},
 {"Timestamp":"2026-10-05T06:10:03Z","LogicalResourceId":"TaskQueue","ResourceStatus":"CREATE_COMPLETE"},
 {"Timestamp":"2026-10-05T06:10:01Z","LogicalResourceId":"task-stack","ResourceStatus":"CREATE_IN_PROGRESS","ResourceStatusReason":"User Initiated"}
]}

AWS CLI の --query と同じ JMESPath ライブラリで評価します。

import json, jmespath

events = json.load(open("events.json"))
expr = "StackEvents[?ends_with(ResourceStatus,'_FAILED')].[LogicalResourceId,ResourceStatus,ResourceStatusReason]"
for row in jmespath.search(expr, events):
    print("\t".join(row))

AppRole CREATE_FAILED   (sample) role name app-role is already in use

6行のうち、原因の1行だけが残りました。複数のリソースが止まったときは、いちばん下（最初に起きたもの）が出発点であることが多いので、最後の1件だけを取る形も便利です。

aws cloudformation describe-stack-events --stack-name task-stack --output text \
  --query "StackEvents[?ends_with(ResourceStatus,'_FAILED')] | [-1].ResourceStatusReason"

エラー文ごとの対処

No updates are to be performed

テンプレートにもパラメータにも、いまのスタックとの違いが無いときに出ます。直すところがあるわけではなく、「反映するものが無い」という知らせです。

deploy の場合、変更が無いと「No changes to deploy. Stack スタック名 is up to date」と表示されます。このときの終了コードは CLI の版で既定が異なります。

v1 の既定は、インストールされている AWS CLI 1.46.1 のヘルプ文（By default, a non-zero exit code is returned）で、v2 の既定は AWS CLI コマンドリファレンスの deploy のページで確かめました。どちらの版でも同じ動きにしたいときは、オプションを明示しておくと揃います。

更新として扱われない変更もあります。CloudFormation のトラブルシューティングのページによると、削除ポリシー、更新ポリシー、条件の宣言、出力の宣言だけを変えた場合は更新と見なされないことがあります。そのような変更だけを反映したいときは、いずれかのリソースのメタデータ属性を追加または変更します。

Requires capabilities

テンプレートに IAM のリソース（ロール、ポリシー、ユーザーなど）が含まれているのに、--capabilities を付けていないときに出ます。権限に関わるリソースを作ることを、利用者が分かったうえで実行していると示すための確認です。

エラー文の角かっこの中に、必要な値がそのまま書かれているので、それを付けて打ち直します。

aws cloudformation deploy \
  --template-file role.yaml \
  --stack-name role-stack \
  --capabilities CAPABILITY_NAMED_IAM

create-stack、update-stack、create-change-set でも同じオプションが使えます。独自の名前を付けた IAM リソースは、アカウントの中で名前が重ならないようにする必要があるため、同じテンプレートから複数のスタックを作るときは、名前にパラメータを含めるか、名前を自動に任せます。

ROLLBACK_COMPLETE state and can not be updated

最初の作成が通らなかったスタックに、もう一度 deploy や update-stack をしたときに出ます。ROLLBACK_COMPLETE のスタックは、作りかけのリソースを片付け終えた「抜け殻」のような状態で、ユーザーガイドにも「この状態で行える操作は削除だけ」と書かれています。

対処は3ステップです。

# 1. 理由を控える（削除の前に）
aws cloudformation describe-stack-events --stack-name task-stack --output text \
  --query "StackEvents[?ends_with(ResourceStatus,'_FAILED')].[LogicalResourceId,ResourceStatusReason]"

# 2. スタックを削除して、終わるまで待つ
aws cloudformation delete-stack --stack-name task-stack
aws cloudformation wait stack-delete-complete --stack-name task-stack

# 3. テンプレートやパラメータを直して、もう一度作成する
aws cloudformation deploy --template-file queue.yaml --stack-name task-stack

2 の削除と待機は、この記事の手順5 で出力を確かめたものと同じコマンドです。

CI で繰り返し反映する場合は、deploy の前に状態を調べ、ROLLBACK_COMPLETE のときだけ削除するようにしておくと、手で片付ける手間が減ります。

status=$(aws cloudformation describe-stacks --stack-name task-stack \
  --query "Stacks[0].StackStatus" --output text 2>/dev/null)
if [ "$status" = "ROLLBACK_COMPLETE" ]; then
  aws cloudformation delete-stack --stack-name task-stack
  aws cloudformation wait stack-delete-complete --stack-name task-stack
fi

なお、更新が通らなかったときの UPDATE_ROLLBACK_COMPLETE は別物で、こちらは更新前の内容に戻っているため、削除せずにそのまま deploy し直せます。

つまずきやすい点のチェックリスト

よくある質問

Q. deploy と create-stack は、どちらを使えばよいですか？ A. 日常の反映には deploy が向いています。作成と更新を同じコマンドで行え、完了まで待ってくれるためです。「必ず新規作成であること」を保証したいときは create-stack、差分を見てから反映したいときは変更セットを使います。

Q. 変更セットを作ると、リソースに影響しますか？ A. 変更セットを作っただけでは、リソースは変わりません。execute-change-set を打ったときに初めて反映されます。使わない変更セットは aws cloudformation delete-change-set で片付けられます。

Q. deploy のパラメータを毎回すべて書く必要はありますか？ A. 更新のときは、書かなかったパラメータはいまの値を引き継ぎます。新しく作るときは、Default の無いパラメータを必ず指定します。

Q. ROLLBACK_COMPLETE と UPDATE_ROLLBACK_COMPLETE の違いは何ですか？ A. ROLLBACK_COMPLETE は最初の作成が通らなかった状態で、削除して作り直します。UPDATE_ROLLBACK_COMPLETE は更新が通らず更新前に戻った状態で、スタックはそのまま使え、直してからもう一度更新できます。

まとめ

• 日常の反映は deploy。作成と更新を1つのコマンドで行い、完了まで待つ
• 差分を先に見たいときは変更セット。create-change-set → describe-change-set → execute-change-set の順
• 変更セットでは Action が Remove、Replacement が True の行を必ず確かめる
• create-stack / update-stack は StackId を返してすぐ戻るので、wait を組み合わせる
• うまくいかなかった理由は describe-stack-events の _FAILED の行を --query で抜く
• ROLLBACK_COMPLETE は削除して作り直す。UPDATE_ROLLBACK_COMPLETE はそのまま更新し直せる
• UPDATE_ROLLBACK_FAILED は continue-update-rollback、DELETE_FAILED は --retain-resources を使う

参考・出典

• AWS CLI Command Reference「cloudformation deploy」「cloudformation describe-change-set」（docs.aws.amazon.com/cli/latest/reference/cloudformation/）
• AWS CloudFormation ユーザーガイド「スタックのイベントと状態コード（view-stack-events）」「トラブルシューティング」「更新のロールバックを続行する」「プロビジョニング済みリソースを残すオプション（stack-failure-options）」「IAM によるアクセス制御（control-access-with-iam）」
• AWS CloudFormation API リファレンス「Stack」

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。