Skip to content

docs: clarify terraform provider configuration modes #33842

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: clarify terraform provider configuration modes #33842

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f9578f1
docs: clarify terraform provider configuration modes
bobbyiliev Oct 13, 2025
bedcb3b
docs: adjust wording in terraform guide
bobbyiliev Oct 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
129 changes: 83 additions & 46 deletions doc/user/content/manage/terraform/get-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we mention the Cloud-specific configs here?
materialize_app_password
materialize_user
materialize_sso_config and related SSO resources
materialize_scim_config and related SCIM resources

Otherwise, we're only mentioning the Cloud-specific configs in SM tab (albeit in the SM tabs to not use them)

- 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_<name>` format.

```shell
export TF_VAR_MZ_PASSWORD=<app_password>
export TF_VAR_materialize_password=<app_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 = <region>
database = <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
{{</ tab >}}

**Minimum requirements:** `terraform-provider-materialize` v0.8.1+
{{< tab "Self-managed" >}}
### Self-managed 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-managed 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-managed 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"]
}
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
- `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-managed mode.
{{< /warning >}}

Configure the provider for self-managed deployments:

```shell
export TF_VAR_materialize_password=<database_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-managed 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 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 >}}