AKO CRDs

Parent: Atlas Kubernetes Operator · Published reference · snapshot 2026-10-01

Depth-first rabbithole dossier for AKO CRDs; source-anchored research pack.

These notes link each claim to its source. A source may be a research report hosted on this site rather than the primary document. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.

How it works

- **Helm CRD lifecycle: upgrade-safe or uninstall-dangerous?** Helm's guidance (claim 31) says CRDs are deliberately never upgraded or deleted, to prevent data loss. AKO's chart puts CRDs in `templates/` (claim 32), which makes them upgradeable. Inference, not verified: `helm uninstall` of the CRD chart may then delete the CRDs. Per claim 7, that would delete every Atlas CR. Atlas objects would likely survive only because of 2.0 deletion protection (claim 1). The AtlasDeployment CRD metadata I read showed no `helm.sh/resource-policy: keep` annotation (https://raw.githubusercontent.com/mongodb/ [source]
— https://www.mongodb.com/docs/atlas/operator/current/custom-resources/ 15. Two install-time switches set deletion protection for the whole operator. `resourceDeletionProtection` covers projects, deployments and similar resources. `subresourceDeletionProtection` covers alerts, integrations and similar subresources. Both default to true. — https://www.mongodb.com/docs/atlas/cli/current/command/atlas-kubernetes-operator-install/ 16. AKO does not delete an Atlas team when you remove that team from an AtlasProject in Kubernetes. — https://www.mongodb.com/docs/atlas/operator/current/custom-resource [source]
13. The root (independent) kinds are AtlasProject, AtlasOrgSettings and Group. Most other kinds hang off a project. — https://www.mongodb.com/docs/atlas/operator/current/custom-resources/ [M7] 14. AtlasOrgSettings (v2.11.0, short name `aos`) is the first org-scoped kind. — https://api.github.com/repos/mongodb/mongodb-atlas-kubernetes/releases?per_page=10&page=2 [H31] 15. A CEL rule enforces an XOR between the two parent references: `(has(self.externalProjectRef) && !has(self.projectRef)) || (!has(self.externalProjectRef) && has(self.projectRef))`. Its message is "must define only one project r [source]
7. The docs class AtlasProject, AtlasOrgSettings, and Group as independent (root) resources. Most other kinds hang off a project. — https://www.mongodb.com/docs/atlas/operator/current/custom-resources/ 8. A project-scoped CR names its parent in one of two ways: `spec.projectRef`, which points to a Kubernetes AtlasProject object, or `spec.externalProjectRef.id`, which holds an Atlas project ID. The two fields are mutually exclusive. — https://www.mongodb.com/docs/atlas/operator/current/atlasdeployment-custom-resource/ 9. A CEL rule enforces the mutual exclusion (XOR): `(has(self.externalProject [source]
24. `mongodb.com/atlas-reconciliation-policy: "skip"` stops AKO from reconciling the CR. Removing the annotation resumes the sync with the spec. — https://www.mongodb.com/docs/atlas/operator/current/custom-resources/ 25. Since AKO 2.0, deleting a CR does not delete the Atlas object by default. AKO only stops managing it. The `--object-deletion-protection` flag or the `OBJECT_DELETION_PROTECTION` env var (default true) controls this behavior. — https://www.mongodb.com/docs/atlas/operator/current/ ; https://www.mongodb.com/docs/atlas/operator/current/ak8so-changelog/ 26. `mongodb.com/atlas-resou [source]

Measurements and reference values

**Verdict: `BUDGET_EXHAUSTED` (soft stop). The concept is not saturated and there was no boundary breach.** All four reports stopped at 10–19% new information per pass. In this synthesis, the practice report was the last one merged, and it still added about 15% unique claims. That is well above the 5%-twice stop rule, so another pass would pay off. The concept also did not turn out to be a family in disguise. The new claims all concern the CRDs themselves, and the per-feature kinds were already out of scope. [source]
| Pass | Focus | New claims | Rate | |---|---|---|---| | 0 | MongoDB CR / migration / independent docs | 14 | — | | 1 | Changelog + GitHub issues | 12 | 46% | | 2 | Helm, Kubernetes CRD semantics, CRD YAML/CEL | 7 | 21% | | 3 | Generated CRDs, IPAccessList doc | 4 (incl. 1 contradiction) | 11% | [source]
| Pass | Focus | New claims | Cumulative | Rate | |---|---|---|---|---| | 0 | Docs changelog | 18 | 18 | 100% | | 1 | GitHub release API dates, 0.x origin | 10 | 28 | 36% | | 2 | Generated CRDs, Go package kinds, stream naming | 7 | 35 | 20% | | 3 | Independent-CRD mechanism, v1→v2 upgrade, name collision | 4 | 39 | 10% | [source]
New-information rate by pass: pass 0 = 100% (≈14 claims), pass 1 = ≈42% (+10), pass 2 = ≈22% (+7), pass 3 = ≈14% (+5). The curve is declining but has not reached the <5%-twice stop rule. Verdict: **BUDGET_EXHAUSTED (soft stop)**. One or two more passes would likely still pay off. The best targets are the raw CRD YAML (exact CEL strings, printer columns, `atlas` category), the controller's finalizer name, and the enablement flag for generated CRDs. This session's fetch path could not reach any of them, because GitHub raw/tree URLs returned 404 through WebFetch. [source]

Problems, failure modes and limitations

- **Independence gate: met, with caveats.** Four independent hosts back the claims: mongodb.com (vendor docs), github.com (vendor releases plus independent user issue reports), helm.sh and kubernetes.io (upstream standards). artifacthub.io supports one claim. I found no independent third-party practitioner article (blog or conference talk) that evaluates AKO CRDs specifically. Searches returned only vendor pages and Ariga's same-name project. The disconfirming evidence comes from user GitHub issues (claims 26, 31–35, 37). - **Fidelity caveat.** Every fetch went through a summarizing model. Cla [source]
1. AKO's hand-written CRD family uses API group `atlas.mongodb.com`, version `v1`. — https://www.mongodb.com/docs/atlas/operator/current/ak8so-independent-crd/ [M2,P1] 2. The current docs list 18 hand-written kinds: AtlasProject, AtlasDeployment, AtlasDatabaseUser, AtlasIPAccessList, AtlasCustomRole, AtlasTeam, AtlasPrivateEndpoint, AtlasNetworkPeering, AtlasNetworkContainer, AtlasBackupPolicy, AtlasBackupSchedule, AtlasBackupCompliancePolicy, AtlasDataFederation, AtlasFederatedAuth, AtlasOrgSettings, AtlasSearchIndexConfig, AtlasStreamConnection and AtlasStreamWorkspace. — https://www.mongodb [source]
17. AtlasDeployment serves and stores a single API version, `v1`. There is no conversion webhook path to a newer version. — https://raw.githubusercontent.com/mongodb/helm-charts/main/charts/atlas-operator-crds/templates/atlas.mongodb.com_atlasdeployments.yaml 18. v2.0.1 removed `advancedDeploymentSpec` (folded into `deploymentSpec`) without bumping `atlas.mongodb.com/v1`, so existing manifests broke in place. The issue asking for a versioned API (`v2alpha1`) was closed "not planned". — https://github.com/mongodb/mongodb-atlas-kubernetes/issues/1330 19. Earlier renames under the same API: v1.0. [source]
23. With `externalProjectRef`, `connectionSecret.name` is mandatory because the CR cannot inherit credentials from a parent project. — https://www.mongodb.com/docs/atlas/operator/v2.16/ak8so-independent-crd/ 24. Each project supports at most one AtlasIPAccessList. Multiple AtlasIPAccessList CRs for the same project conflict. — https://www.mongodb.com/docs/atlas/operator/current/atlasipaccesslist-custom-resource/ 25. A project can have only one integration of each type, whether it comes from AtlasProject `spec.integrations` or from AtlasThirdPartyIntegration. For example, DATADOG cannot be decl [source]
15. MongoDB says not to use v2.0.0, because it cannot reconcile `AtlasBackupSchedule` when deletion protection is on. v2.0.1 (2023-12-04) is the first usable 2.x release. — https://www.mongodb.com/docs/atlas/operator/current/ak8so-changelog/ 16. In 2.0.1, deleting a CR in Kubernetes no longer deletes the matching Atlas resource; AKO only stops managing it. This deletion-protection default is the behavioural break between 1.x and 2.x CRDs. — https://www.mongodb.com/docs/atlas/operator/current/ak8so-changelog/ 17. In 2.0.1, `deploymentSpec` replaced `advancedDeploymentSpec` in `AtlasDeployment`. [source]
1. The current docs list these hand-written kinds: AtlasProject, AtlasDeployment, AtlasDatabaseUser, AtlasIPAccessList, AtlasCustomRole, AtlasTeam, AtlasPrivateEndpoint, AtlasNetworkPeering, AtlasNetworkContainer, AtlasBackupPolicy, AtlasBackupSchedule, AtlasBackupCompliancePolicy, AtlasDataFederation, AtlasFederatedAuth, AtlasOrgSettings, AtlasSearchIndexConfig, AtlasStreamConnection, AtlasStreamWorkspace. Each has a short name (e.g. `ad`, `adu`, `ap`, `aal`). — https://www.mongodb.com/docs/atlas/operator/current/custom-resources/ 2. The doc examples for the hand-written kinds use `apiVersion [source]
29. In 1.0.0, `AtlasCluster` was renamed to `AtlasDeployment` and `clusterSpec` to `deploymentSpec`. In 2.0.x, `advancedDeploymentSpec` was folded into `deploymentSpec`, and secrets moved to `*Ref` fields (e.g. `APITokenRef`). — https://www.mongodb.com/docs/atlas/operator/current/ak8so-changelog/ 30. AKO moved sub-resources out of AtlasProject into standalone CRDs over several releases. 2.6.0 added AtlasPrivateEndpoint and AtlasCustomRole. 2.7.0 added AtlasIPAccessList and made AtlasDeployment and AtlasDatabaseUser usable without a managed project. 2.8.0 added AtlasNetworkPeering and AtlasNetw [source]
34. A full-state AtlasProject treats Atlas items missing from its spec as errors. In issue #2234, private endpoints managed outside AKO left the project stuck at `ProjectPrivateEndpointIsNotReadyInAtlas`, because the code compares the spec count with the Atlas count. Independent CRDs avoid this coupling. — https://github.com/mongodb/mongodb-atlas-kubernetes/issues/2234 35. Fields left unset inherit Atlas defaults, and that inheritance can loop reconciliation forever. Issue #3142 reports AtlasDeployments created before 2.4.1 that never reached Ready after an upgrade to 2.5.0. The documented fix [source]
**In scope:** the AKO custom resource definitions themselves. That covers their catalog and API groups, how references and credentials work, lifecycle annotations, deletion semantics, how CRDs are installed and upgraded, schema evolution and breaking changes, the generated (OpenAPI-derived) CRDs, validation rules, and the failure modes that users have reported. [source]
— https://www.mongodb.com/docs/atlas/operator/current/ak8so-quick-start/ 20. Helm deliberately never upgrades or deletes CRDs that sit in a chart's `crds/` directory: "There is no support at this time for upgrading or deleting CRDs using Helm." Helm recommends putting CRDs in their own chart. — https://helm.sh/docs/chart_best_practices/custom_resource_definitions/ 21. MongoDB ships the CRDs as their own chart, `mongodb/mongodb-atlas-operator-crds`, and upgrades them with `helm upgrade atlas-operator-crds mongodb/mongodb-atlas-operator-crds`. The atlas-operator chart can also install this chart [source]
35. `mongodb.com/atlas-reconciliation-policy: "skip"` pauses sync. While it is set, AKO does not revert manual changes made in Atlas. — https://www.mongodb.com/docs/atlas/operator/current/custom-resources/ [M24,E8,P14] 36. From 2.0.1 on, deleting a CR does not delete the Atlas object; AKO only stops managing it. — https://www.mongodb.com/docs/atlas/operator/current/ak8so-changelog/ [M25,E1,H16,P13] 37. The operator-wide deletion-protection switches have different names on different surfaces: - Flag `--object-deletion-protection`, or env var `OBJECT_DELETION_PROTECTION` (default true). [M25] - [source]
If you skip step 1, there are two failure modes. With deletion protection off, AKO can delete the Atlas project. Otherwise, AKO can block while trying to delete a project that still has sub-resources. — https://www.mongodb.com/docs/atlas/operator/current/ak8so-independent-crd/ ; https://www.mongodb.com/docs/atlas/operator/current/migrate-parameter-to-resource/ [M31,H26,P11,E26] [source]
1. Since AKO 2.0, deleting a CR in Kubernetes does not delete the Atlas object by default. AKO stops managing it instead. — https://www.mongodb.com/docs/atlas/operator/current/custom-resources/ 2. The per-resource override is the annotation `mongodb.com/atlas-resource-policy: "delete"`. Users who reverted to pre-2.0 delete-by-default behavior use `"keep"` to protect individual resources. — https://www.mongodb.com/docs/atlas/operator/current/custom-resources/ 3. Operator-wide flags `--object-deletion-protection` and `--subobject-deletion-protection` revert to v1.x behavior. The quick-start page [source]
8. `mongodb.com/atlas-reconciliation-policy: "skip"` pauses spec sync until you remove the annotation. While it is set, manual Atlas changes are not reverted. — https://www.mongodb.com/docs/atlas/operator/current/custom-resources/ 9. `mongodb.com/atlas-resource-version-policy: "allow"` lets AKO accept a resource whose version label does not match the operator. If the resource is a major version behind, the docs warn that new features may not work. — https://www.mongodb.com/docs/atlas/operator/current/custom-resources/ 10. Implicit Atlas defaults can cause reconcile loops that never reach Ready [source]
28. A second CRD family is generated from the Atlas Admin API OpenAPI spec: Group, Cluster, DatabaseUser, FlexCluster, IpaccessListEntry. MongoDB says it will become the standard. — https://www.mongodb.com/docs/atlas/operator/current/generated-crds-overview/ 29. You cannot manage one Atlas resource with both a generated CRD and a classic CRD. You must pick one family per resource. — https://www.mongodb.com/docs/atlas/operator/current/generated-crds-overview/ 30. The generated CRDs ship in the same `atlas-operator-crds` Helm chart as the classic ones, so they are installed even if unused. — htt [source]
In scope: the set of Kubernetes custom resource kinds that the MongoDB Atlas Kubernetes Operator (AKO) defines, when each kind appeared, how kinds were renamed, split or deprecated, the API groups they use, and the project-reference model. [source]
21. AKO reports reconcile outcome in `status.conditions`. A `Ready` condition sits alongside per-feature condition types (e.g. `IPAccessListReady`), each with a `reason` (e.g. `ProjectIPAccessListNotCreatedInAtlas`) and a `message` that can embed the raw Atlas Admin API error. — https://www.mongodb.com/docs/atlas/operator/current/custom-resources/ 22. AtlasDeployment status also carries `stateName` (IDLE, CREATING, UPDATING, DELETING, DELETED, or REPAIRING), `observedGeneration`, `connectionStrings`, `mongoDBVersion`, and `mongoURIUpdated`. — https://www.mongodb.com/docs/atlas/operator/current [source]
1. The hand-written CRDs live in API group `atlas.mongodb.com/v1`. The current docs list these kinds: AtlasBackupCompliancePolicy, AtlasBackupPolicy, AtlasBackupSchedule, AtlasCustomRole, AtlasDeployment, AtlasDatabaseUser, AtlasIPAccessList, AtlasProject, AtlasTeam, AtlasDataFederation, AtlasNetworkPeering, AtlasNetworkContainer, AtlasOrgSettings, AtlasPrivateEndpoint, AtlasSearchIndexConfig, AtlasStreamConnection, AtlasStreamWorkspace and AtlasFederatedAuth. Each kind has a short name, for example `ad` and `adu`. — https://www.mongodb.com/docs/atlas/operator/current/custom-resources/ 2. `Atl [source]
— https://www.mongodb.com/docs/atlas/operator/current/atlasproject-custom-resource/ 28. AtlasDeployment changes: - It rejects new resources that use `spec.serverlessSpec`, which remains only for existing instances. `spec.flexSpec` replaces it and needs AKO ≥ 2.12.0. - `processArgs` and cluster `labels` are deprecated, in favour of fields inside `deploymentSpec` and of `tags`. - `flexSpec.providerSettings.backingProviderName`, `regionName` and the cluster name cannot change after creation. [source]
| Pass | Focus | New claims | Cumulative claims | Rate | |---|---|---|---|---| | 0 | Catalog and deletion | 14 | 14 | — | | 1 | References and generated CRDs | 9 | 23 | 39% | | 2 | Install/upgrade and lifecycle mechanics | 7 | 30 | 23% | | 3 | Deprecations and failure modes | 7 | 37 | 19% | [source]

Comparisons and alternatives

21. v2.1.0 (2024-02-16) deprecated the `cloudProviderAccess*` fields in favour of `cloudProviderIntegration*` in `AtlasProject`. It also added OIDC and AWS IAM fields to `AtlasDatabaseUser`. — https://www.mongodb.com/docs/atlas/operator/current/ak8so-changelog/ 22. v2.3.0 (2024-06-06) added Atlas Stream Processing, which became the stream instance and connection kinds, and Atlas Search and Vector Search indexes, which became `AtlasSearchIndexConfig`. — https://api.github.com/repos/mongodb/mongodb-atlas-kubernetes/releases?per_page=10&page=3 ; https://www.mongodb.com/docs/atlas/operator/current [source]
60. An AtlasProject manifest has to list everything Atlas holds. If private endpoints in Atlas are missing from the spec, the project sticks at `ProjectPrivateEndpointIsNotReadyInAtlas`, because AKO compares the count in the spec with the count in Atlas. Independent CRDs avoid this coupling. — https://github.com/mongodb/mongodb-atlas-kubernetes/issues/2234 [M34,P34] 61. If a CR leaves a field unset and inherits the Atlas default, reconciliation can loop forever. The docs say: "inheriting Atlas defaults may result in a reconciliation loop which can prevent your custom resource from achieving a [source]
| # | Topic | Side A | Side B | |---|---|---|---| | D1 | When AtlasDeployment and AtlasDatabaseUser became independent | **v2.5.0 (2024-10-29)**: inherited parent extract, plus H24 citing the releases API (page 3) and the changelog | **v2.7.0**: M30, citing the changelog. M's summary bundles it with AtlasIPAccessList. Both reports cite the same changelog, so a summarizer conflated the two releases. | | D2 | Which kinds accept `externalProjectRef` | Independent-CRD page (current and v2.16): only AtlasDeployment and AtlasDatabaseUser | Per-kind pages: AtlasIPAccessList (both CEL rules), AtlasNet [source]
IN: the Atlas Kubernetes Operator's custom resource definitions themselves. That covers CRD schema and API versioning, CEL validation, lifecycle (install, upgrade, delete), deletion and reconciliation annotations, independent versus project-embedded CRDs, generated CRDs, and the CRD-level reconcile failure modes. OUT: AKO vs MCK and Terraform comparisons, Atlas cluster tuning, networking and backup semantics beyond what a CRD field does, and sibling frontier concepts. Inherited parent facts are not repeated as findings. Those facts are: AKO uses controller-runtime, custom condition types, and [source]
14. AtlasDeployment requires exactly one of its deployment shapes: "Only one of DeploymentSpec, AdvancedDeploymentSpec and ServerlessSpec should be defined." The current shapes are `deploymentSpec`, `flexSpec`, and the deprecated `serverlessSpec`. — https://www.mongodb.com/docs/atlas/operator/current/atlasdeployment-custom-resource/ 15. CEL transition rules (`self == oldSelf`) make some fields immutable after creation: `deploymentSpec.name`, `flexSpec.providerSettings.backingProviderName`, and `flexSpec.providerSettings.regionName`. Group's `projectOwnerId` is immutable as well. — https://www. [source]
- **When independent CRDs arrived.** The inherited parent extract says "v2.5+ allows AtlasDeployment / …" as independent CRDs. The changelog puts AtlasDeployment and AtlasDatabaseUser independence at **2.7.0**, and AtlasPrivateEndpoint and AtlasCustomRole at 2.6.0. — https://www.mongodb.com/docs/atlas/operator/current/ak8so-changelog/ . This report does not resolve the conflict. The changelog is the primary source. - **Which kinds support `externalProjectRef`.** The independent-CRD page lists only AtlasDeployment and AtlasDatabaseUser. The AtlasIPAccessList page shows both CEL rules and full ` [source]
These points are drawn from the claims above. - Install the CRDs from the dedicated CRD chart or manifest, and pin it to the operator version (claims 20–22). Never uninstall the CRD chart casually: it cascade-deletes every CR (claim 17). Your Atlas resources are protected only if deletion protection is still on (claims 13–15). - Set autoscaling and other server-defaulted fields explicitly. Then check for a `READY` condition after every upgrade, because the reported regressions show up as loops rather than as errors (claims 30, 31, 36). - New work should prefer the separate child CRs and `exter [source]
**How to read this:** claim tags point back to the four reports: M = mechanism, H = history, E = edge-cases, P = practice. For example, `[M9,E20,P9]` means three reports agree. Facts inherited from the parent are not repeated: the controller-runtime loop, custom condition types, and AKO vs MCK. **Fidelity caveat:** all four runs fetched pages through WebFetch summaries. Quoted CEL strings, error codes and field spellings have not been checked byte-for-byte against raw CRD YAML. [source]
20. The API server enforces CEL `x-kubernetes-validations` at admission time; the operator does not. Transition rules compare against `oldSelf`. — https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/ [M16] 21. AtlasDeployment accepts exactly one deployment shape. The CEL message still reads "Only one of DeploymentSpec, AdvancedDeploymentSpec and ServerlessSpec should be defined", but the current shapes are `deploymentSpec`, `flexSpec` and the deprecated `serverlessSpec`. *Delta (inference):* the message names a field that was removed in 2.0.1. — http [source]
12. Disabling compute autoscaling with `enabled: false` while leaving `minInstanceSize` set fails with `COMPUTE_AUTO_SCALING_MIN_INSTANCE_SIZE_INVALID_FOR_DISABLED` ("min instance size must be unset when scale down is disabled"). You must remove the fields, not just set the flags to false (v0.5.0, 2021). — https://github.com/mongodb/mongodb-atlas-kubernetes/issues/311 13. AKO v2.8.2 fixed an infinite AtlasDeployment reconcile. The trigger was `autoscaling.compute.enabled: false` with `minInstanceSize`/`maxInstanceSize` still set. v2.8.1 fixed a related loop where `minInstanceSize` was not clea [source]
Verdict: **BUDGET_EXHAUSTED (soft stop), not SATURATED-DEPTH.** The rate is falling but never reached two consecutive passes below 5%. One or two more passes would likely still pay off. Candidates: test the `helm uninstall` behavior, check each CRD kind for `externalProjectRef`, and review the CEL rules of the other CRDs. Firecrawl and Bash/curl were unavailable in this session, so all fetches went through WebFetch summaries rather than raw pages. [source]
Out of scope: per-field CRD specs, reconcile-loop internals, AKO versus Terraform or MCK, and install mechanics. Those belong to the parent concept or to sibling concepts. [source]
**Out of scope:** AKO vs Terraform or CLI, MCK/Enterprise operators, Atlas features in general, and how the operator reconciler works inside. Those belong to the parent topic or to sibling topics. Ariga's unrelated "Atlas Operator" (atlasgo.io) shares the name and is excluded. It is a schema-migration operator, not MongoDB's operator (https://github.com/ariga/atlas-operator). [source]
30. If a CR leaves a field unset and inherits the Atlas default, the operator can loop forever. The docs give autoscaling as the example: a static `instanceSize` gets re-applied to a cluster that autoscaling has resized. The docs say: "Explicitly define your desired configuration details … inheriting Atlas defaults may result in a reconciliation loop which can prevent your custom resource from achieving a READY state". — https://www.mongodb.com/docs/atlas/operator/current/atlasproject-custom-resource/ 31. A user reported that AtlasDeployments created before v2.4.1 loop forever after an upgrade [source]
- **Which kinds support independent CRs.** The independent-CRD page lists only AtlasDeployment and AtlasDatabaseUser (https://www.mongodb.com/docs/atlas/operator/current/ak8so-independent-crd/). But per-kind pages and search snippets also document `externalProjectRef` for AtlasNetworkPeering, AtlasCustomRole, AtlasIPAccessList, AtlasNetworkContainer and AtlasThirdPartyIntegration (https://www.mongodb.com/docs/atlas/operator/v2.12/atlasnetworkpeering-custom-resource/). Both are recorded here and neither is chosen. - **The API group of `Group`.** The current custom-resources summary listed `Grou [source]

Facts and statements

The reports found no third-party practitioner write-up about AKO CRDs. Artifact Hub mirrors the OLM listing, so it does not count as independent. [source]
Independent authorship: **not met.** Every substantive claim traces back to MongoDB: its docs, its GitHub repo, or pkg.go.dev, which is generated from that repo. I found no third-party dated history of AKO CRDs. [source]
32. Helm installs CRDs placed in a chart's `crds/` directory but has "no support at this time for upgrading or deleting CRDs." Helm recommends a separate CRD chart instead. — https://helm.sh/docs/chart_best_practices/custom_resource_definitions/ 33. MongoDB ships `atlas-operator-crds` as a separate chart "for installing and upgrading" AKO CRDs. Its listing shows a `templates/` folder and no `crds/` folder. That layout is consistent with getting around Helm's no-upgrade rule (inference). — https://github.com/mongodb/helm-charts/tree/main/charts/atlas-operator-crds [source]
- Whether AKO detects one Atlas object managed by both a generated and a classic CR, or lets the two fight. [M] - The finalizer name, printer columns, and the `atlas` category, read from raw CRD YAML. [M] - How generated CRDs are enabled, and how they will handle conversion and webhooks. [M,P] - The Secret shape for service-account credentials. [P12] - Whether issue #777 is fixed in current releases. [E] [source]
31. Helm never upgrades or deletes CRDs placed in a chart's `crds/` directory. It also does not template them, and `--dry-run` is not supported for them. Helm recommends a separate CRD chart. — https://helm.sh/docs/chart_best_practices/custom_resource_definitions/ 32. AKO follows that separate-chart pattern. `mongodb-atlas-operator-crds` keeps its CRDs under `templates/`, not `crds/`, so `helm upgrade` does update them. — https://github.com/mongodb/helm-charts/tree/main/charts/atlas-operator-crds/templates 33. For kubectl installs, CRDs must be applied before the operator manifest (`deploy/nam [source]
In scope: the Atlas Kubernetes Operator's (AKO) custom resource definitions as objects. This covers their kinds and API groups, the reference graph between them (`projectRef` / `externalProjectRef` / credentials), schema-level invariants (CEL rules, immutability), status contract, annotation controls, lifecycle on delete, how CRDs are installed and upgraded, and their evolution and limits. [source]
- **Verdict: BUDGET_EXHAUSTED (soft stop), not saturated.** At least one or two more passes would likely still pay off: a field-level diff of the live CRD YAML between versions, the conversion/webhook strategy of the generated CRDs, and a check of exact condition types. - **Handoffs for concept-family-explorer:** AKO reconciliation-loop debugging, the generated-CRD migration path, and Helm CRD lifecycle for operators in general. [source]
— https://www.mongodb.com/docs/atlas/operator/current/ak8so-quick-start/ [E33,P19] 49. The official v1→v2 path is not an in-place upgrade: 1. Stand up a new Kubernetes cluster. 2. Scale the v1 operator to 0. 3. Apply the rewritten CRs. 4. Scale v2 to 1. [source]
— https://www.mongodb.com/docs/atlas/operator/current/upgrade-ako-v1-to-v2/ [P25] 50. The OLM community-operators catalog lists 2.17.0, and GitHub tagged v2.17.0 on 2026-09-15. v2.17.0 added maintenance-window wave assignment to AtlasProject. — https://artifacthub.io/packages/olm/community-operators/mongodb-atlas-kubernetes ; https://api.github.com/repos/mongodb/mongodb-atlas-kubernetes/releases?per_page=30&page=1 [P23,H38] [source]
34. v2.14.0 (2026-05-05) added "custom resources that are automatically generated based on the OpenAPI Atlas API specification". — https://github.com/mongodb/mongodb-atlas-kubernetes/releases/tag/v2.14.0 35. The generated kinds use a separate API group, `atlas.generated.mongodb.com/v1`. The documented kinds are `Cluster`, `DatabaseUser`, `FlexCluster`, `Group` and `IPAccessListEntry`. — https://raw.githubusercontent.com/mongodb/mongodb-atlas-kubernetes/main/docs/api-docs-generated.md 36. The specs of generated kinds are keyed by Atlas API version (for example `v20250312`), and "At most one ver [source]
— https://www.mongodb.com/docs/atlas/operator/current/atlasdeployment-custom-resource/ [M22] 34. To check whether AKO has processed the latest spec, compare `status.observedGeneration` with `metadata.generation`. A status write does not bump `generation`. — kubernetes.io CRD page (URL in claim 20) [M23] [source]
45. Helm never upgrades or deletes CRDs in a chart's `crds/` directory. It also does not template them, and `--dry-run` does not cover them. Helm recommends a separate CRD chart. — https://helm.sh/docs/chart_best_practices/custom_resource_definitions/ [M32,E31,P20] 46. MongoDB ships a separate CRD chart: directory `atlas-operator-crds`, published as `mongodb/mongodb-atlas-operator-crds`. It keeps the CRDs under `templates/`, so `helm upgrade` updates them. The atlas-operator chart can pull this chart in as a dependency. — https://github.com/mongodb/helm-charts/blob/main/charts/atlas-operator-c [source]
— changelog and releases API [H9–H13] 54. **2.0.1: breaking changes, still under `v1`** - `advancedDeploymentSpec` folded into `deploymentSpec`; manifests using the old 1.x `deploymentSpec` must be rewritten. - `replicationSpecId` removed from BackupSchedule; AKO now sets it, so one schedule can be shared. - Alert and encryption-at-rest credentials must be Secret references (`*Ref`, `secretRef`). [source]
— changelog [E16,P36] 67. Issue #1954: the upgrade to 2.5.0 deleted AtlasDatabaseUser connection Secrets. ListClusters omitted serverless instances, so AKO treated their Secrets as orphaned. — https://github.com/mongodb/mongodb-atlas-kubernetes/issues/1954 [P32] (from a search summary) 68. Issue #1186 (AKO 1.7.x): the version check read the generic `app.kubernetes.io/version` label. CR creation therefore failed whenever an app's own label was higher than the operator version. — https://github.com/mongodb/mongodb-atlas-kubernetes/issues/1186 [M36,P33] 69. Name collision: Ariga's schema-migratio [source]
- Debugging AKO reconciliation loops - The generated-CRD migration path (classic → `atlas.generated.mongodb.com`) - The Helm CRD lifecycle for operators in general - Migrating from Atlas Flex to Serverless - Atlas Service Accounts as AKO credentials - Per-feature kinds: backup, search, streams, networking (already siblings) [source]
Met. Sources come from 5 hosts: mongodb.com, github.com (user issue reports), raw.githubusercontent.com (CRD source), helm.sh, and kubernetes.io. Three of these are independent of MongoDB documentation: helm.sh, kubernetes.io, and the GitHub user reports. The disconfirming evidence is issue #1330, which disputes v1 API stability, and Helm's CRD guidance, which conflicts with AKO's chart layout. [source]
39. "Atlas Kubernetes Operator" is also the name of Ariga's Atlas schema-migration operator, which has unrelated CRDs. Searches for "Atlas operator CRDs" return both. — https://atlasgo.io/integrations/kubernetes [source]
Out of scope: AKO installation in general, Terraform/CLI comparison, MCK (MongoDB Controllers for Kubernetes), and per-feature Atlas semantics such as backup, search, and streams. Those belong to sibling frontier items. [source]
Met. The report rests on 4 independent hosts: mongodb.com (official docs), kubernetes.io (CRD mechanics), helm.sh (CRD install limits), and github.com (AKO issues and helm-charts as disconfirming field evidence). The GitHub issues supplied disconfirming evidence (claims 34–36 and the disagreements above). [source]
The docs warn that if you skip the annotation, AKO may remove the project or enter a blocked state. — https://www.mongodb.com/docs/atlas/operator/current/ak8so-independent-crd/ 12. Since v2.15.0, Atlas Service Accounts can replace API keys as AKO credentials. — https://api.github.com/repos/mongodb/mongodb-atlas-kubernetes/releases [source]
13. Since AKO 2.0, deleting a CR in Kubernetes no longer deletes the Atlas resource by default. AKO just stops managing it. — https://www.mongodb.com/docs/atlas/operator/current/custom-resources/ 14. You can control this per resource with annotations: - `mongodb.com/atlas-resource-policy: "delete"` or `"keep"` decides whether the Atlas resource is deleted. - `mongodb.com/atlas-reconciliation-policy: "skip"` pauses reconciliation. - `mongodb.com/atlas-resource-version-policy: "allow"` accepts a version-label mismatch. [source]
19. There are three ways to install the CRDs: - `kubectl apply` of `deploy/all-in-one.yaml`, which watches all namespaces. - `deploy/namespaced/crds.yaml` plus `namespaced-config.yaml`, which watches only the operator's own namespace. - `atlas kubernetes operator install`. [source]
24. AKO 2.0 changed the CRD schema but kept the `atlas.mongodb.com/v1` API version: - AtlasDeployment `advancedDeploymentSpec` was renamed to `deploymentSpec`. - AtlasProject inline credentials, such as the alert-notification tokens and the encryption-at-rest keys, became Secret references, such as `APITokenRef` and `secretRef`. [source]
— https://www.mongodb.com/docs/atlas/operator/current/atlasdeployment-custom-resource/ 29. Since v2.13 the CRDs have mostly evolved by adding fields and relaxing validation: - v2.13.0 added dynamic search-index mappings. - v2.13.1 dropped the rule that analytics nodes must match the electable instance size. - v2.13.2 lifted the search-node size limits. - v2.15.0 added `portMappingEnabled` and `supportedRegions` to AtlasPrivateEndpoint. - v2.16.0 added AtlasProject `tags` and the `yearly` value for `AtlasBackupSchedule.frequencyType`. - v2.16.1 removed validation on `frequencyType`. [source]

Related concepts

AKO — is a part of AKO CRDs
CRDs — is a part of AKO CRDs

Children

No children recorded.

← the whole tree · 3D view· how to read this page