この記事では、PipeCDの「Plan Preview」という機能の概要および処理の流れについて説明します。
処理フローがわかることで、トラブルシューティング時やPipeCDの開発時に役立つと思います。
結論
- Plan Previewとは、「マージ+デプロイによってどんな変化が起きるか」をブランチマージ前に確認するための機能。
- 処理フローとしては、pipectlがトリガーして、Control Planeが仲介して、Pipedがコミット間の設定比較を行っている。
Plan Previewとは
下記画像のように、コミット間でマニフェストの差分を比較する機能です。
主な用途は、マージ先ブランチとPRのブランチとで比較して、「どんな変更が起こるのか」レビュー時に確認しやすくすることです。
単純なファイル同士のdiffとは異なり、コメント追加などの非本質的な差分を無視できたり、Kubernetesの場合にはHelmで関連するマニフェストの差分まで出力できたりします。
Plan Previewは現在、Kubernetes, CloudRun, Terraform, ECSでサポートされています。
使い方
Plan Previewを使うには以下の2通りの方法があります。
a. pipectlから呼び出す
b. GitHub Actionsでpipe-cd/actions-plan-previewを使う
GitHub上でレビューフローにPlan Previewを組み込む場合、b. の方が簡単です。
a. pipectlを使う
pipectlとは、PipeCDのCLIツールです。 cf.Docs
pipectlの下記コマンドによって、Plan Previewの実行が可能です。
pipectl plan-preview \
--address={ PIPECD_CONTROL_PLANE_ADDRESS } \
--api-key={ PIPECD_API_KEY (READ_WRITEの権限が必要) } \
--repo-remote-url={ REPO_REMOTE_GIT_SSH_URL } \
--head-branch={ HEAD_BRANCH } \
--head-commit={ HEAD_COMMIT (例: patch-xxx) } \
--base-branch={ BASE_BRANCH (例: main) }
実行結果イメージ(ECSの例):
Requested plan-preview, waiting for its results (commands: [20199604-f608-4b24-8360-a58026d13ed0])
Waiting for result of command 20199604-f608-4b24-8360-a58026d13ed0 from piped a605f2ff-95af-4298-8c58-9d2fd8d69ebb
waiting...
Waiting for result of command 20199604-f608-4b24-8360-a58026d13ed0 from piped a605f2ff-95af-4298-8c58-9d2fd8d69ebb
waiting...
Waiting for result of command 20199604-f608-4b24-8360-a58026d13ed0 from piped a605f2ff-95af-4298-8c58-9d2fd8d69ebb
waiting...
Here are plan-preview for 1 application:
1. app: ecs-plan-preview, kind: ECS
sync strategy: QUICK_SYNC
summary: 2 changes were detected
details:
---DETAILS_BEGIN---
--- Last Deploy
+++ Head Commit
# 1. ServiceDefinition
@@ -10,7 +10,7 @@
DeploymentController:
Type: EXTERNAL
Deployments: null
-DesiredCount: 2
+DesiredCount: 11
EnableECSManagedTags: true
EnableExecuteCommand: false
Events: null
# 2. TaskDefinition
@@ -17,7 +17,7 @@
FirelensConfiguration: null
HealthCheck: null
Hostname: null
- Image: xxx.dkr.ecr.ap-northeast-1.amazonaws.com/nginx:1
+ Image: xxx.dkr.ecr.ap-northeast-1.amazonaws.com/nginx:11
Interactive: null
Links: null
LinuxParameters: null
---DETAILS_END---
複数のapplicationに変更がある場合も対応しています。
b. GitHub Actionsでアクションを使う
pipe-cd/actions-plan-previewというアクションがPipeCD公式から提供されているので、それを使います。
このアクションを使うと、PR作成時に自動でPlan Previewを呼び出し、結果をコメントさせることが可能です。
使い方の詳細はREADME.mdを参照してください。
ちなみに、このアクションは内部的には pipectl のコマンドを呼び出しています。コード
処理フロー
Control PlaneはPull型の処理が基本であるため、フローが少しわかりにくくなっています。
- pipectlから、Plan Previewをリクエストします
- PipedがPlan Previewのリクエストを検知し、Plan Preview処理をトリガーします
- PipedはControl Planeを継続的に監視しています
- Gitリポジトリから、2コミットのマニフェストを取得します
- キャッシュも使われているため、毎回リモートから取得するわけではないです
- 対象のコミットは自由に指定可能です。よく使うのは、「mainの最新コミット」と「PRの最新コミット」です
- 取得したマニフェスト同士で比較します
- 比較処理はPlatform種毎に異なります
- 例）ECS: 各YAMLを struct に落とし込んで比較
- 例）Terraform:
terraform planコマンドを使用
- 比較処理はPlatform種毎に異なります
- PipedからControl Planeに結果を送信します
- 結果はControl Plane内のDBに格納されます
- pipectlがControl Planeから結果を取得します
- pipectlは 1. のリクエスト送信後、Control Planeに対して結果取得APIを呼び続けています
cf. 主な関連コード
- Piped:
- pipectl: /pkg/app/pipectl/cmd/planpreview/planpreview.go#L87-L153
補足: Drift Detectionとの関連性
Plan Previewは、デプロイ済の実際のリソースは見ません。
「実リソース」と「mainブランチ」の差分を検知・解消するための機構が Drift Detection です。
Drift Detectionの中でも比較処理を行いますが、基本的にPlan Previewのと同じ処理が使われています。（実際のリソース状態を取得するために Live State という別機構があります）
Drift Detection, Live Stateについてはまた別の記事で解説予定です。
Discussion