Understanding the Control Plane Migration Assistant

The Control Plane Migration Assistant (CPMA) is a CLI-based tool that assists you in migrating the control plane from OKD 3.7 (or later) to OKD Latest. The CPMA processes the OKD 3 configuration files and generates Custom Resource (CR) manifest files, which are consumed by OKD Latest Operators.

Because OKD 3 and 4 have significant configuration differences, not all parameters are processed. The CPMA can generate a report that describes whether features are supported fully, partially, or not at all.

Configuration files

CPMA uses the Kubernetes and OKD APIs to access the following configuration files on an OKD 3 cluster:

  • Master configuration file (default: /etc/origin/master/master-config.yaml)

  • CRI-O configuration file (default: /etc/crio/crio.conf)

  • etcd configuration file (default: /etc/etcd/etcd.conf)

  • Image registries file (default: /etc/containers/registries.conf)

  • Dependent configuration files:

    • Password files (for example, HTPasswd)

    • ConfigMaps

    • Secrets

CR Manifests

CPMA generates CR manifests for the following configurations:

  • API server CA certificate: 100_CPMA-cluster-config-APISecret.yaml

    If you are using an unsigned API server CA certificate, you must add the certificate manually to the target cluster.

  • CRI-O: 100_CPMA-crio-config.yaml

  • Cluster resource quota: 100_CPMA-cluster-quota-resource-x.yaml

  • Project resource quota: 100_CPMA-resource-quota-x.yaml

  • Portable image registry (/etc/registries/registries.conf) and portable image policy (etc/origin/master/master-config.yam): 100_CPMA-cluster-config-image.yaml

  • OAuth providers: 100_CPMA-cluster-config-oauth.yaml

  • Project configuration: 100_CPMA-cluster-config-project.yaml

  • Scheduler: 100_CPMA-cluster-config-scheduler.yaml

  • SDN: 100_CPMA-cluster-config-sdn.yaml

Installing the Control Plane Migration Assistant

You can download the Control Plane Migration Assistant (CPMA) binary file from the Red Hat Customer Portal and install it on Linux, MacOSX, or Windows operating systems.

Procedure
  1. In the Red Hat Customer Portal, navigate to DownloadsRed Hat OKD.

  2. On the Download Red Hat OKD page, select Red Hat OKD from the Product Variant list.

  3. Select CPMA 1.0 for RHEL 7 from the Version list. This binary works on RHEL 7 and RHEL 8.

  4. Click Download Now to download cpma for Linux or MacOSX or cpma.exe for Windows.

  5. Save the file in a directory defined as $PATH for Linux or MacOSX or %PATH% for Windows.

  6. For Linux, make the file executable:

    $ sudo chmod +x cpma

Using the Control Plane Migration Assistant

The Control Plane Migration Assistant (CPMA) generates CR manifests, which are consumed by OKD Latest Operators, and a report that indicates which OKD 3 features are supported fully, partially, or not at all.

The CPMA can run in remote mode, retrieving the configuration files from the source cluster using SSH, or in local mode, using local copies of the source cluster’s configuration files.

Prerequisites
  • The source cluster must be OKD 3.7 or later.

  • The source cluster must be updated to the latest synchronous release.

  • An environment health check must be run on the source cluster to confirm that there are no diagnostic errors or warnings.

  • The CPMA binary must be executable.

  • You must have cluster-admin privileges for the source cluster.

Procedure
  1. Log in to the OKD 3 cluster:

    $ oc login https://<master1.example.com> (1)
    1 OKD 3 master node. You must be logged in to the cluster to receive a token for the Kubernetes and OKD APIs.
  2. Run the CPMA. Each prompt requires you to provide input, as in the following example:

    $ cpma --manifests=false (1)
    ? Do you wish to save configuration for future use? true
    ? What will be the source for OCP3 config files? Remote host (2)
    ? Path to crio config file /etc/crio/crio.conf
    ? Path to etcd config file /etc/etcd/etcd.conf
    ? Path to master config file /etc/origin/master/master-config.yaml
    ? Path to node config file /etc/origin/node/node-config.yaml
    ? Path to registries config file /etc/containers/registries.conf
    ? Do wish to find source cluster using KUBECONFIG or prompt it? KUBECONFIG
    ? Select cluster obtained from KUBECONFIG contexts master1-example-com:443
    ? Select master node master1.example.com
    ? SSH login root (3)
    ? SSH Port 22
    ? Path to private SSH key /home/user/.ssh/openshift_key
    ? Path to application data, skip to use current directory .
    INFO[29 Aug 19 00:07 UTC] Starting manifest and report generation
    INFO[29 Aug 19 00:07 UTC] Transform:Starting for - API
    INFO[29 Aug 19 00:07 UTC] APITransform::Extract
    INFO[29 Aug 19 00:07 UTC] APITransform::Transform:Reports
    INFO[29 Aug 19 00:07 UTC] Transform:Starting for - Cluster
    INFO[29 Aug 19 00:08 UTC] ClusterTransform::Transform:Reports
    INFO[29 Aug 19 00:08 UTC] ClusterReport::ReportQuotas
    INFO[29 Aug 19 00:08 UTC] ClusterReport::ReportPVs
    INFO[29 Aug 19 00:08 UTC] ClusterReport::ReportNamespaces
    INFO[29 Aug 19 00:08 UTC] ClusterReport::ReportNodes
    INFO[29 Aug 19 00:08 UTC] ClusterReport::ReportRBAC
    INFO[29 Aug 19 00:08 UTC] ClusterReport::ReportStorageClasses
    INFO[29 Aug 19 00:08 UTC] Transform:Starting for - Crio
    INFO[29 Aug 19 00:08 UTC] CrioTransform::Extract
    WARN[29 Aug 19 00:08 UTC] Skipping Crio: No configuration file available
    INFO[29 Aug 19 00:08 UTC] Transform:Starting for - Docker
    INFO[29 Aug 19 00:08 UTC] DockerTransform::Extract
    INFO[29 Aug 19 00:08 UTC] DockerTransform::Transform:Reports
    INFO[29 Aug 19 00:08 UTC] Transform:Starting for - ETCD
    INFO[29 Aug 19 00:08 UTC] ETCDTransform::Extract
    INFO[29 Aug 19 00:08 UTC] ETCDTransform::Transform:Reports
    INFO[29 Aug 19 00:08 UTC] Transform:Starting for - OAuth
    INFO[29 Aug 19 00:08 UTC] OAuthTransform::Extract
    INFO[29 Aug 19 00:08 UTC] OAuthTransform::Transform:Reports
    INFO[29 Aug 19 00:08 UTC] Transform:Starting for - SDN
    INFO[29 Aug 19 00:08 UTC] SDNTransform::Extract
    INFO[29 Aug 19 00:08 UTC] SDNTransform::Transform:Reports
    INFO[29 Aug 19 00:08 UTC] Transform:Starting for - Image
    INFO[29 Aug 19 00:08 UTC] ImageTransform::Extract
    INFO[29 Aug 19 00:08 UTC] ImageTransform::Transform:Reports
    INFO[29 Aug 19 00:08 UTC] Transform:Starting for - Project
    INFO[29 Aug 19 00:08 UTC] ProjectTransform::Extract
    INFO[29 Aug 19 00:08 UTC] ProjectTransform::Transform:Reports
    INFO[29 Aug 19 00:08 UTC] Flushing reports to disk
    INFO[29 Aug 19 00:08 UTC] Report:Added: report.json
    INFO[29 Aug 19 00:08 UTC] Report:Added: report.html
    INFO[29 Aug 19 00:08 UTC] Successfully finished transformations
    1 --manifests=false: Without generating CR manifests
    2 Remote host: Remote mode
    3 SSH login: The SSH user must have sudo permissions on the OKD 3 cluster in order to access the configuration files.

    The CPMA creates the following files and directory in the current directory if you did not specify an output directory:

    • cpma.yaml file: Configuration options that you provided when you ran the CPMA

    • master1.example.com/: Configuration files from the master node

    • report.json: JSON-encoded report

    • report.html: HTML-encoded report

  3. Open the report.html file in a browser to view the CPMA report.

  4. If you generate CR manifests, apply the CR manifests to the OKD Latest cluster, as in the following example:

    $ oc apply -f 100_CPMA-cluster-config-secret-htpasswd-secret.yaml