materialize-terraform-self-managed

Materialize の Terraform セルフマネージドモジュール

AWS、Azure、GCP に Materialize をデプロイするための、本番環境対応の Terraform モジュールです。materialize-terraform-self-managed リポジトリで保守されています。各クラウドプロバイダーには、それぞれ独自のモジュールセットと、オペレーターおよび Materialize インスタンス向けの共有 Kubernetes モジュールがあります。

このスキルに記載されているすべてのファイルパスは、そのリポジトリ内のものです。実際のモジュールコードが必要な場合は、リポジトリをクローンするか、GitHub から個別のファイルを取得してください。

リポジトリの構成

aws/
  modules/         # AWS-specific infra modules
  examples/
    simple/        # Minimal production-like deployment
    enterprise/    # Adds Ory (Kratos + Hydra) for auth
azure/
  modules/         # Azure-specific infra modules
  examples/
    simple/
    enterprise/
gcp/
  modules/         # GCP-specific infra modules
  examples/
    simple/
    enterprise/
kubernetes/
  modules/         # Cloud-agnostic K8s modules (operator, instance, cert-manager)
test/              # Rust-based integration test harness
scripts/           # Migration and utility scripts

このスキルの使い方

1. ユーザーが特定のクラウドに Materialize をデプロイしたい場合：リポジトリ内の該当する <cloud>/examples/simple/ ディレクトリから始めます。完全な動作構成については、そこにある main.tf と variables.tf を読みます。
2. ユーザーが特定のモジュールについて質問した場合：そのモジュールの <cloud>/modules/<name>/variables.tf と main.tf を読みます。
3. ユーザーがインスタンスをカスタマイズしたい場合：インスタンスレベルのすべてのオプションについて、kubernetes/modules/materialize-instance/variables.tf を読みます。
4. ユーザーがアップグレードやロールアウトについて質問した場合：以下の「アップグレード」セクションと、ロールアウト設定について kubernetes/modules/materialize-instance/variables.tf を参照してください。
5. ユーザーがエンタープライズ環境や認証を設定したい場合：<cloud>/examples/enterprise/ を読みます。
6. ユーザーが既存の Terraform プロジェクトを使用している場合：以下の「既存の Terraform プロジェクトでのモジュールの使用」を参照してください。

アーキテクチャのレイヤー

デプロイごとに、次の 2 つのレイヤーが作成されます。

クラウドインフラストラクチャ（クラウド固有のモジュール）：

• ネットワーク：VPC/VNet、サブネット、NAT、セキュリティグループ
• Kubernetes：オートスケーリングに対応した EKS/AKS/GKE クラスター
• データベース：Materialize メタデータ用のマネージド PostgreSQL
• ストレージ：persist レイヤー用のオブジェクトストレージ（S3/Blob/GCS）

Kubernetes アプリケーション（kubernetes/modules/ 配下の共有モジュール）：

• TLS 証明書用の cert-manager
• Materialize Operator（Helm チャート）
• Materialize Instance（カスタムリソース）

クラウドプロバイダーのモジュール

AWS（aws/modules/）

モジュール	用途
networking	VPC、サブネット、NAT ゲートウェイ、セキュリティグループ
eks	OIDC プロバイダーを備えた EKS クラスター
eks-node-group	基本ワークロード用のマネージドノードグループ
karpenter	Karpenter オートスケーラーコントローラー
karpenter-ec2nodeclass	Karpenter のプロビジョニング用 EC2NodeClass
karpenter-nodepool	Karpenter のスケジューリング用 NodePool
database	メタデータ用 RDS PostgreSQL
storage	IRSA を備えた S3 バケット
aws-lbc	AWS Load Balancer Controller
nlb	ネットワークロードバランサー
operator	Materialize Operator（Helm）
ebs-csi-driver	EBS CSI ドライバー
vpc-cni	ネットワークポリシーに対応した VPC CNI

AWS の主なパターン：

• ノードのオートスケーリングには Karpenter を使用（クラスターオートスケーラーは使用しません）
• 2 種類の Karpenter ノードクラス：汎用（t4g.xlarge）と Materialize 用（NVMe スワップを備えた r8gd.2xlarge）
• IRSA（サービスアカウント用 IAM ロール）によるストレージ認証
• ポート 6875（SQL）、6876（HTTP）、8080（コンソール）での外部アクセス用 NLB

Azure（azure/modules/）

モジュール	用途
networking	VNet、サブネット、NAT ゲートウェイ
aks	Cilium ネットワーキングを備えた AKS クラスター
nodepool	追加の AKS ノードプール
database	PostgreSQL Flexible Server
storage	ワークロード ID を備えたストレージアカウント
load_balancers	Azure Load Balancer
operator	Materialize Operator（Helm）

Azure の主なパターン：

• ネットワーキングとネットワークポリシーに Cilium を使用
• ストレージ認証に Workload Identity Federation を使用（パスワード不要の OIDC）
• スワップを備えた Materialize ノード用 Standard_E4pds_v6 インスタンス
• PostgreSQL の名前解決用プライベート DNS ゾーン
• EnableAPIServerVnetIntegrationPreview 機能の登録が必要です

GCP (gcp/modules/)

モジュール	用途
networking	VPC、サブネット、Cloud NAT
gke	Workload Identity を使用する GKE クラスター
nodepool	追加の GKE ノードプール
database	Cloud SQL PostgreSQL
storage	HMAC キーを使用する Cloud Storage バケット
load_balancers	GCP ロードバランサー
operator	Materialize オペレーター（Helm）

主な GCP のパターン：

• S3 互換の GCS アクセスに HMAC キーを使用します（これらのモジュールでは S3 互換 API を使用します）
• Cloud SQL のプライベートアクセスに VPC ピアリングを使用します
• ローカル SSD とスワップを備えた Materialize ノードに、c4a-highmem-8-lssd インスタンスを使用します
• Pod とサービスにセカンダリ IP 範囲を使用します（VPC ネイティブ）
• 複数の GCP API（container、compute、sqladmin、servicenetworking など）を有効にする必要があります

Kubernetes モジュール（kubernetes/modules/）

モジュール	用途
cert-manager	cert-manager Helm チャートをインストールします
self-signed-cluster-issuer	自己署名 ClusterIssuer を作成します
materialize-instance	Materialize CR をデプロイします
coredns	CoreDNS の設定
grafana	Grafana によるモニタリング
prometheus	Prometheus モニタリングスタック
hpa	水平 Pod オートスケーリング
ory-*	エンタープライズ認証向けの Ory スタック（Kratos、Hydra など）

Materialize インスタンスモジュール

これは最も重要な Kubernetes モジュールです。kubernetes/modules/materialize-instance/variables.tf の主な変数は次のとおりです。

変数	デフォルト	備考
crd_version	v1alpha1	v26.30 以降では v1 を使用してください。以下の CRD セクションを参照してください。
instance_name	(必須)	Materialize CR の名前
instance_namespace	(必須)	インスタンスの名前空間
metadata_backend_url	(必須)	PostgreSQL 接続文字列
persist_backend_url	(必須)	オブジェクトストレージ URL
license_key	null	コミュニティ版またはエンタープライズ版のキー
environmentd_version	v26.29.0	Materialize のバージョン
rollout_strategy	WaitUntilReady	以下のロールアウト戦略を参照してください
authenticator_kind	None	選択肢：None、Password、Sasl、Oidc
cpu_request	1	environmentd の CPU リクエスト
memory_request	4095Mi	environmentd のメモリーリクエスト
memory_limit	4Gi	environmentd のメモリー制限
system_parameters	{}	システム設定パラメーターのマップ
issuer_ref	null	TLS 用の cert-manager 発行者
internal_issuer_ref	null	内部 mTLS 証明書のオーバーライド

バックエンド URL の形式

Materialize インスタンスには、2 つのバックエンド URL が必要です。

メタデータバックエンド（PostgreSQL）：

postgres://user:password@host:5432/database?sslmode=require&options=-c%20statement_timeout%3D15min

メタデータ操作には statement_timeout=15min パラメーターが必要です。

永続化バックエンド（オブジェクトストレージ）：

AWS S3：

s3://bucket-name/system:serviceaccount:namespace:name

Azure Blob：

https://storageaccount.blob.core.windows.net/container

GCP Cloud Storage（HMAC/S3 互換 API 経由）：

s3://hmac-access-id:hmac-secret@bucket-name/materialize?endpoint=https%3A%2F%2Fstorage.googleapis.com&region=us-central1

ストレージ認証のサポート： 現在、Materialize が永続化バックエンドで IAM ベースの認証をサポートしているのは、AWS（IRSA）と Azure（Workload Identity Federation）のみです。ネイティブの GCS IAM 認証はサポートされていないため、GCP モジュールでは S3 互換 API と HMAC キーを使用します。

CRD バージョン：v1alpha1 と v1

v1alpha1（デフォルト、v26.30 より前）：2 段階のロールアウトです。spec を変更した後、request_rollout に新しい UUID を設定してロールアウトを開始します。これにより、実行タイミングを明示的に制御できます。

v1（v26.30 以降に推奨）：spec の変更によってロールアウトが自動的に開始されます。オペレーターがハッシュを計算してロールアウトを処理します。request_rollout フィールドは削除されています。手動で開始するには、新しい UUID を指定して force_rollout を使用してください。

例または materialize-instance モジュールの crd_version 変数で設定します。

ロールアウト戦略

戦略	動作	リソースへの影響
WaitUntilReady	新しい Pod を作成し、正常になった時点で切り替えます	一時的にリソースが倍増します
ManuallyPromote	新しい Pod を作成し、手動で forcePromote が実行されるまで待機します	一時的にリソースが倍増します
ImmediatelyPromoteCausingDowntime	先に古い Pod を終了します	追加リソースは不要ですが、ダウンタイムが発生します

デプロイ：クイックスタート

どのクラウドでも、同じパターンに従います。

git clone https://github.com/MaterializeInc/materialize-terraform-self-managed.git
cd materialize-terraform-self-managed/<cloud>/examples/simple

# Create terraform.tfvars with required variables (see below)
terraform init
terraform apply

クラウド別の変数

AWS（aws/examples/simple/）：

name_prefix = "my-mz"                # required
aws_profile = "my-profile"            # required
license_key = "your-license-key"      # required
tags        = { environment = "dev" } # required (no default)
aws_region  = "us-east-1"            # optional, defaults to us-east-1

Azure（azure/examples/simple/）：

subscription_id     = "12345678-..."   # required
resource_group_name = "materialize-rg" # required
name_prefix         = "my-mz"         # required
tags                = { environment = "dev" } # required (no default)
location            = "westus2"        # optional, defaults to westus2
license_key         = "your-key"       # optional (null default), needed for production

GCP（gcp/examples/simple/）：

project_id  = "my-gcp-project"        # required
labels      = { environment = "dev" }  # required (no default)
license_key = "your-license-key"      # optional (null default), needed for production
name_prefix = "my-mz"                # optional, defaults to "materialize"
region      = "us-central1"           # optional, defaults to us-central1

共通のオプション変数（すべてのクラウド）

変数	デフォルト	目的
internal_load_balancer	true	インターネット向けの LB にするには false を設定します
ingress_cidr_blocks	["0.0.0.0/0"]	Materialize のポートへのアクセスを制限します
k8s_apiserver_authorized_networks	varies	K8s API へのアクセスを制限します
crd_version	v1alpha1	v26.30 以降では v1 を使用します
enable_observability	false	Prometheus と Grafana をインストールします

既存の Terraform プロジェクトからモジュールを使用する

リポジトリをクローンしたり、サンプルをプロジェクトにコピーしたりする必要はありません。Git ソースを使ってモジュールを直接参照し、リリースタグまたはコミット SHA に固定します。

module "materialize_instance" {
  source = "github.com/MaterializeInc/materialize-terraform-self-managed//kubernetes/modules/materialize-instance?ref=<tag-or-commit>"

  # module inputs ...
}

• // は、リポジトリ URL とモジュールのサブディレクトリを区切ります。この方法で、リポジトリ内の任意のモジュールを参照できます。
• ref は必ずタグまたはコミット SHA に固定してください。main を追跡しないでください。そうすると、適用結果の再現性が失われ、破壊的変更が取り込まれる可能性があります。
• 更新するには、まずバージョンノートを確認して、現在の ref と対象バージョンの間に破壊的変更がないか調べます。次に ref を更新し、terraform init -upgrade を実行してから、適用前にプランを確認します。全手順についてはMaterialize のアップグレードを参照してください。
• モジュールの構成方法を確認するには、該当する <cloud>/examples/simple/main.tf を参考にしてください。その構成を、自分のプロジェクトで Git ソースを固定して再現します。これは、Materialize が独自の内部デプロイで採用しているパターンです。

デプロイ後のセットアップ

kubectl の設定

terraform apply の後、新しいクラスターと通信するように kubectl を設定します。

AWS：

aws eks update-kubeconfig --name $(terraform output -raw eks_cluster_name) --region <region>

Azure：

az aks get-credentials --resource-group <rg> --name $(terraform output -raw aks_cluster_name)

GCP：

gcloud container clusters get-credentials $(terraform output -raw gke_cluster_name) --region <region>

Materialize への接続

ポート：

• 6875：PostgreSQL 互換 SQL（pgwire）
• 6876：HTTP API
• 8080：Materialize Console（HTTPS）

パブリック（インターネット向け）ロードバランサーを使用する場合（internal_load_balancer = false）：

AWS（NLB DNS を使用）：

psql "postgres://mz_system@$(terraform output -raw nlb_dns_name):6875/materialize"
open "https://$(terraform output -raw nlb_dns_name):8080/materialize"

Azure / GCP（ロードバランサーの IP を使用）：

psql "postgres://mz_system@$(terraform output -raw balancerd_load_balancer_ip):6875/materialize"
open "https://$(terraform output -raw console_load_balancer_ip):8080/materialize"

プライベート（内部）ロードバランサーを使用する場合（デフォルト）：

kubectl のポートフォワーディングを使用します。リソース ID は terraform output materialize_instance_resource_id にあります。

kubectl port-forward svc/mz<resource-id>-balancerd 6875:6875 -n materialize-environment
psql "postgres://mz_system@localhost:6875/materialize"

kubectl port-forward svc/mz<resource-id>-console 8080:8080 -n materialize-environment
open "http://localhost:8080"

認証が有効な場合は、パスワードに external_login_password_mz_system の出力を使用します。初期セットアップ後に専用ユーザーを作成し、通常の操作で mz_system を使用するのは避けてください。

オブザーバビリティ

enable_observability = true の場合、事前設定済みの Materialize ダッシュボードとともに、Prometheus と Grafana が monitoring 名前空間にデプロイされます。

kubectl port-forward svc/grafana 3000:80 -n monitoring
# Username: admin, Password: terraform output -raw grafana_admin_password

Materialize のアップグレード

1. まず、対象バージョンのバージョンノートを確認します。バージョンによっては、更新前に対処が必要な破壊的変更や特別なアップグレード要件があります。
2. v26 より前のバージョンでは、マイナーバージョンを一度に 1 つずつアップグレードします。v26 以降では、マイナーバージョンをスキップできます。
3. ダウングレードはサポートされていません。
4. アップグレードの順序：最初にオペレーターをアップグレードし、次にインスタンスをアップグレードします。

Terraform を使用する場合： 変数の environmentd_version（必要に応じて operator_version も）を更新し、terraform apply を実行します。v1alpha1 の場合は、request_rollout も新しい UUID に更新してください。

アップグレードの全手順については、このリポジトリの skills/materialize-docs/self-managed-deployments/upgrading/index.md にある materialize-docs スキル（クラウド別ガイドは同階層の upgrade-on-* ディレクトリにあります）、またはオンラインのアップグレードドキュメントを参照してください。アップグレード前に、破壊的変更がないか必ずバージョンノートを確認してください。

インスタンスのサイズ選定

Materialize ノードには、スワップ用のローカル NVMe ストレージを備えたメモリ最適化インスタンスを使用してください。

クラウド	インスタンスタイプ	vCPU	メモリ	クラスターの最大サイズ
AWS	r8gd.2xlarge	8	64 GiB	約300cc
AWS	r8gd.4xlarge	16	128 GiB	約600cc
AWS	r8gd.8xlarge	32	256 GiB	約1200cc
AWS	r8gd.16xlarge	64	512 GiB	約3200cc
Azure	Standard_E4pds_v6	4	32 GiB	変動
GCP	c4a-highmem-8-lssd	8	64 GiB	変動

vCPU とメモリの比率が 1:8、ローカルストレージとメモリの比率が 8:1 の ARM ベース CPU を推奨します。

よくある注意点

• ECR 認証の競合：公開イメージの取得時に terraform apply が 403 エラーで失敗する場合は、docker logout public.ecr.aws を実行してから再試行してください。
• GCP API：Terraform を実行する前に、複数の GCP API（container、compute、sqladmin、servicenetworking、iamcredentials、iam、storage）を有効にする必要があります。
• Azure プレビュー機能：Azure にデプロイする前に、EnableAPIServerVnetIntegrationPreview を登録してください。
• 自己署名証明書：シンプルなサンプルでは自己署名 TLS を使用しています。本番環境では、実際の CA または ACME 発行者を使用してください。パブリック ACME 発行者（Let's Encrypt など）を使用する場合は、パブリック CA は *.cluster.local の名前に署名できないため、internal_issuer_ref を別途設定してください。
• statement_timeout：メタデータバックエンド URL に statement_timeout=15min を含めてください。含めない場合、メタデータ操作がタイムアウトする可能性があります。
• コンソールの読み込みが遅い：コンソール UI の読み込みが遅い場合は、内部 SQL ポート 6877 経由で mz_catalog_server クラスターのサイズを 25cc から 50cc に増やしてください。

トラブルシューティング

オペレーターのステータスを確認する：

kubectl -n materialize get all
kubectl -n materialize logs -l app.kubernetes.io/name=materialize-operator

Materialize インスタンスを確認する：

kubectl -n materialize-environment get all
kubectl -n materialize-environment logs <pod-name>
kubectl -n materialize-environment describe pod/<pod-name>

Materialize CR のステータスを確認する：

kubectl get materialize -n materialize-environment -o jsonpath='{.items[0].status}'

正常な場合、CR のステータスには UpToDate と表示されます。

テスト

test/ のテストハーネスは Rust を使用し、ライフサイクル全体のテスト（init、apply、verify、destroy）を実行します。

cd test
cargo run -- run aws --owner "Name" --license-key-file key.txt \
  --aws-region us-east-1 --aws-profile my-profile

検証では、Materialize CR のステータスが UpToDate であること、すべての Pod（environmentd、console、balancerd、clusterd）が Running であること、SQL 経由で SELECT 1 が成功することを確認します。

このスキルを最新の状態に保つ

frontmatter メタデータの verified-against 値には、このスキルが最後に検証された時点のアップストリームのコミットが記録されています。スキルを更新するには、次の手順を実行します。

1. そのコミットから現在の main までのアップストリームリポジトリの差分を確認し、variables.tf ファイル、設定例、README に注目します。
2. 影響を受けるセクション（変数のデフォルト値、モジュールの表、インスタンスタイプ、注意点）をここで更新します。
3. verified-against を新しいコミット SHA に更新します。