Root Access Settings

This page covers settings that control root (superuser) access for the MinIO AIStor process. The root user has complete access and permissions to perform operations on the MinIO AIStor deployment.

Root User and Root Password are required even if you use the MinIO Key Encryption Service or other key management utility.

You can establish or modify settings by defining:

  • an environment variable on the host system prior to starting or restarting the MinIO AIStor Server. Refer to your operating system’s documentation for how to define an environment variable.
  • a configuration setting using mc admin config set.

If you define both an environment variable and the similar configuration setting, MinIO AIStor uses the environment variable value.

Some settings have only an environment variable or a configuration setting, but not both.

Each configuration setting controls fundamental MinIO AIStor behavior and functionality. Test configuration changes in a lower environment, such as DEV or QA, before applying to production.

Settings

Root user

The access key for the root user.

Omitting this value results in using the default minioadmin

NEVER use the default credentials in production environments. MinIO strongly recommends specifying a unique, long, and random MINIO_ROOT_USER value for all environments.

Root user file

Specifies the full path to a file containing the access key for the root user. The file should contain only the access key value with no additional whitespace or newlines.

See file-based environment variables for usage information.

Root password

The secret key for the root user.

Omitting this value results in using the default minioadmin

NEVER use the default credentials in production environments. MinIO strongly recommends specifying a unique, long, and random MINIO_ROOT_PASSWORD value for all environments.

Root password file

Specifies the full path to a file containing the secret key for the root user. The file should contain only the secret key value with no additional whitespace or newlines.

See file-based environment variables for usage information.

Root API access

Specify on to enable and off to disable the root user account. Disabling the root service account also disables all service accounts associated with root, excluding those used by site replication. Defaults to on.

Disabling root API access only disallows authentication with root credentials for public API calls. MinIO AIStor nodes still use the root credentials to authenticate internode cluster communication. Therefore, disabling root API access requires either setting explicit root credentials via the MINIO_ROOT_USER and MINIO_ROOT_PASSWORD environment variables or specifying a KMS configuration to auto-generate root credentials using the KMS.

Ensure you have at least one other admin user, such as one with the consoleAdmin policy, before disabling the root account. If you do not have another admin user, disabling the root account locks administrative access to the deployment.

You can use this variable to temporarily override the configuration setting and re-enable root access to the deployment.

To reset after an unintentional lock, set MINIO_API_ROOT_ACCESS on to override this setting and temporarily re-enable the root account. You can then change this setting to on or make the necessary user/policy changes to ensure normal administrative access through other non-root accounts.

Unique root credentials

For systems with the API root access disabled, MinIO AIStor supports further obfuscation of the root credentials by generating a unique value using a configured external Key Management Service (KMS). These credentials are exclusively for internode authentication and related operations.

MinIO AIStor automatically generates unique root credentials if all of the following conditions are true:

  • MinKMS or KES Release 2024-03-01T18-06-46Z or later running or set a static key via MINIO_KMS_SECRET_KEY
  • Have not defined:
    • MINIO_ROOT_USER variable
    • MINIO_ROOT_PASSWORD variable
  • Have:

When those conditions are met at startup, MinIO AIStor uses the KMS to generate unique root credentials for the deployment using a hash-based message authentication code (HMAC). These credentials provide a fully obfuscated root credential configuration for infrastructures with specific security requirements.

If MinIO AIStor generates such credentials, the key used to generate the credentials must remain the same and continue to exist. All data on the deployment is encrypted with this key.

To rotate the generated root credentials, generate a new key in the KMS, then update the value of the MINIO_KMS_KES_KEY_NAME with the new key.

Rotating Root Credentials in Kubernetes Deployments

In Kubernetes deployments managed by the MinIO AIStor Operator, root credentials are delivered to the MinIO AIStor process through a configuration file mounted from a Kubernetes Secret. The MinIO AIStor Helm chart creates and owns this Secret.

Always use helm upgrade to rotate credentials — modifying the Secret directly with kubectl bypasses Helm and causes configuration drift, where the state tracked by Helm diverges from the actual state in the cluster. A subsequent helm upgrade would overwrite your manual changes.

Prerequisites

  • ObjectStore deployed using the minio/aistor-objectstore Helm chart
  • Helm 3 installed and configured

Rotate root credentials

Run helm upgrade with the updated credentials:

helm upgrade <release-name> minio/aistor-objectstore \
  --namespace <namespace> \
  --reuse-values \
  --set secrets.accessKey=<new-root-user> \
  --set secrets.secretKey=<new-root-password>

Replace <release-name> and <namespace> with your ObjectStore release name and Kubernetes namespace. The --reuse-values flag preserves all other configuration settings.

After helm upgrade completes, the Operator detects the Secret change and automatically propagates the new credentials to all MinIO AIStor Pods. The rotation completes within seconds on a healthy cluster, without requiring a Pod restart.

Passing credentials with --set records them in the Helm release history, which is stored as a Kubernetes Secret in the same namespace. To avoid exposing values on the command line, update your values.yaml file with the new credentials and run:

helm upgrade <release-name> minio/aistor-objectstore \
  --namespace <namespace> \
  --values values.yaml

Verify the rotation

Use the MinIO AIStor Client to confirm that the new credentials are active:

mc alias set myaistor https://<objectstore-endpoint>:9000 <new-root-user> <new-root-password>
mc admin info myaistor

If the command succeeds and the previous credentials no longer authenticate, the rotation completed successfully.