0Pricing
DevOps Bootcamp · レッスン

ドキュメントとセルフサービスワークフロー

生成ドキュメント、READMEの規約、品質を高く保つpre-commit自動化によって、チーム全体がTerraformプロジェクトを扱いやすくします。

「ドキュメントとセルフサービスワークフロー」はCoddyKit上の無料DevOps Bootcampレッスンです。 これはレッスン4/4です。 下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。 これはDevOps Bootcamp学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 DevOps Bootcampコースには全4レッスンが含まれています。

ドキュメントが重要な理由

優れたコラボレーションに必要なのは、整ったコードだけではありません。チームメンバーは、モジュールの機能、必要な入力、そして安全な実行方法を理解する必要があります。常に更新されるドキュメントによって、リポジトリはセルフサービスで使えるツールになります。

README は最初の入り口

すべての Terraform リポジトリには、目的、前提条件、使用例、入力と出力を説明する README を用意してください。新しいコントリビューターが最初に読むドキュメントです。

ドキュメントの自動生成

terraform-docs ツールは変数と出力をスキャンし、Markdown の表を生成します。そのため、ドキュメントがコードからずれることはありません。

terraform-docs markdown table . > README.md

README へのドキュメントの挿入

マーカーコメントを使うと、terraform-docs が特定のセクションだけを更新し、手書きした導入部分を維持できます。

<!-- BEGIN_TF_DOCS -->
<!-- END_TF_DOCS -->

説明がドキュメントの品質を左右する

生成されるドキュメントの品質は、description フィールドの内容次第です。利用者向けの文章として記述してください。

variable "instance_type" {
  type        = string
  description = "EC2 size, e.g. t3.micro for dev or m5.large for prod"
  default     = "t3.micro"
}

Pre-commit フック

pre-commit フレームワークは、コミットするたびにチェックを実行し、レビューに入る前に問題を検出します。YAML ファイルで設定します。

repos:
  - repo: https://github.com/antonbabenko/pre-commit-terraform
    hooks:
      - id: terraform_fmt
      - id: terraform_validate
      - id: terraform_docs

フックのインストール

クローンごとにインストールコマンドを一度実行すると、コミット時にフックが自動的に実行されます。

pre-commit install

フォーマットと Lint の強制

terraform fmt と tflint のようなリンターを組み合わせると、無効なインスタンスタイプなど、プロバイダー固有のミスを検出できます。

tflint --recursive

CONTRIBUTINGガイド

CONTRIBUTINGファイルに、チームのワークフロー（ブランチの命名規則、planの実行方法、applyを承認する担当者）を記録します。これにより、新しく参加した人が推測で対応する必要がなくなります。

アーキテクチャ決定記録

ADRには、なぜその選択をしたのか（たとえば、なぜリモートバックエンドを選んだのか）を記録します。これをリポジトリに保存しておけば、元の作成者が離れた後も背景情報を維持できます。

docs/adr/0001-use-s3-backend.md

例によるセルフサービス

実行可能な小さな設定例を収めたexamples/フォルダーがあれば、ユーザーは入力を試行錯誤して解析する代わりに、動作する設定をコピーできます。また、統合テストの材料としても利用できます。

examples/
  minimal/main.tf
  complete/main.tf

確認テスト

ドキュメントツールに関する知識を確認しましょう。

まとめ: セルフサービス型リポジトリ

コラボレーションをスムーズにする方法を学びました。

  • 充実したREADMEとCONTRIBUTINGガイド。
  • 入力・出力テーブルを自動生成するterraform-docs。
  • fmt、validate、lintを実行するpre-commitフック。
  • 背景情報と使用方法を記録するADRとサンプル。

よくある質問

「ドキュメントとセルフサービスワークフロー」レッスンは無料ですか？

はい。「ドキュメントとセルフサービスワークフロー」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、DevOps Bootcampコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 DevOps Bootcampコースには全4レッスンが含まれています。

「ドキュメントとセルフサービスワークフロー」で何を学びますか？

生成ドキュメント、READMEの規約、品質を高く保つpre-commit自動化によって、チーム全体がTerraformプロジェクトを扱いやすくします。 ブラウザで直接実行するハンズオンコードでDevOps Bootcampを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。

DevOps Bootcampを始めるのに経験は必要ですか？

事前経験は必要ありません。CoddyKitのDevOps Bootcampは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。 これはレッスン4/4です。

「ドキュメントとセルフサービスワークフロー」レッスンにはどのくらい時間がかかりますか？

ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。

このDevOps Bootcampレッスンでコードを書いて実行できますか？

はい。すべてのDevOps Bootcampレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。

このコースのすべてのレッスン

  1. コード構成と命名規則
  2. Git によるバージョン管理
  3. チームコラボレーションとワークフロー
  4. ドキュメントとセルフサービスワークフロー
← DevOps Bootcampに戻る