Skip to content
logo
Percona Operator for MongoDB
Application and system users
Initializing search
    percona/k8spsmdb-docs
    percona/k8spsmdb-docs
    • Welcome
      • Design and architecture
      • Comparison with other solutions
      • Install with Helm
      • Install with kubectl
      • System requirements
      • Install on Minikube
      • Install on Google Kubernetes Engine (GKE)
      • Install on Amazon Elastic Kubernetes Service (AWS EKS)
      • Install on Microsoft Azure Kubernetes Service (AKS)
      • Generic Kubernetes installation
      • Install on OpenShift
      • Application and system users
        • Unprivileged users
        • System Users
          • YAML Object Format
          • Password Rotation Policies and Timing
        • Development Mode
        • MongoDB Internal Authentication Key (optional)
      • Changing MongoDB options
      • Anti-affinity and tolerations
      • Labels and annotations
      • Exposing the cluster
      • Local storage support
      • Arbiter and non-voting nodes
      • MongoDB sharding
      • Transport encryption (TLS/SSL)
      • Data at rest encryption
      • Telemetry
        • About backups
        • Configure storage for backups
        • Making scheduled backups
        • Making on-demand backup
        • Storing operations logs for point-in-time recovery
        • Restore from a previously saved backup
        • Delete the unneeded backup
      • Upgrade MongoDB and the Operator
      • Horizontal and vertical scaling
      • Multi-cluster and multi-region deployment
      • Monitor with Percona Monitoring and Management (PMM)
      • Add sidecar containers
      • Restart or pause the cluster
      • Debug and troubleshoot
      • OpenLDAP integration
      • How to use private registry
      • Creating a private S3-compatible cloud for backups
      • Restore backup to a new Kubernetes-based environment
      • How to use backups to move the external database to Kubernetes
      • Install Percona Server for MongoDB in multi-namespace (cluster-wide) mode
      • Upgrading Percona Server for MongoDB manually
      • Custom Resource options
      • Percona certified images
      • Operator API
      • Frequently asked questions
      • Old releases (documentation archive)
      • Release notes index
      • Percona Operator for MongoDB 1.14.0 (2023-03-13)
      • Percona Operator for MongoDB 1.13.0 (2022-09-15)
      • Percona Operator for MongoDB 1.12.0 (2022-05-05)
      • Percona Distribution for MongoDB Operator 1.11.0 (2021-12-21)
      • Percona Distribution for MongoDB Operator 1.10.0 (2021-09-30)
      • Percona Distribution for MongoDB Operator 1.9.0 (2021-07-29)
      • Percona Kubernetes Operator for Percona Server for MongoDB 1.8.0 (2021-05-06)
      • Percona Kubernetes Operator for Percona Server for MongoDB 1.7.0 (2021-03-08)
      • Percona Kubernetes Operator for Percona Server for MongoDB 1.6.0 (2020-12-22)
      • Percona Kubernetes Operator for Percona Server for MongoDB 1.5.0 (2020-09-07)
      • Percona Kubernetes Operator for Percona Server for MongoDB 1.4.0 (2020-03-31)
      • Percona Kubernetes Operator for Percona Server for MongoDB 1.3.0 (2019-12-11)
      • Percona Kubernetes Operator for Percona Server for MongoDB 1.2.0 (2019-09-20)
      • Percona Kubernetes Operator for Percona Server for MongoDB 1.1.0 (2019-07-15)
      • Percona Kubernetes Operator for Percona Server for MongoDB 1.0.0 (2019-05-29)

    • Unprivileged users
    • System Users
      • YAML Object Format
      • Password Rotation Policies and Timing
    • Development Mode
    • MongoDB Internal Authentication Key (optional)

    Users¶

    MongoDB user accounts within the Cluster can be divided into two different groups:

    • application-level users: the unprivileged user accounts,
    • system-level users: the accounts needed to automate the cluster deployment and management tasks, such as MongoDB Health checks.

    As these two groups of user accounts serve different purposes, they are considered separately in the following sections.

    Unprivileged users¶

    There are no unprivileged (general purpose) user accounts created by default. If you need general purpose users, please run commands below:

    $ kubectl run -i --rm --tty percona-client --image=percona/percona-server-mongodb:4.4.18-18 --restart=Never -- bash -il
    mongodb@percona-client:/$ mongo "mongodb+srv://userAdmin:userAdmin123456@my-cluster-name-rs0.psmdb.svc.cluster.local/admin?replicaSet=rs0&ssl=false"
    rs0:PRIMARY> db.createUser({
        user: "myApp",
        pwd: "myAppPassword",
        roles: [
          { db: "myApp", role: "readWrite" }
        ],
        mechanisms: [
           "SCRAM-SHA-1"
        ]
    
    })
    

    Now check the newly created user:

    $ kubectl run -i --rm --tty percona-client --image=percona/percona-server-mongodb:4.4.18-18 --restart=Never -- bash -il
    mongodb@percona-client:/$ mongo "mongodb+srv://myApp:myAppPassword@my-cluster-name-rs0.psmdb.svc.cluster.local/admin?replicaSet=rs0&ssl=false"
    rs0:PRIMARY> use myApp
    rs0:PRIMARY> db.test.insert({ x: 1 })
    rs0:PRIMARY> db.test.findOne()
    

    System Users¶

    To automate the deployment and management of the cluster components, the Operator requires system-level MongoDB users.

    During installation, the Operator requires Kubernetes Secrets to be deployed before the Operator is started. The name of the required secrets can be set in deploy/cr.yaml under the spec.secrets section.

    Default Secret name: my-cluster-name-secrets

    Secret name field: spec.secrets.users

    Warning

    These users should not be used to run an application.

    User Purpose Username Secret Key Password Secret Key
    Backup/Restore MONGODB_BACKUP_USER MONGODB_BACKUP_PASSWORD
    Cluster Admin MONGODB_CLUSTER_ADMIN_USER MONGODB_CLUSTER_ADMIN_PASSWORD
    Cluster Monitor MONGODB_CLUSTER_MONITOR_USER MONGODB_CLUSTER_MONITOR_PASSWORD
    Database Admin MONGODB_DATABASE_ADMIN_USER MONGODB_DATABASE_ADMIN_PASSWORD
    User Admin MONGODB_USER_ADMIN_USER MONGODB_USER_ADMIN_PASSWORD
    PMM Server PMM_SERVER_USER PMM_SERVER_PASSWORD

    Password-based authorization method for PMM is deprecated since the Operator 1.13.0. Use token-based authorization instead.

    • Backup/Restore - MongoDB Role: backup, restore, clusterMonitor

    • Cluster Admin - MongoDB Roles: clusterAdmin

    • Cluster Monitor - MongoDB Role: clusterMonitor

    • Database Admin - MongoDB Roles: readWriteAnyDatabase, readAnyDatabase, dbAdminAnyDatabase, backup, restore, clusterMonitor

    • User Admin - MongoDB Role: userAdmin

    Note

    If you change credentials for the MONGODB_CLUSTER_MONITOR user, the cluster Pods will go into restart cycle, and the cluster can be not accessible through the mongos service until this cycle finishes.

    YAML Object Format¶

    The default name of the Secrets object for these users is my-cluster-name-secrets and can be set in the CR for your cluster in spec.secrets.users to something different. When you create the object yourself, the corresponding YAML file should match the following simple format:

    apiVersion: v1
    kind: Secret
    metadata:
      name: my-cluster-name-secrets
    type: Opaque
    stringData:
      MONGODB_BACKUP_USER: backup
      MONGODB_BACKUP_PASSWORD: backup123456
      MONGODB_DATABASE_ADMIN_USER: databaseAdmin
      MONGODB_DATABASE_ADMIN_PASSWORD: databaseAdmin123456
      MONGODB_CLUSTER_ADMIN_USER: clusterAdmin
      MONGODB_CLUSTER_ADMIN_PASSWORD: clusterAdmin123456
      MONGODB_CLUSTER_MONITOR_USER: clusterMonitor
      MONGODB_CLUSTER_MONITOR_PASSWORD: clusterMonitor123456
      MONGODB_USER_ADMIN_USER: userAdmin
      MONGODB_USER_ADMIN_PASSWORD: userAdmin123456
      PMM_SERVER_USER: admin
      PMM_SERVER_PASSWORD: admin
      PMM_SERVER_API_KEY: apikey
    

    The example above matches what is shipped in deploy/secrets.yaml which contains default passwords and default API key. You should NOT use these in production, but they are present to assist in automated testing or simple use in a development environment.

    As you can see, because we use the stringData type when creating the Secrets object, all values for each key/value pair are stated in plain text format convenient from the user’s point of view. But the resulting Secrets object contains passwords stored as data - i.e., base64-encoded strings. If you want to update any field, you’ll need to encode the value into base64 format. To do this, you can run echo -n "password" | base64 --wrap=0 (or just echo -n "password" | base64 in case of Apple macOS) in your local shell to get valid values. For example, setting the Database Admin user’s password to new_password in the my-cluster-name-secrets object can be done with the following command:

    $ kubectl patch secret/my-cluster-name-secrets -p '{"data":{"MONGODB_DATABASE_ADMIN_PASSWORD": "'$(echo -n new_password | base64 --wrap=0)'"}}'
    
    $ kubectl patch secret/my-cluster-name-secrets -p '{"data":{"MONGODB_DATABASE_ADMIN_PASSWORD": "'$(echo -n new_password | base64)'"}}'
    

    Note

    The operator creates and updates an additional Secrets object named based on the cluster name, like internal-my-cluster-name-users. It is used only by the Operator and should undergo no manual changes by the user. This object contains secrets with the same passwords as the one specified in spec.secrets.users (e.g. my-cluster-name-secrets). When the user updates my-cluster-name-secrets, the Operator propagates these changes to the internal internal-my-cluster-name-users Secrets object.

    Password Rotation Policies and Timing¶

    When there is a change in user secrets, the Operator creates the necessary transaction to change passwords. This rotation happens almost instantly (the delay can be up to a few seconds), and it’s not needed to take any action beyond changing the password.

    Note

    Please don’t change secrets.users option in CR, make changes inside the secrets object itself.

    Development Mode¶

    To make development and testing easier, deploy/secrets.yaml secrets file contains default passwords for MongoDB system users.

    These development-mode credentials from deploy/secrets.yaml are:

    Secret Key Secret Value
    MONGODB_BACKUP_USER backup
    MONGODB_BACKUP_PASSWORD backup123456
    MONGODB_DATABASE_ADMIN_USER databaseAdmin
    MONGODB_DATABASE_ADMIN_PASSWORD databaseAdmin123456
    MONGODB_CLUSTER_ADMIN_USER clusterAdmin
    MONGODB_CLUSTER_ADMIN_PASSWORD clusterAdmin123456
    MONGODB_CLUSTER_MONITOR_USER clusterMonitor
    MONGODB_CLUSTER_MONITOR_PASSWORD clusterMonitor123456
    MONGODB_USER_ADMIN_USER userAdmin
    MONGODB_USER_ADMIN_PASSWORD userAdmin123456
    PMM_SERVER_USER admin
    PMM_SERVER_PASSWORD admin
    PMM_SERVER_API_KEY apikey

    Warning

    Do not use the default MongoDB Users and/or default PMM API key in production!

    MongoDB Internal Authentication Key (optional)¶

    Default Secret name: my-cluster-name-mongodb-key

    Secret name field: spec.secrets.key

    By default, the operator will create a random, 1024-byte key for MongoDB Internal Authentication if it does not already exist. If you would like to deploy a different key, create the secret manually before starting the operator.

    Contact Us

    For free technical help, visit the Percona Community Forum.

    To report bugs or submit feature requests, open a JIRA ticket.

    For paid support and managed or consulting services , contact Percona Sales.


    Last update: 2023-05-23
    Percona LLC and/or its affiliates, © 2009 - 2023
    Made with Material for MkDocs

    Cookie consent

    We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better.