はじめに
Terraform Enterprise(以下、TFE)を使って、手元のPCからTerraformのPlanを実行する検証を行いました。
まずはTerraformを実行する側の環境が必要なので、Azure上にTFEを用意します。今回はAzure PortalでネットワークとVMを作成し、VMにSSH接続してDocker ComposeでTFEを起動することにしました。
この記事では、TFEの起動と初期設定までをまとめます。Service Principalの準備やTerraform CLIからの実行は、後編のローカルCLIからRemote Plan編で紹介します。
今回作る構成
大まかには、以下のような構成です。
管理端末
│ VPN接続後、許可した送信元からHTTPS / SSH
▼
Azure Public IP + DNS名
│ NSGで接続元を制限
▼
VNet / Subnet
└─ Ubuntu VM
├─ Docker Compose
│ └─ Terraform Enterprise
└─ Data Disk → /opt/tfe-data
TFEのデータはOSディスクと分け、追加したディスクへ保存します。今回は検証用の単一VM(Mounted Disk)構成です。
検証環境と前提
| 項目 | 今回の構成 |
|---|---|
| TFE |
v202507-1 / Docker Compose |
| VM | Ubuntu Server 24.04 LTS / Standard_D4s_v5(4 vCPU / 16 GiB) |
| ディスク | OS 64 GiB + Data Disk 64 GiB |
| リージョン | Japan East |
| TLS | 検証用の自己署名証明書 |
| 管理端末 | Windows / PowerShell / OpenSSH |
| Azureリソース | 検証用の既存Resource Groupを使用 |
以下の名前やアドレスは説明用です。実際にはご自身の環境へ読み替えてください。
| 用途 | 説明用の値 |
|---|---|
| TFE用Resource Group | rg-tfe-poc |
| VNet / Subnet |
vnet-tfe-poc / snet-tfe
|
| アドレス空間 |
10.20.0.0/16 / 10.20.1.0/24
|
| TFEの接続名 | tfe.example.com |
tfe.example.com は説明用のドメインです。検証ではAzure Public IPのDNS名ラベルで取得したFQDNを使用しました。DNS名、証明書のSAN、TFEの設定、後編のCLI接続先を同じFQDNにそろえます。
TFEライセンスと、対象Resource Groupにネットワーク・VMを作成できる権限も必要です。ここで紹介するのは検証時のバージョンを使った構成なので、新しく構築する場合は利用バージョンの要件・サポート状況を公式資料で確認してください。
Azure PortalでネットワークとVMを準備する
VNet・NSGの作成
- Azure Portalの「仮想ネットワーク」からVNetを作成します。
- 対象Resource GroupとJapan Eastを選び、アドレス空間とSubnetを設定します。
- 「ネットワーク セキュリティ グループ」からNSGを作成し、Subnetへ関連付けます。
- NSGへ以下の受信規則を追加します。
| 用途 | プロトコル | ポート | 送信元 |
|---|---|---|---|
| TFE Web UI / API | TCP | 443 | 接続を許可するVPN出口CIDR |
| SSH | TCP | 22 | 接続を許可するVPN出口CIDR |
アドレス範囲が既存ネットワークと重複しないことを確認します。また、送信元を 0.0.0.0/0 にして管理ポートを広く公開しないようにします。
Public IPとVMの作成
続いてStandard SKUのPublic IPを作成し、DNS名ラベルを設定します。このFQDNをTFEへの接続に使います。
VMの作成画面では次のように設定しました。
| タブ | 主な設定 |
|---|---|
| 基本 | Ubuntu 24.04 LTS、Standard_D4s_v5、SSH公開鍵認証 |
| ディスク | OS 64 GiB、空のData Disk 64 GiBを追加 |
| ネットワーク | 作成したVNet・Subnet・Public IPを選択 |
| 受信ポート | なし。Subnet側のNSGで管理する |
| 管理 | 検証時間に合わせて自動シャットダウンを設定 |
VMが作成されたら、Public IP、FQDN、Private IPを控えます。Private IPは後述の名前解決設定にも使うので、NIC側で静的割り当てにしておくと設定を維持しやすくなります。
VM内の準備
SSH接続とデータディスク
ここからはVM内の作業です。PowerShellから、VM作成時に登録した公開鍵に対応する秘密鍵で接続します。
# ※ 自身の環境に合わせたFQDNとSSH秘密鍵のパスを設定
$TfeHost = 'tfe.example.com'
$SshKey = Join-Path $HOME '.ssh/id_rsa_tfe_poc'
ssh -i $SshKey "azureadmin@$TfeHost"
VMでディスクの状態を確認します。
lsblk -o NAME,SIZE,TYPE,MOUNTPOINT
ls -l /dev/disk/azure/scsi1/
今回追加したData Diskにはパーティションを作り、XFSでフォーマットして /opt/tfe-data にマウントしました。/etc/fstab にはUUIDで登録し、VM再起動後もマウントされるようにしています。
フォーマットは対象ディスクのデータを消す操作です。/dev/sdc などの名前を決め打ちせず、追加した空ディスクのサイズ・LUN・既存マウントを確認してから行ってください。
findmnt /opt/tfe-data
df -h /opt/tfe-data
findmnt でData Disk上のパーティションが表示されれば、TFEデータ用の保存先を用意できています。
Docker Engine / Docker Compose
Docker公式のUbuntu向けリポジトリを使って、EngineとCompose Pluginを導入します。導入コマンドはDocker公式手順に沿って実行してください。
sudo systemctl enable --now docker
sudo usermod -aG docker "$USER"
グループ変更後にSSH接続し直し、確認します。なお、docker グループにはホストの管理に相当する強い権限があるので、利用者は限定します。
docker version
docker compose version
証明書とライセンスを準備する
ファイルの配置
TFEの設定を /opt/tfe、データを /opt/tfe-data に置きます。
/opt/tfe/
├── compose.yaml
├── .env # ライセンス・暗号化パスワード
├── terraform.hclic # 入手したライセンス
└── certs/
├── cert.pem
├── key.pem
└── bundle.pem
/opt/tfe-data/ # Data Diskのマウント先
VMで、設定用ディレクトリを作成します。
sudo install -d -m 0750 -o "$USER" -g "$(id -gn)" /opt/tfe
install -d -m 0750 /opt/tfe/certs
検証用の自己署名証明書
今回は自己署名証明書を使用しました。VM内の /opt/tfe/certs で、FQDNをSANに含めた証明書を作成します。以下は初回作成用で、既存の鍵・証明書がある場合は上書きしません。
cd /opt/tfe/certs
# ※ 自身の環境に合わせたTFEのFQDNを設定
TFE_FQDN='tfe.example.com'
# 既存の鍵・証明書を上書きしない
if [ -e key.pem ] || [ -e cert.pem ] || [ -e bundle.pem ]; then
echo '鍵・証明書が既に存在します。既存ファイルを確認してください。'
else
umask 077
if openssl req -x509 -nodes -newkey rsa:4096 -sha256 -days 365 \
-keyout key.pem -out cert.pem \
-subj "/CN=${TFE_FQDN}" \
-addext "subjectAltName=DNS:${TFE_FQDN}" \
-addext "basicConstraints=critical,CA:TRUE" \
-addext "keyUsage=critical,digitalSignature,keyEncipherment,keyCertSign" \
-addext "extendedKeyUsage=serverAuth"; then
# 自己署名証明書をCAバンドルにも使用する
cp cert.pem bundle.pem
chmod 600 key.pem
chmod 644 cert.pem bundle.pem
openssl x509 -in cert.pem -noout -subject -ext subjectAltName -enddate
else
echo '証明書を作成できませんでした。エラー内容を確認してください。'
fi
fi
作業前に pwd で /opt/tfe/certs にいることを確認します。作成に失敗した場合は、そのまま先へ進まずエラーと生成途中のファイルを確認してください。接続名がSANに含まれることも確認します。証明書を端末で信頼させる際は、正当性を別経路で確認してください。これは検証用の構成で、本番では組織の証明書管理方針に従います。
ライセンスと暗号化パスワード
ライセンスファイルを、端末からVMの /opt/tfe/terraform.hclic へ安全に転送します。転送後、VM内で権限を制限します。
chmod 600 /opt/tfe/terraform.hclic
同じディレクトリに .env を作成します。ライセンスの値をターミナルへ出さず、ファイルから読み込みます。
cd /opt/tfe
# 既存の.envは上書きしない。暗号化パスワードも再生成しない
if [ -e .env ]; then
echo '.envが既に存在します。既存の設定を使用してください。'
elif [ ! -s terraform.hclic ]; then
echo 'ライセンスファイルがありません。転送先とファイルサイズを確認してください。'
else
umask 077
if TFE_ENCRYPTION_PASSWORD=$(openssl rand -hex 32); then
# ライセンスと暗号化パスワードは画面に出さず、.envへ保存する
{
printf 'TFE_LICENSE=%s\n' "$(tr -d '\r\n' < terraform.hclic)"
printf 'TFE_ENCRYPTION_PASSWORD=%s\n' "$TFE_ENCRYPTION_PASSWORD"
} > .env
chmod 600 .env
unset TFE_ENCRYPTION_PASSWORD
else
echo '暗号化パスワードを生成できませんでした。エラー内容を確認してください。'
fi
fi
作業ディレクトリが /opt/tfe であることと、.env の作成が成功したことを確認してから進めます。TFE_ENCRYPTION_PASSWORD はTFEデータの暗号化に使う値です。紛失すると復号できなくなるので、安全な場所へ保管します。既存の .env がある場合は、その設定を継続して使用します。
Docker ComposeでTFEを起動する
Compose設定
以下は検証手順を基に、ホスト名などを説明用に置き換えた構成です。/opt/tfe/compose.yaml として配置します。tfe.example.com と 10.20.1.4 は、それぞれ実際のTFEのFQDNとVMのPrivate IPに変更してください。
compose.yamlを表示
name: terraform-enterprise
services:
tfe:
image: images.releases.hashicorp.com/hashicorp/terraform-enterprise:v202507-1
restart: unless-stopped
# ※ 自身の環境に合わせたTFEのFQDNとVMのPrivate IPを設定
extra_hosts:
- "tfe.example.com:10.20.1.4"
environment:
# 同じディレクトリの.envに設定した値を読み込む
TFE_LICENSE: "${TFE_LICENSE}"
TFE_ENCRYPTION_PASSWORD: "${TFE_ENCRYPTION_PASSWORD}"
# ※ 自身の環境に合わせたTFEのFQDNを設定
TFE_HOSTNAME: "tfe.example.com"
# Mounted Disk構成で起動する
TFE_OPERATIONAL_MODE: "disk"
TFE_DISK_CACHE_VOLUME_NAME: "${COMPOSE_PROJECT_NAME}_terraform-enterprise-cache"
TFE_TLS_CERT_FILE: "/etc/ssl/private/terraform-enterprise/cert.pem"
TFE_TLS_KEY_FILE: "/etc/ssl/private/terraform-enterprise/key.pem"
TFE_TLS_CA_BUNDLE_FILE: "/etc/ssl/private/terraform-enterprise/bundle.pem"
TFE_IACT_SUBNETS: ""
# Remote Runからも同じFQDNをVMのPrivate IPへ解決する
# ※ extra_hostsと同じFQDN・Private IPを設定
TFE_RUN_PIPELINE_DOCKER_EXTRA_HOSTS: "tfe.example.com:10.20.1.4"
cap_add:
- IPC_LOCK
read_only: true
tmpfs:
- /tmp:mode=01777
- /run
- /var/log/terraform-enterprise
ports:
- "80:80"
- "443:443"
volumes:
- type: bind
source: /var/run/docker.sock
target: /run/docker.sock
- type: bind
source: ./certs
target: /etc/ssl/private/terraform-enterprise
- type: bind
source: /opt/tfe-data
target: /var/lib/terraform-enterprise
- type: volume
source: terraform-enterprise-cache
target: /var/cache/tfe-task-worker/terraform
volumes:
terraform-enterprise-cache:
ポートの公開
最初にDocker Composeで起動したときは、ポート公開の設定が不足していて端末からTFEへ接続できませんでした。
ここは見落としやすいので、上の compose.yaml からポート公開の部分を取り出しておきます。以下は最終的に使用した設定の抜粋です。
services:
tfe:
ports:
# ホストのポート:コンテナのポート
- "80:80" # HTTP(HTTPSへのリダイレクト用)
- "443:443" # HTTPS(TFEのWeb UI / API)
443:443 は、VMの443番ポートへ届いた通信を、コンテナの443番ポートへ転送する指定です。TFEのWeb UIとAPIには https://自分のTFEのFQDN で接続します。
あわせて、Composeのポート公開とAzure NSGの通信許可をそれぞれ設定します。
| 設定する場所 | 役割 | 今回の設定 |
|---|---|---|
Composeの ports
|
VMのポートからコンテナへ転送する |
80:80 と 443:443
|
| Azure NSG | Azure側で接続元と宛先ポートの通信を制御する | 許可したVPN出口CIDRからTCP 443とSSH用のTCP 22を許可 |
今回のNSGでは443番のみを外部へ許可しているため、端末からは最初からHTTPSを指定してアクセスします。
ポート公開を含むCompose設定を変更した場合は、VM内の /opt/tfe で再度 docker compose up -d を実行して反映し、公開状態を確認します。
cd /opt/tfe
docker compose ps
docker compose port tfe 443
ps のPORTS欄でホスト側443番からコンテナ側443番への対応を確認します。docker compose port tfe 443 でもホスト側の公開先を確認できます。あわせて、後述のヘルスチェックと、許可した端末からのHTTPS接続も確認します。
その他の設定
設定のポイントは以下です。
| 設定 | 役割 |
|---|---|
TFE_OPERATIONAL_MODE: disk |
Mounted Disk構成として起動 |
/opt/tfe-data のbind mount |
TFEデータをData Diskへ保存 |
extra_hosts |
TFE本体から自身のFQDNへ向かう通信をPrivate IPへ解決 |
TFE_RUN_PIPELINE_DOCKER_EXTRA_HOSTS |
Remote RunコンテナからTFEへ接続する際の名前解決 |
docker.sock のmount |
Remote Run用コンテナの起動に使用 |
名前解決の2つの設定は対象が異なります。後編のPlan検証で内部callbackが止まったため、最終的に両方を設定しました。上の例はその対処を反映した構成です。
Docker Socketのマウントはホストに対する強い権限を伴うため、TFE専用の検証VMとして扱います。
イメージ取得と起動確認
VM内でレジストリへログインし、起動します。各コマンドが成功したことを確認しながら、順番に実行してください。Data Diskがマウントされていない場合やログイン・構文確認に失敗した場合は、起動へ進まず設定を確認します。
cd /opt/tfe
# Data Diskがマウントされていることを確認する
findmnt /opt/tfe-data
# ライセンスを画面やコマンド引数に表示せず、標準入力で渡す
tr -d '\r\n' < terraform.hclic | docker login \
--username terraform --password-stdin images.releases.hashicorp.com
# 構文を確認してから、イメージを取得・起動する
docker compose config --quiet
docker compose pull
docker compose up -d
展開済み設定には秘密情報が含まれるので、構文確認は docker compose config --quiet を使います。.env の未配置や変数の未設定について警告が出た場合も、起動前に修正します。レジストリ認証情報もホスト側へ保存されるため、VMのアクセス権限を適切に管理してください。
cd /opt/tfe
docker compose ps
docker compose logs --tail 100 tfe
docker compose exec tfe tfectl app status
初回起動には少し時間がかかります。まだアプリが待ち受けていなければ、ログを確認してから再度チェックします。今回の確認では、最後に All checks passed. が表示されました。
鍵の読み取りやデータ領域への書き込みで権限エラーが出た場合は、コンテナの実行ユーザーとホスト側の所有者・権限を確認します。秘密鍵の公開やディレクトリの全ユーザー書き込み許可で回避しないようにします。
初期管理者・Organization・Workspaceの作成
ここまででTFE本体は起動できたので、ブラウザから利用するための初期設定を行います。
- VMの
/opt/tfeでdocker compose exec tfe tfectl admin tokenを使い、初期管理者作成トークン(IACT)を取得します。 - TFEのFQDNに対し、パス
/admin/account/new?token=取得したIACTへHTTPSでアクセスし、管理者アカウントを作成します。 - ログイン後、Organizationを作成します。
- 「New workspace」から「CLI-Driven Workflow」を選び、Workspaceを作成します。
ブラウザ側でも証明書の信頼設定が必要です。後編の「自己署名証明書の信頼設定」と同様に、証明書を照合してから登録します。IACTを取得する操作は、トークンを表示するため録画・ログ共有の対象にしないでください。URLに含まれるトークンも共有しません。
今回はここでOrganizationとWorkspaceを作成できました。実際のPlanは後編で確認します。
さいごに
Azure PortalでネットワークとVMを作り、そのVM上でTFEを起動するところまで進めました。Portalで完結する部分と、Linux上で準備する部分に分けると、構成を追いやすくなると思います。
今回は検証用の単一VM構成なので、可用性やバックアップ、利用しない時間帯のVM停止も含めたコストとデータの扱いは別途考える必要があります。
続いて、ローカルCLIからRemote Plan編では、SPの認証情報をTFEへ登録し、手元のTerraform CLIからRemote Planを試します。



