HCP Terraforを試してみて感じた使用感

Posted at 2026-03-17

HCP Terraformについて色々と調査・検証したので、忘備録を兼ねて記事にしました。こちらの続きみたいになっているので、もし参考にされるのでしたらそっちもどうぞ。

想定される使用感

初期セットアップの流れ

HCP Terraformの開始

この章では、HCP Terraformのアカウント作成から実際にHCP Terraformのコンソール画面に入るまでを説明します。

こちらより、"Create an account"を押下します。
次の画面でアカウント登録に使うメールアドレスを入力し、"Continue→"を押下します。
次の画面でパスワードを入力し、"Create account"を押下します。
次の画面では利用規約などが表示されるので、最低限"Required"とあるチェック項目にチェックし、"Continue"を押下します。
登録したメールアドレスに"HashiCorp Cloud Platform no-reply@activation.email.hashicorp.com"より"Verify your email"というタイトルのメールが届くため、そこの"Verify"を押下する。
"Create a new organization"の画面になったら成功です。

Organizationsの設定

コンソール画面に入った後、実際にHCP Terraformを使うにはOrganizationsの設定が必要です。以下の手順で設定してください。

"Organizations"の画面が表示されている場合、"Create organization"を押下します。"Create a new organization"の画面が表示されている場合、2. に進んでください。
"Business"と"Personal"が選択できます。今回はFree版を使うため、"Personal"を選択してください。その後、"Terraform organization name"でOrganizationの名前を入力してください。"Email address"にアカウント登録に使ったメールアドレスが入力されていることを確認した後、"Create organization"を押下してください。

WorkspacesおよびGitHubとの連携設定

Organizationを作成したら、実際にterraformを動かす環境であるWorkspaceを設定します。なお、Projectは初期より"Default Project"という名前のものがあります。この章ではこれを使うことを前提とします。また、初めてWorkspacesの設定を行う場合、同時にGitHubとの連携も設定できます。このとき、連携したいGitHubアカウントにサインインしていることを確認してください。

画面左の"Workspaces"欄を押下してください。
"Workspaces"画面中央の"Create a workspace"を押下してください。
"Create a new Workspace"画面に移動します。ここで"Choose your workflow"として3つ選択できる項目があります。今回はGitHubのリポジトリと連携させるため、一番左の"Version Control Workflow"を選択してください。
"Create a new Workspace"画面に移動します。"Connect to a version control provider"欄の"GitHub"を選択し、"Version"欄の"GitHub.com"を選択してください。
以下の画面がポップアップされます。"Verify your GitHub identity"の欄に連携したいGitHubアカウントが表示されていることを確認し、画面下の"Authorize Terraform Cloud"を押下してください。
以下の画面が表示されます。"Install"を押下してください。
ポップアップ画面が閉じ、以下の画面に遷移します。"Organization"に自分が使いたいユーザーが表示されていることを確認してください。次に、"Repository"より、連携したいリポジトリを選択してください。
リポジトリを選択すると、以下の画面に遷移します。"Workspace Name"でWorkspace名を入力し、画面下の"Create"を押下してください。
以下の画面が表示されたら成功です。

運用方針について

HCP Terraformの設定について

HCP Terraformを効果的に運用するためには、事前に設定方針を決めておくことが重要です。

HCP Terraform内リソースの命名規則

Projects名やWorkspaces名には、用途や環境が分かるような命名規則を設けると管理が容易です。

Projects名
- 案件のどこの部分を開発するかを記載する。(例：sales、customerなど)
- 開発段階を記載。（例：dev、stgなど）
Workspaces名
- 開発段階を記載。（例：dev、stgなど）
- 作成しているリソース情報を記載。(例：network、ec2など)
- 開発担当者を記載。(例：Sato、Yamadaなど)

このように、Projects名やWorkspaces名を統一させ、何をしているものかを記載することは非常に重要です。名前の付け方はこれら機能をどれだけ分けるかによっても決まるものなので、案件の大きさによって決めてください。
実際にどのように分け、どのように構成するかは後述する「Organizations・Projects・Workspacesの構成」で詳細を述べます。

Organizations・Projects・Workspacesの構成

「主な機能説明」の章でも説明したように、HCP Terraformでは、Organizations、Projects、Workspacesの3階層でリソースを管理します。
これらの機能を分割することで、管理単位ごとに開発環境を分けることができます。
どの粒度で分けるかは、開発を行う案件の規模に合わせてください。

ここで、「Acme株式会社」のシステム開発を行う場合のサンプルを考えます。このプロジェクトは以下のような前提です。

プロジェクト概要: 社内システム向けのクラウド基盤をHCP TerraformとGitHubで継続的に管理する
チーム構成: インフラ基盤、アプリ基盤、監視基盤の3チームで分担する
環境方針: dev(開発) と prd(本番) の2環境で運用する

Organizations・Projectsの分け方

まず、OrganizationsとProjectsを分けることを考えます。
このサンプルでは、以下のようにOrganization配下にチーム単位のProjectを置きます。

Organization: acme-corp
 ├── Project: infrastructure
~~~
 ├── Project: app
~~~
 └── Project: monitoring
~~~

この構成の分割方針は、以下の通りです。

Organizationの分け方
- 会社・部門単位で1つにまとめる
Projectsの分け方
- infrastructure / app / monitoring のように、責務を持つチーム単位で分ける

この構成の主な利点は以下です。

プロジェクトで1つのOrganizationを使うため、大枠での変数共有が可能
チームごとにProjectを分けるため、責務と管理範囲が明確になる

この構成はあくまでも一例です。他の例としては、devとprdの環境をProjectで分ける構成も考えられます。また、開発チームの機密性保持のために1プロジェクトで複数のOrganizationを使うこともあります。各構成をどのようにするかは、チームメンバーや扱うリソース数で決まります。案件内容や状況に応じて構成を決定してください。

1. Workspaceの分け方(環境ごと)

Workspaceはplan/applyを実行する場所であり、またtfstateの管理も行います。そのため、Workspaceをどのように扱うのかは開発を行う上で重要となります。
はじめに、dev / prd のように、環境単位でWorkspaceを分ける方法を紹介します。これは、最も基本的な分け方です。各環境のWorkspaceはチームで共有します。

構成例

Organization: acme-corp
 ├── Project: infrastructure
 │     ├── Workspace: dev（開発環境：全員で共有）
 │     ├── Workspace: prd（本番環境：基本的にチームリーダーのみが操作）
 ~~~

運用フロー

開発者はローカルでコード編集
共通の開発ブランチ（developなど）にプッシュ・プルリクエスト作成
devでplan/applyして確認
問題なければprdへプロモート

Settings (Version Control)での設定

VCS branch: develop（開発ブランチ）
Terraform Working Directory: dev/ など、環境ディレクトリを明示

メリット

構成がシンプルで、初期導入しやすい
Workspace数を抑えられ、管理コストが低い

デメリット

同一環境での同時作業が競合しやすい
ステートロック待ちが発生しやすい
tfstateが大きくなりやすい
個人で大きな試行錯誤をしづらい

2. Workspaceの分け方(環境ごとだがdevだけ個人)

次に紹介するのは、prd は共有しつつ、dev だけ開発者ごとにWorkspaceを分ける方法です。個人検証の自由度と本番前の統制を両立できます。

構成例

Organization: acme-corp
 ├── Project: infrastructure
 │     ├── Workspace: prd（本番環境：基本的にチームリーダーのみが操作）
 │     ├── Workspace: dev-sato（佐藤さんの開発環境）
 │     ├── Workspace: dev-yamada（山田さんの開発環境）
 │     ├── Workspace: dev-tanaka（田中さんの開発環境）
 ~~~

運用フロー

各開発者は自分専用のdev-* Workspaceで検証
自分のブランチにプッシュし、plan/applyで動作確認
問題なければプルリクエストを作成
レビュー後、共通のprdへ反映

Settings (Version Control)での設定

VCS branch: feature/sato-*、feature/yamada-*など個人ごとに分ける
Terraform Working Directory: dev/など、環境ディレクトリを明示

メリット

個人の試行錯誤がしやすく、他メンバーへ影響しにくい
共有環境（prd）の安定性を保ちやすい
誰の検証かをWorkspace単位で追跡しやすい
Ownerタグに付ける名前変数を各Workspaceで設定することでリソース作成者を特定しやすい

デメリット

Workspace数が増え、管理が煩雑になりやすい
個人devと共有環境の差異が生まれる可能性がある
未使用Workspaceの棚卸しが必要

3. Workspaceの分け方(モジュールごと)

最後に紹介するのは、network、app、db など、Terraformの責務（モジュール/コンポーネント）単位でWorkspaceを分ける方法です。必要に応じて各モジュール内でdev/prdをさらに分離します。

構成例

Organization: acme-corp
 ├── Project: infrastructure
 │     ├── Workspace: network-dev
 │     ├── Workspace: network-prd
 │     ├── Workspace: app-dev
 │     ├── Workspace: app-prd
 │     ├── Workspace: db-dev
 │     └── Workspace: db-prd
 ~~~

運用フロー

各開発者は変更対象モジュール（例:network-dev）のWorkspaceだけで検証
- 依存モジュールがある場合はterraform_remote_stateで連携確認
問題なければプルリクエストを作成
レビュー後、モジュール単位で段階的にprdへ反映

Settings (Version Control)での設定

VCS branch: feature/dev-network、feature/dev-appなどモジュールごとに分ける
Terraform Working Directory: dev/network、dev/app、dev/db などモジュールごとに設定

メリット

変更の影響範囲をモジュール単位で限定できる
不要なplan/applyを減らし、実行時間を短縮しやすい

デメリット

Workspace数が増えやすい
モジュール間依存の設計が不十分だと運用が複雑になる
変数・権限の設計負荷が高い

以上のように、チームでWorkspaceをどう使っていくかは、やり方によってそれぞれ利点欠点があります。基本的にはモジュールごとにWorkspaceを分ける運用を推奨します。しかし、プロジェクト規模やチーム人数が小さい場合は他の分け方もメリットがあります。自身が実施する規模や人数に応じて使い分けてください。また、運用を開始した後も、状況に応じて柔軟に構成を見直すことも重要です。

Terraformコードに関わる設定について

Terraformコードの管理や運用に関しても、以下のような方針を決めておくと良いでしょう。

変数管理の方針

可変の値はvariablesで変数定義する
パスワードなどの機密情報はHCP TerraformのVariables上で管理し、「Sensitive」属性を付与する
変数の値を設定する際は、共通変数はProjectsのVariable sets、個別変数はWorkspacesで設定

ポリシー管理

SentinelやOPAによるPolicy as Codeを活用し、組織のルールを自動チェック
- これはOrganizationsの単位での設定となることに注意してください
Freeプランではポリシー数や適用範囲に制限があるため、重要なルールから優先的に設定

ディレクトリ構成・モジュール化

環境ごとにディレクトリを分ける（例：/dev、/stg、/prd）
共通リソースはmodulesディレクトリでモジュール化し、各環境から呼び出す

バージョン管理

required_versionやProviderのバージョンをversions.tfで明示
コードの変更は必ずGitで管理し、プルリクエストベースでレビュー・マージ
Workspacesの設定でTerraform versionを指定する

これらの方針を事前に決めておくことで、チームでのTerraform運用がスムーズになります。

terraformコマンドの実行ユーザー

HCP Terraformでは、terraformコマンドの実行方法が重要です。

クラウドリソースを操作する際、HCP Terraformから実行するterraformコマンドに対して、どのように認証を行うかを決める必要があります。主に以下の2つの方法があります。

1. HCP Terraform用の実行ユーザーを作る

最もシンプルな方法は、HCP Terraform専用のIAMユーザーを作成し、そのアクセスキーとシークレットアクセスキーをHCP Terraformの環境変数に設定する方法です。

メリット

設定がシンプルで理解しやすい
すぐに導入できる
追加のロール等のリソースが不要

デメリット

アクセスキーが漏洩すると悪用される可能性が高い
長期的な静的認証情報の管理が必要
どのWorkspaceからの操作か判別しづらい
定期的なキーの更新作業が必要

推奨される使用場面

検証・学習目的の一時的な環境
小規模なプロジェクトで厳格なセキュリティ要件がない場合
本番環境では原則として推奨しない

2. AssumeRoleを使い実行用ロールを経由するようにする

この方法では、HCP Terraform用の最小権限を持つIAMユーザーを作成し、実際の操作は別のIAMロールを引き受けて実行します。これにより、一時的な認証情報を使用し、権限の分離と監査が容易になります。

メリット

一時的な認証情報を使用（デフォルトで1時間有効）
基盤ユーザーは最小権限、実行ロールのみが強い権限を持つ
環境ごとに異なるロールを使用可能
基盤ユーザーのキーのみ管理すればよい

デメリット

設定がやや複雑
ロールとポリシーの理解が必要
初期構築に時間がかかる

推奨される使用場面

本番環境での運用
複数環境（dev/stg/prd）を管理する場合
セキュリティ要件が厳格なプロジェクト
組織のガバナンスが求められる場合

基本的には、AssumeRoleを使用する方法（方法2）を推奨します。特に本番環境や長期運用するプロジェクトでは、初期の複雑さを上回るセキュリティメリットがあります。

一方、学習目的や短期的な検証環境では、方法1のシンプルな実行ユーザー方式でも問題ありません。ただし、その場合でも最小権限の原則を守り、定期的なキーローテーションを実施してください。

よくある課題と対処法

HCP Terraformを使用する際に遭遇しやすい問題とその解決方法をまとめます。

1. plan/applyが失敗する

よくある原因

認証情報の設定ミス
AWSやAzureなどのクラウドプロバイダーへの認証情報が正しく設定されていない、または有効期限が切れている場合に発生します。
Terraform Working Directoryの設定ミス
"Settings"で指定したディレクトリにTerraformファイルが存在しない、またはパスの記述が誤っている場合に発生します。
バージョンの不一致
ローカルで動作していたコードが、HCP Terraformで指定しているTerraformバージョンでは動作しない場合があります。
プロバイダーのダウンロード失敗
ネットワーク問題やプロバイダーレジストリの一時的な障害により、必要なプロバイダーがダウンロードできない場合があります。

対処法

Runsの詳細ログを確認
Workspaces > Runs から失敗したRunを選択し、詳細なエラーメッセージを確認します。多くの場合、ここにエラーの原因が記載されています。
認証情報の再確認
Environment variableに設定したAWS_ACCESS_KEY_IDやAWS_SECRET_ACCESS_KEYなどが正しいか確認します。AssumeRoleを使用している場合は、ロールの信頼関係やポリシーも確認してください。
Terraform Working Directoryのパスを確認
Settings > General または Settings > Version Control で設定したパスが正しいか確認します。先頭の/の有無にも注意してください。
Terraformバージョンを確認
Settings > General の"Terraform Version"で、ローカルで動作確認したバージョンと同じバージョンが指定されているか確認します。必要に応じてrequired_versionをversions.tfに明記してください。

2. 変数が正しく反映されない

よくある原因

変数の優先順位
HCP Terraformでは、Workspaces > VariablesがProjects > Variable setsより優先されます。同じ変数名で両方に設定されている場合、Workspacesの値が使用されます。
変数の型が正しくない
リストやマップなどの複合型を設定する際に、HCLチェックボックスをONにしていないと、文字列として解釈されてしまいます。
Terraform variableとEnvironment variableの混同
Terraformコード内で使う変数は"Terraform variable"として設定する必要があります。"Environment variable"はTerraform実行環境の環境変数です。
変数名のタイポ
変数名の大文字小文字やスペルミスにより、意図した変数が参照されていない場合があります。

対処法

変数の設定箇所を確認
"Projects > Settings > Variable sets"と"Workspaces > Variables"の両方を確認し、同じ変数名が複数箇所に定義されていないか確認します。
HCLチェックボックスの確認
リスト型やマップ型、boolean型の変数を設定する場合は、必ず"HCL"チェックボックスをONにしてください。例：["value1", "value2"]やtrueなど。
variables.tfとの整合性を確認
Terraformコード内のvariables.tfで定義されている変数名と、HCP Terraformで設定している変数名が完全に一致しているか確認します。
デフォルト値の有無を確認
variables.tfでデフォルト値が設定されている場合、HCP Terraformで変数を設定しなくてもエラーにはなりません。意図的にデフォルト値を上書きしたい場合は、HCP Terraformで明示的に設定する必要があります。

3. 実行が遅い

よくある原因

ステートファイルが大きい
管理しているリソース数が多いと、ステートファイルのダウンロードや解析に時間がかかります。
プロバイダーのダウンロード時間
実行のたびに必要なプロバイダーをダウンロードするため、プロバイダー数が多いと初期化に時間がかかります。
リモート実行のオーバーヘッド
HCP Terraformとの通信やジョブのキューイング待機時間により、ローカル実行に比べて若干のオーバーヘッドが発生します。
リソースの依存関係が複雑
Terraformがリソース間の依存関係を解決するのに時間がかかっている可能性があります。

対処法

Workspaceを分割する
大きなステートファイルを複数のWorkspacesに分割することで、各実行の対象リソースを減らします。例えば、ネットワーク、コンピューティング、データベースなど用途別に分けます。
不要なリソースをステートから削除
terraform state rmコマンドを使って、もう管理していないリソースをステートから削除します。ただし、実際のリソースは削除されないため注意してください。
モジュールの最適化
過度に細かいモジュール分割を避け、適切な粒度でモジュール化します。モジュールのfor_eachで大量のリソースを作成している場合は、設計を見直します。
依存関係の明示化
depends_onを適切に使い、不要な暗黙的依存関係を減らします。これにより、Terraformのグラフ解析が効率化されます。
並列実行数の調整（有料プランのみ）
有料プランでは、並列実行数を増やすことができます。Freeプランでは制限があるため、大規模プロジェクトでは有料プランへのアップグレードを検討してください。
ローカル実行との使い分け
頻繁に試行錯誤する開発初期段階では、ローカルでterraform planを実行し、ある程度固まってからHCP Terraformで実行することで、待ち時間を削減できます。

4. その他課題

GitHubとの連携に失敗する
WorkspaceよりGitHubと連携させる際、"Failed to install GitHub App Please disable pop-up blocker and try again"というエラーが発生することがあります。この場合、ブラウザのポップアップブロッカーが原因となっております。ブラウザの設定より、https://app.terraform.io:443からのポップアップ送信を許可してください。

これらの対処法を適用しても問題が解決しない場合は、HCP Terraformのサポートやコミュニティフォーラムに相談することをお勧めします。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up