Custom Resources
On this page
Atlas Kubernetes Operator supports the following custom resource definitions:
Resource | Description | Short Name |
|---|---|---|
Configuration of a Backup Compliance Policy to protect your backup data. | abcp | |
Backup policy to back up your cluster Atlas. | abp | |
Backup schedule to back up your cluster Atlas. | abs | |
a custom database role to allocate privileges to your database users. | acr | |
Cluster inside some project in Atlas. | ad | |
Database user inside some project in Atlas. | adu | |
Project in Atlas. | ap | |
Project team in Atlas. | at | |
federated database instance and its private endpoints in Atlas. | adf | |
Private endpoint connection from your chosen cloud provider to Atlas. | ape | |
Index for some collection in your Atlas cluster. | asic | |
Atlas Stream Processing connection. | asc | |
Atlas Stream Processing instance. | asi | |
Federated authentication in Atlas. | afa |
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 (by default) deleted in Atlas. Instead, Atlas Kubernetes Operator simply stops managing those resources in Atlas. For example, if you delete an
AtlasProjectCustom Resource in Kubernetes, by default the Atlas Kubernetes Operator no longer automatically deletes the corresponding project from Atlas. This change in behavior is intended to help prevent 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.Similarly, Atlas Kubernetes Operator does not delete teams from Atlas if you remove them from an Atlas project in Kubernetes with the Atlas Kubernetes Operator.
Explicitly define your desired configuration details in order to avoid implicitly using default Atlas configuration values. In some cases, inheriting Atlas defaults may result in a reconciliation loop which can prevent your custom resource from achieving a
READYstate. For example, explicitly defining your desired autoscaling behavior in yourAtlasDeploymentcustom resource, as shown in the included example, ensures that a static instance size in your custom resource is not being repeatedly applied to an Atlas deployment which has autoscaling enabled.autoScaling: diskGB: enabled: true compute: enabled: true scaleDownEnabled: true minInstanceSize: M30 maxInstanceSize: M40
Managing Atlas Kubernetes Operator with kubectl
To list all Atlas Kubernetes Operator resources in your cluster with kubectl, you can run:
kubectl get atlas
For your convenience, to list or describe specific types of Atlas Kubernetes Operator CRDs,
you can use the short names listed in the above table. For example, to list all
atlasdatabaseusers in the mongodb namespace, you can run:
kubectl get adu -n mongodb
Atlas Kubernetes Operator Workflow
When you use Atlas Kubernetes Operator, you can create a new Atlas project, or you can work with an existing Atlas project.
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, Grant Programmatic Access to 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, Add Project Access from 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.
To learn more, see Configure Access to Atlas.
Create and Update Process
Each time you change the spec field in any of the supported
custom resources, the following workflow begins in Atlas Kubernetes Operator:
Atlas Kubernetes Operator receives an event about the changed custom resource.
Atlas Kubernetes Operator updates the
status.conditionsfield to reflect that the resource is not ready:conditions: - lastTransitionTime: "2021-03-13T16:26:17Z" status: "False" type: Ready To connect to the Atlas Administration API, Atlas Kubernetes Operator reads the organization ID and API keys from one of the following locations:
spec.connectionSecretRef.name(if specified in theAtlasProjectCustom Resource).By default, Atlas Kubernetes Operator keeps connection secrets in the same namespace as the
AtlasProjectCustom Resource. To store secrets in another namespace, specify thespec.connectionSecretRef.namespaceparameter.globalAtlas Kubernetes Operator secret<operator-deployment-name>-api-key(ifspec.connectionSecretRef.nameis not specified).
To create or update resources in Atlas, Atlas Kubernetes Operator uses the connection information to make API calls to Atlas.
Note
Sometimes Atlas Kubernetes Operator makes multiple API calls in Atlas during the reconciliation of a custom resource. For example,
AtlasProjecthas an IP Access List configuration for calling the matching API.If any errors occur during the reconciliation,
status.conditionsupdates to reflect the error.Example
- lastTransitionTime: "2021-03-15T14:26:44Z" message: 'POST https://cloud.mongodb.com/api/atlas/v1.0/groups/604a47de73cd8cag77239021/accessList: 400 (request "INVALID_IP_ADDRESS_OR_CIDR_NOTATION") The address 192.0.2.1dfdfd5 must be in valid IP address or CIDR notation.' reason: ProjectIPAccessListNotCreatedInAtlas status: "False" type: IPAccessListReady If the update succeeds,
status.conditionsreflects that the resource is ready:conditions: - lastTransitionTime: "2021-03-13T16:26:17Z" status: "True" type: Ready
Delete Process
As of Atlas Kubernetes Operator 2.0, when you delete a custom resource from Kubernetes, the object stays in Atlas by default but Atlas Kubernetes Operator no longer controls the object. You can revert this default for your entire deployment, or override this default for a specific custom resource with an annotation to allow Atlas Kubernetes Operator to delete the corresponding object from Atlas. If you override with an annotation, the following workflow begins:
Atlas Kubernetes Operator receives an event about the deleted custom resource.
To connect to the Atlas Administration API, Atlas Kubernetes Operator reads the organization ID and API keys from one of the following locations:
spec.connectionSecretRef.name(if specified in theAtlasProjectCustom Resource).By default, Atlas Kubernetes Operator keeps connection secrets in the same namespace as the
AtlasProjectCustom Resource. To store secrets in another namespace, specify thespec.connectionSecretRef.namespaceparameter.globalAtlas Kubernetes Operator secret<operator-deployment-name>-api-key(ifspec.connectionSecretRef.nameis not specified).
To delete the resource from Atlas, Atlas Kubernetes Operator uses the connection information to make API calls to Atlas.
Note
Atlas Kubernetes Operator removes any related objects created in Kubernetes. For example, if you remove
AtlasDatabaseUser, Atlas Kubernetes Operator removes the related connection secrets.
Use Annotations to Skip or Override Defaults
You can use annotations to modify the new default behaviour of Atlas Kubernetes Operator.
If you add the
mongodb.com/atlas-resource-policy: "delete"annotation to a custom resource'smetadata, Atlas Kubernetes Operator deletes the corresponding object in Atlas when you delete the Atlas Kubernetes Operator resource.Example
apiVersion: atlas.mongodb.com/v1 kind: AtlasProject metadata: name: my-project annotations: mongodb.com/atlas-resource-policy: "delete" If you have reverted the new delete behavior to the default used prior to Atlas Kubernetes Operator 2.0, you can add the
mongodb.com/atlas-resource-policy: "keep"annotation to a custom resource'smetadataso Atlas Kubernetes Operator won't delete the resource when you delete the Atlas Kubernetes Operator resource.If you add the
mongodb.com/atlas-reconciliation-policy: "skip"annotation to a custom resource'smetadata, Atlas Kubernetes Operator doesn't start the reconciliation for the resource. This annotation lets you pause the sync with the spec until you remove the annotation. You can use this annotation to make manual changes to a custom resource and avoid Atlas Kubernetes Operator undoing them during a sync. When you remove this annotation, Atlas Kubernetes Operator reconciles the resource and syncs it with the spec.If you add the
mongodb.com/atlas-resource-version-policy: "allow"annotation to a custom resource'smetadata, Atlas Kubernetes Operator lets you use a resource even if its version label doesn't match the version of Atlas Kubernetes Operator that you are using. If your resource version is a major version behind your Atlas Kubernetes Operator version, the latest features might not work. Minor version discrepancies are backward-compatible.