[HCP Terraform 実践その7] ローカル上のTerraformのstateをHCP Terraform へ移行する

Posted at 2025-03-23

はじめに

今回はローカルバックエンド上で構築済みのtfstateファイルをHCP Terraform に移行しようと思います。

これまでの「HCP Terraform 実戦」シリーズは以下の通りです。

移行シナリオ & 事前準備

現在、tfstateの管理およびterraformの実行をローカル上で実施しているプロジェクトがあり、これを以下のようにHCP Terraform 上に移行したいです。

tfstateをローカル → HCP Terraform上に移行.
Terraform テンプレートをVCS上で管理し、mainブランチのプルリクエスト/マージをトリガーに、plan/applyを実行.

今回使用するリポジトリとしては、以前実施したRDSの自動停止のイベントのモジュールを呼び出すようにします。
モジュールのリポジトリは以下になります。

モジュールの呼び出し用のTerraformテンプレートは、以下の通りになります。

terraform.tf

terraform {
  required_providers {
    aws = {
      source = "hashicorp/aws"
    }
  }
}

providers.tf

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

variables.tf

variable "pj_tags" {
  type = object({
    name = string
    env  = string
  })
  default = {
    name = "hoge"
    env  = "test"
  }
}

main.tf

module "event_rds_stop" {
  source  = "./modules/events_rds_stop"
  pj_tags = var.pj_tags
  iam_role_prefix = {
    is_create_iam_role = true
  }
  lambda_env_variables = {
    exclude_tag_key = "Env"
    exclude_tag_value = "prd"
  }
  events_prefix = {
    schedule_expression = "cron(0 15 ? * * *)"
  }
}

1. HCP Terraform へtfstateを移行する

ローカルのtfstateをHCP Terraform 上で管理するためには、以下の記事を参考に移行していきます。

前章でのTerraformにてHCP Terraform 上で実行するための組織やワークスペースを明示的に指定するため、terraform.tfにて以下のように変更します。

terraform.tf

terraform {
  # 追加
  cloud {
    organization = "atsuw0-org-mng"
    hostname = "app.terraform.io"
    workspaces {
      name = "atsuw0-workspace-aws-stop-instances"
    }
  }

  required_providers {
    aws = {
      source = "hashicorp/aws"
    }
  }
}

backend 構文と cloud 構文の違いに関しては以下のリンクを参照。
HCP Terraform を利用する場合は, cloud 構文を使用することをお勧めされています。

上記のようにテンプレートを変更したら、ローカル上のターミナルでterraform initを実行します。

initを実行した結果、「 Initializing HCP Terraform... 」と出力されるので、Enter a value の部分でyesを入力すると、tfstateの移行が完了します。以下の画像のように成功すればtfstateファイルのHCP Terraformへの移行は成功です。

HCP Terraform のコンソールを確認すると、terraform構内で定義したworkspaceがCLI-Driven Workflow作成され、デフォルトプロジェクトに配置されます。
(CLI-Driven Workflow形式のworkspaceとして作成.)
このタイミングで、ローカル上でterraform applyを実行すると、HCP Terraform 上で

ここまでの手順を実行したら、ローカル上のtfstateファイルの中身は空になっていますのでこのタイミングでtfstateファイルを削除しても問題ありません。

また、バックエンドがAmazon S3などオブジェクトストレージで管理している場合は、tfstateファイルをローカルにコピーした後、ローカル → HCP Terraform へ移行した方が良いと思います。

2. ワークフローのトリガータイプを変更

現在、CLI Drivenタイプのワークフローが定義されており、Terraformの実行はCLI上で実行する形式になってます。これをGitHubのバージョンコントロールによってデプロイしたいので、
VCS Drivenタイプのワークフローに変更したいと思います。

本記事では、VCSはGitHubを利用する程で話を進めます。

事前準備として、CLI上で実行していたTerraform テンプレートを、GitHubで作成したリポジトリ(test-repository)上にPush します。

次に、リポジトリ(test-repository)のプルリクエストやマージをトリガーとするようにVCS Drivenタイプにトリガーを変更します。
VCSからのトリガーを設定する場合は、以下の画像のように連携するGitHubリポジトリ(test-repository)を選択します。

次に環境変数を定義します。
ローカル環境と異なり、tfstateなどのファイルをリポジトリに保存したくないケースがあると思います。
そのような場合は、Workspace Variablesを定義して、変数管理をした方が良いかと思われます。

設定した変数は、以下の画像の通りとなります。

tfvars内で定義していた変数は、HCL形式でTerraform変数として設定します。
AWSリソース作成用IAMロールなどの変数(TFC_AWS_PROVIDER_AUTH,TFC_AWS_RUN_ROLE_ARN)は、環境変数として定義します。値については、以前実施したこちらの手順を参考に設定。