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

by 濱田孝治

Slide 1

Slide 1 text

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

Slide 2

Slide 2 text

@hamako9999 濱⽥孝治（ハマコー） 2

Slide 3

Slide 3 text

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

Slide 4

Slide 4 text

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

Slide 5

Slide 5 text

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

Slide 6

Slide 6 text

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

Slide 7

Slide 7 text

7 経験上インフラを担う我々が必ず作っているドキュメントがある

Slide 8

Slide 8 text

Slide 9

Slide 9 text

9 構成図

Slide 10

Slide 10 text

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

Slide 11

Slide 11 text

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

Slide 12

Slide 12 text

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

Slide 13

Slide 13 text

13 構成図の管理どうするのか︖

Slide 14

Slide 14 text

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

Slide 15

Slide 15 text

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

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

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

Slide 18

Slide 18 text

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

Slide 19

Slide 19 text

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

Slide 20

Slide 20 text

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

Slide 21

Slide 21 text

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

Slide 22

Slide 22 text

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

Slide 23

Slide 23 text

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

Slide 24

Slide 24 text

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

Slide 25

Slide 25 text

25 ③専⽤ツールを使って構成図（SVG）を修正良い理由︓ • 専⽤ツール（Cacoo, draw.io）を使って構成図が書ける（導⼊コストが低い） • SVGファイル（XML）を扱えるためリポジトリにのせやすい GitHubなどでもSVGはそのまま図として表現されるため、 READMEに埋め込んだり、Pull requestでIaCと合わせてレビュー対象にするのが簡単

Slide 26

Slide 26 text

26 さらに最近いい感じのがリリースされました

Slide 27

Slide 27 text

27 Visual Studio Code Draw.io Integration 「コードと⼀緒に構成図が書ける︕」 • Visual Studio CodeのエクスプローラからSVG ファイルクリックでdraw.ioのUI起動 • そのまま編集して保存でSVGファイルが更新される

Slide 28

Slide 28 text

28 こんな雰囲気になる

Slide 29

Slide 29 text

29 まとめ

Slide 30

Slide 30 text

30 まとめ • インフラを扱うとき構成図は必須のドキュメント • IaCのコードと合わせて構成図もリポジトリ管理するべき • 餅は餅屋。構成図の編集は専⽤ツールを使う • draw.ioインテグレーションなどを使って、IaCと同じデベロッパーエクスペリエンスを実現しよう︕

Slide 31

Slide 31 text

31 IaCで楽しいエンジニアライフを濱⽥孝治（ハマコー） @hamako9999