Overview
Atlas API Service Accounts provide a secure, token-based alternative to Programmatic API Keys for authenticating Atlas Kubernetes Operator with the Atlas Administration API. Service Accounts use short-lived access tokens derived from a clientId and clientSecret pair, reducing the risk of long-lived credential exposure.
MongoDB recommends Service Accounts over Programmatic API Keys for new deployments. Service Accounts offer the following benefits:
Token-based authentication with automatic token refresh managed by the operator.
Support for both organization-level and project-level scopes.
Auditable, distinct identity for your Atlas Kubernetes Operator workloads.
Important
Service Account Secret Expiration
Unlike API Keys, Service Account secrets are expirable. You can set a TTL of up to one year maximum. You must rotate Service Account secrets before they expire to maintain uninterrupted access. Atlas automatically raises a Service Account Secrets are about to expire alert as the expiry date approaches. Plan your rotation schedule accordingly.
This applies to both organization-level and project-level Service Accounts.
Prerequisites
Before you begin, ensure you have the following:
An Atlas account with the Organization Owner role for organization-level Service Accounts, or Project Owner role for project-level Service Accounts.
A running Kubernetes cluster with Atlas Kubernetes Operator installed.
kubectlaccess to the Kubernetes cluster where Atlas Kubernetes Operator runs.
Procedure
Create the Service Account in Atlas
Create a Service Account in Atlas using the Atlas UI or the Atlas Administration API. To learn how to create an organization-level Service Account, see Create a Service Account in an Organization. To learn how to create a project-level Service Account, see Create a Service Account in a Project.
Copy the clientId and clientSecret. Store them securely because you cannot retrieve the clientSecret again after creation.
Create the Kubernetes Connection Secret
Create a Kubernetes secret containing the orgId, clientId, and clientSecret.
For a
globalAtlas Kubernetes Operator secret, run the following commands:Note
The name of the
globalAtlas Kubernetes Operator secret must conform to the predefined format. The default name of the Atlas Kubernetes Operator deployment ismongodb-atlas-operator. So, the secret should be namedmongodb-atlas-operator-service-account.kubectl create secret generic mongodb-atlas-operator-service-account \ --from-literal="orgId=<the_atlas_organization_id>" \ --from-literal="clientId=<the_service_account_client_id>" \ --from-literal="clientSecret=<the_service_account_client_secret>" \ -n <operator_namespace> kubectl label secret mongodb-atlas-operator-service-account \ atlas.mongodb.com/type=credentials \ -n mongodb-atlas-system For a
projectAtlas Kubernetes Operator secret, run the following commands:kubectl create secret generic my-project-connection \ --from-literal="orgId=<the_atlas_organization_id>" \ --from-literal="clientId=<the_service_account_client_id>" \ --from-literal="clientSecret=<the_service_account_client_secret>" \ -n <atlas_project_namespace> kubectl label secret my-project-connection \ atlas.mongodb.com/type=credentials \ -n <atlas_project_namespace>
Reference the Secret from AtlasProject
Reference the secret from your AtlasProject custom resource using spec.connectionSecretRef.name.
If you created a global secret, all projects use it by default and no additional configuration is needed.
If you created a project secret, add the connectionSecretRef to your AtlasProject custom resource:
apiVersion: atlas.mongodb.com/v1 kind: AtlasProject metadata: name: my-project spec: name: "My Project" connectionSecretRef: name: my-project-connection
Verify the Operator Uses the Service Account
After you configure the secret, verify that Atlas Kubernetes Operator authenticates successfully:
kubectl get atlasproject my-project -o jsonpath='{.status.conditions}'
Check that the Ready condition is True. If Atlas Kubernetes Operator can't authenticate with the Service Account credentials, the conditions show an error describing the issue.
YAML Example
The following example shows a Connection Secret configured for a Service Account:
apiVersion: v1 kind: Secret metadata: name: my-project-connection namespace: atlas-operator labels: atlas.mongodb.com/type: credentials type: Opaque stringData: orgId: "5d39f0719ccf646554345678" clientId: "mdb_sa_id_67890abcdef1234567890abc" clientSecret: "mdb_sa_sk_abcdef1234567890abcdef12"
Considerations
Token Management
Atlas Kubernetes Operator manages access tokens automatically. When the Atlas Kubernetes Operator detects a Service Account Connection Secret, it obtains an access token from the Atlas Administration API and stores it in a separate Kubernetes secret. Do not manually edit or delete the Access Token Secret. Atlas Kubernetes Operator refreshes tokens as needed.
Credential Rotation
When you rotate the Service Account secret in Atlas:
Update the Kubernetes Connection Secret with the new
clientSecret.The Atlas Kubernetes Operator detects the change and acquires a new access token on the next reconcile cycle. No restart is required.
Important
Service Account secrets have a maximum TTL of one year. Monitor the Service Account Secrets are about to expire alert in Atlas and rotate your secrets before they expire to avoid authentication failures. This applies to both organization-level and project-level Service Accounts.
IP Access List
The Service Account's API access list must include the egress IP address or CIDR block used by the Atlas Kubernetes Operator pod, the same as for Programmatic API Keys. If the operator pod's egress IP is not on the Service Account access list, API requests fail.