Custom resource keys migration during upgrade

From 23.3 version, there are changes how is working answer to the question: Edit list of custom resource keys that will migrate to the new Deploy CR:.

The list of the custom resource keys that are used in migration is for mapping between a previous version and new version to which we are doing upgrade.

Choosing which keys to preserve

Preserve only the keys that hold configuration you set yourself. Preserving a broader path than you need can carry stale values into the new custom resource and leave the upgraded pods running the previous version's configuration.

Keep the following in mind when you edit the list:

• Scope volume permission keys narrowly. Preserve the specific volumePermissions.enabled key rather than the whole volumePermissions block, which also carries the image reference. For Deploy, the keys are:

  .spec.centralConfiguration.volumePermissions.enabled
  .spec.master.volumePermissions.enabled
  .spec.worker.volumePermissions.enabled

  Apply the same principle to the operator-based dependencies, such as PostgreSQL and RabbitMQ: preserve the individual setting you changed, not the parent block.

• Do not preserve image tags or repositories. The upgrade evaluates image tag and repository values fresh for the target version. Preserving them pins the installation to the previous version's images.

caution

Preserving a volumePermissions block that contains an image reference results in the upgraded pods using the previous version's volume permission image, and the master, worker, and RabbitMQ pods may not restart with the upgrade changes. If the pods do not pick up the upgrade, check the preserved keys for image references before you investigate further.

Migration mapping example

Here is a snippet of the answer:

.metadata.name: .
.spec.global.storageClass: 
  0.0: .spec.Persistence.StorageClass
  23.3: .
.spec.auth.adminPassword: 
  0.0: .spec.AdminPassword
  23.3: .
.spec.centralConfiguration.replicaCount: .
.spec.centralConfiguration.persistence.accessModes[0]:
  0.0: .spec.Persistence.AccessMode
  23.3: 
.spec.centralConfiguration.persistence.accessModes:
  0.0: 
  23.3: .
.spec.centralConfiguration.persistence.size: 
  0.0: .spec.centralConfiguration.persistence.pvcSize
  23.3: .
.spec.centralConfiguration.persistence.existingClaim: 
  0.0: 
    existence: .spec.deploy.centralConfiguration.persistence.existingClaim
    expression: .spec.deploy.centralConfiguration.persistence.existingClaim
  23.3: .

Here we will explain different mapping types:

.metadata.name: .

The .metadata.name is path in the new version CR. The value . represents the same path. This mapping defines that old version CR value under path .metadata.name will be copied to the new version CR under the same path.

.spec.auth.adminPassword:
  0.0: .spec.AdminPassword
  23.3: .

The .spec.auth.adminPassword is path in the new version CR. The value here is composed of two parts:

• 0.0: .spec.AdminPassword - for versions below 23.3 (the next key below) it is using this mapping path for the old version CR.
• 23.3: . - for versions from 23.3 it is using this mapping path for the old version CR.

This mapping defined that old version CR, for versions below 23.3, is using .spec.AdminPassword as a source of value, that is migrated under path .spec.auth.adminPassword in the new version CR. From version 23.3 it is using .spec.auth.adminPassword as a source of value, same path as where the value will be migrated to the new CR.

.spec.centralConfiguration.persistence.accessModes:
  0.0:
  23.3: .

The .spec.centralConfiguration.persistence.accessModes is path in the new version CR. The value here is composed of two parts:

• 0.0: - for versions below 23.3 (the next key below) it is not mapping the value because this mapping is empty.
• 23.3: . - for versions from 23.3 it is using this mapping path for the old version CR.

This mapping does not define that old version CR, for versions below 23.3, it it not migrating the value. From version 23.3 it is using .spec.centralConfiguration.persistence.accessModes as a source of value, same path as where the value will be migrated to the new CR.

.spec.centralConfiguration.persistence.existingClaim:
  0.0:
    existence: .spec.deploy.centralConfiguration.persistence.existingClaim
    expression: .spec.deploy.centralConfiguration.persistence.existingClaim
  23.3: .

The .spec.centralConfiguration.persistence.existingClaim is path in the new version CR. The value here is composed of two parts:

0.0:
  existence: .spec.deploy.centralConfiguration.persistence.existingClaim
  expression: .spec.deploy.centralConfiguration.persistence.existingClaim

• for versions below 23.3 (the next key below) it is using this complex expression for the old version CR.
• 23.3: . - for versions from 23.3 it is using this mapping path for the old version CR.

This mapping defined that old version CR, for versions below 23.3, is checking if there is true value under .spec.deploy.centralConfiguration.persistence.existingClaim and it is using same value as a source of value (defined by expression), that is migrated under path .spec.centralConfiguration.persistence.existingClaim in the new version CR. expression can be any kind of expression that is possible to evaluate with yq. From version 23.3 it is using .spec.centralConfiguration.persistence.existingClaim as a source of value, same path as where the value will be migrated to the new CR.