IaCにおける理想のドキュメント管理を目指す

 IaCにおける理想のドキュメント管理を目指す

インフラをコード化してVCSで管理するIaC。インフラの全てがコードで完結できることのメリットは無数にありますが、IaCだからこそ管理するべきドキュメントがあります。その管理方法についての視座をみなさんにお伝えできれば。

C47bda32c8455a59471cd7e19c32c074?s=128

濱田孝治

May 20, 2020
Tweet

Transcript

  1. IaCにおける 理想のドキュメント管理を⽬指す 濱⽥孝治(ハマコー)

  2. @hamako9999 濱⽥孝治 (ハマコー) 2

  3. 3 IaCに必要な ドキュメントとは︖

  4. 4 最初にお聞きしたい 皆さんがIaCで実現したいことって なんですか︖

  5. 5 IaCで期待されることの例 • 構築⼿順書をなくしたい • ヒューマンエラーを無くしたい • 効率よくインフラを構築したい • 不要なドキュメントを無くしたい

  6. 6 IaCで期待されることの例 • 構築⼿順書をなくしたい • ヒューマンエラーを無くしたい • 効率よくインフラを構築したい • 不要なドキュメントを無くしたい

    エクセルで作ったパラメー タシートとかとか
  7. 7 経験上 インフラを担う我々が必ず作っている ドキュメントがある

  8. 8

  9. 9 構成図

  10. 10 構成図を書くことのメリット・デメリット メリット • 管理対象領域にどんなリソースがあるのかひと⽬で 把握できる • 各リソースのリレーションが把握できる • 他⼈と対象領域に対する認識を共有しやすい

  11. 11 構成図を書くことのメリット・デメリット メリット • 管理対象領域にどんなリソースがあるのかひと⽬で 把握できる • 各リソースのリレーションが把握できる • 他⼈と対象領域に対する認識を共有しやすい

    デメリット • IaCとは別に管理しメンテする必要がある
  12. 12 構成図を書くことのメリット・デメリット メリット • 管理対象領域にどんなリソースがあるのかひと⽬で 把握できる • 各リソースのリレーションが把握できる • 他⼈と対象領域に対する認識を共有しやすい

    デメリット • IaCとは別に管理しメンテする必要がある 多大なメリットを感じながらも、 運用していくなかで忘れられがち
  13. 13 構成図の管理 どうするのか︖

  14. 14 構成図の管理がめんどくさい 問題に対する解決アプローチ 3つ

  15. 15 構成図の管理アプローチ3点 リポジトリ管理しない ①インフラから構成図を常に⾃動⽣成 リポジトリ管理する ②コードで構成図を作成するツールを使う ③専⽤ツールを使って構成図(SVG)を修正

  16. 16 リポジトリ管理しない ①インフラから構成図を常に⾃動⽣成

  17. 17 ①インフラから構成図を常に⾃動⽣成 ⾃動⽣成 Cloudviz Cacoo Cloud Mapper 構成図

  18. 18 ①インフラから構成図を常に⾃動⽣成 しんどい理由︓ 情報量が⾜りない(もしくは多すぎる) 構成図に表現すべきなのはシステムのコンテキストを把 握した上で⼈間が表現したいと意図した箇所 例)リソースのグルーピング、並び順、リレーション ⾃動⽣成にそのあたりを求めることはできない

  19. 19 リポジトリ管理する ②コードで構成図を作成するツールを使う

  20. 20 ②コードで構成図を作成するツールを使う ⾃動⽣成 PlantUML nwdiag Diagrams 構成図 txt Python

  21. 21 ②コードで構成図を作成するツールを使う https://gigazine.net/news/20200518-diagrams/

  22. 22 ②コードで構成図を作成するツールを使う しんどい理由︓ • 図を書くための独⾃記法を習得する必要がある テキストで構成図を書く⽬的だけに新しい記法を習得す るコストを払うか︖ 構成図をコードで管理するのであれば、他のアプローチ があるはず

  23. 23 リポジトリ管理する ③専⽤ツールを使って構成図(SVG) を修正

  24. 24 ③専⽤ツールを使って構成図(SVG)を修正 Cacoo draw.io SVG ⼿動修正

  25. 25 ③専⽤ツールを使って構成図(SVG)を修正 良い理由︓ • 専⽤ツール(Cacoo, draw.io)を使って構成図が書ける (導⼊コストが低い) • SVGファイル(XML)を扱えるためリポジトリにのせや すい

    GitHubなどでもSVGはそのまま図として表現されるため、 READMEに埋め込んだり、Pull requestでIaCと合わせてレ ビュー対象にするのが簡単
  26. 26 さらに最近いい感じのがリリースされました

  27. 27 Visual Studio Code Draw.io Integration 「コードと⼀緒に構成図が書ける︕」 • Visual Studio

    CodeのエクスプローラからSVG ファイルクリックでdraw.ioのUI起動 • そのまま編集して保存でSVGファイルが更新される
  28. 28 こんな雰囲気になる

  29. 29 まとめ

  30. 30 まとめ • インフラを扱うとき構成図は必須のドキュメント • IaCのコードと合わせて構成図もリポジトリ管理す るべき • 餅は餅屋。構成図の編集は専⽤ツールを使う •

    draw.ioインテグレーションなどを使って、IaCと同 じデベロッパーエクスペリエンスを実現しよう︕
  31. 31 IaCで楽しいエンジニアライフを 濱⽥孝治(ハマコー) @hamako9999