Quick Start
On this page
- Prerequisites
- Procedure
- Register for an Atlas account or log in.
- Create API keys for your organization.
- Deploy Atlas Kubernetes Operator.
- Create a secret with your API keys and organization ID.
- Create the
AtlasProject
custom resource. - Create the
AtlasDeployment
custom resource. - Create a secret with a password to log into the Atlas cluster database.
- Create the
AtlasDatabaseUser
custom resource. - Check the status of your database user.
- Retrieve the secret that Atlas Kubernetes Operator created to connect to the cluster.
You can use Atlas Kubernetes Operator to manage resources in Atlas without leaving Kubernetes. This tutorial demonstrates how to create your first cluster in Atlas from Kubernetes configuration files with Atlas Kubernetes Operator.
Note
Would you prefer to start with Helm?
To create your first cluster in Atlas from Helm Charts with Atlas Kubernetes Operator, see Helm Charts Quick Start.
Prerequisites
This tutorial requires:
A running Kubernetes cluster with nodes running processors with the x86-64, AMD64, or ARM64 architecture.
jq
1.6 or higher
You can access the Atlas Kubernetes Operator project on GitHub:
To install the Atlas Kubernetes operator using the Atlas CLI, run the following command:
atlas kubernetes operator install [options]
To learn more about the command syntax and parameters, see the Atlas CLI documentation for atlas kubernetes operator install.
Procedure
Important
Custom Resources No Longer Delete Objects by Default
Atlas Kubernetes Operator uses custom resource configuration
files to manage your Atlas configuration, but as of Atlas Kubernetes Operator 2.0,
custom resources you delete in Kubernetes are no longer deleted in
Atlas. Instead, Atlas Kubernetes Operator simply stops managing those resources.
For example, if you delete an AtlasProject
Custom Resource
in Kubernetes, Atlas Kubernetes Operator no longer automatically deletes the corresponding project
from Atlas, preventing accidental or unexpected deletions. To learn more,
including how to revert this behavior to
the default used prior to Atlas Kubernetes Operator 2.0, see New Default: Deletion Protection in Atlas Kubernetes Operator 2.0.
Register for an Atlas account or log in.
Register a new Atlas Account or Log in to Your Atlas Account.
Create API keys for your organization.
Note
You need the following public API key, private API key, and the organization ID information to configure Atlas Kubernetes Operator access to Atlas.
Create an API (Application Programming Interface) Key in an Organization and configure the API Access List.
You need the following public API key, private API key, and the organization ID information to configure Atlas Kubernetes Operator access to Atlas.
If you want Atlas Kubernetes Operator to create a new Atlas project, Create an API (Application Programming Interface) Key in an Organization. If your organization requires an IP access list for the Atlas Administration API, you must also configure the API access list.
Important
You must assign the API key the Organization Project Creator organization role or higher.
If you want to work with an existing Atlas project, Create an API (Application Programming Interface) Key for a Project. If your organization requires an IP access list for the Atlas Administration API, you must also configure the API access list.
Important
You must assign the API key the Project Owner project role.
Deploy Atlas Kubernetes Operator.
In one of the following scenarios, replace <version>
with the
latest release number:
If you want Atlas Kubernetes Operator to watch all the namespaces in the Kubernetes cluster, run the following command:
kubectl apply -f https://raw.githubusercontent.com/mongodb/mongodb-atlas-kubernetes/v<version>/deploy/all-in-one.yaml If you want Atlas Kubernetes Operator to watch only its namespace, you must install the configuration files from the
deploy/namespaced
directory:kubectl apply -f https://raw.githubusercontent.com/mongodb/mongodb-atlas-kubernetes/v<version>/deploy/namespaced/crds.yaml kubectl apply -f https://raw.githubusercontent.com/mongodb/mongodb-atlas-kubernetes/v<version>/deploy/namespaced/namespaced-config.yaml
Create a secret with your API keys and organization ID.
To create and label a secret, run the following commands with your API keys and organization ID:
kubectl create secret generic mongodb-atlas-operator-api-key \ --from-literal="orgId=<atlas_organization_id>" \ --from-literal="publicApiKey=<atlas_api_public_key>" \ --from-literal="privateApiKey=<atlas_api_private_key>" \ -n mongodb-atlas-system
kubectl label secret mongodb-atlas-operator-api-key atlas.mongodb.com/type=credentials -n mongodb-atlas-system
If you use external secret storage, you don't need to put sensitive information directly into Kubernetes secrets. To learn more, see Configure Secret Storage.
Create the AtlasProject
custom resource.
Run the following command to create the
AtlasProject
Custom Resource:
Note
The following example does not specify
spec.connectionSecretRef.name
. If unspecified, Atlas Kubernetes Operator
uses the default connection secret previously set with your
API keys and organization ID.
Deploy the Atlas Kubernetes Operator custom resource.
cat <<EOF | kubectl apply -f - apiVersion: atlas.mongodb.com/v1 kind: AtlasProject metadata: name: my-project spec: name: Test Atlas Operator Project projectIpAccessList: - ipAddress: <your-ip-address-range> comment: "Adding your IP to Atlas access list" EOF
Create the AtlasDeployment
custom resource.
Run one of the following commands to create an
AtlasDeployment
Custom Resource and create a cluster:
Paid Tier:
cat <<EOF | kubectl apply -f - apiVersion: atlas.mongodb.com/v1 kind: AtlasDeployment metadata: name: my-atlas-cluster spec: projectRef: name: my-project deploymentSpec: clusterType: REPLICASET name: "Test-cluster" tags: - key: "environment" value: "production" replicationSpecs: - zoneName: US-Zone regionConfigs: - electableSpecs: instanceSize: M10 nodeCount: 3 providerName: AWS regionName: US_EAST_1 priority: 7 EOF
Free Tier:
cat <<EOF | kubectl apply -f - apiVersion: atlas.mongodb.com/v1 kind: AtlasDeployment metadata: name: my-atlas-cluster spec: projectRef: name: my-project deploymentSpec: clusterType: REPLICASET name: "Test-cluster" replicationSpecs: - regionConfigs: - regionName: US_EAST_1 providerName: TENANT backingProviderName: AWS electableSpecs: instanceSize: M0 nodeCount: 3 EOF
To create a serverless instance, see the serverless instance example.
Create a secret with a password to log into the Atlas cluster database.
Replace P@@ssword%
with your password and run the following
commands:
kubectl create secret generic the-user-password --from-literal="password=P@@sword%"
kubectl label secret the-user-password atlas.mongodb.com/type=credentials
If you use external secret storage, you don't need to put sensitive information directly into Kubernetes secrets. To learn more, see Configure Secret Storage.
Create the AtlasDatabaseUser
custom resource.
Run the following command to create the
AtlasDatabaseUser
Custom Resource:
Note
spec.passwordSecretRef
must reference the password that
you created previously.
cat <<EOF | kubectl apply -f - apiVersion: atlas.mongodb.com/v1 kind: AtlasDatabaseUser metadata: name: my-database-user spec: roles: - roleName: "readWriteAnyDatabase" databaseName: "admin" projectRef: name: my-project username: theuser passwordSecretRef: name: the-user-password EOF
Check the status of your database user.
Run the following command until you recieve a True
response,
which indicates the database user is ready:
Note
The AtlasDatabaseUser
Custom Resource waits until the
cluster is ready. Creating a new cluster can take up to 10 minutes.
kubectl get atlasdatabaseusers my-database-user -o=jsonpath='{.status.conditions[?(@.type=="Ready")].status}'
Retrieve the secret that Atlas Kubernetes Operator created to connect to the cluster.
Copy the following command:
Important
The following command requires
jq
1.6 or higher.kubectl get secret {my-project}-{my-atlas-cluster}-{my-database-user} -o json | jq -r '.data | with_entries(.value |= @base64d)'; Replace the following placeholders with the details for your custom resources:
my-project
Specify the value of themetadata
field of yourAtlasProject
Custom Resource.my-atlas-cluster
Specify the value of themetadata
field of yourAtlasDeployment
Custom Resource.my-database-user
Specify the value of themetadata
field of yourAtlasDatabaseUser
Custom Resource.Run the command.
Note
Your connection strings will differ from the following example.
{ "connectionStringStandard": "mongodb://theuser:P%40%40sword%25@test-cluster-shard-00-00.peqtm.mongodb.net:27017,test-cluster-shard-00-01.peqtm.mongodb.net:27017,test-cluster-shard-00-02.peqtm.mongodb.net:27017/?ssl=true&authSource=admin&replicaSet=atlas-pk82fl-shard-0", "connectionStringStandardSrv": "mongodb+srv://theuser:P%40%40sword%25@test-cluster.peqtm.mongodb.net", "password": "P@@sword%", "username": "theuser" } You can use this secret in your application:
containers: - name: test-app env: - name: "CONNECTION_STRING" valueFrom: secretKeyRef: name: test-atlas-operator-project-test-cluster-theuser key: connectionStringStandardSrv