Resource Transformation

Use the instructions to create a transform CR.

1. Define a transform CR that contains all the necessary transformations. The transform CR must be referenced in the restore CR, which ensures that the transformations get applied.
   • Create transform CR
   • Create restore CR with a transform CR
   • Apply the restore CR
2. A transform CR can consist of multiple transform rules. Each transform must have the following three sections:

   Name

   The name of each transform rule must be unique.

   Patch type

   There are four types of patches that can be defined:

   • Json patch
   • Merge patch
   • Strategic patch
   • String patch

   Subject

   The subject specifies the resources on which the patch gets to apply.

   • groupResource - Fully qualified resource name, such as
     • Core API group (v1) - pods, services, configmaps, secrets, persistentvolumeclaims, and so on.
     • Named API groups (apps/v1) - deployments.apps, statefulsets.apps, and so on.
     • Batch (batch/v1): jobs.batch, cronjobs.batch
     • networking.k8s.io/v1 - ingress.networking.k8s.io, networkpolicies.networking.k8s.io
   • resourceNameRegex - matching resource name
   • labelSelector - matching resource label
   • namespaces - the namespace where the resource is available

3. The four kinds of patches that can be applied in transform CR.

   JSON patch

   A JSON patch supports operations like test, add, remove, and replace on specific paths. There are three fields need to define in the JSON patch:

   • op - operation name
     • test - to test if specific value is present on the given path
     • add - to add the value on the given path
     • remove - to remove the value on the given path
     • replace - to replace the value on the given path
   • path - on which the operation applies
   • value - value on which these operations acted upon

   For example, transform CR to transform multiple storage classes with JSON patch:

   apiVersion: data-protection.isf.ibm.com/v1alpha1
   kind: Transform
   metadata:
     name: transform-storage-classes
     namespace: ibm-spectrum-fusion-ns
   spec:
     transforms:
     - name: pvc-test-replace-storage-class-fs
       json:
       - op: test
         path: /spec/storageClassName
         value: "${SOURCE_STORAGE_CLASS_FS}"
       - op: replace
         path: /spec/storageClassName
         value: "${TARGET_STORAGE_CLASS_FS}"
       subject:
         groupResource: persistentvolumeclaims
     - name: pvc-test-replace-storage-class-rbd
       json:
       - op: test
         path: /spec/storageClassName
         value: "${SOURCE_STORAGE_CLASS_RBD}"
       - op: replace
         path: /spec/storageClassName
         value: "${TARGET_STORAGE_CLASS_RBD}"
       subject:
         groupResource: persistentvolumeclaims 
   

   Note: ${SOURCE_STORAGE_CLASS_FS}, ${TARGET_STORAGE_CLASS_FS}, ${SOURCE_STORAGE_CLASS_RBD}, ${TARGET_STORAGE_CLASS_RBD}, these are the placeholders here which can be pass dynamically using transformMapping in restore CR.

   Merge patch

   Merges provided fields into the target resource using a simple JSON structure. A specific field needs to be defined.

   patchData - provide a JSON structure

   For example, transform CR to add labels to statefulsets using merge patch.

   apiVersion: data-protection.isf.ibm.com/v1alpha1
   kind: Transform
   metadata:
     name: transform-using-merge-patch
     namespace: ibm-spectrum-fusion-ns
    - name: statefulsets-with-merge-patch-labels
       mergePatches:
       - patchData: |
           {
             "metadata": {
               "labels": {
                 "modify-by": "${MODIFY_BY}"
               }
             }
           }
       subject:
         groupResource: statefulsets.apps
         labelSelector: 'a=b'

   Note: {MODIFY_BY} is a placeholder here that can be pass dynamically using transformMapping in restore CR.

   Strategic patch

   Merges fields intelligently based on resource schema, preserving arrays like containers by name. A specific field needs to be defined.

   patchData - provide a JSON structure

   For example, transform CR to update image version and add a env variable using strategic patch.

   apiVersion: data-protection.isf.ibm.com/v1alpha1
   kind: Transform
   metadata:
     name: transform-using-strategic-patch
     namespace: ibm-spectrum-fusion-ns
     - name: deployment-with-strategic-patch
       strategicPatches:
       - patchData: |
           { 
             "spec":
               {
                 "template":
                   {
                     "spec": {
                       "containers": [
                         { 
                           "name": "nginx-main",
                           "image": "nginx:1.25.6",
                           "imagePullPolicy": "Always",
                           "env": [
                             {
                               "name": "test",
                               "value": "${MODIFY_BY}"
                             },
                           ]
                         }
                       ]
                     }
                   }
               }
           }
       subject:
         groupResource: deployments.apps
         resourceNameRegex: nginx-multi-container
   

   String patch

   Replaces specific strings in a target resource using key-value pairs. Two specific fields needs to be defined.

   • key - fully qualified path where string need to be replaced
   • replaceStrings
     • Old - old string, which needs to be replaced
     • New - new string, which needs to be replaced on the place of old string.

   For example, transform CR to transform data in the configmap using string patch.

   apiVersion: data-protection.isf.ibm.com/v1alpha1
   kind: Transform
   metadata:
     name: transform-using-string-patch
     namespace: ibm-spectrum-fusion-ns
   spec:
     transforms:
     - name: configmap-with-string-patch
       stringPatch:
       - key: data/instance.json
         replaceStrings:
         - new: '\"persistence.cachingpv.storageClass\": \"${TARGET_STORAGE_CLASS_FS}\"'
           old: '\"persistence.cachingpv.storageClass\": \"transform\"'
       subject:
         groupResource: configmaps
         resourceNameRegex: dv-instance-config
   

4. After the transform CR is define, then create a restore CR with its reference.
   For example:

   apiVersion: data-protection.isf.ibm.com/v1alpha1
   kind: Restore
   metadata:
     name: restore-with-transform
     namespace: ibm-spectrum-fusion-ns
   spec:
     backup: <backup-name>
     targetCluster: <target-cluster-name>
     transform: transform-storage-classes
     transformMapping:
       INGRESS_HOST:  transformed.com
       SOURCE_STORAGE_CLASS_FS: ocs-storagecluster-cephfs
       TARGET_STORAGE_CLASS_FS: ocs-storagecluster-cephfs-1
       SOURCE_STORAGE_CLASS_RBD: ocs-storagecluster-ceph-rbd
       TARGET_STORAGE_CLASS_RBD: ocs-storagecluster-ceph-rbd-1
       MODIFY_BY: fusion-transform
   

   Define the two new fields transform and transformMapping in the restore CR.

   • transform - name of the transform CR.
   • transformMapping - If required, pass the variable that can be substituted in the transform CR.
5. Apply the restore CR.
   Note:

   • Transform CR should be present on the target cluster where restoring the application.
   • For persistentvolumeclaims, only JSON patch is supported, and all the 4 patches are supported for resources.
   • The test operation in JSON patch is used in conjunction with other operations (add, replace, remove). If the test operation fails, the entire patch is aborted and none of the subsequent operations are run in that transform rule.
   • Strategic Merge patch operates based on the name field within arrays (such as containers):
     • If the name field is missing, then the merge is skipped.
     • If a matching name field is present, then the existing entry is merged.
     • If a matching name field is not present, then a new entry is added to the array.
   • For more examples of using Transform CR, see Sample Transform CR.