PulumiでTerraformプロバイダをそのまま使う：tf2pulumiを超えたブリッジプロバイダの徹底活用術
Infrastructure as Code（IaC）のパラダイムシフトは完了した。宣言的記法におけるボイラープレートの地獄から私たちを救い出したのはPulumiであり、真のプログラミング言語の表現力をもってクラウドを従える時代が到来している。
だが、現実のエンタープライズ環境を見渡せば、巨大なTerraformエコシステムという無視できない遺産と現実がある。HashiCorp Terraform Registryには数千を超えるプロバイダが存在し、AWSやGCPといった主要クラウドの最新機能は、多くの場合Terraformプロバイダとして最速で実装される。
「Pulumiを使いたいが、最新のTerraformプロバイダのアップデート速度に追従したい。あるいは、社内で秘伝のタレとして育て上げたTerraformのカスタムプロバイダがある」
ここで凡百のエンジニアであれば、コードを一度きり変換するだけの場当たり的なツール `tf2pulumi` に手を伸ばし、生成された静的なコードのメンテナンス地獄に沈むことだろう。だが、我々は違う。今回は、Terraformプロバイダの生態系を丸ごとPulumiの世界へと召喚する「Terraform Bridge（pulumi-tf-provider）」の深淵を暴く。
静的なコード変換の呪縛を断ち切り、Terraformプロバイダを動的に、かつネイティブのPulumiパッケージとして完全統合するための極限の知見を授けよう。
—
1. 内部アーキテクチャの理解：なぜ `tf2pulumi` では不十分なのか
まず、過去の遺物となりつつある `tf2pulumi` の限界を明確にしておく必要がある。
`tf2pulumi` は、HCL（HashiCorp Configuration Language）の抽象構文木（AST）を解析し、それをTypeScriptやPythonなどのPulumiコードへ一方向に静的トランスパイルするツールに過ぎない。
これの何が問題か？
1. ドリフトの放置: 変換した瞬間に、元となったTerraformモジュールとの「乖離」が始まる。
2. エコシステムの追従放棄: プロバイダ側の仕様変更（Schemaの更新など）が発生するたびに、人間が手動でコードを書き直すか、再度トランスパイルして差分マージ地獄に突入する必要がある。
3. 動的言語機能の欠如: 生成されるのは「HCLを模した手続き的コード」であり、Pulumiが持つクラス、ループ、型安全なモジュール化の恩恵を十分に受けられない。
Terraform Bridge（`pulumi-tf-provider`）の真髄
これに対し、Pulumiの Terraform Bridge は次元が違う。これは、Terraformプロバイダ（Go製バイナリ）をラップし、gRPCを介してPulumiエンジンと対話する動的なプロキシサーバー（ネイティブプロバイダ）を生成する技術である。
[Pulumi CLI / Engine]
│ (gRPC)
▼
[Bridge層 (pulumi-tf-provider)]
│ (内部Goコール / Schema変換)
▼
[Terraform Provider (AWS/GCP/Custom)]
│
▼
[Cloud Provider API]
Terraformプロバイダが持つスキーマ定義（Schema）を、実行時にPulumiの型システム（TypeScriptの `Output
—
2. 実践：カスタムTerraformプロバイダのブリッジ化
ここでは、社内ニッチなプライベートAPIやオンプレミス機器を制御するために独自開発した「Terraformカスタムプロバイダ（`terraform-provider-onprem`）」を、Pulumiエコシステムに完全統合する手順をコードベースで解説する。
Step 1: ブリッジプロジェクトの構造定義
Pulumiの公式テンプレートである `pulumi-tf-provider-boilerplate` をベースに、ブリッジ用のGoプロジェクトを構築する。
pulumi-onprem/
├── cmd/
│ └── pulumi-resource-onprem/
│ └── main.go # プロバイダのエントリーポイント
├── provider/
│ ├── provider.go # Bridgeの設定とスキーマのマッピング
│ └── resources.go # リソース・データソースの紐付け
├── sdk/ # 自動生成されるPulumi用SDK出力先
│ ├── dotnet/
│ ├── go/
│ ├── nodejs/
│ └── python/
└── pulumi-onprem.json # メタデータ
Step 2: `provider/provider.go` でのブリッジ構成
ここでTerraformプロバイダのバイナリをラップし、Pulumiのリソーススキーマへと変換するロジックを記述する。
package provider
import (
“unicode”
“github.com/pulumi/pulumi-terraform-bridge/v3/pkg/tfbridge”
shimv2 “github.com/pulumi/pulumi-terraform-bridge/v3/pkg/tfshim/sdk-v2”
“github.com/your-org/terraform-provider-onprem/onprem” // 実際のTerraformプロバイダ
“github.com/your-org/pulumi-onprem/provider/pkg/version”
)
// Provider はPulumiプロバイダのメタデータを返却する
func Provider() tfbridge.ProviderInfo {
// TerraformプロバイダのShim（v2スキーマ対応）を取得
prov := shimv2.NewProvider(onprem.Provider())
contract := tfbridge.ProviderInfo{
P: prov,
Name: “onprem”,
Description: “A Pulumi package for controlling on-premise infrastructure via Terraform provider.”,
Keywords: []string{“pulumi”, “onprem”, “category/infrastructure”},
License: “Apache-2.0”,
Homepage: “https://example.com”,
Repository: “https://github.com/your-org/pulumi-onprem”,
Version: version.Version,
Config: map[string]tfbridge.SchemaInfo{
// 必要に応じて設定プロパティのオーバーライドを定義
“endpoint”: {
Default: &tfbridge.DefaultInfo{
Value: “https://api.onprem.local:8443”,
},
},
},
Resources: map[string]tfbridge.ResourceInfo{
“onprem_server”: {
Tok: tfbridge.MakeResource(“onprem”, “index”, “Server”),
// プロパティ名のキャメルケース化などのカスタマイズをここに記述
Fields: map[string]tfbridge.SchemaInfo{
“ip_address”: {
CSharpName: “IPAddress”,
},
},
},
},
DataSources: map[string]tfbridge.DataSourceInfo{
“onprem_cluster”: {
Tok: tfbridge.MakeDataSource(“onprem”, “index”, “getCluster”),
},
},
}
// スキーマの自動補正とドキュメント生成の準備
contract.SetAutonaming(255)
return contract
}
Step 3: ビルドとSDKの自動生成
このブリッジコードをコンパイルし、各言語（TypeScript, Python, Go）向けのPulumi SDKを自動生成するMakefileを用意する。
VERSION := 0.1.0
build::
go build -o bin/pulumi-resource-onprem ./cmd/pulumi-resource-onprem
sdk::
pulumi-tfgen-onprem nodejs –out ./sdk/nodejs/
pulumi-tfgen-onprem python –out ./sdk/python/
pulumi-tfgen-onprem golang –out ./sdk/go/
install:: build
cp bin/pulumi-resource-onprem ${GOPATH}/bin/
これにより、手元で `make build sdk` を実行するだけで、自社製Terraformプロバイダが完全に型安全なPulumiパッケージへと生まれ変わる。
—
3. 最先端プロバイダの迅速な取り込みとバージョニング戦略
AWS（`pulumi-aws`）やGCP（`pulumi-gcp`）などのメジャープロバイダは、公式がすでにネイティブブリッジを提供しているが、「公式がまだサポートしていない最新のTerraformプロバイダのマイナーバージョン、あるいはフォーク版を数時間以内に社内環境で使いたい」という要請はSREの現場で頻繁に発生する。
ここで重要となるのが、`pulumi-tf-provider-scaffolding` を利用したCI/CDパイプラインによる「プロバイダ自動ブリッジ生成システム」の構築である。
GitHub Actionsによるプロバイダ自動同期パイプライン
upstreamのTerraformプロバイダのリリースを検知し、自動的にブリッジをコンパイルしてプライベートレジストリ（あるいはGitHub Packages）に配信するワークフローの極意をここに明かす。
name: Auto-Bridge Terraform Provider
on:
schedule:
- cron: ‘0 2 ‘ # 毎日深夜2時に実行
workflow_dispatch:
inputs:
tf_version:
description: ‘Target Terraform Provider Version’
required: true
type: string
jobs:
build-bridge:
runs-on: ubuntu-latest
steps:
- name: Checkout Repository
uses: actions/checkout@v4
- name: Set up Go
uses: actions/setup-go@v5
with:
go-version: ‘1.22’
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: ’20’
- name: Inject Target Terraform Provider Version
run: |
# go.modのrequireを最新のTerraformプロバイダに書き換え
go get github.com/hashicorp/terraform-provider-aws/v5@${{ github.event.inputs.tf_version }}
go mod tidy
- name: Generate Pulumi Schema and SDKs
run: |
make build
make sdk
- name: Publish to NPM / PyPI / Go Proxy
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
PYPI_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
run: |
# 各言語のパッケージマネージャーへ自動パブリッシュ
cd sdk/nodejs && npm publish –access public
# PythonやGoのパブリッシュ処理が続く…
このパイプラインを回すことで、Terraform側で新しいリソースが追加された翌日には、開発チームはPulumi経由でそのリソースをTypeScriptやPythonで呼び出せるようになる。`tf2pulumi` のようなその場しのぎのハックとは一線を画す、持続可能な自動化の極みである。
—
4. 低レイヤ＆エキスパート知見：メモリ消費、並行処理、パフォーマンスの極限最適化
Terraform Bridgeを使用する上で、上級エンジニアが必ず直面するのが「メモリリーク」と「gRPC通信のボトルネック」である。
プロバイダの規模が大きくなると（例えばAWSプロバイダなど）、スキーマのメモリ上での展開だけで数ギガバイトを消費することがある。また、大規模なインフラストラクチャの `pulumi up` 実行時に、Bridgeを経由したプロセス間通信（IPC）がオーバーヘッドとなり、パフォーマンスが低下する現象が発生する。
これを極限までチューニングするための実践的ハックを公開する。
1. 接続プーリングとプラグインプロセスのライフサイクル管理
Pulumiエンジンは、必要に応じてプロバイダプロセスを子プロセスとして起動し、終了する。しかし、巨大なプロバイダにおいて毎度スキーマのパースが行われると、起動時間が異常に長くなる。
これに対処するため、環境変数によるプラグインのタイムアウトとゴルーチンの制御を明示的に行う。
プロバイダプラグインのタイムアウトを延長し、予期せぬ切断を防ぐ
export PULUMI_PLUGIN_TIMEOUT=”1h”
gRPCの最大メッセージサイズを拡張し、巨大なスキーマ構造体の転送エラーを防ぐ
export GRPC_GO_MAX_METADATA_SIZE=”16777216″
2. `TF_ACC` を用いたブリッジ自体の単体テスト
Terraformプロバイダをブリッジした場合、変換レイヤ（Schema Mapping）で予期せぬ型変換エラー（例：Terraformの `string` が Pulumi側で意図せず `float` や `any` に化ける）が起きることがある。これを防ぐため、ブリッジ側でユニットテストを書く。
package provider_test
import (
“testing”
“github.com/pulumi/pulumi-terraform-bridge/v3/pkg/tfbridge”
“github.com/your-org/pulumi-onprem/provider”
“github.com/stretchr/testify/assert”
)
// スキーマの整合性を担保するテスト
data “TestProviderSchema”(t testing.T) {
p := provider.Provider()
err := p.P.InternalGetProvider().Validate()
assert.NoError(t, err, “Terraform provider schema validation failed in Pulumi bridge”)
}
CIパイプラインのテストステージにこれを組み込むことで、Terraformプロバイダのバージョンアップ時にスキーマ破壊的変更（Breaking Changes）が発生した場合でも、本番デプロイ前に検知することが可能となる。
—
5. 結び：技術至上主義のインフラエンジニアリングへ
Terraform Bridgeは、単なる「移行期のための妥協案」ではない。それは、世界中の数千人・数万人のコントリビューターが作り上げたTerraformの強大なアセットを、高潔なプログラミング言語のパラダイムへとシームレスに架橋する最強の武器である。
`tf2pulumi` という過去の呪縛に囚われるな。プロバイダの内部構造を理解し、Bridge層を自らの手で掌握し、CI/CDパイプラインによって完全に自動化されたインフラストラクチャの構築基盤こそが、現代のSRE、そして真に卓越したインフラエンジニアに求められる姿である。
コードを書け。クラウドを従えろ。限界のその先へ。