StatefileをAmazon S3からHCP Terraformに移行してみた(HCP Terraform API利用、VCS Driven Workflow)

佐藤雅樹

2025.03.17

TerraformのStatefileをS3から、HCP Terraform Workspace(VCS Driven Workflow)にHCP Terraform APIを使って移行してみます。

やってみた

ざっくりした流れは以下です。

S3からStatefileをダウンロード
HCP Terraform Workspaceを作成
HCP Terraform APIを使って、WorkspaceにStatefileをアップロード

ディレクトリ構成(移行前)

今回は以下のディレクトリ構成を例にします。

環境差異をtfvarsで表現するパターンです。それに伴い、backend設定もterraform.tfbackendで表現します。

.
├── envs/
│   ├── prod/
│   │   ├── terraform.tfvars
│   │   └── terraform.tfbackend
│   └── dev/
│       ├── terraform.tfvars
│       └── terraform.tfbackend
└── main.tf

backend切り替えや環境ごとのPlan・Applyは以下のように実施します。

terraform init -reconfigure -backend-config="envs/dev/terraform.tfbackend"
terraform plan -var-file envs/dev/terraform.tfvars
terraform apply -var-file envs/dev/terraform.tfvars

Terraformコード(移行前)

VPCを作成するシンプルなコードです。

main.tf

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 5.90.1"
    }
  }
  backend "s3" {}
}

provider "aws" {
  region = "ap-northeast-1"
}

variable "env" {
  description = "The environment name"
  type        = string
}

resource "aws_vpc" "example" {
  cidr_block = "10.0.0.0/16"

  tags = {
    Name = "${var.env}"
  }
}

envs/test/terraform.tfbackend

bucket  = "<Terraform Stateバケット名>"
region  = "ap-northeast-1"
key     = "<Statefileファイルパス>" # example: "hoge/terraform.tfstate"
encrypt = true

envs/test/terraform.tfvars

env = "dev"

HCP Terraformログイン

ローカルからHCP Terraformにログインします。

terraform login

Statefileをダウンロード

Statefileをローカルにダウンロードします。

Statefileの数分作業を繰り返します。

例

# AWS認証情報をセット
terraform init -reconfigure -backend-config="envs/dev/terraform.tfbackend"
terraform state pull > dev.tfstate

以下のようにファイルが保存されていればOKです。

dev.tfstate
prod.tfstate

HCP Terraform Workspaceの作成

HCP Terraformのコンソールを開きます。

Workspace -> New -> Workspace -> [任意のプロジェクト] -> Createの順に選択します。

workflow: Version Control Workflow
VCS Provider: 移行対象のVCS Provider
repository: 移行対象のrepository
Workspace Name: Workspace名 ※
Advanced options > Terraform Working Directory: Terraform実行ディレクトリ
※環境毎にWorkspaceを作成するため環境名(dev,prod)をつけることを推奨します

以下のようにVariableの設定を求められますので、必要な値を設定しています。

terraform.tfvarsの内容を設定するイメージです。

WorkspaceからAWSへアクセスするための、Variables Setも設定しておいてください。

Statefile移行前の操作ミスによるApplyを防止するために、WorkspaceをLockしておきます。

上記作業をStatefileの数分繰り返します。

例えば、prod.tfstateとdev.tfstateがある場合は、それぞれprod workspaceとdev workspaceを作成します。

HCP Terraform Tokenの準備

HCP Terraform APIを使うため、トークンを設定します。

terraform login実行済みの場合は、デフォルトでは以下にトークンが保存されています。

cat ~/.terraform.d/credentials.tfrc.json

出力例

{
  "credentials": {
    "app.terraform.io": {
      "token": "<トークン>"
    }
  }
}

トークンをシェル変数にセットします。

TOKEN=<トークン>

HCP Terraform APIを使用してStatefileを移行する

作成したWorkspaceにStatefileを移行します。

以下のAPIを利用します。

payload用のjsonファイルを準備します。

dev_payload.json

{
"data": {
    "type":"state-versions",
    "attributes": {
    "serial": 1,
    "md5": "<Statefileのmd5ハッシュ>",
    "state": "<Statefileをbase64エンコードした値>"
    }
}
}

data.serialはStatefileのserialと一致させる必要があります。

data.m5にセットする値は以下のコマンドで作成します。

md5sum dev.tfstate

出力例

690a3f8ae079c629494a52c68757d585  dev.tfstate

data.stateは値は以下のコマンドで作成します。

cat dev.tfstate | base64

出力例

 dGVycmFmb3JtLnRmc3RhdGUK

WS_ID="<Workspace ID>" # 「ws-」から始まるID、Workspace画面から確認可能
curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @prod_payload.json \
  https://app.terraform.io/api/v2/workspaces/$WS_ID/state-versions

Statefile移行が成功すると、HCP Terraform上からStatefileを確認できます。

この作業も、StatefileとWorkspace IDを変更して、Statefileの数分繰り返します。

動作確認

HCP Terraform上からPlanを実行して、差分が表示されないことを確認します。

Workspace上部のUnlockを選択しWorkspaceのlockを解除します。

New Run -> Run Type: Plan onlyの順に選択します。

Planが正常に実行されて、No changes(差分なし)になっていることを確認します。

一応VCSとの接続が正常に行われているか確認するため、適当なPull Requestを作成しました。こちらでもPlanが実行されることを確認できました。(vpcにタグを付けるPRのため、add,1になっています。)

これでStatefileの移行は完了です。

backendブロックの置き換え

最後に、terraform.backendの部分をterraform.cloudに置き換えましょう。

main.tf

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 5.90.1"
    }
  }
-  backend "s3" {}
+  cloud {}
}

VCSへのコミットも忘れずに行いましょう。

terraform.cloudの部分は、HCP Terraform上で実行する際は必要ありません。

次に紹介する「Tips: HCP Terraform移行後のローカルからのTerraform CLIの実行」で必要です。

Tips: HCP Terraform移行後のローカルからのTerraform CLIの実行

tfファイルの変更時にローカルからterraform planを実行して、変更差分を確認したいことがあると思います。

今までは、-backend-configと-var-fileを指定して環境を切り替えていました。

terraform init -reconfigure -backend-config="envs/dev/terraform.tfbackend"
terraform plan -var-file envs/dev/terraform.tfvars

移行後は、環境変数で切り替えることができます。

export TF_CLOUD_ORGANIZATION=<HCP Terraform Organizations名>
export TF_WORKSPACE=<ワークスペース名>
terraform plan

CLIで移行する

vars-fileで環境を切り替えるパターンだと、CLIで移行するのは少し手順が煩雑です。

おすすめは、上記で紹介したAPIを使う方法です。

逆に、環境毎ディレクトリを分けるパターン(env/dev/main.tf, env/prod/main.tfのような)ならCLIがおすすめです。

参考までに、vars-fileで環境を分けるパターンでCLIで移行する方法に少し触れます。

vars-fileで環境を分けるパターンでCLI手順が煩雑な理由は、terraform.backendとterraform.cloudの記述を同時に書けないためです。

main.tf

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 5.90.1"
    }
  }
  # これはできない
  backend "s3" {}
  cloud {
    organization = "my-org"
    workspaces {
        name = "my-workspace"
    }
  }
}

そのため、以下のように1 Statefileの移行毎に各設定を削除・追加が必要です。

(dev・prod)VCS Driven Workflowを作成
(dev)reconfigureで環境切り替え
- terraform init -reconfigure -backend-config="envs/dev/terraform.tfbackend"
terraform.backendを削除、terraform.cloudを追加
StatefileをS3からHCP Terraformに移行
- terraform init　-migrate-state
terraform.cloudを削除・terraform.backendを追加
(prod)reconfigureで環境切り替え
- terraform init -reconfigure -backend-config="envs/dev/terraform.tfbackend"
terraform.backendを削除、terraform.cloudを追加
StatefileをS3からHCP Terraformに移行
- terraform init　-migrate-state

個人的には、できないことは無いが環境切り替えが多く「ミスしやすそう」という印象です。

一方、Tokenのセットやbase64エンコードが不要な点は良いと思います。

対象Statefileの数が少ない場合はvars-fileで環境を分けるパターンでCLIを採用するのは有りだと思います。

おわりに

HCP TerraformへのStatefileの移行についてでした。

WorkspaceのWorkflow TypeはVCS Driven・CLI Drivenどちらでも手順は変わりません。

Workspaceを作成して、Terraform CLI(terraform init)やHCP Terraform APIを使ってStatefileを移行できます。

APIを使った移行を複数のStatefile移行を自動化するPythonスクリプトを作成する記事もあったので、興味がある方はご確認ください。

tf-migrateも今回の用途では利用できると思います。

こちらも追々試していきたいと思います。

以上、AWS事業本部の佐藤(@chari7311)でした。

StatefileをAmazon S3からHCP Terraformに移行してみた(HCP Terraform API利用、VCS Driven Workflow)

やってみた

ディレクトリ構成(移行前)

Terraformコード(移行前)

HCP Terraformログイン

Statefileをダウンロード

HCP Terraform Workspaceの作成

HCP Terraform Tokenの準備

HCP Terraform APIを使用してStatefileを移行する

動作確認

backendブロックの置き換え

Tips: HCP Terraform移行後のローカルからのTerraform CLIの実行

CLIで移行する

おわりに

関連記事

主なカテゴリ

AWS

おすすめ

プロダクト

コンテンツ

お問い合わせ

運営会社