crossplane-migrator

Crossplane release 1.14 introduced functions and the Deployment Runtime.

In order to take advantage of these features, this golang-based binary can be used to convert legacy YAML manifests to newer APIs.

The following conversions are supported:

ControllerConfig to DeploymentRuntimeConfig
Compositions to use Function-based Patch and Transform instead of the built-in engine.

This utility is proposed to be added to the Crossplane CLI in 1.15.

Installing
Example Use
- Migrating ControllerConfigs to DeploymentRuntimeConfigs
- Migrating Existing Compositions to use Pipelines
  - Setting the Function Name
  - Migrating Running Compositions to Function Patch and Transform
Building
Known Issues

Installing

Binary releases are available at https://github.com/crossplane-contrib/crossplane-migrator/releases.

To install the latest version, run:

go install github.com/crossplane-contrib/crossplane-migrator@latest

Example Use

Usage: crossplane-migrator <command>

Crossplane migration utilities

Commands:
  new-deployment-runtime      Convert deprecated ControllerConfigs to
                              DeploymentRuntimeConfigs.
  new-pipeline-composition    Convert Compositions to Composition Pipelines with
                              function-patch-and-transform.

Migrating ControllerConfigs to DeploymentRuntimeConfigs

Crossplane ControllerConfig to a DeploymentRuntimeConfig.

DeploymentRuntimeConfig was introduced in Crossplane 1.14 and ControllerConfig has been marked deprecated since Crossplane 1.11.0.

Write out a DeploymentRuntimeConfig file from a ControllerConfig manifest:

crossplane-migrator new-deployment-runtime  -i examples/enable-flags.yaml  -o my-drconfig.yaml

Create a new DeploymentRuntimeConfig via Stdout

crossplane-migrator new-deployment-runtime -i cc.yaml | grep -v creationTimestamp | kubectl apply -f -

Once the new DeploymentRuntimeConfig has been created on the Crossplane Cluster it can be used by Function and Provider packages via the runtimeConfigRef, which replaces controllerConfigRef.

apiVersion: pkg.crossplane.io/v1beta1
kind: Function
metadata:
  name: function-patch-and-transform
spec:
  package: xpkg.upbound.io/crossplane-contrib/function-patch-and-transform:v0.1.4
  runtimeConfigRef:
    apiVersion: pkg.crossplane.io/v1beta1   # currently apiVersion and kind are optional
    kind: DeploymentRuntimeConfig
    name: func-env

Migrating Existing Compositions to use Pipelines

function-patch-and-transform runs Crossplane's built-in Patch&Transform engine in a function pipeline. This utility can migrate existing compositions to run in a pipeline:

./crossplane-migrator new-pipeline-composition -i composition.yaml -o composition-pipeline.yaml

Setting the Function Name

By default, the functionNameRef is set to function-patch-and-transform. If installing a function via a Crossplane Configuration package, the package organization will be added (i.e. crossplane-contrib-function-patch-and-transform).

./crossplane-migrator new-pipeline-composition --function-name crossplane-contrib-function-patch-and-transform -i composition.yaml

Migrating Running Compositions to Function Patch and Transform

Note: please test this procedure in non-production environments and back up all resources before attempting a migration of live resources.

First, ensure that a function that supports the legacy Path and Transform is installed in your cluster and is in a healthy state.

$ kubectl get function
NAME                           INSTALLED   HEALTHY   PACKAGE                                                       AGE
function-patch-and-transform   True        True      xpkg.upbound.io/upbound/function-patch-and-transform:v0.2.1   8m48s

Ensure all resources generated by this Composition are healthy:

$ kubectl get composite 
NAME              SYNCED   READY   COMPOSITION                         AGE
ref-aws-network   True     True    xnetworks.aws.platform.upbound.io   33m

Convert the composition and apply it to the cluster:

crossplane-migrator new-pipeline-composition -i composition.yaml -o composition-pt.yaml

$ kubectl apply -f composition-pt.yaml
composition.apiextensions.crossplane.io/xnetworks.aws.platform.upbound.io configured

Confirm that resources are healthy:

$ kubectl get composite 
NAME              SYNCED   READY   COMPOSITION                         AGE
ref-aws-network   True     True    xnetworks.aws.platform.upbound.io   33m

Building

go build -o crossplane-migrator

Known Issues

The migrator attempts to be as accurate as possible in mapping fields but has not been fully tested. The ControllerConfig test suite and Composition test suite attempt to cover all cases.
The generated DeploymentRuntimeConfig has the same Name: as the ControllerConfig.

phisco/crossplane-migrator