mig-controller

README

mig-controller

Installing

mig-controller is installed by mig-operator.

Demo Video

This video shows a CLI driven migration of a rocket-chat app and associated PersistentVolume data from OpenShift 3.11 => OpenShift 4.6.

Development

HACKING.md has instructions for:

• Building mig-controller
• Running mig-controller locally
• Invoking CI on pull requests

DEVGUIDE.md has guidelines for:

• Design patterns
• Conventions
• Dev practices

Quick-start: CLI based migration

1. Identify a pair of running OpenShift clusters to migrate workloads between

mig-controller can help you move OpenShift application workloads from a source to a destination cluster. You'll need cluster-admin permissions on both OpenShift clusters.

• velero will need to be installed on both clusters, and will be driven by mig-controller
• mig-controller should only be installed on one of the two clusters. You can decide which cluster will host this component.

---

2. Use mig-operator to deploy Migration Tools to both the source and destination OpenShift clusters

Use mig-operator to install selected components of Migration Tooling (mig-controller, mig-ui, velero) onto your source and destination OpenShift clusters.

After installing mig-operator, you can select which components should be installed by creating a MigrationController CR:

apiVersion: migration.openshift.io/v1alpha1
kind: MigrationController
[...]
spec:
  migration_velero: true
  migration_controller: true
  migration_ui: true
 
[...]

See mig-operator docs for more details: https://github.com/konveyor/mig-operator

---

3. Create Mig CRs to describe the Migration that will be performed

Before mig-controller can run a Migration, you'll need to provide it with:

• Coordinates & auth info for 2 OpenShift clusters (source + destination)
• A list of namespaces to be migrated
• Storage to use for the migration

These details are specified by "Mig" CRs. For the source of truth on what will be accepted in CR fields, see the appropriate types.go file.

• MigPlan
• MigCluster
• MigStorage
• MigMigration

---

To make it easier to run your first Migration with mig-controller, we've published a set of annotated sample CRs in config/samples that you can walk through and fill out values on. The first step will be to run make samples, which will copy these to migsamples.

make samples
# [... sample CR content will be copied to 'migsamples' dir, which is .gitignored]

These sample resources describe a migration where the source cluster is running the controller, so a Service Account (SA) token and cluster URL must be provided for the destination cluster only.

---

Inspect and edit each of the files in the 'migsamples' directory, making changes as needed. Much of the content in these sample files can stay unchanged.

As an example, you'll need to provide the following parameters to perform a Migration using an AWS S3 bucket as temporary migration storage:

Parameter	Purpose	Sample CR File
namespaces	List of namespaces to migrate from source to destination cluster	mig-plan.yaml
url	Endpoint of remote cluster mig-controller will connect to	cluster-remote.yaml
saToken	Base64 encoded SA token used to authenticate with remote cluster	sa-secret-remote.yaml
awsBucketName	Name of the S3 bucket to be used for temporary Migration storage	mig-storage.yaml
awsRegion	Region of S3 bucket to be used for temporary Migration storage	mig-storage.yaml
aws-access-key-id	AWS access key to auth with AWS services	mig-storage-creds.yaml
aws-secret-access-key	AWS secret access key to auth with AWS services	mig-storage-creds.yaml

After modifying resource yaml, create the resources on the OpenShift cluster where the controller is running.

# Option 1: Create everything in a single command
oc apply -f migsamples

# ------------------------------------------------

# Option 2: Create resources individually
cd migsamples

# Remote cluster definition, coordinates, auth details
oc apply -f sa-secret-remote.yaml
oc apply -f mig-cluster-remote.yaml

# Describes where to store data during Migration, storage auth details
oc apply -f mig-storage-creds.yaml
oc apply -f mig-storage.yaml

# Describes which clusters, storage, and namespaces should be to run a Migration
oc apply -f mig-plan.yaml

# Declares that a Migration operation should be run 
oc apply -f mig-migration.yaml

---

Getting a migration-controller Service Account (SA) token

For mig-controller to perform migration actions on a remote cluster, you'll need to provide a valid Service Account (SA) token granting 'cluster-admin' access to the remote cluster.

To get the SA token created by mig-operator, run the following on the remote cluster:

# Get the ServiceAccount token in a base64-encoded format to put in the remote MigCluster spec
# If you are providing this token to mig-ui, skip the base64 encoding step
oc sa get-token -n openshift-migration migration-controller | base64 -w 0

Use the base64-encoded SA token from the last command output to fill in migsamples/sa-secret-remote.yaml