既に存在するリソースをPulumiで管理してみよう

はじめに

前回は「Pulumi Kubernetes Operator」を利用したPulumi Programの継続デリバリーについて解説しました。今回は、Pulumiのリソース更新の流れをおさらいしつつ、既にクラウド環境にデプロイされているリソースについてPulumiで管理(import)する方法を紹介します。

おさらい：Pulumiの基本

既にクラウド環境などにデプロイされているリソースのPulumi管理化を実践するためには、Stack/Stateの概要やPulumiによるリソース更新の流れについて、ある程度理解しておく必要があります。Pulumiの基本的な内容となりますが、ここでPulumiのコンポーネントやリソース更新の流れについて、おさらいしておきます。

Pulumiの主要コンポーネントとState

Pulumiの主要コンポーネントの構成は下図に示すとおりです。Stackごとに現在のインフラストラクチャに関する情報がjsonで記録されていて、これを「State」と呼んでいます。

• Program → インフラストラクチャのあるべき姿を定義したもの
• Resource → インフラストラクチャを構成するオブジェクト(実際のインフラリソース)。オブジェクトのプロパティ(設定値)は他のオブジェクトに共有することが可能(図のInputs/Outputsの部分)
• Project → Programのソースコードとメタデータ(どのようにProgramを動かすかの情報)を格納するディレクトリ
• Stack → Projectディレクトリ内でProgramを「pulumi up」(Pulumi CLI)した後のインスタンス。同一のProgramから本番環境/ステージング環境など、用途に応じて複数の環境用にインスタンスを作成可能

Pulumiは、Stateからそのインフラストラクチャがいつどのように作成/削除/読み取り/更新されたかなどの情報を読み取り、「pulumi up」コマンド実行時のアクション(次はリソースを作成/更新または削除すべきかどうか)を決定します。

ちなみに、現在のStateは以下の手順で確認できます。

[前提]

• Pulumi v3.72.2
• あらかじめ「pulumi new」コマンドなどでStackが作成された状態

1. 現在アクティブなStackを確認します。

   $ pulumi stack ls
   NAME  LAST UPDATE  RESOURCE COUNT  URL
   dev   1 hour ago   5               https://app.pulumi.com/****/quickstart2/dev
   stg*  n/a          n/a             https://app.pulumi.com/****/quickstart2/stg

2. 今回は「dev」StackのStateを取得するので、「dev」Stackを選択します。選択後は再度stack lsで「dev」stackがアクティブであることを確認します。

   $ pulumi stack select dev
   
   $ pulumi stack ls
   NAME  LAST UPDATE  RESOURCE COUNT  URL
   dev*  1 hour ago   5               https://app.pulumi.com/****/quickstart2/dev
   stg   n/a          n/a             https://app.pulumi.com/****/quickstart2/stg

3. 「pulumi stack export」コマンドを実行して、現在のStackでStateを標準出力します。

   $ pulumi stack export
   {
       "version": 3,
       "deployment": {
           "manifest": {
               "time": "2023-09-26T17:36:36.814054+09:00",
               "magic": "c57d2cc6e4ddc1ad908bcf42d81d39304d5e92a1de5a6e1d5a5c485a70ff807b",
               "version": "v3.72.2"
           },
           "secrets_providers": {
               "type": "service",
               "state": {
                   "url": "https://api.pulumi.com",
                   "owner": "***",
                   "project": "quickstart2",
                   "stack": "dev"
               }
           },
           "resources": [
               {
                   "urn": "urn:pulumi:dev::quickstart2::pulumi:pulumi:Stack::quickstart2-dev",
                   "custom": false,
                   "type": "pulumi:pulumi:Stack",
                   "outputs": {
                       "bucketEndpoint": "http://storage.googleapis.com/my-bucket-b5f5f89/index.html-12e5385",
                       "bucketName": "gs://my-bucket-b5f5f89"
                   }
               },
               {
                   "urn": "urn:pulumi:dev::quickstart2::pulumi:providers:gcp::default",
                   "custom": true,
                   "id": "80738ccf-25df-4478-8b0a-f6c4c3a15dba",
                   "type": "pulumi:providers:gcp",
                   "inputs": {
                       "project": "pulumi-test",
                       "version": "6.29.0"
                   },
                   "outputs": {
                       "project": "pulumi-test",
                       "version": "6.29.0"
                   },
                   "parent": "urn:pulumi:dev::quickstart2::pulumi:pulumi:Stack::quickstart2-dev"
               },
   ~~~~~~(略)~~~~~~

また、Stateの内容はPulumi service(GUI)でも「いつどのように作成/削除/読み取り/更新されたか」が視覚的に分かりやすい形で確認できます。

1. 以下のコマンドを実行するとPulumi service画面が表示されます。実行前にログインが済んでいない場合は、ここで一度ログイン処理を実施します。

   $ pulumi console
   Manage your Pulumi stacks by logging in.
   Run `pulumi login --help` for alternative login options.
   Enter your access token from https://app.pulumi.com/account/tokens
       or hit  to log in using your browser

2. pulumi service画面の「Stacks」タブに移動し、Stateを確認したい対象ProjectのStackをクリックします。
   
3. リソース変更履歴欄右側の[Details]リンクをクリックします。
   
   一番直近のpulumi実行履歴(activity)が表示されます。
   

Pulumiリソース更新の流れ

Pulumiによるリソース更新を簡単に図で表すと、下図のようになります。

Pulumiユーザーが「pulumi up」コマンドを実行すると、Programの更新をPulumi CLIで検知します。更新を検知したPulumi CLIは「Program(あるべき状態)」と「State（現在の状態）」を比較したのち、必要なアクション(リソースの作成/更新/削除)を決定します。実際のリソース作成/更新/削除はPulumi CLIからの情報を元に、AWSやGCPなどの各サービスに対応した「Provider」で行われます。

既存リソースのPulumi管理化(state import)

既に存在しているクラウド環境のインフラストラクチャ(リソース)をPulumiで管理したい場合は、2つの方法「Programにimport option(リソースID)を付与するimport」または「Pulumiコマンドによるimport」でimport処理を実施できます。

import処理を実施すると、PulumiのStateに対して「既に存在しているリソースの情報」を記録できます。Stateに「既に存在しているリソースの情報」が記録されていない状態、かつ「Programにはリソースの情報が記載されている状態」で「Pulumi up」を実施してしまうと、同じリソースが重複して作成されてしまいますので(詳細は後述)、必ず既存リソースのimport処理を実施しておく必要があります。

【Stateがカラだとリソースが新規作成される(リソース名にランダム16進数のsuffixが付く】

【import option(リソースID)をProgramに付与してimportする流れ】

• Pulumiで管理したいリソースのリソースIDを調べる
• import option(リソースID)をProgramに記載する(管理したいリソースと同様の設定値もProgramに記載する)
• Pulumi upを実行して差分確認

【事前にimportを実施して既存リソースをPulumi管理化(Pulumiコマンドによるimport)】

【Pulumiコマンドによるimportの流れ】

• Pulumiで管理したいリソースのリソースIDを調べる
• リソースIDを引数に指定してPulumi importコマンドを実行する
• コマンド実行時に出力されたコードをProgramに記載する
• Pulumi upを実行して差分確認

【事前にimport実施して既存リソースをPulumi管理化(Programにimport option付与)】