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 1 commit
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

@kay-kim kay-kim Oct 20, 2025

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-hosted" >}}
Copy link
Contributor

@kay-kim kay-kim Oct 14, 2025

Choose a reason for hiding this comment

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

Heh ... "Self-managed"

### 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.
Copy link
Contributor

@kay-kim kay-kim Oct 14, 2025

Choose a reason for hiding this comment

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

Not quite sure this is characterized as a limitation. And we don't mention Frontegg anywhere, which is more of our implementation detail on the cloud side anyways. So, probably combine the lines 86-88 up here, kind of like:

The following resources apply only to Materialize Cloud and are not supported in self-managed configurations:

or

The following resources apply only to Materialize Cloud's identity provider and are not supported in self-managed configurations:

Copy link
Contributor Author

@bobbyiliev bobbyiliev Oct 17, 2025

Choose a reason for hiding this comment

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

Thank you for the suggestions, @kay-kim. Let me know what you think now!

{{< /warning >}}

Configure the provider for self-hosted 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-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` |
Comment on lines 114 to 125
Copy link
Contributor

@jubrad jubrad Oct 15, 2025

Choose a reason for hiding this comment

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

Configuration Parameters here is provider configuration?


{{< /tab >}}
{{< /tabs >}}

{{< warning >}}
**Migration warning:**

Switching between SaaS and self-hosted modes requires careful state file
Copy link
Contributor

@kay-kim kay-kim Oct 14, 2025

Choose a reason for hiding this comment

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

SaaS -> Cloud?
self-hosted -> self-managed

management as resource references and regional configurations differ between
modes. We strongly recommend using a consistent configuration mode from the
Copy link
Contributor

@kay-kim kay-kim Oct 14, 2025

Choose a reason for hiding this comment

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

What does "using a consistent configuration mode" mean?
Does that mean don't migrate?

Copy link
Contributor Author

@bobbyiliev bobbyiliev Oct 17, 2025

Choose a reason for hiding this comment

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

Yep, it mainly applies to the Cloud setup. If you configure the Terraform provider using hostname and password, you won't be able to use the Frontegg resources. Switching later to use only an App Password would break the existing state file, since it changes how resource IDs are stored.

With App Password + Frontegg authentication, you can manage resources across all Cloud regions, so the state file also includes the region ID as part of each resource identifier. That concept doesn't exist in self-managed mode, which makes the state incompatible between the two configurations. This is why we recommend sticking with one configuration from the start.

Copy link
Contributor

@kay-kim kay-kim Oct 17, 2025

Choose a reason for hiding this comment

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

Then, should we just tell people that they can't use the Materialize provider to switch between Materialize Cloud and Self-managed Materialize? (not sure if that is a product question, cc: @maheshwarip

Copy link
Contributor Author

@bobbyiliev bobbyiliev Oct 17, 2025

Choose a reason for hiding this comment

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

Hm no, not really. The issue only happens if you start using Materialize Cloud with one auth mode and later switch to another.

For example, if you first configure the provider with host and password (the self-managed style but with Cloud), and then switch to using an app password (eg. Frontegg) for Cloud, Terraform won't recognize your existing resources anymore because the resource IDs are generated differently in each mode.

So "use a consistent configuration mode" just means: when using Cloud pick the right setup from the start and stick with it, otherwise your Terraform state will break when you switch the auth mode (not going from Cloud to Self-managed, but the auth mode in the Terraform Provider itself).

Copy link
Contributor

@kay-kim kay-kim Oct 20, 2025

Choose a reason for hiding this comment

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

Oh ... then, should we clarify by explicitly stating "authentication" mode then?

The authentication mode impacts how Terraform manages your resource state. Switching authentication mode breaks your Terraform state file; i.e., Terraform will no longer recognize existing resources after such a switch. If possible, avoid changing the authentication mode after initial configuration.

beginning to avoid complex state migrations.
{{< /warning >}}