From f9578f1d0b6130b9db15afd14972088bf5363d21 Mon Sep 17 00:00:00 2001 From: bobbyiliev Date: Mon, 13 Oct 2025 15:30:42 +0300 Subject: [PATCH 1/2] docs: clarify terraform provider configuration modes --- .../content/manage/terraform/get-started.md | 129 +++++++++++------- 1 file changed, 83 insertions(+), 46 deletions(-) diff --git a/doc/user/content/manage/terraform/get-started.md b/doc/user/content/manage/terraform/get-started.md index ef3c395ee6869..31a3bbc510380 100644 --- a/doc/user/content/manage/terraform/get-started.md +++ b/doc/user/content/manage/terraform/get-started.md @@ -28,73 +28,110 @@ terraform { } ``` -## Authentication +## Provider configuration -To configure the provider to communicate with your Materialize region, you -need to authenticate with a Materialize username, app password, and other -specifics from your account. +The Materialize provider supports two distinct configuration modes depending on +your deployment type: + +{{< tabs >}} +{{< tab "Materialize Cloud" >}} +### Materialize Cloud + +For Materialize Cloud environments, configure the provider with your app password +and region. This configuration provides access to **all provider resources**, +including: + +- App passwords, users, SSO, and SCIM resources +- All database resources (clusters, sources, sinks, schemas, etc.) We recommend saving sensitive input variables as environment variables to avoid -checking secrets into source control. In Terraform, you can export Materialize -app passwords as a [Terraform environment variable](https://developer.hashicorp.com/terraform/cli/config/environment-variables#tf_var_name) +checking secrets into source control. In Terraform, you can export variables as +[Terraform environment variables](https://developer.hashicorp.com/terraform/cli/config/environment-variables#tf_var_name) with the `TF_VAR_` format. ```shell -export TF_VAR_MZ_PASSWORD= +export TF_VAR_materialize_password= ``` -In the `main.tf` file, add the provider configuration and any variable -references: +In your `main.tf` file, add the provider configuration: ```hcl -variable "MZ_PASSWORD" {} +variable "materialize_password" { + sensitive = true +} provider "materialize" { - password = var.MZ_PASSWORD - default_region = - database = + password = var.materialize_password # or use MZ_PASSWORD env var + default_region = "aws/us-east-1" # or use MZ_DEFAULT_REGION env var } ``` -## Creating service accounts +{{}} -**Minimum requirements:** `terraform-provider-materialize` v0.8.1+ +{{< tab "Self-hosted" >}} +### Self-hosted Materialize -As a best practice, we strongly recommend using [service accounts](/manage/access-control/create-service-accounts) -to connect external applications to Materialize. To create a -service account, create a new [`materialize_role`](https://registry.terraform.io/providers/MaterializeInc/materialize/latest/docs/resources/role) -and associate it with a new [`materialize_app_password`](https://registry.terraform.io/providers/MaterializeInc/materialize/latest/docs/resources/app_password) -of type `service`. More granular permissions for the service account can then -be configured using [role-based access control (RBAC)](/manage/access-control/#role-based-access-control-rbac). +For self-hosted Materialize instances, configure the provider with connection +parameters similar to a standard PostgreSQL connection. -```hcl -# Create a service user in the aws/us-east-1 region. -resource "materialize_role" "production_dashboard" { - name = "svc_production_dashboard" - region = "aws/us-east-1" -} +{{< warning >}} +**Important limitations for self-hosted mode:** -# Create an app password for the service user. -resource "materialize_app_password" "production_dashboard" { - name = "production_dashboard_app_password" - type = "service" - user = materialize_role.production_dashboard.name - roles = ["Member"] -} +Self-hosted configurations do **not** support Frontegg-dependent resources: +- `materialize_app_password` +- `materialize_user` +- `materialize_sso_config` and related SSO resources +- `materialize_scim_config` and related SCIM resources -# Allow the service user to use the "production_analytics" database. -resource "materialize_database_grant" "database_usage" { - role_name = materialize_role.production_dashboard.name - privilege = "USAGE" - database_name = "production_analytics" - region = "aws/us-east-1" -} +Only database resources are available (clusters, sources, sinks, schemas, etc.). +These organization and identity management resources require Materialize Cloud's +identity provider and will produce error messages if used in self-hosted mode. +{{< /warning >}} + +Configure the provider for self-hosted deployments: + +```shell +export TF_VAR_materialize_password= +``` + +In your `main.tf` file: -# Export the user and password for use in the external tool. -output "production_dashboard_user" { - value = materialize_role.production_dashboard.name +```hcl +variable "materialize_password" { + sensitive = true } -output "production_dashboard_password" { - value = materialize_app_password.production_dashboard.password + +provider "materialize" { + host = "materialized" # or use MZ_HOST env var + port = 6875 # or use MZ_PORT env var + username = "materialize" # or use MZ_USER env var + database = "materialize" # or use MZ_DATABASE env var + password = var.materialize_password # or use MZ_PASSWORD env var + sslmode = "disable" # or use MZ_SSLMODE env var } ``` + +#### Configuration parameters + +The following parameters are available for self-hosted configurations: + +| Parameter | Description | Environment Variable | Default | +|-----------|-------------|---------------------|---------| +| `host` | Materialize host address | `MZ_HOST` | - | +| `port` | Materialize port | `MZ_PORT` | `6875` | +| `username` | Database username | `MZ_USER` | `materialize` | +| `database` | Database name | `MZ_DATABASE` | `materialize` | +| `password` | Database password | `MZ_PASSWORD` | - | +| `sslmode` | SSL mode (`disable`, `require`, `verify-ca`, `verify-full`) | `MZ_SSLMODE` | `require` | + +{{< /tab >}} +{{< /tabs >}} + +{{< warning >}} +**Migration warning:** + +Switching between SaaS and self-hosted modes requires careful state file +management as resource references and regional configurations differ between +modes. We strongly recommend using a consistent configuration mode from the +beginning to avoid complex state migrations. +{{< /warning >}} From bedcb3be35f6de5465125f86e17a79a091b6ac8f Mon Sep 17 00:00:00 2001 From: bobbyiliev Date: Fri, 17 Oct 2025 15:55:56 +0300 Subject: [PATCH 2/2] docs: adjust wording in terraform guide --- .../content/manage/terraform/get-started.md | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/doc/user/content/manage/terraform/get-started.md b/doc/user/content/manage/terraform/get-started.md index 31a3bbc510380..b73644263c448 100644 --- a/doc/user/content/manage/terraform/get-started.md +++ b/doc/user/content/manage/terraform/get-started.md @@ -68,16 +68,16 @@ provider "materialize" { {{}} -{{< tab "Self-hosted" >}} -### Self-hosted Materialize +{{< tab "Self-managed" >}} +### Self-managed Materialize -For self-hosted Materialize instances, configure the provider with connection +For self-managed Materialize instances, configure the provider with connection parameters similar to a standard PostgreSQL connection. {{< warning >}} -**Important limitations for self-hosted mode:** +**Important limitations for self-managed mode:** -Self-hosted configurations do **not** support Frontegg-dependent resources: +The following resources apply only to Materialize Cloud's identity provider and are not supported in self-managed configurations: - `materialize_app_password` - `materialize_user` - `materialize_sso_config` and related SSO resources @@ -85,10 +85,10 @@ Self-hosted configurations do **not** support Frontegg-dependent resources: Only database resources are available (clusters, sources, sinks, schemas, etc.). These organization and identity management resources require Materialize Cloud's -identity provider and will produce error messages if used in self-hosted mode. +identity provider and will produce error messages if used in self-managed mode. {{< /warning >}} -Configure the provider for self-hosted deployments: +Configure the provider for self-managed deployments: ```shell export TF_VAR_materialize_password= @@ -113,7 +113,7 @@ provider "materialize" { #### Configuration parameters -The following parameters are available for self-hosted configurations: +The following parameters are available for self-managed configurations: | Parameter | Description | Environment Variable | Default | |-----------|-------------|---------------------|---------| @@ -130,8 +130,8 @@ The following parameters are available for self-hosted configurations: {{< warning >}} **Migration warning:** -Switching between SaaS and self-hosted modes requires careful state file -management as resource references and regional configurations differ between -modes. We strongly recommend using a consistent configuration mode from the -beginning to avoid complex state migrations. +Switching between Materialize Cloud and self-managed modes requires careful state +file management, as resource references and regional configurations differ between +the two. To avoid complex state migrations, we recommend choosing consistent configuration +mode from the beginning to avoid complex state migrations. {{< /warning >}}