tech.guitarrapc.cóm

Technical updates

Infrastructure as Code に最低限求めること

Infrastructure as Code (以降 IaC) で組むときに IaC ツールを選ぶ基準はいろいろあります。 IaCの言語がチームとって扱いやすいか、クラウドやサービスへのIaCの対応状況は早い/十分か、コミュニティの大きさは十分でググれば情報を入手できるか、実装がオープンソースで公開されているか、利用事例が欲しいか、など様々な理由で選ぶことでしょう。

しかし、こういった基準よりまず 「IaC というからには最低限出来ていないと困ること」というのが個人的にあります。

最近、Bicep で組んでいた Azure の環境を Pulumi に移行したのですが、その理由は Bicep では IaC が維持できないと判断したためでした。 IaC ツールを使っていて IaC が維持できないと判断したのは初めてだったので、いい機会ですし IaC に最低限求めることを言語化しようと思います。

tl;dr;

私はIaC に、コードとリソース1 状態の一致保障、実行プランが出力できること、ステート2 を持てることを求めます。 これらが不完全なIaCでは、コードでのリソース管理は不完全なものになり、今回のように維持できない原因になるため避けます。

  • コードとリソース状態の一致を保障できることを求めます。一致が保障できることで、コードからリソースの状態を完全に制御できます。(コードファースト)

コードとリソースの状態が一致

  • 実行前に実行プランを出力できることを求めます。実行プランによりコードの変更適用前にリソースへの影響がわかるため、PRベースでレビューをうけつつ開発ができます。また、正確な実行プランには、ステートかそれに準じたものと継続した開発体制が必要になるでしょう。

実行プランによるコード変更によるリソース差分の確認

  • ステートをIaCサービスやオブジェクトストレージに配置し、ステート実行時にロックできることを求めます。ステートをローカル以外に持ち、実行ごとにロックがかかることで、チーム開発でブランチを同時に複数稼働させることができます。

ステートファイルは実行ごとにロック

IaC でやりたいこと

IaC でやりたいことは「コードでクラウドリソースを管理できる」 これだけです。しかし、コードでクラウドリソースを管理できるとはどういうことでしょうか?

私は、コードで定義を書いたらリソースが追加されてほしいし、コードの定義を変更したらリソースが変更されてほしいし、コードの定義を消したらリソースが削除されてほしいです。 コードの定義 = リソースの状態と一致するとコードでクラウドリソースが管理でき、クラウドコンソールで操作する機会を大きく減らすことができます。3

コードでリソースを管理するためにはチームでスムーズに開発を行いたいです。 チーム各自でブランチを切って並行してコードを修正、修正ごとに実行プランで差分を確認し、レビューを受け、問題ないならマージしたいでしょう。 ステートをリモートに置いたり、実行ごとにロックされるとチーム開発で扱いやすくなります。

レビューの漏れに対応するためには、コードで誤って消されてもリソースの削除をブロックする機能も必要になるでしょう。 コードをリソースに適用した後に、クラウド側でリソースに変更がかかったりすることがあるのを考慮すると、リソースの変更差分を無視する機能も必要になるでしょう。

IaC に最低限求めること

IaC でやりたいことから、IaC に最低限求めることがわかります。

  • コード = リソース状態になることを期待します。
    • コードを追加したときに、リソースでも追加されることを期待します。
    • コードを変更したときに、リソースでも変更されることを期待します。
    • コードを削除したときに、リソースは削除されることを期待します。
    • コードで誤って削除がかかる変更を記述したときに、リソースの削除をブロックする記述ができることを期待します。(protection)
    • コードの適用時に、リソースで起こった変更を無視したりコードの変更を無視する記述ができることを期待します。(ignore)
  • コードの適用前に、実行プランを表示して実リソースとの差分を正確に示せることを期待します。
    • 実行プランは、「現在のリソース状態とコードの差分」を示せることを期待します。(ステートとの差分では実リソースとずれることが多くある)
  • ステートは、オブジェクトストレージやIaCのサービスで保持できることを期待します。
    • 実行ごとに透過的にロックがかかるとよいでしょう。

IaC でコードとリソースの状態一致が保証できないとどうなるのか

やりたいことや求めることは分かりましたが、それは本当に必要なのでしょうか? IaC でコードとリソースの一致を保証できないと何が起こるのかを考えてみましょう。

題材は、冒頭にあげたAzure の Bicep です。

ARM Template と Bicep について軽く説明しましょう。ARM TemplateBicep は、Azureにおいて IaC の位置づけにあります。Bicep は ARM Template のための DSL という位置づけでビルドすると ARM Template (JSON定義) を出力します。

Bicep でコードを記述し、Azure にデプロイしたときに次の挙動をします。

  1. Bicepコードをビルドして ARM Template を出力
  2. Azure に ARM Template をデプロイ
  3. Azure は ARM Template に基づいてリソースの作成、既存のリソースがある場合は変更を実施
  4. Azure へデプロイを Complete モードで実施した場合は、Azure のリソースが削除対象か見て削除対象ならリソースを削除、削除対象じゃない場合は ARM Template からは消すがリソースは維持

一連の流れの中で特徴的なのが、Step3 と Step4 です。

ステートを持たない

Step3 は、Bicep/ARM Template がステートを持たない IaC であり、展開されたARM Template に基づいてリソースを更新することを示します。 このためか、Bicep でコードとリソースの実行プランには6つのステータスがあります。4 ステータスで注目すべきは デプロイ という適用まで挙動が不定なケースが含まれていることです。

  • デプロイ: リソースは存在し、Bicep ファイル内で定義されています。 リソースは再デプロイされます。 リソースのプロパティは、変更される場合と変更されない場合があります。 いずれかのプロパティが変更されるかどうか判断するのに十分な情報がない場合、操作ではこの変更の種類が返されます。 この状況は、ResultFormat が ResourceIdOnly に設定されている場合にのみ表示されます。

ARM Template は、ステートではなく変更する予定の定義になります。定義と実リソースでも差分が取得できるか不明というのは、実行プランが信用できないということであり残念な体験に思います。

コードとリソースは一致が保証されていない

Step4 は、Bicep/ARM Template は、その定義を消してもリソースが削除される保証はないことを示します。 これは 削除のステータス説明にも明記されています。

  • 削除: この変更の種類は、JSON テンプレートのデプロイに完全モードを使用する場合にのみ適用されます。 リソースは存在しますが、Bicep ファイル内では定義されていません。 完全モードでは、リソースが削除されます。 この変更の種類には、完全モードの削除をサポートしているリソースのみが含まれます。

BicepのデプロイにはIncrement と Complete の2モードがあります。 Increment は増分デプロイで、Bicep コードから定義を消してもリソースは残ります。 Complete は 完全デプロイで、ARM Template とリソースの同期のため変更や削除をします。コードとリソースの一致を考えると Complete モード一択ですが、コードを削除してもリソースが消えるかはリソース次第です。

Bicep でIaC を行おうとしてもコードとリソースの一致保障がなく、コードとリソースの乖離が進みます。 コードを見てもリソースの状態は保証できないため、今の状態、適用した後の状態を正確に把握するには Azure ポータルやCLIで状態を取得するしかありません。IaC とは?

残念ながら、Bicep や ARM Template は IaC に最低限求めることができず、継続的に IaC をすることはできないと判断しPulumi に移行したのでした。 Pulumi に移行したのは、Azure のネイティブ実装がありAzure の新規API公開から最速1日で対応するなどの高速な対応と Terraform に比べた時のAzure API の網羅性からです。

まとめ

リソースを作る、変更する、削除するをすべてコードで行うには、TerraformPulumiCDK などを採用します。いずれも、現在のリソースの状態とコードの差分を常に管理でき、正確な実行プランを持ち、ステートを安全に維持できます。

リソースを作ることに注力し、変更や削除はコンソールでいいという場合、ARM TemplateBicep が候補に入ります。しかし、作りっぱなしでメンテナンスされなくなるコードは、限定的なシーンでしか活用できない上に負債返却の機会を失うため、採用には慎重です。(再現環境を作ったりするのにはいいんですけどね!)

IaC を選ぶ前に、それが自分の期待する IaC かは考えたいと思う日々でした。

おまけ

書こう書こうと思って、ずっと書いていなかったので、IaC を使うにあたっての注意をいくつかおまけにどうぞ。

IaC やクラウドによる挙動の違い

IaC実行時の挙動は、IaCの実装やクラウド側のAPIにより異なります。同じIaC でもクラウドによって挙動が変わることがあるのは、マルチクラウドをしたことがある人なら経験があるのではないでしょうか。

  • リソースの設定がコード上でリソースのインラインで設定するのではなく別リソース定義を作る場合、コード削除時のリソース状態は IaC によって変わります。コード未設定時の値戻らず、設定されたときの状態が残るケースが散見されます。この場合、コードとリソースが不一致になるため使いにくいと感じるでしょう。
  • 連続でIaC を実行すると、前回の実行が残っていて後から実行してね、と言われれる IaC とクラウドの組み合わせがあったりします。

IaC とコンソールやCLIの違い

クラウドコンソールや CLI でリソースを作ると、クラウド側で設定していないことまで設定してくれます。

一方で、IaC はコードで設定したことしか設定しない (デフォルト値はある) ということ多いです。

これにより、IaC で作ったときはコンソールやCLI より手間がかかるという面もありますが、コードとリソースの状態が一致する要素になっていると感じます。

IaC 実行はローカルかリモートか

IaC を実行したときに、ローカル実行されるか、IaCのサービスでリモート実行されるかは、 IaC や連携方法によって変わります。 例えば Terraform は Terraform Cloud を使うとリモート実行することもできますし、Terraform Cloud には ステートだけ保持してローカル実行をすることもできます。


  1. リソース = クラウド環境における設定対象とします。

  2. ステート = 前回IaCを適用した状態とします。

  3. クラウドによる面があるのは同意するところです。AWS や GCP の場合ほぼコンソール操作がほぼなくなりますが、Azure では何かとポータルを使う機会があります。

  4. 6つもある理由は不明ですが、ステートがないことに由来すると考えています。多くの IaC のステータスは 4つ (create、update、delete、ignore) なのを考えると多いですね。

静音マウスと M650 SIGNATUREワイヤレスマウス

MxAnywhere3 は素敵なマウスですが、最近出た M650 SIGNATURE マウス (以降 m650) もいい静音マウスです。

2年前に静音マウスを試したときは「クリック感が鈍く、静音という割に音がする」と思ってやめていましたが、m650 はMxAnywhere3 に比べて違和感がすくないという風の噂を聞いて試してみました。

購入してから3か月使ってみて、いい感じだと思ったので記事に起こしておきます。

tl;dr;

左右のクリックは音が全くしないので静音最高です。が、ミドルクリックとサイドボタンは静かながら音はします。

いくつか使うにあたって気を付けたいと思ったことがあります。

  • MxAnywhere3 を使っていたなら m650 は サイズ M にしましょう。L は大きすぎてつらい。
  • 電池が入っている分、前が軽く中~後に重心があるので、軽く浮かした時のバランスは微妙です。(前だけ上がる感じ)
  • ラバーグリップは MxAnywhere よりも硬質でざらざらします。
  • Unifying ではなく Logi Bolt なので、接続の仕方が微妙に違います。時にUSB切り替えしている場合、PCごとにペアリングが必要です。(Unifying のようなレシーバーとのペアリングではない)

この静かさになれたら、MxAnywhere3 には戻れなくなりました。 そして、静音 Realforce R3 は圧倒的にマウスに比べてうるさいので、もっと静音してほしい。

tech.guitarrapc.com

MxAnywhere3 に残された課題

MxAnywhere3 を買ってからずっと使っています。

tech.guitarrapc.com

個人的には今までで最高のマウスですが、最後の課題が音です。

MxAnywhere3 は静音マウスではないので、静かな室内でクリック音がカチカチ鳴りうるさいと感じることがあります。これが静音化されればいいのに。 では実際 Logicool の静音マウスでどれぐらい期待できるのかを確認するため m650 を試しています。

m650 と MxAnywhere3の比較

m650 は 2022年2月3日発売のマウスです。

www.logicool.co.jp

価格レンジが違うものの、m650 は発売されてすぐで4290円、MxAnywhere 3 は10000円前後とお手頃になっています。

マウスの比較

引用: https://www.logicool.co.jp/ja-jp/products/mice/m650-signature-wireless-mouse.html

サイズ

サイズが2通り(LとM) があります。MxAnywhere3 を使っているなら M 一択です。

気づかずL を買ったのですが、大きすぎて失敗しました。

グリップ

m650はラバーグリップです。 MxAnywhere 3のような シリコンじゃないのかと気になりますが、触った感じはべたべたしなさそうなのでスルーしています。

価格がお求めやすいのもあり、ダメになったら買い替えてもいいでしょう。

電池

充電式ではなく、単三電池1つで24か月持ちます。 電池はマウスが重くなる、予備電池が必要なので好みではないのですが長寿命なので気にしないことにしています。

MxAnyehre は数か月に一度気が付いたときに充電していたので、頻度的には m650 のほうが少なくなります。

静音

SilentTouch を採用しているとのことで、M170と比べるとM650のクリック音は90%軽減と聞きますが買うまでは眉唾でした。

実際に購入してみると、クリック音がほぼ聞こえないので確かに静音です。 1m 離れると聞こえないので、ほかの人に聞こえることはまずないと思います。

クリック感は普通のマウス同様にあるので違和感もありません。

MacBook のトラックパッドかな? とはじめ思ったぐらいには静かですごい。

ホイール

SmartWheel になっているので、MxAnywhere 3 の高速スクロール時のフリースピンはありません。 ページを一気に移動するときに若干不便ですが、勢いよくスクロールするとある程度一気に移動してくれるので妥協できる良さはあります。

水平スクロールはMxAnywhere 3と同じサイドボタンを押しながらスクロールなので便利。

接続

MxAnywhere 3 はUnifying でしたが、m650 は Logi Bolt に変わりました。 Logi Bolt は各PC でペアリングが必要なのは面倒ですが、安定して接続できており今のところ一切不便はありません。

Bluetooth も可能ですが、マウスのBT接続は PCが高負荷時に困るのはあるあるなので Logi Bolt で利用しています。

まとめ

静音マウスすごく気に入ったのでm650 大好きです。 コスパ考えても、このマウスは他の人がちょっと試すにはいいと思います。

MxAnywhere 3 を使っている人は サイズは Mにしましょう、忘れずに。 MxMaster 3 の人は L でもいいですね。

GitHub Actions で README にリポジトリのコードを埋め込みたい

README に、リポジトリにおいているコードを埋め込みたい時があります。 そんな時に便利なのが、embedme です。

github.com

今回は、GitHub Actions を使って README にリポジトリのコードを埋め込むことをしたので紹介します。

tl;dr;

  • GitHub Actions で embedme を実行して、README.md にリポジトリのコードを埋め込み自動化ができる。
  • リポジトリと README.md で同じコードを示す時の二重管理が解消するのでうれしい。
  • 軽量シンプルなので、pull_request、push、workflow_dispatch など任意のトリガーで組めて便利。

embedme の基本的な利用例

例として、README.md に src/example.ts の中身を埋め込むことを考えてみましょう。

まずはembedme をインストールします。

npm install -g embedme

README.md に次のようにコードブロックと言語を示しておいてリポジトリのファイルパスを示します。

gist.github.com

TIPS: OS問わずファイルパスは / 区切りがいいです。

あとは、インストールした embedme をREADME.md に実行します。

embedme README.md

これでexample.ts のファイルがコードブロックに差し込まれます。便利。

gist.github.com

行指定も直感的にできます。

// src/embedme.lib.ts#L44-L82

embedme のいいところ

個人的に気に入ってるところは3つあります。

埋め込むときに使ったコメントがコードブロックに残る

埋め込み後もコメントが残ることで、埋め込むソースコードを更新してembedmeを実行すると埋め込みが更新されるので、勝手にメンテが維持します。 どことリンクしていたかも一目瞭然で、README.md を見る人が探すこともできるので好きです。

実行が軽い

インストールも実行も早いのはいいこととです。 npm install -g embedme で入るので、GitHub Actions などの CI との相性もいいです。

実行も即座に終了するのでカジュアルに走らせられる安心感があります。

実行履歴

README.md の何行目のコードブロックを実行した、実行できなかったを理由を添えて表示してくれます。 例えばファイルパスが見つからず埋め込みができなかったら次のように教えてくれます。

   README.md#L381-L383 Found filename .github\workflows\concurrency_control_cancel_in_progress.yaml in comment in first line, but file does not exist at /home/runner/work/githubactions-lab/githubactions-lab/.github\workflows\concurrency_control_cancel_in_progress.yaml!

十分です。

embedme で困るであろうこと

コードブロックのコメント

コードブロック内のコメントを検知するので、埋め込む前提になってないのにコメントを適当にいれたコードブロックを作ると警告は出ます。 ファイルパスが示されていないければ問題ないですが注意です。

言語ごとのコメントが違う

言語ごとに対応しているので当然ですが注意しましょう。 yaml や bash なら # でコメント認識ですし、js や ts なら // でコメント認識です。

GitHub Actions で自動化する

embedme は GitHub Actions としては公開されていないので適当に組みます。 今回は、GitHub Actions をいろいろ試しているリポジトリで組んだ例を示します。

github.com

大量に yaml を埋め込んでいるので本当に助かっています。

https://github.com/guitarrapc/githubactions-lab での自動埋め込み例

GitHub Actions workflow を用意する

普段は pull_request で実行して、変更があれば PR にコミットを積むようにします。 必要に応じて workflow_dispatch で手動で更新もできるようにします。

gist.github.com

PRで リポジトリを checkout するときは、Merge コミットではなく PR のコミットを checkout します。 refを指定せず checkout すると、後段で git push したときにマージコミットが PR に入ってしまいます。

      - if: ${{ github.event_name == 'pull_request' }}
        uses: actions/checkout@v3
        with:
          ref: ${{ github.event.pull_request.head.sha }} # checkout PR HEAD commit instead of merge commit

19-22行目で embedded を実行します。

      - name: Embedding Code into README
        run: |
          npm install -g embedme
          embedme README.md

あとは変更があれば git push します。

      - name: git diff
        id: diff
        run: |
          git add -N .
          git diff --name-only --exit-code
        continue-on-error: true
      - if: steps.diff.outcome == 'failure'
        name: git-commit
        run: |
          git config user.name github-actions[bot]
          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
          git add .
          git commit -m "[auto commit] Embed code"
      - if: steps.diff.outcome == 'failure'
        name: Push changes
        uses: ad-m/github-push-action@master
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          branch: ${{ github.head_ref }}

push で実行してもいいですが、私のリポジトリではREADMEの目次作成 (toc) を push でやっているので pull_request にしています。 コード生成は重なると直列実行 と checkout 時の ref 伝搬を気にしないといけないので注意です。

まとめ

embedme 便利です。 あんまり README にリポジトリのコードを埋め込むのを考えてこなかったのですが、いざやってみると便利でいろいろ使えそうです。(実際コピペではることありますし)

補足情報として、類似したものに tokusumi/markdown-embed-codeがありますが、これはそもそも実行できなかったのと docker のpullが走って重すぎるので好みじゃなかったです。

github.com

Pulumi を C# で書くときに気を付けていること

Pulumi は複数の言語で書くことができるのですが、そのうちの一つに .NET (C#) もあります。

f:id:guitarrapc_tech:20220406161700p:plain
Languages より https://www.pulumi.com/docs/intro/languages/

以前 Pulumi を C# で書く時の事始めシリーズを書いていましたが、あれから時間がたって書き方も変わりました。 今回は、実際にどのように書くことで Pulumi で書きやすい、IaC制御しやすいを目指しているのかを言語化します。

tl;dr;

Pulumi + C# の時に、Pulumi の考えているやりやすいにのっかりつつ、C# 的に書きやすく、IaC として管理しやすいかを検討します。 ポイントは4点です。

  • コンストラクタで処理を完結させる
  • Output`T型 で将来の値を表現する
  • リソースインスタンス作成はコンポーネントの責務を徹底する
  • 定数クラスと分岐で環境差分を表現する

DO/DO NOT/CONSIDER で気を付けていることを順にあげていきます。

コンストラクタで処理を完結させる

  • ✔️ DO: コンストラクタで処理を行う。
  • ❌ DO NOT: Task メソッドに処理を分けて呼び出すことを避ける。

AWS CDK も似た感じですが、リソース/コンポーネントの作成処理は コンストラクタで完結させます。 例えば次のようになります。

// DO
return await Deployment.RunAsync<MyStack>();

class MyStack : Stack
{
    public MyStack()
    {
        var foo = new FooResource("Foo",  new FooArgs
        {
            // 何か処理
        });
    }
}

Task ExecuteAsync() のように非同期メソッドを生やして呼び出す、ということは避けるといいでしょう。 非同期メソッドに処理を分けると、そのメソッド内部では async/await を使えますが、呼び出し元の最上流はコンストラクタです。 コンストラクタ呼び出し時点でリソースが作られないのは良しとしても、ExecuteAsync 呼び出し忘れや、Task<T>.GetAwaiter().GetResult() とか絶対避けたいでしょう。 あと、明らかに冗長です。

// DO NOT
return await Deployment.RunAsync<MyStack>();

class MyStack : Stack
{
    public MyStack()
    {
        var foo = new FooComponent();
        foo.ExecuteAsync().GetAwaiter().GetResult(); // したくない
    }
}

public class FooComponent : ComponentResource
{
    public FooComponent() : base()
    {
        // 初期化
    }

    public async Task ExecuteAsync()
    {
        var foo = new FooResource("Foo",  new FooArgs
        {
            // 何か処理
        });
    }
}

コンストラクタで async/await は使えないので非同期処理をどうするのか、という疑問がわきますが、それは次の Output<T> を使う話になります。

Output`T型 で将来の値を表現する

Pulumi で何かしらのリソースを作成するときに、リソースが作成されないと決定できない「将来の値 = (いわゆるPromise)」は Output<T> 型で表現されます。

www.pulumi.com

  • ✔️ DO: 将来の値は Output<T> を伝搬させる。
  • ✔️ DO: Taskを扱う非同期処理は Output<T> でくるむ。
  • ❌ DO NOT: await して生の値をとろうとしない。
  • ✔️ DO: Output<T> の 生の値 Tが必要な場合は Output<T>.Apply() メソッド内部のラムダで利用する。

Pulumi を C# で書くときは、Output<T> で将来の値を伝搬するのを徹底するのがよいでしょう。 例えば Output<T> を活用すると、次のように foo リソースが作成されていなくても bar リソースで fooリソースを使う/依存があることを示すことができます。

// DO
return await Deployment.RunAsync<MyStack>();

class MyStack : Stack
{
    public MyStack()
    {
        var foo = new FooResource("Foo",  new FooArgs
        {
            // 何か処理
        });

        var bar = new BarResource("Bar", new BarArgs
        {
            FooId = foo.Arn, // foo が生成されるまで値が未確定。fooへの依存も自動的に解析される。
        });
    }
}

Output<T> に対応する、リソースが受け入れるときの型が Input<T> ですが、自分で利用する機会はほぼなく Output<T> しか使わないでしょう。

非同期メソッドと Output`T

Pulumi には、現在認証している クラウド環境 やその環境のリソースを取得するメソッドが用意されています。 例えば、AWS 環境で既存の Vpc を取得するメソッドがあります。

// メソッドの返り値は、Task<Pulumi.Aws.Ec2.GetVocResult>
Pulumi.Aws.Ec2.GetVpc.InvokeAsync(new Pulumi.Aws.Ec2.GetVpcArgs { Id = "foo" });

C# 的には Task なんだから await することで待ちたくなりますが、それでは前出のasync/await を書こうとしたときのジレンマに陥ります。 Taskを扱う非同期処理は、await する代わりに Output<T> でくるんであげることで自然と扱えます。

先の例を Output<T> でくるむには、Output.Create<T>() メソッドを利用するといいでしょう。

// DO
var vpcId = Output.Create(Pulumi.Aws.Ec2.GetVpc.InvokeAsync(new Pulumi.Aws.Ec2.GetVpcArgs { Id = "vpc-0123456" }));

// DO NOT
var vpcId = await Pulumi.Aws.Ec2.GetVpc.InvokeAsync(new Pulumi.Aws.Ec2.GetVpcArgs { Id = "vpc-0123456" });

Output`T の T を取り出したい

また、リソースを生成した結果の Output<T> を 先ほどのInvokeAsync 内の処理で使いたいことがあります。

var foo = new FooResource("Foo",  new FooArgs
{
    // 何か処理
});

// プロパティは仮です、実際とは異なります。
Pulumi.Aws.Iam.GetPolicyDocument.InvokeAsync(new GetPolicyDocumentArgs
{
    Resources = new [] { /* ここでfooリソースのArnを使いたい*/ }
});

直接 foo.Arn を指定しようとすると foo.Arn は Output<T> なので文字列には変換されません。(ここが CDK との違いですね)

Output<T>T を直接使用した処理を書きたい場合は、Output<T>.Apply<a>()メソッドのラムダ内部で処理を書くといいでしょう。 Output<T>.Apply<a>() の返り値は Output<a> となるので、結果を他リソースに食わせる時も自然と与えることができます。

// DO
var policy = foo.Arn.Apply(arn => Pulumi.Aws.Iam.GetPolicyDocument.InvokeAsync(new GetPolicyDocumentArgs
{
    Resources = new [] { $"{arn}/*" } // T が入っている
}));

// DO NOT
var policy = Output.Create(Pulumi.Aws.Iam.GetPolicyDocument.InvokeAsync(new GetPolicyDocumentArgs
{
    Resources = new [] { $"{foo.Arn}/*" } // Output<T> のままなのでダメ
}));

Output<T> から別の Output<T> に変換したいときも同じように Output<T>.Apply()Output<T>.Format() が利用できます。

// 出力される Output<string> は arn:aws:s3:::foo に変換される。
Output.Create("foo").Apply(x => $"arn:aws:s3:::{x}");

リソースインスタンス作成はコンポーネントの責務を徹底する

  • ✔️ DO: 実装 (リソース) は コンポーネントに管理させる。
  • ❌ DO NOT: Stack に直接実装 (リソース) を記述する。
  • ✔️ CONSIDER: リソース処理の前に値の検証をする。
  • ✔️ DO: 他のコンポーネントからリソースの結果を使用たいときはプロパティを公開する。

Pulumi でリソースを作る = リソースインスタンスを作ることを指します。 また、リソースは一つ一つがユニークな urnで識別され、urn は リソースがコンポーネントに含まれるかどうかでも IDが変わります。 このため、リソースは当初からコンポーネントに分離することを念頭において、 Stack に直接書き出すのは避けるといいでしょう。

// DO
class MyStack : Stack
{
    public MyStack()
    {
        var opts = new ComponentResourceOptions { Parent = this };

        // コンポーネントを呼び出す
        var sg = new SecurityGroupComponent("my-sg", "securitygroup", opts, new SecurityGroupComponentArgs
        {
            VpcId = "vpc-0123456",
        });
    }
}

public class SecurityGroupComponent : ComponentResource
{
    public SecurityGroupComponent(string service, string component, ComponentResourceoptions opts, SecurityGroupComponentArgs args): base($"{service}:components:{component}", $"{service}-{component}", opts)
    {
        var opt = new CustomResourceOptions { Parent = this };

        // リソースインスタンス管理はコンポーネントのお仕事
        var egresss = new SecurityGroupEgressArgs
        {
            FromPort = 0,
            ToPort = 0,
            Protocol = "-1",
            CidrBlocks = new[] { "0.0.0.0/0" },
        };

        var aSg = new SecurityGroup("a-sg", new SecurityGroupArgs
        {
            Description = "a-SG"
            VpcId = args.VpcId
            Ingress = new[] {
                new SerurityGroupIngressArgs
                {
                    FromPort = 80,
                    ToPort = 80,
                    Protocol = "TCP",
                    Descrsiption = "HTTP access from XXXX",
                    CidrBlocks = "0.0.0.0/0",
                }
                new SerurityGroupIngressArgs
                {
                    FromPort = 443,
                    ToPort = 443,
                    Protocol = "TCP",
                    Descrsiption = "HTTPS access from XXXX",
                    CidrBlocks = "0.0.0.0/0",
                }
            },
            Egress = new[] { egress },
        }, opt);

        var bSg = new SecurityGroup("b-sg", new SecurityGroupArgs
        {
            Description = "b-SG"
            VpcId = args.VpcId
            Ingress = new[] {
                new SerurityGroupIngressArgs
                {
                    FromPort = 0,
                    ToPort = 0,
                    Protocol = "-1",
                    Descrsiption = aSg.Name,
                    SecurityGroups = aSg.Id,
                    Self = false,
                }
            },
            Egress = new[] { egress },
        }, opt);
    }
}

次のようにリソースを Stack に直接書き出したが最後、そのリソースの管理は誰がやるのか困り始めることでしょう。

// DO NOT
class MyStack : Stack
{
    public MyStack()
    {
        var opt = new CustomResourceOptions { Parent = this };

        // リソースを直接Stackに書き出す
        var egresss = new SecurityGroupEgressArgs
        {
            FromPort = 0,
            ToPort = 0,
            Protocol = "-1",
            CidrBlocks = new[] { "0.0.0.0/0" },
        };

        var aSg = new SecurityGroup("a-sg", new SecurityGroupArgs
        {
            Description = "a-SG"
            VpcId = args.VpcId
            Ingress = new[] {
                new SerurityGroupIngressArgs
                {
                    FromPort = 80,
                    ToPort = 80,
                    Protocol = "TCP",
                    Descrsiption = "HTTP access from XXXX",
                    CidrBlocks = "0.0.0.0/0",
                }
                new SerurityGroupIngressArgs
                {
                    FromPort = 443,
                    ToPort = 443,
                    Protocol = "TCP",
                    Descrsiption = "HTTPS access from XXXX",
                    CidrBlocks = "0.0.0.0/0",
                }
            },
            Egress = new[] { egress },
        }, opt);
    }
}

コンポーネントでリソースインスタンスを作成するので、リソース作成に必要な値をコンポーネントに渡す必要があります。 適当なrecord クラスで渡してあげると簡単でいいでしょう。

// DO
class MyStack : Stack
{
    public MyStack()
    {
        var opts = new ComponentResourceOptions { Parent = this };

        // コンポーネントを呼び出す
        var sg = new SecurityGroupComponent("my-sg", "securitygroup", opts, new SecurityGroupCompoonentArgs
        {
            VpcId = "vpc-0123456",
        });
    }
}

public class SecurityGroupComponent : ComponentResource
{
    public SecurityGroupComponent(string service, string component, ComponentResourceoptions opts, SecurityGroupComponentArgs args): base($"{service}:components:{component}", $"{service}-{component}", opts)
    {
        // 省略
    }
}

public record SecurityGroupComponentArgs
{
    public Output<string> VpcId { get; init; }
}

リソース処理の前に値の検証をする

各種ComponentArgs には、値の検証を担保させると Component内部での入力値の検査のほとんどを考慮しなくてよくなるのでオススメです。

// CONSIDER
public class SecurityGroupComponent : ComponentResource
{
    public SecurityGroupComponent(string service, string component, ComponentResourceoptions opts, SecurityGroupComponentArgs args): base($"{service}:components:{component}", $"{service}-{component}", opts)
    {
        // 初めに検証する
        args.Validate();

        // 省略
    }
}

public interface IValidate
{
    void Validate();
}

public record SecurityGroupComponentArgs : IValidate
{
    public Output<string>? VpcId { get; init; }

    [MemberNotNull(nameof(VpcId))]
    public void Validate()
    {
        if (VpcId is null) throw new ArgumentOutOfRangeException(nameof(VpcId));
    }
}

もちろんVpcId のように必須なものはコンストラクタでもいいでしょう。

// CONSIDER
public record SecurityGroupComponentArgs(Output<string> VpcId) : IValidate
{
    public IReadOnlyList<string>? Nanika { get; init; }

    [MemberNotNull(nameof(Nanika))]
    public void Validate()
    {
        if (Nanika is null) throw new ArgumentOutOfRangeException(nameof(Nanika));
    }
}

コンポーネント外部へのプロパティの公開

C# ではクラスの内部の情報を公開するときに プロパティを使いますが、Pulumi でもそれは変わりません。 公開したいリソースは get only プロパティを使うといいでしょう。

Pulumi コンソールでStack 出力に表示したい場合は、[Output] 属性を付けたプロパティで公開します。 プリミティブな型でないと表示できないので注意です。

// DO
class MyStack : Stack
{
    public MyStack()
    {
        var opts = new ComponentResourceOptions { Parent = this };

        var sg = new SecurityGroupComponent("my-sg", "securitygroup", opts, new SecurityGroupComponentArgs
        {
            VpcId = "vpc-0123456",
        });

        SecurityGroupAId = sg.A.Id
    }

    // Stack の Output に公開
    [Output]
    public Output<string> SecurityGroupAId { get; set; } // set 必須
}

public class SecurityGroupComponent : ComponentResource
{
    // リソースを公開する
    public SecurityGroup A { get; }

    public SecurityGroupComponent(string service, string component, ComponentResourceoptions opts, SecurityGroupComponentArgs args): base($"{service}:components:{component}", $"{service}-{component}", opts)
    {
        var aSg = new SecurityGroup("a-sg", new SecurityGroupArgs
        {
            // 省略
        }

        A = aSg;
    }
}

定数クラスと分岐で環境差分を表現する

  • ✔️ DO: 定数クラスに環境ごとの値を定義して Stack で参照させる。
  • ❌ DO NOT: Stack に環境ごとの値を直接書く。
  • ✔️ CONSIDER: 環境ごとのリソースの違いはコンポーネントの分岐などで表現する

環境差分と定数クラス

コンポーネントの処理は環境で同じ、コンポーネントに与える値だけ違うというケースが多いでしょう。 この場合、コンポーネント呼び出し時にStackへ直接値を書くのではなく、定数クラスを用意して参照させると環境ごとの差分が管理しやすいのでオススメです。

// DO
public static class Constants
{
    public const string Project = "MyProject";
    public const string Env = "dev";
    public const string Service = Project + "-" + Env;

    public static class Vpc
    {
        VpcId = "vpc-0123456"; // 環境ごとに違うであろう値
    }
}

class MyStack : Stack
{
    public MyStack()
    {
        var opts = new ComponentResourceOptions { Parent = this };

        var sg = new SecurityGroupComponent("my-sg", "securitygroup", opts, new SecurityGroupComponentArgs
        {
            VpcId = Constants.Vpc.VpcId,
        });
    }
}

// DO NOT
class MyStack : Stack
{
    public MyStack()
    {
        var opts = new ComponentResourceOptions { Parent = this };

        var sg = new SecurityGroupComponent("my-sg", "securitygroup", opts, new SecurityGroupComponentArgs
        {
            VpcId = "vpc-0123456", // 直接値を指定するのは避けたい
        });
    }
}

環境ごとのリソースの違いはコンポーネントで頑張る

コンポーネントの処理は環境で同じ、コンポーネントに与える値だけ違うというケースが多いでしょう。

と書きましたが、そんなの絵空事です。 実際には、開発にはあるけど、本番にはないリソースというのはよくある話でしょう。

こういった環境差分は、コンポーネントの中で分岐などで適当に頑張るといいでしょう。 幸いにして Terraform と違ってこういった処理は圧倒的にやりやすいのでいい感じの方法をとればいいと思います。

// CONSIDER
public class SecurityGroupComponent : ComponentResource
{
    public SecurityGroupComponent(string service, string component, ComponentResourceoptions opts, SecurityGroupComponentArgs args): base($"{service}:components:{component}", $"{service}-{component}", opts)
    {
        args.Validate();

        if (args.EnableA)
        {
            // A の セキュリティグループを作る
        }
    }
}

public record SecurityGroupComponentArgs : IValidate
{
    public Output<string>? VpcId { get; init; }
    public bool EnableA { get; init; }

    [MemberNotNull(nameof(VpcId))]
    public void Validate()
    {
        if (VpcId is null) throw new ArgumentOutOfRangeException(nameof(VpcId));
    }
}

まとめ

つらつらと普段気を付けていることを挙げてみました。 C# に限らず、Pulumiは各種言語のやりやすいように書けばインフラが管理できるのはとても便利です。 Pulumi と Terraform を行き来していると、Terraform の言語機能の貧弱さに驚くとともに、今ある値かを意識することなくかけるのはすごいと感じます。

利用者の多さ、言語機能の小ささから 今後もTerraform は広く使われるでしょうが、アプリケーションエンジニアの立場から見ると Pulumi は非常に扱いやすく設計も応用できるので好ましいと感じます。

Terrafom も Pulumi もよい、チームとしてより書きやすい、手になじむものを採用していけるといいですね。

Pulumi で Stack解析中の例外でリソースが全て消えてしまうのを防ぐ

Pulumi は Stack の解析を行って、現在のステートとの差分でどのような処理をするか preview / up で表示します。 このため、Stack の解析中 (=コードをビルドして実行してStack生成中) に例外が生じたときにどのようにハンドルされるかは重要です。

今回は ユーザー側の誤った記述で、Stack解析に例外が起こっても処理が止まらず実行されたのをメモしておきます。

目次

tl;dr;

  • sdk/dotnet を利用する場合、Program.Main の返り値の型は int または Task<int> にしましょう。
  • Top-level statement なら return を忘れずに、return await Deployment.RunAsync<MyStack>(); としましょう。

どういう問題なのか

C# でPulumi を記述する場合、多くの場合は Stack を継承した自分の定義を用いるでしょう。 pulumi previewpulumi apply でStack を実行中に例外が発生した場合は、pulumi cli はそれを検知して実行を止めなくてはいけません。 pulumiは 例外を検知すると、「何もStackの内容を実行せず」例外をターミナルに表示して終了します。

しかしProgram.Mainメソッド の返り値の型を int あるいは Task<int> にしていないと、例外が起こっても pulumi cli は実行を継続しようとします。 この状態で例外が起こると、「例外以降のコードで記述されたリソースに削除マーカーを付与」して差分+例外をターミナルに表示して終了します。

// bad
public static async Task Main(string[] args)
{
    await Deployment.RunAsync<MyStack>();
}

// bad (Top-Level statement)
await Deployment.RunAsync<MyStack>();

Issue が作られておりそちらを見ると詳しくわかります。

github.com

対処方法は前述のとおり、Mainメソッドの返り値を intTask<int> にしましょう。

// ok
public static async Task<int> Main(string[] args)
{
    return await Deployment.RunAsync<MyStack>();
}

// ok (Expression-bodied Method)
public static async Task<int> Main(string[] args) => await Deployment.RunAsync<MyStack>();

// ok (Top-Level statement)
await Deployment.RunAsync<MyStack>();

何がおこったのか

Pulumi は言語のビルドは pulumi cli と切り離されているので、何気に .NET 6 でもビルド、実行できたりします。 その際にうかつにも、await Deployment.RunAsync<MyStack>(); と return を忘れて書いてしまったために、作成してあったリソースの多くが消えるという目にあったのでした。

// missing return!!
await Deployment.RunAsync<MyStack>();

Pulumi は GitHub Aapp あるいは GitHub Actions で PR で差分を表示できるのですが、GitHub Actions でコメントを書くのを使っていたために、差分が埋もれてしまい気づけなかったという顛末です。

対処は return をつけるだけです。 誰かの役に立つと幸いです。

Pulumi に期待すること

例外起こったら Environment.ExitCode = -1 など適切な終了コードをセットしてほしいです。 現在はそういったことをしていないのを、終了コードを Main メソッドで示さないと死ぬので基盤で対処してほしい....

github.com