default cluster to quickstart by jshiwamV · Pull Request #136 · MaterializeInc/materialize-terraform-self-managed

jshiwamV · 2026-01-05T14:14:16Z

create a default service account super user role which the user will use for their default login when password based auth is enabled.

Screen.Recording.2026-01-06.at.8.53.23.PM.mov

jubrad

We might want to think about this a bit more...

There are a couple of ways we could approach this, one way is to just automatically create a new role (not service account), if we're using password or sasl (or probably No auth).

The other way would be to take a list of objects that represent initial users that should be created... This would be a tuple of something like user, password, superuser, login

Yet another way would be to have a pod that reads from a secret and generates all roles in that secret.

I'm not convinced that always creating a role is the best option to choose here.

jshiwamV · 2026-01-07T06:15:03Z

I am inclined towards having user provided input for generating credentials, yet I don't like the idea of exposing a lot of configuration knobs to the user. I went ahead with the service account role because it could be used by user applications via serivce account, while the user roles would only be useful for login. I want to know the reason why you suggested that we shouldn't be creating service account role.

jshiwamV · 2026-01-07T06:18:16Z

the idea behind this implementation was to provide a superuser role with credentials which can be used to further create other roles needed by the user.

jubrad · 2026-01-29T05:38:53Z

+Connect using psql with the default service account credentials:
+```bash
+# Get the password (use jq -r to decode JSON-escaped characters)
+terraform output -json mz_instance_service_account_credentials | jq -r '.password'


service_account isn't applicable in self-managed, I think this should be something like default_superuser_credentials

jubrad · 2026-01-29T05:45:58Z

+locals {
+  secret_name          = "${var.instance_name}-materialize-backend"
+  mz_resource_id       = data.kubernetes_resource.materialize_instance.object.status.resourceId
+  service_account_name = "default"


yeah, lets not call this default...

I'd rather this just be a default_superuser variable..

variable "server_config" { description = "Username and password for default super user" type = tuple([string, string]) default = null sensitive = true }

jubrad

Definitely some changes required, here. I'd like to see this be optoinal in general rather than based being based on the type of authenticator. We can default in the examples.

Might be worth @bobbyiliev taking a look as well.

bobbyiliev · 2026-01-29T16:22:03Z

+# Create a job to create the default service account with superuser privileges
+# https://materialize.com/docs/security/self-managed/access-control/manage-roles/#create-individual-userservice-account-roles
+resource "kubernetes_job" "create_service_account" {
+  count = contains(["Password", "Sasl"], var.authenticator_kind) ? 1 : 0


Thanks for working on this!

As Justin mentioned, rather than tying this to authenticator_kind, maybe we can make superuser creation explicitly optional?

Eg:

variable "superuser_credentials" { description = "Username and password for superuser. If null, no superuser will be created." type = object({ username = string password = string }) default = null sensitive = true }

Then the job only runs when set:

resource "kubernetes_job" "create_superuser" { count = var.superuser_credentials != null ? 1 : 0 # ... }

That way users explicitly opt-in and the username isn't hardcoded to "default".

are these credentials useful when authenticator_kind is None? I tied it to authenticator_kind, because if auth_kind is None, then there would be no use of credentials isn't it?

Should we rather check for both conditions? i.e.

superuser_credentials != null && authenticator_kind != None?

Good point! As we discussed this during the call yesterday, if the authenticator kind is None the CREATE ROLE "<role>" WITH LOGIN PASSWORD '<password>'; statement will fail I believe.

bobbyiliev · 2026-01-29T16:23:56Z

+    }
+  }
+
+  wait_for_completion = true


With wait_for_completion = true and 5m timeout, does this work reliably if balancerd isn't ready yet?

yeah balancerd doesn't take that long to be ready. I remember @jubrad had mentioned some scenarios where envd would take time to be ready, but that is well under 5mins now after we disabled caching in coredns. #134

I might as well add update = 5m so that this timeout is applied for updates as well.

bobbyiliev · 2026-01-29T16:24:24Z

+
+        container {
+          name  = "psql"
+          image = "postgres:16-alpine"


Shall we bump this to a newer Postgres version?

jshiwamV · 2026-02-03T12:00:07Z

Results after addressing comments:

PGwire:

 psql -h sj-man2026020210314845120000002e-73afc19726db6ff3.elb.us-east-1.amazonaws.com -U materialize_admin -p 6875
Password for user materialize_admin: 
NOTICE:  connected to Materialize v26.3.0
  Org ID: 6c64cfb5-85f0-422e-a489-e34eb3c5991c
  Region: aws/us-east-1
  User: materialize_admin
  Cluster: quickstart
  Database: materialize_admin
  Schema: public
  Session UUID: 019c235a-a9cc-7b6d-8bd3-0b9b3302d4e4

Issue a SQL query to get started. Need help?
  View documentation: https://materialize.com/s/docs
  Join our Slack community: https://materialize.com/s/chat
    
NOTICE:  session database "materialize_admin" does not exist
HINT:  Create the database with CREATE DATABASE or pick an extant database with SET DATABASE = name. List available databases with SHOW DATABASES.
psql (15.13 (Homebrew), server 9.5.0)
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off)
Type "help" for help.

materialize_admin=> show cluster;
  cluster   
------------
 quickstart
(1 row)

materialize_admin=> show role;
ERROR:  Expected MEMBERSHIP, found semicolon
LINE 1: show role;
                 ^
materialize_admin=> show roles;
        name         | comment 
---------------------+---------
 anonymous_http_user | 
 default             | 
 materialize_admin   | 
(3 rows)

materialize_admin=>

Console

SuperUser is redirected to quickstart cluster

jshiwamV · 2026-02-03T13:10:28Z

Job Logs don't contain sensitive info:

kubectl logs  main-create-role-58e0fa75-8ccgf    -n materialize-environment             
NOTICE:  connected to Materialize v26.3.0
  Org ID: 6c64cfb5-85f0-422e-a489-e34eb3c5991c
  Region: aws/us-east-1
  User: mz_system
  Cluster: mz_system
  Database: materialize
  Schema: public
  Session UUID: 019c234c-a2ac-7c48-b021-83f446eff8ba

Issue a SQL query to get started. Need help?
  View documentation: https://materialize.com/s/docs
  Join our Slack community: https://materialize.com/s/chat
    
NOTICE:  connected to Materialize v26.3.0
  Org ID: 6c64cfb5-85f0-422e-a489-e34eb3c5991c
  Region: aws/us-east-1
  User: mz_system
  Cluster: mz_system
  Database: materialize
  Schema: public
  Session UUID: 019c234c-a374-74d4-9492-418bdaa53398

Issue a SQL query to get started. Need help?
  View documentation: https://materialize.com/s/docs
  Join our Slack community: https://materialize.com/s/chat
    
CREATE ROLE
NOTICE:  RBAC is disabled so no role attributes or object ownership will be considered when executing statements
HINT:  To enable RBAC globally run `ALTER SYSTEM SET enable_rbac_checks TO TRUE` as a superuser. TO enable RBAC for just this session run `SET enable_session_rbac_checks TO TRUE`.

Update Secnario when ALTER ROLE command is run

kubectl logs main-create-superuser-dzq7l -n materialize-environment                                   
NOTICE:  connected to Materialize v26.3.0
  Org ID: 6c64cfb5-85f0-422e-a489-e34eb3c5991c
  Region: aws/us-east-1
  User: mz_system
  Cluster: mz_system
  Database: materialize
  Schema: public
  Session UUID: 019c2380-6edf-7ad8-bc2c-92a72e8e717a

Issue a SQL query to get started. Need help?
  View documentation: https://materialize.com/s/docs
  Join our Slack community: https://materialize.com/s/chat
    
NOTICE:  connected to Materialize v26.3.0
  Org ID: 6c64cfb5-85f0-422e-a489-e34eb3c5991c
  Region: aws/us-east-1
  User: mz_system
  Cluster: mz_system
  Database: materialize
  Schema: public
  Session UUID: 019c2380-6fa4-7a6f-a2a2-8992b9848e84

Issue a SQL query to get started. Need help?
  View documentation: https://materialize.com/s/docs
  Join our Slack community: https://materialize.com/s/chat
    
ALTER ROLE
NOTICE:  RBAC is disabled so no role attributes or object ownership will be considered when executing statements
HINT:  To enable RBAC globally run `ALTER SYSTEM SET enable_rbac_checks TO TRUE` as a superuser. TO enable RBAC for just this session run `SET enable_session_rbac_checks TO TRUE`.

I have also created secret for superuser creds so that we can refer the secrets in the job and the secrets won't be visible in job spec as well.

job spec

automountServiceAccountToken: true
  containers:
  - command:
    - sh
    - -c
    - |
      ROLE_EXISTS=$(PGPASSWORD=$MZ_PASSWORD psql -h $MZ_HOST -p 6875 -U mz_system -d materialize -tAc "SELECT 1 FROM mz_roles WHERE name = '$SUPERUSER_USERNAME';")
      if [ -z "$ROLE_EXISTS" ]; then
        PGPASSWORD=$MZ_PASSWORD psql -h $MZ_HOST -p 6875 -U mz_system -d materialize \
          -c "CREATE ROLE $SUPERUSER_USERNAME WITH SUPERUSER LOGIN PASSWORD '$SUPERUSER_PASSWORD';"
      else
        PGPASSWORD=$MZ_PASSWORD psql -h $MZ_HOST -p 6875 -U mz_system -d materialize \
          -c "ALTER ROLE $SUPERUSER_USERNAME PASSWORD '$SUPERUSER_PASSWORD';"
      fi
    env:
    - name: MZ_HOST
      value: mz71qwyy52se-balancerd.materialize-environment.svc.cluster.local
    - name: MZ_PASSWORD
      valueFrom:
        secretKeyRef:
          key: external_login_password_mz_system
          name: main-materialize-backend
          optional: false
    - name: SUPERUSER_USERNAME
      valueFrom:
        secretKeyRef:
          key: username
          name: main-superuser-credentials
          optional: false
    - name: SUPERUSER_PASSWORD
      valueFrom:
        secretKeyRef:
          key: password
          name: main-superuser-credentials
          optional: false

bobbyiliev

Overall looking good! The refactoring to use secrets for credentials is a nice improvement.

Would maybe still want @jubrad to take a quick look too.

Also, leaving a few extra suggestions.

bobbyiliev · 2026-02-06T12:56:23Z

+terraform output -json mz_instance_superuser_credentials | jq -r '.password'
+
+psql -h <NLB_DNS> -p 6875 -U <username>


Should we show how to get the username too? Something like:

terraform output -json mz_instance_superuser_credentials | jq -r '.username'

bobbyiliev · 2026-02-06T12:56:49Z

+# Get the password (use jq -r to decode JSON-escaped characters)
+terraform output -json mz_instance_superuser_credentials | jq -r '.password'
+
+psql -h <LoadBalancerIP> -p 6875 -U <username>


Should we show how to get the username too? Something like:

terraform output -json mz_instance_superuser_credentials | jq -r '.username'

bobbyiliev · 2026-02-06T12:56:57Z

+# Get the password (use jq -r to decode JSON-escaped characters)
+terraform output -json mz_instance_superuser_credentials | jq -r '.password'
+
+psql -h <LoadBalancerIP> -p 6875 -U <username>


Should we show how to get the username too? Something like:

terraform output -json mz_instance_superuser_credentials | jq -r '.username'

bobbyiliev · 2026-02-06T12:58:44Z

+                -c "CREATE ROLE $SUPERUSER_USERNAME WITH SUPERUSER LOGIN PASSWORD '$SUPERUSER_PASSWORD';"
+            else
+              PGPASSWORD=$MZ_PASSWORD psql -h $MZ_HOST -p 6875 -U mz_system -d materialize \
+                -c "ALTER ROLE $SUPERUSER_USERNAME PASSWORD '$SUPERUSER_PASSWORD';"
+            fi
+            EOT


Thanks for verifying the logs! The env vars from secrets are good. I just wonder if psql errors out, would it echo the query?

nope psql won't echo the query, we need to pass the following flags for different scenarios in order to get querie/ output of command that's been run

Input and output options: -a, --echo-all echo all input from script -b, --echo-errors echo failed commands -e, --echo-queries echo commands sent to server -E, --echo-hidden display queries that internal commands generate

bobbyiliev · 2026-02-06T13:01:01Z

+locals {
+  secret_name      = "${var.instance_name}-materialize-backend"
+  mz_resource_id   = data.kubernetes_resource.materialize_instance.object.status.resourceId
+  create_superuser = contains(["Password", "Sasl"], var.authenticator_kind) && var.superuser_credentials != null


This addresses the earlier discussion nicely! Just one thing to confirm, if someone sets superuser_credentials but uses authenticator_kind = "None", should we add a validation to warn them it won't do anything?

Might be overkill though.

that actually makes sense, here I made the change

jshiwamV · 2026-03-11T03:17:29Z

I can close this PR if you don't see it as a good fit @jubrad

jshiwamV marked this pull request as ready for review January 6, 2026 15:22

jshiwamV requested review from alex-hunt-materialize, bobbyiliev and jubrad January 6, 2026 15:57

jubrad reviewed Jan 6, 2026

View reviewed changes

jubrad reviewed Jan 29, 2026

View reviewed changes

jubrad requested changes Jan 29, 2026

View reviewed changes

bobbyiliev reviewed Jan 29, 2026

View reviewed changes

Comment thread kubernetes/modules/materialize-instance/main.tf

jshiwamV added 6 commits February 2, 2026 20:28

default cluster to quickstart, doesn't work

29565c4

lint fixes

53fe6a3

create role

efb34dc

create job with hash to avoid recreation and keep sql idempotent

0f650ab

readme updates

95586cd

better readme

b332900

fix security concerns and address comments

88c9b50

jshiwamV force-pushed the fix-default-cluster branch from 64c6bab to 88c9b50 Compare February 3, 2026 13:09

jshiwamV added 2 commits February 3, 2026 18:42

don't forget to auto gen readme, comeonn

26be619

azure

2d96336

bobbyiliev requested changes Feb 6, 2026

View reviewed changes

fix nit comments

45bab19

jshiwamV mentioned this pull request Mar 3, 2026

Network policies #153

Merged

		terraform output -json mz_instance_superuser_credentials \| jq -r '.password'

		psql -h <NLB_DNS> -p 6875 -U <username>

Conversation

jshiwamV commented Jan 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jubrad left a comment

Choose a reason for hiding this comment

Uh oh!

jshiwamV commented Jan 7, 2026

Uh oh!

jshiwamV commented Jan 7, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jubrad left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jshiwamV commented Feb 3, 2026

Uh oh!

jshiwamV commented Feb 3, 2026

Uh oh!

bobbyiliev left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jshiwamV commented Mar 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jshiwamV commented Jan 5, 2026 •

edited

Loading