docs: clarify terraform provider configuration modes #33842
Conversation
| {{</ tab >}} | ||
|
|
||
| **Minimum requirements:** `terraform-provider-materialize` v0.8.1+ | ||
| {{< tab "Self-hosted" >}} |
| **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. |
There was a problem hiding this comment.
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:
There was a problem hiding this comment.
Thank you for the suggestions, @kay-kim. Let me know what you think now!
| {{< warning >}} | ||
| **Migration warning:** | ||
|
|
||
| Switching between SaaS and self-hosted modes requires careful state file |
There was a problem hiding this comment.
SaaS -> Cloud?
self-hosted -> self-managed
|
|
||
| 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 |
There was a problem hiding this comment.
What does "using a consistent configuration mode" mean?
Does that mean don't migrate?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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).
2 participants
Motivation
Adding details for the two different auth modes available in our terraform provider to prevent confusion in users.
Tips for reviewer
Checklist
$T ⇔ Proto$Tmapping (possibly in a backwards-incompatible way), then it is tagged with aT-protolabel.