Skip to main content
Version: v5.0 Stable

Reset the admin password

If you're locked out of vCluster Platform, pick the method that matches the access you still have.

  • UI access. Use Reset a user's password. It works for the admin account too.
  • Kubernetes access to the platform storage API and credential Secrets. Use the vCluster CLI method. No platform login is required.
  • Direct credential-Secret access. Use Kubectl to patch an existing account's password without revoking sessions.
  • No platform login, a deleted admin, or an external database. Use Helm recovery.

On installations with an external database, the platform's embedded Kubernetes API stores the admin User and credentials in that database. The hosting cluster's Kubernetes API doesn't expose that User or its password reference. Use Helm recovery instead.

No authentication methods on the login page

If you don't see any authentication methods on the login page at all, password login was likely disabled and you lost access to SSO. Re-enable password login first, then come back to reset the password. See Recovery.

vCluster CLI​

Your Kubernetes credentials must allow reading the User and reading and updating its credential Secret. They must also allow listing and deleting its access keys. Select the Kubernetes context that exposes storage.loft.sh. A platform CLI login alone is insufficient. For external-database installations, use Helm recovery.

Modify the following with your specific values to generate a copyable command:
vcluster platform reset password --user=admin
Check session and access-key revocation

When updating an existing credential Secret, the CLI attempts to delete the user's access keys, including browser sessions and API tokens. Check warnings for failed deletions. If the CLI creates a missing credential Secret, it doesn't delete existing access keys. Rotating through Helm recovery or Kubectl leaves existing sessions and access keys untouched. After an incident, revoke keys and sessions separately.

Kubectl​

Use this method for an existing User whose credential Secret is accessible through Kubernetes. You need permission to read the User and read and update that Secret. For an external database, use Helm recovery.

Find the password secret​

Run the following command to look up the admin user's password reference. Replace admin with the username configured by admin.username:

$ kubectl get users.storage.loft.sh admin -o yaml
apiVersion: storage.loft.sh/v1
kind: User
metadata:
...
spec:
passwordRef:
key: password
secretName: loft-user-secret-admin
secretNamespace: vcluster-platform
...

Note secretName, secretNamespace, and key under passwordRef. Older installs can use the loft namespace. Use those values in the next step. If the reference or key is absent, use Helm recovery.

Set a new password​

Run this example in Bash with jq and sha256sum installed. Set the Secret name, namespace, and key from the User's password reference. Enter a strong new password when prompted, so it doesn't appear in shell history:

Modify the following with your specific values to generate a copyable command:
SECRET_NAME=loft-user-secret-admin
SECRET_NAMESPACE=vcluster-platform
SECRET_KEY=password
read -r -s -p "New password: " NEW_PASSWORD
printf "\n"
NEW_PASSWORD_HASH=$(printf '%s' "$NEW_PASSWORD" | sha256sum | awk '{print $1}')
kubectl get secret "$SECRET_NAME" -n "$SECRET_NAMESPACE" -o json | jq --arg key "$SECRET_KEY" --arg password "$(printf '%s' "$NEW_PASSWORD_HASH" | base64 | tr -d '\n')" '.data[$key]=$password' | kubectl apply -f -
unset NEW_PASSWORD NEW_PASSWORD_HASH

After that you can log in to vCluster Platform with the configured admin username and your new password.

Recover through Helm​

Use Helm recovery to restore administrator access during an SSO outage or after the local admin was deleted. This procedure restores account access. It doesn't restore management resources or databases. For those tasks, see Restore Platform.

System admins with access to the platform's Helm release and Kubernetes namespace can recover access without a platform login. Use this procedure when:

  • The admin never existed because the installation used admin.create: false.
  • The admin User was deleted.
  • The admin User exists, but its credential Secret was deleted.
  • An existing admin needs a new password on an external-database installation, or you want to rotate it through Helm configuration.

Recovery runs when a platform instance becomes leader, so it needs a rolling restart of the platform Deployment. It supports normal installations and installations with an external database, and it still applies when env.DISABLE_DEFAULTS: "true" is set.

Admin recovery is available in Platform v4.12.2 and is included in Platform v5.0. To see which versions your Helm repository offers, run helm search repo loft/vcluster-platform.

The first configuration-driven rotation can take two upgrades

If the admin account and credential Secret exist but no baseline is recorded, the first run records one and leaves the live password unchanged. Read Rotate the password of an existing admin before you start.

Locked accounts remain locked

Recovery doesn't unlock an existing admin account. Restore SSO or use another authenticated global admin to unlock it. If neither is available, contact support. Don't delete the account or database as a recovery shortcut.

Required access​

You need Kubernetes access to manage the platform Helm release, password-source Secret, configuration, and Deployment. These permissions allow recovery of a global administrator account. Restrict and audit their use. Helm recovery doesn't require a platform login or direct database access, but the database must be reachable for startup to complete.

Configure the admin password​

Add the recovery settings to the values file that holds the rest of your custom settings. Don't put them in a new file containing only the admin snippet, because the upgrade applies whichever values file you pass.

Set admin.create: true and a strong password with admin.password, or reference an existing Kubernetes Secret in the release namespace:

admin:
# Enable recovery for the configured administrator.
create: true
passwordSecretRef:
# Create this Secret in the release namespace before upgrading.
name: platform-admin-password
key: password
config:
auth:
password:
# Enable password login during SSO recovery.
disabled: false

The Secret key holds the plaintext password, and admin.passwordSecretRef.key defaults to password. admin.passwordSecretRef takes precedence over admin.password.

Keep admin.username set to the account you need to recover. Changing it targets a different admin account. It doesn't rename or recover the original account.

Password authentication must be enabled. SSO-only installations can set config.auth.password.disabled: false in Helm values.

If you already use environment-based Secret references, that pattern also works:

admin:
create: true
password: "$PLATFORM_ADMIN_PASSWORD"
envValueFrom:
PLATFORM_ADMIN_PASSWORD:
secretKeyRef:
name: platform-admin-password
key: password

Leave admin.passwordSecretRef.name empty for this form, which is the chart default.

Don't drop admin.password while admin.create is true

The chart ships admin.password: "my-password". Removing the key from your values file doesn't remove the password configuration. It restores that default. If the default differs from the recorded baseline, the next restart rotates the live admin password to a well-known value. Keep the key set to the password you want.

To clear admin credentials out of a values file safely, set admin.create: false first. That turns recovery off. See Disable the local admin account.

Apply the configuration​

Keep the chart version pinned to your installed compatible version during recovery. If GitOps manages the release, update its source manifests and reconcile them instead of running a separate Helm upgrade.

Modify the following with your specific values to generate a copyable command:
helm upgrade vcluster-platform loft/vcluster-platform --namespace vcluster-platform --version 5.0.0 --values values.yaml --wait
kubectl --namespace vcluster-platform rollout restart deployment/loft
kubectl --namespace vcluster-platform rollout status deployment/loft

Replace the release, namespace, and Deployment names with your own.

The explicit restart matters when the upgrade leaves the pod template unchanged, which is what happens when only the contents of the referenced Secret change. Allow leader handover to finish before testing login. Password rotation through Helm preserves existing sessions and access keys.

Rotate the password of an existing admin​

When the account and its credential Secret exist without a recorded baseline, the first recovery run records the configured password and leaves the live password alone. This prevents recovery from overwriting a password set through the UI or CLI. Rotation happens on a later run after the configured password differs from that baseline.

Rotating for the first time after moving to a chart with admin recovery therefore takes two upgrades:

  1. Upgrade and restart with your admin password configuration unchanged. Recovery records the baseline and the live password stays as it is.
  2. Set the new password, then apply and restart again. Recovery now sees a change and rotates the live password to match.

When you reference a Secret, set the new password in the key selected by admin.passwordSecretRef.key, then restart. This key defaults to password.

If the credential Secret is missing, recovery recreates it with the configured password on the next restart. The baseline-only first run doesn't apply in that case.

Verify recovery​

Log in with the username set by admin.username and the password you configured. The username defaults to admin. After a baseline-only first upgrade, the previous password still works. That's expected, and the section above explains why.

Recovery doesn't re-enable an admin account that was locked or disabled. An authenticated global admin must unlock the account in the UI. If no authenticated global admin session remains, restore SSO access first. See SSO recovery.

Accounts disabled on purpose

If the account was turned off by Disable the local admin account, set admin.create: false again once you regain access. Leaving it true lets the platform recreate a missing admin the next time an instance becomes leader.

Cleanup after recovery​

Verify SSO works with global admin permissions before disabling temporary password access. If your policy disables the local admin, follow Disable local admin, including locking the account and setting admin.create: false. Then restore your intended password-login policy. Keep all unrelated Helm settings intact.

Helm recovery preserves access keys and sessions. Revoke temporary or potentially compromised keys and sessions separately. Review audit logs and Kubernetes audit records for the recovery period. Startup reconciliation runs without an interactive platform user. Check startup logs as well, rather than expecting a user-initiated password-reset event. Remove temporary credentials and local files according to your secret-handling policy.

Troubleshoot recovery​

If recovery doesn't take effect, check the platform startup logs. Deliberate skips are logged as Admin recovery skipped along with the reason, such as an invalid password configuration or a credential Secret annotated with loft.sh/skip-update: "true".

A same-named User that isn't the managed admin, or a User without a valid password reference, is left unchanged. If recovery still fails after correcting the logged cause, contact support with versions and redacted logs. Don't delete loft-applied-defaults, replace the database, or share password Secrets to bypass recovery.