Skip to main content
Version: Release 24.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 used during the upgrade process:

.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 understand how they work in the upgrade process:

Simple Path Mapping​

The simplest form of mapping copies values directly between identical paths:

.metadata.name: .

This mapping indicates that .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​

Version-specific mappings define different paths based on the source version:

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

In this example:

  • 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 mappings may only apply to specific versions:

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

This configuration shows that:

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

Complex Expression Mapping​

Advanced mappings can use conditions and expressions for more sophisticated migration logic:

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

This type of mapping:

  • For versions before 23.3: Checks for a true value and uses a custom yq expression
  • From version 23.3 onwards: Uses direct path mapping