Terraform-docsとは? ドキュメント自動生成ツールの概要・機能・特徴を初心者向けに詳しく解説

Terraform-docsとは? ドキュメント自動生成ツールの概要・機能・特徴を初心者向けに詳しく解説

terraform-docs は、Terraformモジュールからドキュメントを生成するためのユーティリティツールです。公式サイトでも「terraform-docsはTerraformモジュールのドキュメントを様々な形式で生成するユーティリティ」と説明されています。このツールを使うと、複雑なTerraformコードから入力変数や出力値の一覧を自動で抽出し、表形式などでまとめてくれます。

対応する出力形式も豊富で、Markdown、AsciiDoc、JSON、YAMLなど多くの形式をサポートしています。特にMarkdownテーブル形式はTerraformモジュールのREADME生成に適しており人気があります。またCIパイプラインとの親和性が高く、GitHub Actionsなどでドキュメント生成を自動化できる点も特徴です。

開発歴としては、元々Segment社が作成しオープンソース化されたプロジェクトです。terraform-docsはTerraform 0.13以降をサポートしており、公式サイトの互換性マトリクスによれば最新バージョンではTerraform 0.15以降が必要になります。このように最新のTerraformでも動作するよう設計されているため、モジュール開発者はドキュメントのメンテナンスにかかるコストを低減できます。

Terraform-docsの主要機能と利点: ドキュメント自動生成機能の特徴を詳しく解説

terraform-docsの主要な機能は、Terraformモジュールの「Inputs（変数）」「Outputs（出力値）」「Providers（プロバイダー要件）」「Resources（リソース）」などを自動的に抽出し、表形式でドキュメント化することです。例えば、terraform-docs markdown tableコマンドを実行すると、指定したモジュール内の変数や出力をMarkdownテーブルとして一覧表示できます。これによりREADMEなどのドキュメントを手作業で更新する手間を大幅に削減できます。

出力内容は細かく制御可能で、不要な情報を除外したり整形オプションを適用したりできます。formatter設定でMarkdownやJSONなどのフォーマットを選択し、--output-fileやテンプレートで出力形式を柔軟にカスタマイズできます。これにより、チーム内で統一したドキュメントスタイルを簡単に実現できます。

Terraform-docsで解決できる課題: Terraformモジュールドキュメントの管理と共有を強化

Terraform-docsを使うことで、モジュールの変更に伴うREADMEなどドキュメントの更新漏れを防げます。手作業でドキュメントを維持するのは煩雑でミスが生じやすいですが、terraform-docsであればコードの変更と同期して自動生成できるため、ドキュメントの信頼性が向上します。また、複数人のチーム開発でも同じフォーマットのドキュメントが得られ、一貫性を保てます。

Terraform-docsの対応Terraformバージョンと互換性の目安

Terraform-docsはバージョン0.13以降のTerraformに対応しています。公式サイトの互換性マトリクスによれば、terraform-docs v0.13以降はTerraform 0.15以上をサポートし、v0.8以降はTerraform 0.12以上をサポートしています。古いバージョンのTerraformを扱う場合は、過去のterraform-docsリリース（v0.9.1以前はsegmentio名義）を使用する必要があります。

Terraform-docsの開発背景とオープンソースプロジェクトとしての由来

Terraform-docsは元々Segment社のインフラエンジニアが開発したツールで、後にオープンソースとしてコミュニティに公開されました。現在はGitHub上で活発にメンテナンスされており、多数のコントリビューターが参加しています。Apache 2.0ライセンスの下で開発されており、GitHub上でIssueやPull Requestが日々議論され、新機能の追加や改善が続けられています。

Terraform-docsと他のドキュメント生成ツールとの比較と差別化

同様の目的で利用されるツールは他にもありますが、terraform-docsはそのシンプルさと拡張性で特に人気があります。例えば、Terraformの状態や構成を可視化するツールとも異なり、terraform-docsは直接TerraformのHCLを解析しているため純粋にドキュメント生成に特化しています。また、フォーマット選択やテンプレートカスタマイズ機能が豊富で、幅広いユースケースに対応できる点も強みです。さらにGitHub ActionsなどCI連携が公式に整備されているため、導入しやすい点が高く評価されています。

Terraform-docsのインストール方法: Mac・Windows・Linux環境別に導入手順を徹底解説（各OS対応）

Terraform-docsは主要なOS（macOS、Windows、Linux）に対応しており、公式ドキュメントで各環境別のインストール方法が案内されています。macOSの場合、Homebrewで簡単にインストールできます。例えばbrew install terraform-docsと実行するだけです。

Windows環境ではScoopやChocolateyが利用可能です。Scoopの場合は以下のように導入します：
scoop bucket add terraform-docs https://github.com/terraform-docs/scoop-bucket
scoop install terraform-docs
また、Chocolateyを使う場合はchoco install terraform-docsでインストールできます。

Linuxではスナップパッケージが用意されています。Ubuntuなどではsudo snap install terraform-docsと実行すると最新版がインストールされます。また、GitHubリリースページからプラットフォーム別のバイナリをダウンロードしてインストールする方法も一般的です。ダウンロードしたZIPやtar.gzを展開し、実行権限を付与してPATH上に移動すれば使えるようになります。

Go言語環境が整っていれば、Goコマンドで直接インストールする方法もあります。公式にはGo 1.16以降でgo install github.com/terraform-docs/terraform-docs@latestを実行する方法が案内されています。特定バージョンを指定する場合はタグ（例: @v0.21.0）を付けます。インストール後は$(go env GOPATH)/binにバイナリが配置されるので、PATH設定を確認してください。

macOSでのインストール方法: Homebrewを使ったTerraform-docs導入手順を徹底解説

macOSではHomebrewで導入できます。ターミナルでbrew install terraform-docsと入力するだけで、最新バージョンがインストールされます。Homebrewのtapが更新されていない場合は、公式tapを追加してインストールすることもできます。たとえばbrew install terraform-docs/tap/terraform-docsとする方法も案内されています。

Windowsでのインストール方法: Scoop/Chocolateyを使ったTerraform-docs導入手順を解説

WindowsではScoopやChocolateyを使用できます。Scoopの場合はリポジトリを追加してからインストールします：
scoop bucket add terraform-docs https://github.com/terraform-docs/scoop-bucket
scoop install terraform-docs
Chocolateyを使う場合は、管理者権限のPowerShellでchoco install terraform-docsを実行するだけです。これらのパッケージ管理ツールを用いると、依存関係の設定を意識せずに導入できます。

Linuxでのインストール方法: Snapやバイナリ取得による導入手順を解説

LinuxではSnapパッケージを使ったインストールが便利です。Ubuntuなどの多くのディストリビューションでsudo snap install terraform-docsとすれば最新バージョンが導入されます。ほかにも、GitHubのリリースページからLinux向けのバイナリをダウンロードし、手動でインストールする方法があります。リリースから該当の.tar.gzを取得して展開し、実行可能ファイルをPATHに移動すれば完了です。

Go言語環境でのインストール方法: go installによるTerraform-docs導入手順

Go言語がインストールされた環境では、Goのモジュールコマンドでterraform-docsを導入できます。たとえばgo install github.com/terraform-docs/terraform-docs@latestとすると、最新のバージョンがインストールされます。特定のバージョンが欲しい場合はタグを指定します（例: @v0.21.0）。実行後は$(go env GOPATH)/binにterraform-docsバイナリが配置されるので、そのパスを通しておきます。

その他のインストール方法: 手動ビルドやパッケージマネージャによる導入例

その他の方法としては、ソースからの手動ビルドがあります。GitHubリポジトリをクローンしてmake buildを実行すると実行ファイルが生成されます。また、一部のディストリビューションでは独自のパッケージ管理システム（debやrpm）が提供されている場合があります。必要に応じて最適な方法を選んでください。

Terraform-docsの基本的な使い方（コマンド例付き）: ドキュメント生成手順を詳しく紹介します

terraform-docs の基本的な使い方は、対象モジュールのディレクトリでコマンドを実行することです。例えばMarkdownテーブル形式でドキュメントを生成するには、以下のように実行します：

terraform-docs markdown table --output-file README.md --output-mode inject /path/to/module

上記コマンドでは、/path/to/module内のTerraform構成を解析し、入力変数（inputs）や出力値（outputs）をMarkdownテーブルとして生成してREADME.mdに書き込みます。--output-mode injectを指定すると、既存のREADME内の / コメントブロックに生成結果が挿入されます。逆に--output-fileを省略すると、標準出力（ターミナル）に結果が表示されます。

terraform-docsコマンドの基本構文と使い方: サブコマンドと主要フラグを解説

terraform-docsコマンドの基本形はterraform-docs [FORMAT] [PATH]です。FORMATにはmarkdown、json、yamlなどの形式を指定し、PATHにモジュールのパスを指定します。たとえばMarkdownテーブル形式で出力する場合、terraform-docs markdown table .と実行します。ここでmarkdown tableは、Markdownのテーブル形式でドキュメントを生成するサブコマンドです。

README.mdへの組み込み例: Markdownテーブル形式でドキュメントを自動生成

通常はREADMEにドキュメントを埋め込む形で利用します。先の例のように--output-file README.mdと--output-mode injectを指定すると、README内の特定ブロックが更新されます。READMEにはあらかじめとで囲んだコメントを入れておくのが一般的です。これにより、モジュールの説明部分は手動で記述し、変数一覧などは自動生成で管理できます。

設定ファイルなしでの実行例: シンプルなコマンドラインオプションで利用

設定ファイルを用意しない場合は、必要な設定をコマンドラインオプションで指定します。たとえばフォーマットは--output-formatオプション（またはサブコマンド）で選択し、ヘッダー用ファイルは--header-from、フッター用ファイルは--footer-fromで指定できます。例：terraform-docs markdown table --header-from main.tf .とすると、出力の冒頭にmain.tfの内容が追加されます。

複数フォーマットのサブコマンド例: markdown、json、yamlなどの使い方

各フォーマットには対応するサブコマンドがあります。Markdownテーブル・ドキュメント形式のほか、terraform-docs jsonでJSON出力、terraform-docs yamlでYAML出力できます。たとえばterraform-docs json .と実行すれば、モジュール情報がJSON形式で標準出力に出力されます。このように複数のフォーマットを使い分けることで、人間向けドキュメントと機械処理向けデータの双方を得ることができます。

出力制御オプションの例: –output-fileや–output-modeの指定方法

生成結果の出力先や方法は以下のオプションで制御します。--output-fileで出力ファイルのパスを指定し、--output-modeで挿入方法（injectまたはreplace）を選択します。例えば--output-mode replaceを指定すると既存ファイル全体を置き換えます。また、--output-valuesオプションを付けると、出力値の詳細情報をドキュメントに含めることができます。これらを組み合わせて柔軟に出力を制御します。

Terraform-docsの出力フォーマット一覧（Markdown/JSON/YAMLなど）: サポートする形式を網羅

terraform-docsが対応する出力フォーマットには、主に以下のものがあります。Markdownテーブル形式（markdown table）、Markdownドキュメント形式（markdown document）、JSON、YAML、AsciiDoc、Pretty（プレーンテキスト）、Terraform変数形式（tfvars、HCL/JSON）、TOML、XMLなどです。公式サイトでも「Markdown、AsciiDoc、JSONなど多彩な形式」に対応と案内されています。

最もよく使われるのはMarkdownテーブル形式で、入力変数や出力値を表形式で表示できるためREADMEに組み込む際に見栄えが良くなります。JSON/YAML形式は機械可読なため、他ツールとの連携や自動化に便利です。AsciiDoc形式はドキュメント整形で一部Markdownと互換性があり、Pretty形式は純粋なテキストで出力されます。これらを用途に応じて使い分けられます。

Markdown形式の出力: ドキュメント形式とテーブル形式の違い

Markdown形式には「ドキュメント形式」と「テーブル形式」の2種類があります。ドキュメント形式（markdown document）では説明文付きのセクションが作成され、テーブル形式（markdown table）では変数や出力値を列挙したテーブルが生成されます。たとえばterraform-docs markdown document .では見出しと箇条書きのMarkdownが得られ、terraform-docs markdown table .では表形式になります。用途に応じて使い分けます。

JSON/YAML形式の出力: 構造化データとしてドキュメントを生成

JSON/YAML形式では、モジュール情報が構造化データとして出力されます。たとえばterraform-docs json .を実行すると、Terraformバージョン要件や変数、出力、プロバイダー情報がJSONオブジェクトで出力されます。同様にYAML形式も選べます。これらはスクリプトや他ツールで扱いやすいため、連携処理や自動化に適しています。

その他の出力形式: AsciiDoc、Pretty（プレーンテキスト）、Terraform変数形式など

その他に、AsciiDoc形式（asciidoc）、Pretty形式（プレーンテキスト）、Terraform変数ファイル形式（tfvars hcl/json）、TOML、XMLなどが利用できます。AsciiDoc形式は軽量な文書フォーマットで、Pretty形式は余計な装飾なしに出力します。Terraform変数形式はTerraformファイルと同様の形式で変数を出力できます。必要に応じてこれらのフォーマットを選択してください。

各フォーマットの使い分けと適用例

フォーマットは用途に応じて使い分けます。READMEなど人が読む文書にはMarkdown形式が最適で、スクリプトでの処理が必要な場合はJSON/YAMLを使います。複数形式を同時に生成することも可能で、CIパイプラインでMarkdownとJSONを同時に出力して別々に利用する例もあります。必要な情報を適切な形式で取得できるよう、サブコマンドや設定を組み合わせて使い分けます。

フォーマット指定の実践例: サブコマンドによる指定方法

フォーマットの指定はコマンド名やフラグで行います。Markdown形式ではterraform-docs markdown table .やterraform-docs markdown document .、JSON形式ではterraform-docs json .、YAML形式ではterraform-docs yaml .のように実行します。サブコマンド名の後にモジュールパスを指定する形です。これらを組み合わせることで、同じモジュールから異なる形式のドキュメントを生成できます。

Terraform-docs設定ファイル（.terraform-docs.yml）の書き方: 主要オプションと設定例解説

terraform-docsでは設定ファイル（YAML形式）を用いて挙動を細かく指定できます。デフォルトの設定ファイル名は.terraform-docs.ymlで、モジュールルート直下のディレクトリやその下の.config/フォルダ、カレントディレクトリや~/.tfdocs.d/などを順に検索します。最初に見つかったファイルが使用されます。

設定ファイルでは主にformatter（出力形式）、header-from/footer-from（前後に挿入するファイル）、sections.hide/sections.show（表示・非表示セクション）、output.file、output.mode（出力先と挿入方式）などを指定します。以下は設定例です：

formatter: "markdown table" header-from: main.tf sections: hide: [] show: [] output: file: README.md mode: inject template: |-  {{ .Content }} 

この例ではMarkdownテーブル形式を指定し、main.tfをヘッダーに追加します。出力先はREADME.mdで、指定ブロック内に内容を挿入します。公式ドキュメントによれば、formatterは必須オプションであることが明記されています。

設定ファイルを使用すると、チーム全体で同じドキュメント生成ルールを共有できます。また、複数のプロジェクトで一貫したフォーマットに保つことができます。必要に応じて-cオプションで別名の設定ファイルを指定することも可能です。

Terraform-docs設定ファイルの基本構造と書式

.terraform-docs.ymlはYAML形式で記述します。トップレベルにformatterなどのキーを置き、その下にネストして詳細設定を書きます。例えば、versionやヘッダー/フッターのファイルパス、セクション指定、出力制御の設定などが含まれます。YAMLの記法に従い、コメントやインデントに注意して記述します。

設定ファイルの配置場所と優先順位: .terraform-docs.ymlの検索順序

terraform-docsは実行時に設定ファイルを自動検索します。デフォルトではモジュールのルート直下の.terraform-docs.ymlを探し、次に同じディレクトリ内の.config/フォルダ、その後カレントディレクトリ、さらにユーザーの~/.tfdocs.d/を検索します。最も優先度の高いディレクトリにあるファイルが読み込まれます。

主要設定オプションの説明: formatter、header-from、footer-fromなど

最も重要な設定はformatterです。これは出力形式を指定し必須オプションです。その他、header-fromで冒頭に挿入するファイル、footer-fromで末尾に挿入するファイルを設定できます。出力先や挿入方法はoutput.fileやoutput.modeで制御します。またrecursiveやsortなど再帰実行・ソートの設定も可能です。セクション制御にはsections.hide/sections.showを使い、除外・表示するセクション名を配列で指定します。

セクション表示制御の設定: inputs/outputsなどセクションの表示/非表示

設定ファイルではsections.hideにセクション名を指定して非表示にできます。例: sections.hide: ["requirements","providers"]とすると、RequirementsセクションやProvidersセクションが生成されなくなります。一方、sections.showで表示したいセクションのみを列挙することも可能です。この機能を使えば、必要な情報だけをドキュメントに含められます。

設定ファイルの実例: 各種オプションを用いたカスタマイズ例

下記は具体例です：

formatter: "markdown table" version: "0.13" header-from: main.tf footer-from: "" recursive: enabled: true include-main: true path: modules sections: hide: [] show: [] content: "" output: file: README.md mode: inject template: |-  {{ .Content }} 

この例では、マークダウンテーブル形式を指定し、サブディレクトリのmodules/以下も再帰処理する設定です。出力先はREADME.mdで、既存の該当ブロックに結果を挿入します。また、共通のヘッダーやテンプレートを設定ファイルで定義することで、全チームメンバーで同じフォーマットを使えます。

Terraformモジュールからのドキュメント自動生成: READMEへの組み込みと自動化方法を詳しく解説

Terraformモジュールのドキュメントを自動生成するには、モジュールディレクトリ内でterraform-docsを実行するだけです。通常はREADMEにドキュメントを埋め込む形で利用します。先の例のようにREADMEにブロックコメントを用意し、terraform-docsコマンドを実行すると、そのブロック内に生成結果が挿入されます。この方式により、READMEの導入部や説明部分は手動で維持しつつ、変数・出力表だけを自動更新できます。

複数のモジュールを含むプロジェクトでは、--recursiveオプションを使うとサブディレクトリもまとめて処理できます。例: terraform-docs markdown table --recursive ./。これによりルートのREADMEだけでなく、各サブモジュールのREADMEにも一括でドキュメントを追加できます。CIパイプラインやプレコミットフックと組み合わせれば、コード変更時に自動でドキュメントが更新される仕組みを構築できます。

Terraformモジュールのディレクトリ構造とterraform-docsの連携

terraform-docsはモジュールルートのディレクトリ構造を前提に動作します。主にTerraformファイル（.tf）が置いてあるディレクトリでコマンドを実行し、同階層のREADMEや設定ファイルを参照します。モジュールのルートに.terraform-docs.ymlを置き、そのディレクトリでterraform-docs .と実行すると、そのモジュール内の情報がまとめて処理されます。

READMEテンプレートへの自動挿入方法: 注釈（BEGIN_TF_DOCS）を使った更新

READMEにドキュメントを自動挿入するには、あらかじめマーカーコメントを設置します。たとえば<!-- BEGIN_TF_DOCS -->と<!-- END_TF_DOCS -->で囲む形式です。このテンプレートは設定ファイルのoutput.templateで指定できます。例：

output: file: README.md mode: inject template: |-  {{ .Content }} 

この設定により、実行時にREADME内の同じマーカー間が置換され、それ以外の部分はそのまま残ります。これで、紹介文や例など手動で記載したセクションと、自動生成部分を区別できます。

モジュール使用例の記述: inputs/outputs情報を含むドキュメント生成

生成されるドキュメントには通常、以下のセクションが含まれます：Requirements（Terraformバージョン要件）、Providers（プロバイダー要件）、Modules（サブモジュール）、Resources（リソース）、Inputs（入力変数）、Outputs（出力値）などです。これらのセクションで各種情報を網羅できます。READMEの「使用例」セクションには、必要に応じて具体的なコード例や説明を追加できます。

複数モジュールプロジェクトでの実行例: 再帰オプションによる一括更新

複数モジュールを含むプロジェクトでは、Monorepo運用が可能です。モノリポジトリのルートからterraform-docs --recursiveを実行すると、サブディレクトリ内のモジュールも再帰的に処理されます。これにより、複数モジュールのREADMEを一括で最新化できます。各モジュールごとにREADMEや設定ファイルを準備しておけば、まとめて更新できるので管理が効率化されます。

ドキュメント生成時に含まれる内容: プロバイダー、リソース、例などの説明

terraform-docsによるドキュメント生成では、モジュールの基本情報から各セクションの詳細まで自動的に作成されます。特に重要なのがInputsやOutputsで、これらはMarkdown表にまとめられます。必要に応じて、ModulesやProvidersセクションも含めることで、モジュールが依存する情報を網羅できます。たとえば--showオプションでプロバイダー情報を追加することも可能です。

GitHub ActionsでTerraform-docsを自動実行する方法: CI/CDパイプラインでの設定例を紹介

GitHub Actionsを使うと、リポジトリにコードがプッシュされるたびに自動でterraform-docsを実行できます。terraform-docs用の公式GitHub Action「terraform-docs/gh-actions」が提供されており、ワークフローYAMLで以下のように設定します。

name: Generate terraform docs on: [pull_request] jobs: docs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 with: ref: \${{ github.event.pull_request.head.ref }} - name: Render terraform docs uses: terraform-docs/[email protected] with: working-dir: . output-file: README.md output-method: inject git-push: "true"

上記例ではプルリクエスト発生時にTerraformモジュールのドキュメントを生成し、自動でそのブランチにコミットしています。output-method: injectによりREADME内の指定ブロックが更新され、git-push: "true"で生成結果がPRに反映されます。CIに組み込むことで、ドキュメントの更新漏れを防ぎ、常に最新の状態を保つことができます。

公式アクション以外にも、Dockerコンテナを使った自作ワークフローや、GitLab CI/CDでの実行も可能です。基本的にはterraform-docsコマンドを呼び出すだけなので、GitLabやCircleCIなど任意のCI環境で同様に実行できます。

さらに、ローカル開発ではpre-commitフックを使う方法も一般的です。.pre-commit-config.yamlにterraform-docsのフックを追加すれば、コミット時に自動的にドキュメントが更新されます。これにより、開発者が意識せずとも最新のドキュメントが維持されるようになります。

GitHub ActionsでTerraform-docsを実行するメリットと概要

GitHub Actionsに組み込むと、プルリクエストやmainブランチへのマージ時に自動でドキュメント生成が実行されます。これにより、ドキュメントの更新忘れを防止でき、常に最新のREADMEをリポジトリ上に保てます。自動生成結果をリポジトリにコミットすることで、レビュー段階で変更内容を確認できる利点もあります。

Terraform-docs公式GitHub Actionの使い方: ワークフロー設定例

公式アクションterraform-docs/gh-actionsを使ったワークフローの例を示します。以下はプルリクエスト発生時にREADMEを更新する一例です：

- name: Render terraform docs uses: terraform-docs/[email protected] with: working-dir: . output-file: README.md output-method: inject git-push: "true" 

このようにoutput-method: injectを指定すると既存READMEの該当ブロックに挿入し、git-push: "true"で自動的にコミットとプッシュを行います。

自動コミットとプルリクエスト更新設定: 出力内容の反映方法

terraform-docs/gh-actionsでは生成したドキュメントを自動コミットできます。上記例のgit-push: "true"を付けると、アクション実行後に生成結果がPRに追加されます。これによりレビュー画面で変更内容が確認できます。なおgit-pushを省略すると自動コミットされないため、注意して設定しましょう。

主なAction入力パラメータの説明: working-dir、output-file、output-methodなど

主な入力パラメータにはworking-dir（処理対象のモジュールパス）、output-file（更新するファイル名）、output-method（inject/replace）、config-file（使用する設定ファイル名）などがあります。たとえばworking-dir: "."で現在ディレクトリを指定し、output-file: README.mdでターゲットファイルを指定します。これらを設定することでアクションの挙動をカスタマイズできます。

その他のCIツールでの利用例: GitLab CI/CDでの実行例

GitHub以外のCIツールでも同様にterraform-docsを実行できます。例えばGitLab CIではジョブでscriptにterraform-docsコマンドを記述します：

script: - terraform-docs markdown table --output-file README.md --output-mode inject ./

このように設定すれば、パイプライン実行時に自動でドキュメントを生成・更新できます。他のCIでも基本的な考え方は同じです。

Terraform-docsコンテナ版の利用方法（Docker/Podman対応）: コンテナでの実行手順

Terraform-docsはコンテナイメージでも提供されており、環境構築なしで利用できます。公式のDockerイメージ（quay.io/terraform-docs/terraform-docs）を使えば、ホストのTerraformコードをマウントして実行できます。例えば以下のように実行します：

docker run --rm -v "$(pwd):/terraform-docs" quay.io/terraform-docs/terraform-docs:latest markdown /terraform-docs

このコマンドでは、ホスト側のカレントディレクトリをコンテナ内の/terraform-docsにマウントし、Markdown形式でドキュメントを標準出力に出力します。--rmオプションで終了時にコンテナを自動削除します。

また、-u \$(id -u)オプションを付けてコンテナ内の実行ユーザーをホストユーザーに合わせられます。こうすることで生成されたファイルの所有者をホスト側ユーザーに揃えられます。Podmanでも同様のコマンドでイメージを実行できます。

コンテナ版の利点は、TerraformやGoをホストにインストールする必要がない点です。CI環境などで依存関係を簡素化でき、同じイメージを使うことでバージョンの違いによる問題を防げます。一方で、初回のイメージ取得に時間がかかることや、マウント時のファイル権限に注意が必要です。

公式Dockerイメージの利用方法: ボリュームマウントを使った実行例

Terraform-docs公式イメージはQuay.ioで公開されています。先述の例の通り、ホストの作業ディレクトリをコンテナにマウントして実行します。例：docker run --rm -v "$(pwd):/terraform-docs" quay.io/terraform-docs/terraform-docs:latest markdown /terraform-docs。これにより、ホスト側のコードを元にドキュメントが生成されます。

Podmanを使った実行方法: Dockerコマンドとの互換例

Podmanでもほぼ同様のコマンドで実行できます。docker run の代わりに podman run を使い、同じオプションを指定します。たとえば podman run --rm -v "$(pwd):/terraform-docs" quay.io/terraform-docs/terraform-docs:latest markdown /terraform-docs のように実行します。-u \$(id -u)も同様に使えます。

実行時のユーザー権限とボリュームマウント: –userオプションの利用

上記コマンドで -u \$(id -u) を指定すると、コンテナ内のプロセスがホストユーザーと同じUIDで実行されます。これにより生成されるファイルの所有者がホストユーザーに揃い、パーミッション関連のトラブルを防ぎます。マウント時はホストパスを正しく指定し、ファイルを書き込める権限があることを確認してください。

コンテナ版利用のメリット: 環境依存性の排除と容易なバージョン管理

コンテナ版のメリットは、依存環境をコンテナに閉じ込められる点です。TerraformやGoなどのツールをホストにインストールする必要がなく、全てコンテナ内で完結します。CI環境でも同じコンテナを使うことで必ず同じバージョンが実行され、環境差による動作不具合を防げます。バージョンアップもイメージタグを変えるだけで簡単です。

コンテナ版利用時の注意点: パーミッションや環境設定

注意点として、ファイルシステムのマウント時にはホストのパーミッション設定に依存することがあります。特にWindowsや特殊なファイル共有環境では権限がうまく適用されない場合があります。また、コンテナ内では通常rootユーザーで実行されるため、必要に応じて-uオプションでユーザーを切り替えましょう。環境変数やネットワーク設定もコンテナ側で独立しているため、必要な設定は明示的に指定します。

よく使うTerraform-docsのオプション・コマンド一覧: 主要フラグと使い方を解説します

terraform-docsには多くのオプションがありますが、よく使うものをいくつか紹介します。まず出力制御系では、--output-fileで出力先ファイルを指定し、--output-modeで書き込み方式（inject/replace）を指定できます。これにより生成ドキュメントの保存先や挿入方法を制御します。--header-fromや--footer-fromを使うと、ヘッダー用やフッター用のファイルを指定して内容を追加できます。

セクション制御系では--hideと--showが便利です。たとえば--hide requirementsと指定するとRequirementsセクションが生成されなくなります。--recursiveを付けるとサブモジュールも再帰的に処理でき、--sortで項目名順にソートして出力できます。これらオプションを組み合わせることで、必要な情報だけを整理してドキュメント化できます。

例: terraform-docs markdown table --output-file README.md --output-mode inject --recursive のように実行します。このコマンドはMarkdownテーブルを生成し、README.mdにinjectで挿入し、サブモジュールも再帰的に処理します。

–output系オプションの使い方: ファイル名や出力方法（inject/replace）の指定

--output-fileで出力先のファイルパスを指定し、--output-modeで挿入方式を選びます。injectを選ぶと既存ファイルの特定ブロックに挿入し、replaceを選ぶとファイル全体を新しい内容で置き換えます。たとえば--output-file README.md --output-mode replaceとすると、README.md全体が新しいドキュメントに置換されます。

セクション選択オプションの使い方: –hide/–showで出力するセクションを制御

--hideにセクション名を指定すると、そのセクションが生成対象から除外されます。逆に--showに指定したセクションのみを出力することもできます。たとえばterraform-docs markdown table --hide requirements,providersとすると、RequirementsとProvidersセクションがドキュメントに含まれません。これにより、不要な情報を簡単に除外できます。

–recursiveオプションの使い方: サブモジュール配下のドキュメントも同時生成

--recursiveを指定すると、指定ディレクトリ配下のすべてのTerraformモジュールを再帰的に処理します。デフォルトではサブディレクトリは無視されますが、--recursiveを付けることで子モジュールのREADMEも一括生成できます。モノリポジトリで複数モジュールを管理している場合に便利なオプションです。

–sortオプションの使い方: 出力項目をソートして表示

--sortを付けると、生成される項目（入力変数や出力値）が名前順にソートされます。デフォルトで有効になっていますが、必要に応じて明示的に指定できます。また--sort-byでソート基準（名前、必須、型など）を指定することも可能です。ソートを有効にすると、ドキュメントが整理されて読みやすくなります。

その他の便利オプション: –lockfile, –read-comments, –no-colorなど

その他にも便利なオプションがあります。--lockfileは.terraform.lock.hclファイルを読み込むかを指定します。--read-commentsを付けるとTerraformコード内のコメントが説明文に含まれます。--no-colorは色付き出力を無効にします。これらは特殊な用途で役立つオプションです。

Terraform-docs活用例・ベストプラクティス: README自動生成など具体的な導入事例を紹介

terraform-docsの活用例としては、モジュールのREADMEを自動生成するケースが一般的です。モジュールの利用方法や説明文は手動で記述し、変数・出力セクションだけterraform-docsで自動生成するパターンです。以下はREADMEの例です：

# Terraform Module
Requirements
（手動で記載） <!-- BEGIN_TF_DOCS -->
Requirements | Name | Version |
|------|---------| | terraform | >= 1.0.0 | ... (変数・出力の表) ... <!-- END_TF_DOCS -->
Usage
（手動で記載）

上記例では<!-- BEGIN_TF_DOCS -->と<!-- END_TF_DOCS -->で囲まれた部分にterraform-docsで生成されたテーブルが挿入されます。これによりREADMEの他部分はそのままに、必要な箇所だけを最新の情報に保てます。

さらに、pre-commitフックを使ってローカル開発時に自動更新する方法もあります。.pre-commit-config.yamlにterraform-docsのフックを設定すると、コミットのたびにドキュメントが生成されます。こうすることで、開発者が意識しなくても常に最新のドキュメントが維持されます。

実際の導入事例としては、複数モジュールを含むMonorepoで全モジュールのREADMEを一括更新する運用があります。例えば、全モジュールに共通のフッターやテンプレートを設定ファイルで管理し、CIで全モジュールのドキュメントを更新することで運用が簡略化されます。オープンソースプロジェクトでもこのパターンが採用されており、Terraform-docsを使ってREADMEの雛形を自動生成するベストプラクティスが多数紹介されています。