Operator v2.x.x breaking changes to the CRD

[danielloader]

So it's covered by the following release note (on v2.0.1) but it's not visible anywhere else in the documentation nor the README.md:

Remove legacy deployment by @igor-karpukhin in #1182
In order to standardize on one deployment type (for non-serverless deployments), we have removed the notion of advancedDeploymentSpec. All deployment options are now supported as part of the deploymentSpec. For the AtlasDeployment resource, the following things were changed:
spec.deploymentSpec - now contains all fields from the spec.advancedDeploymentSpec.
spec.advancedDeploymentSpec - is gone. If you used advancedDeploymentSpec before, the only change you need to make is to rename the advancedDeploymentSpec to deploymentSpec in the AtlasDeployment resource. If you used deploymentSpec, you will need to rewrite it to advancedDeploymentSpec format.

But... the CRD is still the same version and thus overwrites the existing one in a breaking way in existing clusters if you update the operator.

https://doc.crds.dev/github.com/mongodb/mongodb-atlas-kubernetes/atlas.mongodb.com/AtlasDeployment/[email protected]
https://doc.crds.dev/github.com/mongodb/mongodb-atlas-kubernetes/atlas.mongodb.com/AtlasDeployment/[email protected]

One would expect a bump from apiVersion atlas.monogdb.com/v1 to atlas.mongodb.com/v2alpha1 or similar with the operator having some sort of backwards compatibility with both CRDs for a few releases so you can soft migrate your objects to the new spec.

Furthermore this breaks the examples and the documentation upstream https://www.mongodb.com/docs/atlas/reference/atlas-operator/atlasdeployment-custom-resource/#examples as those are targetting the old prior spec of the CRD.

[s-urbaniak]

Hello 👋 We are sorry to hear that you are having trouble upgrading our operator and indeed, you are absolutely correct, currently it is hard to do an in-cluster upgrade of our operator since the CRD version didn't change. Please stay tuned, we are working on improving the upgrade story. Just bumping the CRD version though is not as easy as it seems due to invariants that need to be maintained within Kubernetes between resource version conversions. When it comes to the documentation samples, thank you a lot! We will make sure to update those.

[danielloader]

Thanks for the update and glad to hear the examples will get updated!

I appreciate dealing with two mutually exclusive API contracts is difficult, but that's why they're different versions - and if they can't be mutually dealt with inside the codebase then I suggest just hard cutting over at v1 to v2 on the operator, so the v2 operator can't read atlas.mongodb.com/v1 versioned objects.

If the code can't read perfectly valid v1 spec AtlasDeployments then it's an operator side problem is it not?

For an alternative, AWS had to go through this very pain with Karpenter recently:
https://karpenter.sh/docs/upgrading/upgrade-guide/#upgrading-to-v0320

[comptonad]

Maybe this should be it's own issue but spec.deploymentSpec.providerSettings no longer exists. I've just installed a fresh v2.0.1 and it's missing from the CRD. Looking at the diff from 8676519 it looks like it was removed when generating with refactored changes.

[s-urbaniak]

@comptonad indeed, you are right, please advise the changelog available at https://github.com/mongodb/mongodb-atlas-kubernetes/releases/tag/v2.0.1. This release indeed includes breaking changes.

[damaca]

Where I can finde the updated documentation for this? Looks like the doc in https://www.mongodb.com/docs/atlas/atlas-operator/stable/atlasdeployment-custom-resource/ still have references to the old format

[damaca]

Where I can finde the updated documentation for this? Looks like the doc in https://www.mongodb.com/docs/atlas/atlas-operator/stable/atlasdeployment-custom-resource/ still have references to the old format

I managed to make my manifest work but I had to review the whole CRD as there are multiple "typos" in some of the doc examples:

• regionsConfig instead of regionConfigs
• providerSettings examples
• etc

[roothorp]

Hi @damaca - thanks for pointing these out. We're going to go through and review the docs examples to make sure they're accurate. Thanks!

[github-actions]

This issue has gone 30 days without any activity and meets the project’s definition of 'stale'. This will be auto-closed if there is no new activity over the next 60 days. If the issue is still relevant and active, you can simply comment with a 'bump' to keep it open. Thanks for keeping our repository healthy!

[eli-kasa]

bump

Still an issue in the latest release. Docs are still wrong, CRD is still incoherent, stuck on 1.9.3 as there is no clear path forward for just a simple AtlasDeployment definition

[github-actions]

This issue has gone 30 days without any activity and meets the project’s definition of 'stale'. This will be auto-closed if there is no new activity over the next 60 days. If the issue is still relevant and active, you can simply comment with a 'bump' to keep it open. Thanks for keeping our repository healthy!

[s-urbaniak]

Hello 👋 please see our upgrade instructions available at https://www.mongodb.com/docs/atlas/operator/current/upgrade-ako-v1-to-v2/ for a migration guide from 1.x to 2.x.