# AKO Subobject CRDs Deprecated > Depth-first rabbithole dossier for AKO Subobject CRDs Deprecated; source-anchored research pack. Parent: [MongoDB Atlas Infrastructure as Code](https://llms-explorer.com/tree/mongodb-atlas-infrastructure-as-code/) · 6 facets · 51 facts · page: https://llms-explorer.com/tree/ako-subobject-crds-deprecated/ ## Structure and components - 24. [P1] The `--subobject-deletion-protection` flag is a separate topic about deletion protection. v2.1.0 disabled it because of a bug and kept `--object-deletion-protection`. It is not part of the subobject → CRD deprecation, even though the name is similar. https://www.mongodb.com/docs/atlas/operator/current/ak8so-changelog/ 25. [P3] Ariga's "Atlas Kubernetes Operator" (atlasgo.io, `ariga/atlas-operator`) is an unrelated database schema-migration operator, and it appears in searches for "Atlas Kubernetes Operator". https://atlasgo.io/integrations/kubernetes · https://github.com/ariga/atlas-o — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/history.md#terminology-traps` ## How it works - 26. v2.6.1 fixed a bug that deleted custom roles configured by `AtlasProject` resources. https://www.mongodb.com/docs/atlas/operator/v2.16/ak8so-changelog/ 27. v2.7.0 fixed AKO ignoring the migration of custom roles from `AtlasProject` subresources to independent CRs. Before that fix, the documented migration did not take effect for custom roles. https://www.mongodb.com/docs/atlas/operator/v2.16/ak8so-changelog/ 28. v2.7.1 fixed accidental deletion of network peerings that `AtlasProject` neither managed nor declared, triggered by applying an `AtlasProject`. https://www.mongodb.com/docs/atlas/o — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/edge-cases.md#d-bug-history-at-the-seam` - - **C1.** `ensureProjectResources()` handles sub-resources in a fixed order: IP list, private endpoints, regionalized private-endpoint mode, cloud-provider integration, peers, alerts, integrations, maintenance window, encryption at rest, audit, settings, custom roles, teams, backup compliance, X.509. [M] https://raw.githubusercontent.com/mongodb/mongodb-atlas-kubernetes/main/internal/controller/atlasproject/atlasproject_controller.go - **C2.** The controller keeps the previously applied spec in an annotation. `lastAppliedSpecFrom()` reads it through `customresource.AnnotationLastAppliedConfigu — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/rabbithole-synthesis.md#c-how-the-controller-decides-what-it-owns-source-on-main` - - **Saturated:** the core is settled, and all four reports agree on it: the field-to-CRD mapping, the timeline (apart from X2–X4), the skip/last-applied mechanism and the migration steps. - **Not saturated:** - How the `AtlasProject` controller decides ownership for private endpoints, custom roles and integrations. M and E both name this gap, citing `custom_roles.go` and `integrations.go`. - A reproduction of the flapping behaviour (X5). - Which key AKO honours for `keep` (X6). - The v2.6.0 deprecation status and the v2.9.0 date (X2, X3). — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/rabbithole-synthesis.md#saturation` - 17. [P0] Step 1 is to add the `mongodb.com/atlas-reconciliation-policy: "skip"` annotation to the `AtlasProject`. Step 2 is to delete the parameter. Step 3 is to create the new CR. Step 4 is to wait for the new CR's status to sync. Step 5 is to remove the annotation. https://www.mongodb.com/docs/atlas/operator/v2.14/migrate-parameter-to-resource/ 18. [P0] The guide's example new CR has the label `mongodb.com/atlas-reconciliation-policy: keep`. https://www.mongodb.com/docs/atlas/operator/v2.14/migrate-parameter-to-resource/ 19. [P0] The docs warn about skipping the annotation when deletion prot — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/history.md#migration-mechanism` - 8. The `AtlasProject` reconciler handles each subobject in a fixed order inside `ensureProjectResources()`: IP access list, private endpoints, regionalized PE mode, cloud provider integration, network peers, alerts, integrations, maintenance window, encryption at rest, audit, project settings, custom roles, teams, backup compliance, X.509. — https://raw.githubusercontent.com/mongodb/mongodb-atlas-kubernetes/main/internal/controller/atlasproject/atlasproject_controller.go 9. The reconciler stores the previously applied spec in a last-applied-configuration annotation on the `AtlasProject`. `last — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/mechanism.md#controller-mechanism-from-source-internal-controller-atlasproject` ## Measurements and reference values - | Pass | Focus | New claims | Cumulative | Rate | |---|---|---|---|---| | P0 | migration guide, CRD pages | 9 | 9 | 100% | | P1 | release notes, changelog | 8 | 17 | 47% | | P2 | Go source, commit dates | 7 | 24 | 29% | | P3 | third-party search | 1 | 25 | 4% | | P4 | doc.crds.dev, artifacthub, second third-party search | 0 | 25 | 0% | — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/history.md#saturation-new-information-rate-per-pass` ## Problems, failure modes and limitations - - **K1. The change did not all happen in v2.6.** It rolled out one resource at a time from v2.6 to v2.9. M also counts v2.5 as the first step. [M H E P] https://www.mongodb.com/docs/atlas/operator/current/ak8so-changelog.md - **K2. Database users and teams were never deprecated `AtlasProject` subobjects.** `AtlasDatabaseUser` was always a separate CR. `spec.teams` has no `Deprecated:` marker. [M H E P] https://raw.githubusercontent.com/mongodb/mongodb-atlas-kubernetes/main/api/v1/atlasproject_types.go - **K3. The replacement CRs are not tied to `projectRef`.** They accept either `projectRef` o — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/rabbithole-synthesis.md#corrections-to-the-parent-evidence` - - **C1. Not everything changed in v2.6.** The parent says the subobjects "became independent CRDs" in v2.6. The change was actually staggered across four releases: v2.6.0 added `AtlasPrivateEndpoint` and `AtlasCustomRole`, v2.7.0 added `AtlasIPAccessList`, v2.8.0 added `AtlasNetworkPeering` and `AtlasNetworkContainer`, and v2.9.0 added `AtlasThirdPartyIntegration`. https://github.com/mongodb/mongodb-atlas-kubernetes/releases/tag/v2.6.0 · https://github.com/mongodb/mongodb-atlas-kubernetes/releases/tag/v2.7.0 · https://github.com/mongodb/mongodb-atlas-kubernetes/releases/tag/v2.8.0 · https://gi — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/history.md#corrections-to-inherited-parent-facts` - 1. [P1] AKO v2.5.0 (GitHub release 2024-10-29) made `AtlasDeployment` usable "as an independent resource, meaning you can manage Atlas Deployments without managing the Project". This was the first step of the independent-resource pattern, and it came before any subobject was deprecated. https://api.github.com/repos/mongodb/mongodb-atlas-kubernetes/releases?per_page=12&page=2 2. [P1] AKO v2.6.0 was released on 2024-12-20. Its notes say private endpoints and custom roles "can now be **optionally** configured as an independent custom resource". The notes do not use the word "deprecated". https:// — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/history.md#timeline` - In scope: which `AtlasProject.spec.*` subobject fields of the Atlas Kubernetes Operator (AKO) are deprecated, when each was deprecated, what replaces each, how migration works, operational risks during and after migration, and the removal status. Out of scope: the replacement CRDs' own feature specs, the auto-generated experimental CRDs, other IaC tools, and the parent domain. — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/practice.md#scope` - 26. Kubernetes' own API policy (Rule #1): "API elements may only be removed by incrementing the version of the API group." The policy applies to fields of REST resources. https://kubernetes.io/docs/reference/using-api/deprecation-policy/ 27. Kubernetes CRDs support deprecation per version (`deprecated`, `deprecationWarning`). The CRD versioning docs show no built-in way to deprecate a single field. In AKO, the deprecation is therefore only a schema description and docs text, with no API-server warning when you apply a deprecated field (inferred; not tested). https://kubernetes.io/docs/tasks/ex — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/practice.md#evaluation-against-kubernetes-deprecation-norms-disconfirming-angle` - [M H E P] https://www.mongodb.com/docs/atlas/operator/current/migrate-parameter-to-resource/ - **A2.** `spec.networkPeers.containerId` becomes `AtlasNetworkContainer`, so one peering migration can need two CRs. `AtlasNetworkPeering.spec.containerRef` (`name` or `id`) is required and cannot be changed later. You can skip the container CR if something outside AKO already manages the container. [M E P] https://www.mongodb.com/docs/atlas/operator/current/atlasnetworkpeering-custom-resource/ - **A3.** `spec.cloudProviderAccessRoles` has been deprecated since v2.1.0. It was renamed to `spec.cloudPro — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/rabbithole-synthesis.md#a-deprecated-fields-and-their-replacements` - - **B1. v2.5.0** (GitHub release 2024-10-29): `AtlasDeployment` and `AtlasDatabaseUser` can run without a managed project, using `externalProjectRef.id`. No subobject was deprecated yet. [M H P] https://api.github.com/repos/mongodb/mongodb-atlas-kubernetes/releases?per_page=12&page=2 - **B2. v2.6.0** (2024-12-20): private endpoints and custom roles "can now be **optionally** configured" as independent CRs. The release notes do not say "deprecated". [H P] https://github.com/mongodb/mongodb-atlas-kubernetes/releases/tag/v2.6.0 - **B3. v2.6.1**: fixed a bug that deleted custom roles configured in — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/rabbithole-synthesis.md#b-timeline` - In scope: the deprecated `AtlasProject.spec.*` subobject fields of the Atlas Kubernetes Operator (AKO), their replacement independent CRs, the migration procedure, and what goes wrong at the seam between the two forms. Out of scope: siblings (each independent CRD's full feature set, AKO Helm install, GitOps, dry-run mode), the parent IaC domain, and Terraform/CLI/Pulumi. — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/edge-cases.md#scope` - 1. Six `AtlasProject` parameters map to independent CRs: `spec.customRoles`→`AtlasCustomRole`, `spec.privateEndpoints`→`AtlasPrivateEndpoint`, `spec.projectIpAccessList`→`AtlasIPAccessList`, `spec.networkPeers`→`AtlasNetworkPeering`, `spec.networkPeers.containerId`→`AtlasNetworkContainer`, `spec.integrations`→`AtlasThirdPartyIntegration`. https://www.mongodb.com/docs/atlas/operator/current/migrate-parameter-to-resource/ 2. The Go API carries a `// Deprecated:` comment on `ProjectIPAccessList`, `PrivateEndpoints`, `CustomRoles`, `NetworkPeers`, and `Integrations`. https://raw.githubusercontent. — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/edge-cases.md#a-what-is-deprecated-and-when` - **In scope.** This report covers the deprecation of configuring Atlas resources as parameters ("subresources" or "subobjects") inside the Atlas Kubernetes Operator (AKO) `AtlasProject.spec`. It covers which fields were deprecated, in which release, what replaced them, the migration procedure, the controller behaviour, and the current removal status. — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/history.md#scope` - - **In scope:** which `AtlasProject.spec` fields are deprecated and when; their replacement CRDs; the controller mechanism that makes migration safe or unsafe (the last-applied annotation, the skip annotation, deletion rules); the documented migration procedure; limits and caveats. - **Out of scope:** the general design of each replacement CRD (`AtlasIPAccessList`, `AtlasNetworkPeering` and so on), Terraform/CFN equivalents, AKO dry-run, and the parent IaC domain. These are separate frontier items. — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/mechanism.md#scope` - - **C1. "Starting with v2.6" is a simplification.** The change was staged across five releases: 2.5.0 (`AtlasDeployment` and `AtlasDatabaseUser` usable as independent resources), 2.6.0 (`AtlasPrivateEndpoint`, `AtlasCustomRole`), 2.7.0 (`AtlasIPAccessList`), 2.8.0 (`AtlasNetworkPeering`, `AtlasNetworkContainer`) and 2.9.0 (`AtlasThirdPartyIntegration`). — https://www.mongodb.com/docs/atlas/operator/current/ak8so-changelog.md ; https://github.com/mongodb/mongodb-atlas-kubernetes/releases/tag/v2.9.0 - The "2.6" framing comes from MongoDB's own docs: "Beginning with Atlas Kubernetes Operator vers — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/mechanism.md#corrections-to-inherited-parent-facts` - 1. `spec.projectIpAccessList` → `AtlasIPAccessList`. Deprecated in 2.7.0: "Configuring IP Access Lists using the `AtlasProject` custom resource is deprecated and support will end in a future release." — https://www.mongodb.com/docs/atlas/operator/current/ak8so-changelog.md 2. `spec.networkPeers` → `AtlasNetworkPeering`, and `spec.networkPeers.containerId` → `AtlasNetworkContainer`. Deprecated in 2.8.0. — https://www.mongodb.com/docs/atlas/operator/current/ak8so-changelog.md ; https://www.mongodb.com/docs/atlas/operator/current/migrate-parameter-to-resource/ 3. `spec.privateEndpoints` → `AtlasP — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/mechanism.md#deprecated-fields-and-replacements` - 1. Exactly six `AtlasProjectSpec` fields carry a `Deprecated:` comment in the Go API types on `main`: `projectIpAccessList`, `privateEndpoints`, `cloudProviderAccessRoles`, `networkPeers`, `integrations`, `customRoles`. https://raw.githubusercontent.com/mongodb/mongodb-atlas-kubernetes/main/api/v1/atlasproject_types.go 2. `teams`, `auditing`, `encryptionAtRest`, `alertConfigurations`, `backupCompliancePolicyRef` and `x509CertRef` are NOT marked deprecated. https://raw.githubusercontent.com/mongodb/mongodb-atlas-kubernetes/main/api/v1/atlasproject_types.go 3. **Correction:** the inherited paren — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/practice.md#which-fields-are-deprecated-corrects-the-inherited-parent-fact` - | # | Question | Position A | Position B | |---|---|---|---| | X1 | When did it start? | Migration guide: "Beginning with … 2.6" [M H E] | Changelog: per resource in 2.7, 2.8 and 2.9. M counts 2.5–2.9 (five releases); H and P count 2.6–2.9 | | X2 | Were private endpoints and custom roles deprecated in v2.6.0? | E: the v2.16 changelog says v2.6.0 deprecated both | H and P: the v2.6.0 release notes say "optionally" and never "deprecated". P: the changelog's v2.6.0 deprecation bullet names only private endpoints | | X3 | v2.9.0 date | P: 2025-10-31, giving a rollout of "about ten months" | H: the — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/rabbithole-synthesis.md#disagreements-side-by-side` - 12. The documented order has five steps. (1) Annotate the `AtlasProject` with `mongodb.com/atlas-reconciliation-policy: "skip"`. (2) Delete the parameter. (3) Create the new CR. (4) Wait for its status to sync. (5) Remove the skip annotation. https://www.mongodb.com/docs/atlas/operator/current/migrate-parameter-to-resource/ 13. The skip step does more than pause reconciliation. While skipped, the `AtlasProject` reconciler calls `clearLastAppliedMigratedResources()`. That function sets `CustomRoles`, `PrivateEndpoints`, `ProjectIPAccessList`, `NetworkPeers`, and `Integrations` to nil in the las — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/edge-cases.md#b-the-migration-procedure-and-the-mechanism-it-hides` - 10. [P0] The migration table maps `spec.customRoles` → `AtlasCustomRole`, `spec.privateEndpoints` → `AtlasPrivateEndpoint`, `spec.projectIpAccessList` → `AtlasIPAccessList`, `spec.networkPeers` → `AtlasNetworkPeering`, `spec.networkPeers.containerId` → `AtlasNetworkContainer`, and `spec.integrations` → `AtlasThirdPartyIntegration`. The v2.11 and v2.14 pages show the same table. https://www.mongodb.com/docs/atlas/operator/v2.11/migrate-parameter-to-resource/ · https://www.mongodb.com/docs/atlas/operator/v2.14/migrate-parameter-to-resource/ 11. [P2] On `main`, the Go types carry `Deprecated:` do — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/history.md#what-is-deprecated-field-and-replacement` - 15. [P1] As of v2.17.0 (released 2026-09-15), none of the deprecated subobject fields have been removed. The fields are still in the current `AtlasProject` reference and in the v2.17.0 Go module. The v2.13–v2.17 release notes announce no removal. https://www.mongodb.com/docs/atlas/operator/current/atlasproject-custom-resource/ · https://pkg.go.dev/github.com/mongodb/mongodb-atlas-kubernetes/v2/api/v1/project · https://github.com/mongodb/mongodb-atlas-kubernetes/releases 16. [P0] No official source gives a removal version or date. Every source says only "a future release" or "a later release". — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/history.md#removal-status` - - **D1. When were private endpoints and custom roles deprecated?** The migration guide says parameter-based configuration has been deprecated "beginning with … 2.6" (claim 8). The v2.6.0 release notes say the new CRs are "optionally" available and never use the word "deprecated" (claim 2). The changelog's explicit deprecation wording first appears in v2.7.0 (IP access list) and v2.8.0 (network peering). One possible reading: private endpoints and custom roles were deprecated retroactively, through the general rule in claim 9. - **D2. Do the docs agree that `spec.networkPeers` is deprecated?** — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/history.md#unresolved-disagreements` - 17. The steps are: (1) annotate the `AtlasProject` with `mongodb.com/atlas-reconciliation-policy: "skip"`; (2) delete the deprecated field from `AtlasProject.spec`; (3) create the replacement CR, using `projectRef` or `externalProjectRef`; (4) wait for the new CR to show a synced status; (5) remove the skip annotation. — https://www.mongodb.com/docs/atlas/operator/current/migrate-parameter-to-resource/ 18. MongoDB warns that without the annotation, AKO "will continue to attempt reconciliation as you modify your other resources". If deletion protection is disabled, AKO may remove the project or — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/mechanism.md#documented-migration-procedure` - 22. A project supports at most one `AtlasIPAccessList`. If several exist for the same project, "they conflict with one another". — https://www.mongodb.com/docs/atlas/operator/current/atlasipaccesslist-custom-resource/ 23. A project can have only one integration of each type. You cannot declare `DATADOG` both in `spec.integrations` and in an `AtlasThirdPartyIntegration`. Each `AtlasThirdPartyIntegration` holds exactly one integration. — https://www.mongodb.com/docs/atlas/operator/current/migrate-parameter-to-resource/ 24. You do not need a new `AtlasNetworkContainer` if the container is managed — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/mechanism.md#limits-and-edge-cases` - 7. v2.5.0 (2024-10-29): `AtlasDeployment` and `AtlasDatabaseUser` can be used independently of a managed project. This laid the groundwork; no subobject was deprecated yet. https://api.github.com/repos/mongodb/mongodb-atlas-kubernetes/releases?per_page=12&page=2 ; https://www.mongodb.com/docs/atlas/operator/current/ak8so-changelog/ 8. v2.6.0 (2024-12-20): "Private Endpoints can now be optionally configured as an independent custom resource - AtlasPrivateEndpoint" and "Custom Roles can now be optionally configured as an independent CR - AtlasCustomRole". https://github.com/mongodb/mongodb-atlas — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/practice.md#timeline-from-github-release-published-at-dates` - 13. No removal has shipped yet. The deprecated fields are still in the `main` API types (claim 1). The current docs are v2.17, released 2026-09-15. https://www.mongodb.com/docs/atlas/operator/current/ak8so-independent-crd/ ; https://api.github.com/repos/mongodb/mongodb-atlas-kubernetes/releases?per_page=40 14. No removal version or date has been published. The changelog only says "support will be removed in a later release". https://www.mongodb.com/docs/atlas/operator/current/ak8so-changelog/ 15. Deprecated subobjects still get feature work. In v2.15.0 (2026-06-09), MongoDB "Added missing `sen — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/practice.md#removal-status` - 16. Official procedure: (1) add the annotation `mongodb.com/atlas-reconciliation-policy: "skip"` to the `AtlasProject`; (2) delete the deprecated parameter from its spec; (3) create the replacement CR with `projectRef`; (4) wait for that CR to sync; (5) remove the skip annotation. https://www.mongodb.com/docs/atlas/operator/v2.15/migrate-parameter-to-resource/ 17. The docs warn about skipping step 1. If deletion protection is disabled, AKO may remove the Atlas project when you remove the `atlasProject` resource, or get stuck trying to remove a project that still has active subresources. https: — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/practice.md#migration-mechanics` - **Scope.** In scope: the deprecated `AtlasProject.spec` fields, when each was deprecated, what replaces each, how the controller decides what it owns, the migration steps, failure modes and removal status. Out of scope: the full feature set of each replacement CRD, dry-run, deletion-protection internals, `AtlasTeam`, Helm/GitOps and other IaC tools. — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/rabbithole-synthesis.md` - [M H E P] https://www.mongodb.com/docs/atlas/operator/current/ak8so-changelog/ - **B5. v2.7.1**: fixed a bug where applying an `AtlasProject` deleted network peerings it neither managed nor declared. [M E] - **B6. v2.8.0** (2025-03-06): added `AtlasNetworkPeering` and `AtlasNetworkContainer` and deprecated those fields. The same release added dry-run as Public Preview. [H P] https://github.com/mongodb/mongodb-atlas-kubernetes/releases/tag/v2.8.0 - **B7. v2.9.0**: added `AtlasThirdPartyIntegration`, saying "Support will be removed in a later release". The date is disputed (X3). [M H P] https:// — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/rabbithole-synthesis.md#b-timeline` - - **D1.** The documented steps: 1. Add the `skip` annotation to the `AtlasProject`. 2. Delete the deprecated field. 3. Create the replacement CR. 4. Wait for it to sync. 5. Remove the annotation. — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/rabbithole-synthesis.md#d-migration` - [M H E P] https://www.mongodb.com/docs/atlas/operator/current/migrate-parameter-to-resource/ - **D2.** The official example uses only `projectRef`. Migrating therefore does not take the project out of AKO management; switching to `externalProjectRef` is a separate step [P]. With `externalProjectRef` you can delete the `AtlasProject` CR. With `projectRef` you must keep it [M]. https://www.mongodb.com/docs/atlas/operator/v2.16/ak8so-independent-crd/ - **D3.** A replacement CR must set exactly one of `projectRef` or `externalProjectRef`; a CEL rule enforces this. `externalProjectRef` also needs a — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/rabbithole-synthesis.md#d-migration` - 21. **Disconfirming the parent's RBAC rationale for IP lists:** "Each Atlas project supports at most one `AtlasIPAccessList` resource. If you define multiple … they conflict." Teams in different namespaces cannot each own part of one project's IP list. https://www.mongodb.com/docs/atlas/operator/current/atlasipaccesslist-custom-resource/ 22. Third-party integrations allow one instance per type per project, counted across both forms. An `AtlasThirdPartyIntegration` of type `DATADOG` therefore forbids a `spec.integrations` entry of type `DATADOG`. https://www.mongodb.com/docs/atlas/operator/curr — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/edge-cases.md#c-per-resource-boundary-conditions` - **Out of scope.** The report does not cover sibling AKO topics (dry-run, Helm install, the independent-CRD feature as a whole, or deletion protection), Terraform, or the parent IaC domain. It mentions those topics only where they correct or limit a claim about this concept. — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/history.md#scope` ## Comparisons and alternatives - - **"Alternating reconcile" claim (inherited parent fact):** the parent says AKO flips between the two configurations on each reconcile if both the subobject and the independent CR define the same resource. No primary source found confirms or refutes this. The only documented conflict is between several `AtlasIPAccessList` CRs (claims 23–24). Treat it as unverified. - **Docs inconsistency:** the migration guide puts `mongodb.com/atlas-reconciliation-policy: keep` under `labels` on the new CR. The annotations reference defines `atlas-reconciliation-policy` only with `skip`, and `keep` only for — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/practice.md#unresolved-disagreements-and-gaps` - - **Start version.** The migration guide says the transition began in v2.6. The changelog dates IP lists to v2.7 and peering/containers to v2.8. Both are MongoDB sources. The changelog is more precise per resource. https://www.mongodb.com/docs/atlas/operator/current/migrate-parameter-to-resource/ vs https://www.mongodb.com/docs/atlas/operator/v2.16/ak8so-changelog/ - **Wording of the end of support.** One changelog entry says support "will end in a future release" (v2.7 IP lists). Others say it "will be removed in a later release" (v2.6, v2.8). Neither gives a date. https://www.mongodb.com/doc — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/edge-cases.md#unresolved-disagreements` - - **Label or annotation for `keep`.** The migration guide's `AtlasCustomRole` example puts `mongodb.com/atlas-reconciliation-policy: keep` under `metadata.labels` (https://www.mongodb.com/docs/atlas/operator/current/migrate-parameter-to-resource/). In the source, `keep` belongs to a different key, the annotation `mongodb.com/atlas-resource-policy`, and the reconciliation-policy key recognises only `skip` (https://raw.githubusercontent.com/mongodb/mongodb-atlas-kubernetes/main/internal/controller/customresource/customresource.go). The doc example appears to be wrong. Not reconciled. - **CRD nam — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/mechanism.md#unresolved-disagreements-and-inconsistencies` ## Facts and statements - - **A1.** Five fields map to new CRDs: - `spec.customRoles` → `AtlasCustomRole` - `spec.privateEndpoints` → `AtlasPrivateEndpoint` - `spec.projectIpAccessList` → `AtlasIPAccessList` - `spec.networkPeers` → `AtlasNetworkPeering` - `spec.integrations` → `AtlasThirdPartyIntegration` — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/rabbithole-synthesis.md#a-deprecated-fields-and-their-replacements` - - **E1.** Only one `AtlasIPAccessList` is allowed per project; multiple CRs "conflict with one another". [M H E P] - **E2.** Issue #2869 (AKO 2.11.0, 2025-11-05) reports that with several `AtlasIPAccessList` CRs, "whichever CR reconciles last overwrites" the others. It was closed as not planned. [P] https://github.com/mongodb/mongodb-atlas-kubernetes/issues/2869 - **E3.** A project can have one integration of each type, counted across both forms. Each `AtlasThirdPartyIntegration` holds exactly one integration. [M E] - **E4.** A peering belongs to exactly one project, so you need one CR per pro — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/rabbithole-synthesis.md#e-limits-and-failure-modes` - - **F1.** MongoDB's docs call subobjects "parameters" or "subresources". [M H] - **F2.** The "Independent CRDs" page covers only `AtlasDeployment` and `AtlasDatabaseUser` in `externalProjectRef` mode. It does not mention the deprecation. [H P] - **F3.** Ariga's `atlas-operator` is an unrelated schema-migration operator that shows up in searches for this name. [H] https://github.com/ariga/atlas-operator — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/rabbithole-synthesis.md#f-terminology-traps` - Researched 2026-10-01. Concept: the deprecation of configuring Atlas sub-resources as fields ("subobjects", which MongoDB's docs call "parameters") inside `AtlasProject.spec`, and how the Atlas Kubernetes Operator (AKO) handles the move to independent custom resources. — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/mechanism.md` - - The `AtlasTeam` CR and how teams are assigned to projects - `atlas-resource-policy: keep` and deletion-protection internals - AKO dry-run as a way to verify a migration - `externalProjectRef` mode - The `cloudProviderAccessRoles` → `cloudProviderIntegrations` field rename - The auto-generated `IPAccessListEntry` resource (PR #3296, cited by P without a URL) — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/rabbithole-synthesis.md#handoffs-to-concept-family-explorer-not-researched-here` - Method note: Bash, Firecrawl, and the shared-source cache were unavailable in this session (permission denied). All evidence came from WebFetch/WebSearch against live pages and the AKO source on `main`, fetched 2026-10-01. Claims marked **[code-derived]** are my reading of controller source, not documented vendor statements. — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/edge-cases.md#scope` - - **Distinct hosts:** www.mongodb.com (docs), github.com / api.github.com / raw.githubusercontent.com (primary repo), and pkg.go.dev (Go module index). That makes three host families, so the host count is met. - **Independent authorship: NOT met.** All substantive evidence comes from MongoDB, through its docs, its repository, or the Go index's rendering of its source. I searched for third-party analysis twice and found only an unrelated namesake (claim 25). doc.crds.dev and artifacthub.io pages returned no field content. - **Disconfirming evidence was sought and found:** D1, D2 and C1–C4 contr — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/history.md#quality-gate` - Handoff list for concept-family-explorer (not researched here): AKO dry-run mode, AKO deletion-protection flags, `externalProjectRef` independent-resource mode, and the `cloudProviderAccessRoles` → `cloudProviderIntegrations` field migration. — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/history.md#saturation-new-information-rate-per-pass` - - `AtlasTeam` CR and team assignment model - AKO `atlas-resource-policy: keep` and deletion protection internals - AKO dry-run as a migration-verification tool — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/mechanism.md#handoffs-not-researched-here` - 23. The new CRs keep whole-list ownership. "Each Atlas project supports at most one `AtlasIPAccessList` resource. If you define multiple … they conflict with one another." So splitting one access list across teams as several CRs is not supported. https://www.mongodb.com/docs/atlas/operator/current/atlasipaccesslist-custom-resource/ 24. A user on AKO 2.11.0 reported this in practice (2025-11-05): with several `AtlasIPAccessList` CRs on one project, "whichever CR reconciles last overwrites" the others' entries. The issue was closed as not planned with no fix from a maintainer. https://github.com — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/practice.md#trade-offs-and-post-migration-risks` - Handoffs (not researched here): auto-generated `IPAccessListEntry` resource (PR #3296); `CloudProviderIntegrations` field; AKO dry-run mode as a migration check. — source: `~/.global-ai-hub/research-tests/mongodb-full-frontier-20261002/full-frontier-run/ako-subobject-crds-deprecated-143c37f899/reports/practice.md#quality-gate` ## Related concepts - AKO — is a part of AKO Subobject CRDs Deprecated - Deprecated — is a part of AKO Subobject CRDs Deprecated - Subobject — is a part of AKO Subobject CRDs Deprecated - CRDs — is a part of AKO Subobject CRDs Deprecated