Secret handling

[ISaxvik]

Nebari version: 2026.3.1rc1

Hello!
We are trying to redeploy nebari from wsl, running on azure. I have troubles with security.keycloak.initial_root_password in nebari config, and am unsure about the best way to handle it :) Help is greatly appreciated!

Scenario 1:
I set security.keycloak.initial_root_password: NEBARI_SECRET_initial_root_password in my config and set the environment variable before running nebari deploy.
As per Omitting sensitive values, I expected secret substitution.
However, the rendered config and deployment pass the literal string "NEBARI_SECRET_initial_root_password" as the password, causing Keycloak login to fail:

[tofu]: + set {
[tofu]: + name  = "initial_root_password"
[tofu]: + value = "NEBARI_SECRET_initial_root_password"
[tofu]: }

Scenario 2:
If I omit security.keycloak.initial_root_password from the config, Nebari generates a new password each deploy, which is not the current root password, so Keycloak login fails:

[tofu]: + set {
[tofu]: + name  = "initial_root_password"
[tofu]: + value = "NEW_PASSWORD_GENERATED_DURING_DEPLOY"
[tofu]: }

Both scenarios result in:

Failed to configure nebari-bot user after 10 attempts: 401: b'{"error":"invalid_grant","error_description":"Invalid user credentials"}'

The only way I have managed to get the deployment to succeed is by having security.keycloak.initial_root_password in clear text (and then resetting it in keycloakx manually afterwards).

Expected:
Either

• Environment variable substitution works for this field, or
• Nebari persists and reuses the original root password after first deploy.

Question:
What is the recommended way to manage the Keycloak root password securely across redeploys?

[viniciusdc]

Hey @ISaxvik! 👋

I just traced through the codebase and found the issue - looks like the docs are out of date. There was a pretty major refactor back in PR #1833 (Aug 2023) that completely changed how secret handling works, but the documentation wasn't fully updated.

The old pattern (which the docs still reference) used to work like:

security:
  keycloak:
    initial_root_password: NEBARI_SECRET_my_password

export my_password="actual_password"

But that code was removed during the refactor of the extension mechanism. The current implementation works differently - it doesn't look for placeholder strings in the YAML at all.

Can you try this instead?

Option 1: Omit the field entirely from your config
Just remove the initial_root_password line from your nebari-config.yaml, then set:

export NEBARI_SECRET__security__keycloak__initial_root_password="your_actual_current_keycloak_password"
nebari deploy -c nebari-config.yaml

Option 2: Set it to an empty string

security:
  keycloak:
    initial_root_password: ""

Then use the same env var as above.

Can you give that a shot and let me know if it picks up the env var correctly? If it works, I'll get the docs updated to reflect the current approach.

[ISaxvik]

Great, that worked! Thank you 😄

For both options, the deploy completes successfully. However, at the end of the deploy logs, the initial root password is printed in clear text so that the last few lines look like this:

Kubernetes kubeconfig located at file:///tmp/NEBARI_KUBECONFIG
Keycloak master realm username=root password=INITIAL_ROOT_PASSWORD_IN_CLEARTEXT
Additional administration docs can be found at https://www.nebari.dev/docs/how-tos/configuring-keycloak

Is there also a way to avoid this? :) 🙂

[viniciusdc]

Uhmmm, that's interesting, in the option where the field is left empty, it should've triggered the false condition for this if statement:

nebari/src/_nebari/deploy.py

Lines 72 to 77 in 88f38d9

	if password:
	print(f"Kubecloak master realm username={username} password={password}")
	print(
	"Additional administration docs can be found at https://www.nebari.dev/docs/how-tos/configuring-keycloak"
	)

Also, if you are using the latest RC version, the message should have been a bit different. Can you double-check the nebari-- version?

[ISaxvik]

I was trying out
nebari --version 2026.3.1rc1 but can try tomorrow with a downgraded version 😄

Tested again and for me, the logs display the secret in cleartext for both options

Kubernetes kubeconfig located at file:///tmp/NEBARI_KUBECONFIG
Keycloak master realm username=root password=INITIAL_ROOT_PASSWORD_IN_CLEARTEXT
Additional administration docs can be found at https://www.nebari.dev/docs/how-tos/configuring-keycloak