Skip to main content
Version: Release 23.3

Custom Resource Keys Migration During Upgrade

This guide explains how custom resource keys are migrated during the Digital.ai Release operator upgrade process. Understanding this process is crucial for maintaining your configuration when upgrading to newer versions of the operator.

note

Starting from Release 23.3, there are changes to how the system handles the response to the following upgrade prompt: Edit list of custom resource keys that will migrate to the new Release CR:

The custom resource keys migration list defines the mapping between previous versions and the target upgrade version. This mapping ensures your configuration data is correctly preserved during the upgrade process.

Migration Mapping Examples

The following example demonstrates the structure of migration mappings that define how configuration values are preserved during upgrades:

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

Understanding Different Mapping Types

Let's explore each type of mapping and its specific purpose in the upgrade process.

Simple Path Mapping

The most straightforward form of mapping where values are copied directly between versions:

.metadata.name: .

In this case, .metadata.name from the old CR will be copied directly to the same path in the new CR. The . indicates the path remains identical.

Version-Specific Path Mapping

This mapping type handles different paths based on the source version:

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

This defines how values are mapped differently based on the version:

  • For versions before 23.3: Uses .spec.AdminPassword as the source path
  • From version 23.3 onwards: Uses the same path (.spec.auth.adminPassword)

Conditional Mapping

Some fields may only be relevant in certain versions:

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

This mapping structure indicates:

  • For versions before 23.3: No migration occurs (empty mapping)
  • From version 23.3 onwards: Migrates from the same path

Complex Expression Mapping

For scenarios requiring advanced logic:

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

This advanced mapping type:

  • For versions before 23.3: Validates existence and uses custom yq expressions
  • From version 23.3 onwards: Uses direct path mapping