2026年6月20日

Terraform Cloud（HCP Terraform）の設定とリモートstateの管理

バックアップ・監視

Terraform Cloud（現在の名称は HCP Terraform）を使うと、手元の terraform.tfstate をクラウド上のワークスペースへ移し、ロック・履歴・アクセス権をまとめて管理できます。この記事では、組織とワークスペースの作成、cloud ブロックによる接続、既存のローカルstateの移行、変数と認証情報の置き場所、stateを他の構成から参照する方法までを、つまずきやすい点と確認方法を添えて説明します。

Terraform Cloud と HCP Terraform の関係

HashiCorp は2024年に Terraform Cloud の名称を HCP Terraform に改めました。ログイン先のURL（app.terraform.io）や Terraform の設定の書き方は基本的に同じで、ドキュメントや画面では新しい名称が使われています。古い記事やブログで「Terraform Cloud」と書かれていれば、同じサービスのことだと考えて差し支えありません。

料金プランと無料枠の内容は何度か改定されており、旧来の無料プランの扱いも変わっています（2026年10月現在）。管理できるリソース数やチーム機能の範囲はプランによって異なるため、契約前に HashiCorp 公式の料金ページで最新の条件を確認してください。この記事では料金には触れず、どのプランでも共通する基本の使い方に絞ります。

自前でstateを管理する方法（S3＋ロック用のテーブルなど）と比べたときの利点は、主に次の3点です。

stateのロックが自動でかかり、2人が同時に apply してstateが壊れる事故を防げる
stateのバージョン履歴が残り、いつ・誰の実行で何が変わったかを画面で追える
stateファイルを各自のPCに置かずに済み、中に含まれる機密値の拡散を抑えられる

事前に用意するもの

Terraform CLI（cloud ブロックは Terraform 1.1 以降で使えます。新しめの版を推奨）
HCP Terraform のアカウント
管理対象のクラウド（AWS など）の認証情報

組織とワークスペースを作る

HCP Terraform にログインしたら、まず組織（Organization）を作ります。組織は請求とメンバー管理の単位で、その下にワークスペースを作ります。

ワークスペースは「1つのstateと、それに紐づく変数・実行履歴」の単位です。本番と検証を同じワークスペースに混ぜると、検証の変更が本番のstateを書き換える原因になるため、環境ごとに分けるのが基本です。たとえば wordpress-prod と wordpress-staging のように、用途と環境が名前で分かるようにしておきます。

ワークスペース作成時には、ワークフローの種類を選びます。画面上の表記は変わることがありますが、考え方は次の3つです。

VCS連携：GitHub などのリポジトリと結び付け、プルリクエストで plan、マージで apply する
CLI主導：手元の terraform plan / apply から実行し、処理とstateをHCP Terraform側に置く
API主導：独自のパイプラインから API で実行する

最初は CLI主導で始め、慣れてからVCS連携に切り替える進め方が分かりやすいでしょう。以下の手順も CLI主導を前提にしています。

CLI からログインする

手元の端末で次を実行すると、ブラウザでAPIトークンの発行画面が開きます。発行したトークンを端末に貼り付けると、ユーザーのホームディレクトリ配下の認証情報ファイルに保存されます。

terraform login

CIなど対話できない環境では、環境変数でトークンを渡せます。変数名はホスト名のドットをアンダースコアに置き換えた形です。

export TF_TOKEN_app_terraform_io="your-api-token"

トークンはstateを読み書きできる強い権限を持ちます。リポジトリにコミットしない、CIではシークレット機能に格納する、使わなくなったら画面から失効させる、の3点を守ってください。

cloud ブロックでワークスペースに接続する

Terraformの設定に cloud ブロックを追加します。backend ブロックと同時には書けないので、既存の backend "s3" などがある場合は置き換えます（移行手順は次の章で説明します）。

terraform {
  required_version = ">= 1.6.0"

  cloud {
    organization = "your-org"

    workspaces {
      name = "wordpress-prod"
    }
  }

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

書き換えたら初期化します。

terraform init

ここでのつまずきは、組織名やワークスペース名の綴り違いと、トークンが別の組織のものになっているケースです。init がエラーになったら、まず画面上の組織名と organization の値が一致しているか、terraform login をどのアカウントで行ったかを見直してください。

既存のローカルstateを移行する

すでにローカルや S3 でstateを管理している場合は、移行前にstateファイルのバックアップを取ります。ローカルなら terraform.tfstate をコピー、S3 ならバケットのバージョニングが有効かを確かめておきます。

# 移行前の状態を保存しておく
terraform state pull > backup-before-migration.tfstate

そのうえで backend ブロックを cloud ブロックに置き換えて terraform init を実行すると、既存のstateをワークスペースへ移すかどうかを尋ねられます。了承するとstateがアップロードされます。

移行後は次の2点で結果を確認します。

terraform state list   # 管理中のリソース一覧が移行前と同じか
terraform plan         # 変更なし（No changes）になるか

plan で大量の作成や削除が出る場合は、別のワークスペースに接続している、あるいは認証情報が別アカウントを向いている可能性が高いので、apply せずに設定を見直してください。

実行モードと認証情報の置き場所

CLI主導のワークスペースでも、既定では plan と apply は HCP Terraform 側のサーバーで実行されます（リモート実行）。ここで多くの人が戸惑うのが、「手元では動いたのにリモートで認証エラーになる」という症状です。手元の ~/.aws/credentials や環境変数は、リモートの実行環境には渡らないためです。

対処は2通りあります。

ワークスペースの変数に、クラウドの認証情報を「環境変数」として登録し、機密（Sensitive）として扱う
OIDC を使う動的な認証情報（Dynamic Provider Credentials）を設定し、長期のアクセスキーを置かない

長期キーを登録する方法は手軽ですが、漏えい時の影響が大きくなります。AWS などが対応していれば、2の方法を検討する価値があります。設定手順はクラウドごとに異なるため、HCP Terraform の公式ドキュメントの該当ページに沿って進めてください。

また、リモート実行では作業ディレクトリの内容がアップロードされます。大きなファイルや不要なディレクトリを送らないよう、.terraformignore で除外できます。

実行だけは手元で行い、stateの保管とロックだけをHCP Terraformに任せる「ローカル実行」に切り替えることもできます。ワークスペースの設定から実行モードを変更します。既存の手元の認証情報をそのまま使いたい場合の移行期には便利です。

変数の扱い

ワークスペースの変数には2種類あります。

Terraform変数：variable ブロックに対応する値（instance_type など）
環境変数：実行環境に設定される値（AWS_REGION やプロバイダの認証情報など）

データベースのパスワードのような値は「Sensitive」にしておくと、画面やAPIから値を読み出せなくなります。ただし、Sensitive にしても、その値をリソースの属性として使えばstateの中には記録されます。stateを読める人の範囲を絞ることが、機密値を守るうえで最も効く対策です。

複数のワークスペースで同じ値を使う場合は、変数セット（Variable Sets）にまとめると、更新漏れを防げます。

stateを他の構成から参照する

ネットワーク用とアプリ用のように構成を分けた場合、アプリ側からネットワーク側の出力（サブネットIDなど）を読みたくなります。HCP Terraform では、tfe プロバイダの tfe_outputs データソースで、別ワークスペースの出力を読むのが推奨されています。

data "tfe_outputs" "network" {
  organization = "your-org"
  workspace    = "network-prod"
}

resource "aws_instance" "web" {
  # 出力は values の下にあり、sensitive として扱われる
  subnet_id = data.tfe_outputs.network.values.public_subnet_id
  # ...
}

tfe プロバイダ自体もHCP Terraformへの認証（APIトークン）を必要とします。トークンの渡し方は実行環境によって変わるため、プロバイダのドキュメントで確認してから使ってください。

参照される側のワークスペースでは、他のワークスペースからのstate参照を許可する設定が必要です。許可範囲は「組織全体」と「指定したワークスペースのみ」を選べるので、必要なワークスペースだけに絞るのが安全です。

運用で見ておきたいポイント

ロックの解除：実行が途中で止まりロックが残った場合は、画面から解除できます。誰かが実行中でないことを確かめてから解除してください。
stateの履歴：ワークスペースの State の画面から過去のバージョンを確認できます。問題が起きたときは、まず差分を見て、どの実行で変わったかを特定します。
権限：チームごとにワークスペースの権限（読み取りのみ、plan まで、apply まで等）を分けられます。利用できる粒度はプランによって異なります。
代替手段：ライセンスやベンダーの方針が気になる場合、OpenTofu などの選択肢もあります。移行する場合はstateの互換性と機能差を検証環境で確かめてから判断してください。

まとめ

Terraform Cloud は HCP Terraform に名称が変わっており、設定方法は cloud ブロックが基本
環境ごとにワークスペースを分け、stateの混在を防ぐ
移行前に terraform state pull でバックアップし、移行後は plan が No changes になるかで確認する
リモート実行では手元の認証情報が使われないため、ワークスペース変数か動的な認証情報を設定する
Sensitive 指定でもstateには値が残るので、stateを読める人を絞る
別ワークスペースの出力は tfe_outputs で参照し、共有範囲は必要最小限にする