【HCP Terraform】Stateファイル管理とGitHub連携機能を使ってみる

インフラ

【HCP Terraform】Stateファイル管理とGitHub連携機能を使ってみる

2025/02/25

# AWS

# Terraform

HCP Terraformとは
今回使用する機能
Stateファイル管理
OSS TerraformでStateファイル管理
HCP TerraformでStateファイル管理
GitHubとの連携
GitHubリポジトリの作成
VCSプロバイダーの追加
Workspaceの作成
AWS認証情報の登録
HCP Terraformから実行
GitHubリポジトリへの変更をトリガーに実行

今回はHCP Terraformを使ってみたので一部の機能を紹介します。

HCP Terraformとは

HCP TerraformとはチームでTerraformを使用するのに役立つ機能を提供するアプリケーションです。
元々Terraform Cloudと呼ばれていましたが、2024年4月22日にHCP Terraformという名称に変更されています。

今回使用する機能

Stateファイルの管理

OSS版のTerraformではapplyコマンド実行後リソースの状態を管理するterraform.tfstateファイルがローカルに作成されます。

複数人で管理する場合、AWSのS3などで管理することもできますが、専用のリソースを作成する必要があります。

HCP TerraformではStateファイルを管理する機能が備わっているので専用のリソースを作成する手間なく複数人での運用が可能になります。

VCS(バージョン管理システム)との連携

各ワークスペースでGitHubなどのVCSと連携ができます。
オプションでブランチや、対象とするディレクトリの指定、自動Apply設定などが可能です。

サポートされるVSCは以下です。

GitHub
GitLub
Bitbucket
Azure DevOps

上記以外のVCSとの連携もAPIなどを使用すれば可能なようです。

Stateファイル管理

Stateファイル管理機能を実際に使ってみます。

OSS TerraformでStateファイル管理

まずはOSS版のTerraformでAWSリソースを作成するときの挙動を確認します。
AWSアカウントを作成済み、Terraformの環境構築が完了していることを前提に進めて行きます。

main.tfを以下の内容で作成します。

terraform {
  required_version = "1.9.3"

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

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

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

terraform initで初期化します。

$ terraform init

terraform applyでリソースを作成します。

$ terraform apply

AWSマネジメントコンソールでVPCが作成されていることを確認が確認できます。

terraform applyコマンド実行後、ローカルではterraform.tfstateファイルが作成されています。
複数人でTerraformを使ってリソースを管理する場合、リソースの状態を表すこのterraform.tfstateファイルを他のメンバーにも共有する必要があります。

$ ls
main.tf           terraform.tfstate

HCP TerraformでStateファイル管理

HCP Terraformを使って同様の操作を行なってみます。

アカウント作成

signupページからアカウントを作成します。

認証メールが送られるのでメール内のリンクをクリックして認証を完了します。

トークンを作成するモーダルが表示されますが、一旦「キャンセル」を押してとして閉じます。

Organizationを作成

HCP Terraformでは一番上位の概念としてOrganization(組織)があり、その中にStateファイルを管理するWorkspaceを作成します。
WorkspaceはProjectという単位の中にまとめることができます。

その他のHCP Terraformの概念に関してはこちらの記事が分かりやすかったです。

トップページにアクセスして「Create organization」をクリックします。

適当な名前をつけてOrganizationを作成します。

※Organization名はユニークな値である必要があります。

Workspaceを作成

「Workspaces」にアクセスして「Create a workspace」をクリックします。

Workflowの種類を選択する画面が表示されるので今回は「CLI-Driven Workflow」を選択します。

適当な名前をつけて「Create」をクリックします。
Projectはデフォルトで作成されている「Default Project」が選択されています。

Workspaceが作成され、詳細情報が表示されます。
現在「Execution mode」が「Remote」となっています。これはHCP Terraform上でリソース作成処理を実行するという設定ですが、今回はローカルから実行できる「Local」に変更します。

「Remote」の箇所をクリックすると設定画面に遷移します。
「Execution Mode」を「Local」に変更して「Save settings」をクリックします。

ターミナルからHCP Terraformにログイン

Workspace詳細ページに戻り、「Local runs」の箇所の指示通りにterraform loginコマンドを実行します。

$ terraform login

続けるか聞かれるのでYesと入力します。

Do you want to proceed?
  Only 'yes' will be accepted to confirm.

  Enter a value: Yes

トークン作成用のURLが出力されるのでアクセスします。

---------------------------------------------------------------------------------

Open the following URL to access the tokens page for app.terraform.io:
    https://app.terraform.io/app/settings/tokens?source=terraform-login


---------------------------------------------------------------------------------

トークン作成のモーダルが表示されます。
Description(説明)、Expiration(有効期限)はデフォルトのままで「Generate token」をクリックします。

生成されたトークンをコピーしてターミナルに戻り、「Enter a value」の箇所に貼り付けます。

Token for app.terraform.io:
  Enter a value:

Welcome to HCP Terraform! の表示が出力されたらログインは完了です。

main.tfファイルの修正

Workspace詳細ページに戻り、「Local runs」の手順2の内容をコピーしてmain.tfに追記します。

main.tfにorganization, workspaceの情報を追加

terraform {
  required_version = "1.9.3"

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

  # 追加
  cloud {
    organization = "Organization名"

    workspaces {
      name = "Workspace名"
    }
  }
}

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

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

再度初期化

この状態で再度terraform initで初期化してみます。

terraform init

Stateファイルの内容をHCP TerraformのWorkspaceにコピーするかどうかを聞かれるのでyesとします。

Initializing HCP Terraform...
Do you wish to proceed?
  As part of migrating to HCP Terraform, Terraform can optionally copy
  your current workspace state to the configured HCP Terraform workspace.
  
  Answer "yes" to copy the latest state snapshot to the configured
  HCP Terraform workspace.
  
  Answer "no" to ignore the existing state and just activate the configured
  HCP Terraform workspace with its existing state, if any.
  
  Should Terraform migrate your existing state?

  Enter a value: yes

init完了後ローカルのterraform.tfstateファイルの中身が空になっていることが確認できます。

$ cat terraform.tfstate
$

HCP TerraformのWorkspace詳細 → 「States」にアクセスすると新しいStateファイルが作成されています。

「Overview」では「Resources」の箇所に最初に作成したVPCが表示されています。

リソースの更新

作成したVPCリソースを少し編集してみます。

タグを追加します。

terraform {
  required_version = "1.10.2"

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

  # 追加
  cloud {
    organization = "MyOrganization10311998"

    workspaces {
      name = "cli-test"
    }
  }
}

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

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

  # 追加
  tags = {
    Name = "sample-vpc"
  }
}

この状態でterraform applyを再度実行します。

$ terraform apply

AWSマネジメントコンソールで変更が反映されたことを確認します。

HCP TerraformのWorkspace詳細 → 「States」にアクセスするとStateファイルが新たに作成されています。

また、実行中にはWorkspaceにロックがかかるようになっており、リソース作成中に他のユーザーが編集をしてしまうことを防ぐことができます。

以上がStateファイル管理機能でした。

後片付けをしておきます。

terraform destroyでVPCを削除します。

$ terraform destroy

Workspace詳細ページ → 「Settings」→ 「Destruction and Deletion」にアクセスし、「Delete from HCP Terraform」をクリックします。

確認のため「delete」と入力してWorkspaceを削除します。

GitHubとの連携

GitHubリポジトリの作成

適当なリポジトリを作成して、以下の内容で作成したmain.tfファイルをpushしておきます。

VCSプロバイダーの追加

Organizationの詳細ページから「Settings」→ 「Version Control」→ 「Providers」にアクセスします。

「Add a VCS provider」をクリックして「GitHub」→ 「GitHub.com (Custom)」を選択します。

Proivder設定の手順1にGitHubのOAuth Application作成ページで入力する項目が表示されます。
「register a new OAuth Application」をクリックするとすでに入力された状態で遷移することができます。

GitHubのOAuth Application作成ページで情報が入力されていることを確認して「Register application」をクリックします。

Client ID, Client secretsを控えておきます。
Client secretsは「Generate a new client secret」をクリックして生成します。

HCP Terraformのページに戻り、Name, Client ID, Client Secretを入力して「Connect and continue」をクリックします。

GitHubの認証画面が表示されるので手順に従って進めます。

「Advanced Settings」の画面が表示されたらVCSプロバイダーの追加は完了です。

Workspaceの作成

HCP TerraformのWorkspaceにアクセスし、「Create a workspace」をクリックします。

「Version Control Workflow」を選択します。

先ほど追加した「GitHub.com」から該当のリポジトリを選択します。

適当なWorkspaceの名前(デフォルトではリポジトリ名)を入力して「Advanced options」を開きます。

「Advanced options」では実行対象のディレクトリや、ブランチの設定などが可能です。

今回は「Auto-apply」→「Auto-apply API, CLI, & VCS runs」にチェックを入れて自動でterraform applyが実行されるようにしておきます。
ここにチェックを入れない状態ではapplyは手動で実行する必要があります。

設定を確認して「Create」をクリックします。

これでWorkspaceの作成が完了しました。

AWS認証情報の登録

先ほどのローカルからのTerraformの実行と異なり、今回はHCP Terraform上からAWSリソースにアクセスを行うため、WorkspaceにAWS認証情報の登録が必要となります。

Workspaceの詳細ページにアクセスし、「Configure variables」をクリックします。

「Add variable」からIAMのアクセス情報もしくはOpenID Connectを使用したIAMロールの情報などを設定します。
OpenID Connectを使った認証については公式のこちらの記事で解説されています。

また、Variable setという機能でプロジェクト全体で共通する変数の定義も可能です。

HCP Terraformから実行

HCP TerraformのGUIで最初の実行を行います。

Workspace詳細の「Runs」にアクセスし、「New run」をクリックします。

必要に応じて「Run name」を入力して「Start」をクリックします。

Variablesの設定に問題がなければHCP Terraform上でplan, applyが実行されVPCが作成されます。

「Auto-apply API, CLI, & VCS runs」にチェックを入れたため、plan実行後にそのままapplyが実行されています。

GitHubリポジトリへの変更をトリガーに実行

main.tfに変更を加え、プルリクエストを作成します。

terraform {
  required_version = "1.10.2"

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

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

resource "aws_vpc" "example" {
  cidr_block = "10.0.0.0/21" # 変更

  tags = {
    Name = "sample-vpc"
  }
}

プルリクエスト作成後、Terraform Cloudの表示が追加されるようになります。