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.

Important

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 Structure

The following example demonstrates various migration mapping patterns used during the upgrade process:

// filepath: example-mapping.yaml
.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:
        existance: .spec.Persistence.ExistingClaim
        expression: .spec.Persistence.ExistingClaim
    23.3: .

Understanding Mapping Types

Let's explore the different mapping patterns and their specific use cases in the migration process.

Simple Path Mapping

The most straightforward mapping type directly copies values between identical paths:

// filepath: simple-mapping.yaml
.metadata.name: .

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

Version-Specific Path Mapping

This mapping type handles different paths based on source versions:

// filepath: version-specific-mapping.yaml
.spec.auth.adminPassword:
  0.0: .spec.AdminPassword
  23.3: .

For versions before 23.3, the system reads from .spec.AdminPassword. From version 23.3 onwards, it uses .spec.auth.adminPassword directly.

Conditional Mapping

Some fields may require conditional migration based on versions:

// filepath: conditional-mapping.yaml
.spec.persistence.accessModes:
  0.0:
  23.3: .

This pattern skips migration for versions before 23.3 but implements direct path mapping from 23.3 onwards.

Expression-Based Mapping

Complex migrations may require additional validation or transformation:

// filepath: expression-mapping.yaml
.spec.persistence.existingClaim:
  0.0:
    existence: .spec.persistence.existingClaim
    expression: .spec.persistence.existingClaim
  23.3: .

For pre-23.3 versions, this mapping:

1. Verifies the existence of a value at .spec.persistence.existingClaim
2. Uses a custom yq expression for value transformation
3. Applies direct mapping for version 23.3 and later