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.
• An authenticated vCluster CLI session. Use the vCluster CLI method.
• Kubernetes access only. Use Kubectl to patch the credential Secret of an account that still exists.
• No platform login, a deleted admin, or an external database. Use Helm recovery.

On installations with an external database, the admin User lives in the database rather than as a Kubernetes object. The kubectl procedure can't look up the password reference there, so 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

If you are still authenticated using the vCluster CLI you can easily reset the admin password:

Modify the following with your specific values to generate a copyable command:

ADMIN_USERNAME

vcluster platform reset password --user=admin

Existing sessions and access keys are invalidated

Resetting a password through the CLI deletes all of that user's existing access keys, including browser sessions, other CLI sessions, and any API tokens the user generated. Anyone using the old password or an existing access key for this user must log in again. Rotating the password through Helm recovery or the Kubectl method patches the credential Secret and leaves existing sessions and access keys untouched.

Kubectl

If you don't have CLI access, you can reset the password by patching the underlying Kubernetes secret directly.

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 user admin -o yaml
apiVersion: management.loft.sh/v1
kind: User
metadata:
  ...
spec:
  passwordRef:
    key: password
    secretName: loft-user-secret-admin
    secretNamespace: vcluster-platform
...

Note the secretName and secretNamespace under passwordRef. Older installs may use the loft namespace instead of vcluster-platform. You'll use both values in the next step.

Set a new password

Replace SECRET_NAME, SECRET_NAMESPACE, and my-new-password below with the values from the previous step and your new password, then run:

SECRET_NAME=loft-user-secret-admin
SECRET_NAMESPACE=vcluster-platform
NEW_PASSWORD_HASH=$(echo -n "my-new-password" | sha256sum | awk '{print $1}')

kubectl get secret "$SECRET_NAME" -n "$SECRET_NAMESPACE" -o json \
  | jq --arg password "$(printf '%s' "$NEW_PASSWORD_HASH" | base64)" '.data["password"]=$password' \
  | kubectl apply -f -

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

Recover through Helm

Operators 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 requires vCluster Platform MIN_PLATFORM_VERSION or later. 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.

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:
  create: true
  passwordSecretRef:
    name: platform-admin-password
    key: password

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

Modify the following with your specific values to generate a copyable command:

RELEASE

CHART

NAMESPACE

DEPLOYMENT

helm upgrade vcluster-platform loft/vcluster-platform --namespace vcluster-platform --values values.yaml --wait
kubectl --namespace vcluster-platform rollout restart deployment/vcluster-platform
kubectl --namespace vcluster-platform rollout status deployment/vcluster-platform

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.

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".