Added documentation for upgrading address spaces

[vbusch]

fixes: #2825 Address spaces are not upgraded as part of the upgrade process. Adding documentation for how to do it manually.

Signed-off-by: Vanessa vbusch@redhat.com

[k-wall]

thanks @vbusch for the address space upgrade investigation. The user having to trigger it by amending the infraconfigs' version just seems weird to me. Did we really design it that way? To me the implication is that the infraconfig plans should always be replaced as part of the upgrade, but this would be odd as the infraconfig belongs to the user. They may have tailored it. Also what would it mean if, after the upgrade, I didn't update the infraconfig's version and then created new addressspaces. The 'old' infraconfig would applied to the new addresspace. If I then went on to update the infraconfig, changes would be ignored by the controller because the version didn't match that of the running code.. One thing I don't understand at the moment is what circumstances we actually materialise the version field in the infraconfig. The infraconfig from the install is versionless.

[lulf]

@k-wall @vbusch allow me to shed some light on this :) In 0.26 and older, the 'version' field was mandatory, and upgrading required applying new infra configs with the updated version. The problem with this, as you point out Keith, is that the infra configs are user owned and it is odd to having to reapply it for every version.

So, in 0.27 and newer, the version field was made optional, so that users would not have to maintain the version number. If version is not set, KubeSchemaApi.assembleSchema() will set the version of the parsed infra config to the same version as the controller before updating the 'current' schema.

The reconciliation loop will compare the infra config in the address space annotation with the 'desired' infra config to decide if changes should be applied (see CreateController).

Why upgrade did not happen automatically I'm not sure, but hopefully the above should explain a little why things are the way they are.

[vbusch]

@lulf thank you, that explanation was really helpful.
For upstream, sounds like we won't need this if we assume the users have a version newer then 0.26

[k-wall]

@vbusch if io.enmasse.k8s.api.KubeSchemaApi#assembleSchema were changed to unconditionally replace the infraconfig's version with the runtime version, wouldn't that give the correct behaviour? Whenever the version changes, surely we want to give the addressspacecontroller the chance to rewrite the deployments etc.

[vbusch]

@k-wall When upgrading from 0.26 to 0.27, the version is removed. Which allows the upgrade from 0.27 to 0.28 to work. When going from 0.26 -> 0.28 removing the check as you suggested fixes the issue as well.
Closing this, since docs upstream are not required.