Terraform コードと複数の HCP Terraform Workspaceを関連付ける方法

terraform コードと HCP Terraform の Workspace の関連付けに関する作業は、Workspace の初期設定時に実施すればほとんど意識することがないため、仕組みをご存じない場合もあると思います。今回はこの仕組みについて解説します。

基本知識: terraform ブロックで接続先の Workspace を指定する

terraform ブロック内に、下記のどちらかを指定することで HCP Terraform の Workspace に接続します。

• backend ブロック
• cloud ブロック

下記のドキュメントを見ると、cloud ブロックの利用が推奨されています。

Note: We introduced the remote backend in Terraform v0.11.13 and Terraform Enterprise v201809-1. As of Terraform v1.1.0 and Terraform Enterprise v202201-1, we recommend using HCP Terraform's built-in cloud integration instead. The cloud option supports an improved user experience and more features, such as structured run output mode, which displays your plan and apply results in a human-readable format.

backend / cloud ブロックの記載方法にはいくつかのパターンがあります。
特に 1 つの terraform コードを複数の Workspace に関連付けている場合は、接続先の Workspace を柔軟に切り替えられる方法を採用する必要があります。

以下、いくつかのパターンを解説します。

backend ブロック + .tfbackend ファイルを用いた接続先の切り替え

HCP Terraform に接続する場合は、backend タイプとして remote を指定します。
backend ブロックを空で定義しておき、.tfbackend ファイルを使用して接続先を切り替える方法があります。

main.tf

terraform {
  backend "remote" {}
}

example.tfbackend

hostname     = "app.terraform.io"
organization = "example-org" # Workspace の所属する Organization を記載

workspaces {
  name = "my-workspace"
}

この実装では、terraform init 時に -backend-config パラメータで接続先を切り替えできます。

terraform init -reconfigure -backend-config example.tfbackend

この際、-reconfigure も指定して、現在の state を切り替え先の state に反映しないよう注意が必要です。

環境ごとに .tfbackend ファイルを用意することで、下記のように接続先を切り替えられます。

# 開発環境
terraform init -reconfigure -backend-config dev.tfbackend

# 本番環境
terraform init -reconfigure -backend-config prod.tfbackend

cloud ブロック + タグを用いた複数 Workspace への接続

cloud ブロックの記載には様々なバリエーションがあります。

cloud ブロック使用時は、.tfbackend ファイルは使用できません。
何らかの指定で接続したい Workspace を絞り込んだ状態で workspace select を用いて切り替える必要があります。

タグで複数の Workspace を絞り込む

HCP Terraform の Workspace にはタグを指定できます。
cloud ブロックでタグを指定することで、そのタグが付与された複数の Workspace に接続できる状態を作ることができます。

タグには single-value 形式と key-value 形式があります。single-value 形式は古い方式で、今後は key-value 形式を利用することが推奨されています。

single-value 形式でのタグ指定

例えば、myapp-dev、myapp-staging、myapp-prod という 3 つの Workspace があり、それぞれに myapp という single-value タグが付与されている場合、下記のように記述します。

main.tf

terraform {
  cloud {
    organization = "example-org" # Workspace の所属する Organization を記載
    
    workspaces {
      tags = ["myapp"]
    }
  }
}

この設定により、myapp タグが付いた複数の Workspace に接続できる状態になります。

key-value 形式でのタグ指定

key-value 形式の場合、より柔軟な絞り込みが可能です。例えば、複数の Workspace に env: dev というタグを付与している場合は下記のようになります。

main.tf

terraform {
  cloud {
    organization = "example-org" # Workspace の所属する Organization を記載
    
    workspaces {
      tags = {
        env = "dev"
      }
    }
  }
}

project 引数による絞り込み

project 引数を使用すると、HCP Terraform の Project に紐づく Workspace に絞り込むことができます。
ただし project 引数単体では使用できず、tags (または name) の指定も必要なことに注意してください。

main.tf

terraform {
  cloud {
    organization = "example-org" # Workspace の所属する Organization を記載
    
    workspaces {
      project = "myapp"

      tags = {
          app = "myapp"
      }
    }
  }
}

この設定により、myapp という Project に所属する複数の Workspace に接続できる状態になります。

workspace select で接続先を切り替える

タグで複数の Workspace に接続できる状態を作った後、terraform workspace list コマンドで接続可能な Workspace の一覧を確認できます。

$ terraform workspace list
  myapp-dev
* myapp-staging
  myapp-prod

* が付いているのが現在選択されている Workspace です。

terraform workspace select コマンドを使用して、実際に接続する Workspace を切り替えます。

$ terraform workspace select myapp-prod
Switched to workspace "myapp-prod".

この方法により、同じ terraform コードで複数の環境を管理できます。

まとめ

HCP Terraform の Workspace への接続方法をいくつか紹介しました。

• backend ブロック + .tfbackend: 従来の方式。ファイルベースで接続先を管理
• cloud ブロック + タグ + workspace select: 推奨される方式。タグで複数の Workspace を絞り込み、コマンドで切り替え

複数環境を管理する場合は、cloud ブロックとタグを組み合わせた方法が柔軟で便利です。プロジェクトの要件に応じて、適切な方法を選択してください。