Chapter 9. High availability for hosted control planes

Procedure

1. Log in to an etcd pod by entering the following command:

   $ oc rsh -n clusters-<hosted_cluster_name> -c etcd <etcd_pod_name>

2. Print the health status of an etcd cluster by entering the following command:

   sh-4.4# etcdctl endpoint status -w table

   Example output

   +------------------------------+-----------------+---------+---------+-----------+------------+-----------+------------+--------------------+--------+
   |          ENDPOINT            |       ID        | VERSION | DB SIZE | IS LEADER | IS LEARNER | RAFT TERM | RAFT INDEX | RAFT APPLIED INDEX | ERRORS |
   +------------------------------+-----------------+---------+---------+-----------+------------+-----------+------------+--------------------+--------+
   | https://192.168.1xxx.20:2379 | 8fxxxxxxxxxx    |  3.5.12 |  123 MB |     false |      false |        10 |     180156 |             180156 |        |
   | https://192.168.1xxx.21:2379 | a5xxxxxxxxxx    |  3.5.12 |  122 MB |     false |      false |        10 |     180156 |             180156 |        |
   | https://192.168.1xxx.22:2379 | 7cxxxxxxxxxx    |  3.5.12 |  124 MB |      true |      false |        10 |     180156 |             180156 |        |
   +-----------------------------+------------------+---------+---------+-----------+------------+-----------+------------+--------------------+--------+

Procedure

1. To confirm that the etcd pod is failing, enter the following command:

   $ oc get pods -l app=etcd -n clusters-<hosted_cluster_name>

   Replace <hosted_cluster_name> with the name of the hosted cluster of the etcd instance.

   Example output

   NAME     READY   STATUS             RESTARTS     AGE
   etcd-0   2/2     Running            0            64m
   etcd-1   2/2     Running            0            45m
   etcd-2   1/2     CrashLoopBackOff   1 (5s ago)   64m

   The failing etcd pod might have the CrashLoopBackOff or Error status.

2. Delete the failing pod and its PVC by entering the following command:

   $ oc delete pods <etcd_pod_name> -n clusters-<hosted_cluster_name>

   Replace <etcd_pod_name> with the name of the failing pod.

Procedure

1. Set up your environment variables:

   1. Set up environment variables for your hosted cluster by entering the following commands, replacing values as necessary:

      $ CLUSTER_NAME=my-cluster

      $ HOSTED_CLUSTER_NAMESPACE=clusters

      $ CONTROL_PLANE_NAMESPACE="${HOSTED_CLUSTER_NAMESPACE}-${CLUSTER_NAME}"

   2. Pause reconciliation of the hosted cluster by entering the following command, replacing values as necessary:

      $ oc patch -n ${HOSTED_CLUSTER_NAMESPACE} hostedclusters/${CLUSTER_NAME} \
        -p '{"spec":{"pausedUntil":"true"}}' --type=merge

2. Take a snapshot of etcd by using one of the following methods:

   1. Use a previously backed-up snapshot of etcd.

   2. If you have an available etcd pod, take a snapshot from the active etcd pod by completing the following steps:

      1. List etcd pods by entering the following command:

         $ oc get -n ${CONTROL_PLANE_NAMESPACE} pods -l app=etcd

      2. Take a snapshot of the pod database and save it locally to your machine by entering the following commands:

         $ ETCD_POD=etcd-0

         $ oc exec -n ${CONTROL_PLANE_NAMESPACE} -c etcd -t ${ETCD_POD} -- \
           env ETCDCTL_API=3 /usr/bin/etcdctl \
           --cacert /etc/etcd/tls/etcd-ca/ca.crt \
           --cert /etc/etcd/tls/client/etcd-client.crt \
           --key /etc/etcd/tls/client/etcd-client.key \
           --endpoints=https://localhost:2379 \
           snapshot save /var/lib/snapshot.db

      3. Verify that the snapshot is successful by entering the following command:

         $ oc exec -n ${CONTROL_PLANE_NAMESPACE} -c etcd -t ${ETCD_POD} -- \
           env ETCDCTL_API=3 /usr/bin/etcdctl -w table snapshot status \
           /var/lib/snapshot.db

   3. Make a local copy of the snapshot by entering the following command:

      $ oc cp -c etcd ${CONTROL_PLANE_NAMESPACE}/${ETCD_POD}:/var/lib/snapshot.db \
        /tmp/etcd.snapshot.db

      1. Make a copy of the snapshot database from etcd persistent storage:

         1. List etcd pods by entering the following command:

            $ oc get -n ${CONTROL_PLANE_NAMESPACE} pods -l app=etcd

         2. Find a pod that is running and set its name as the value of ETCD_POD: ETCD_POD=etcd-0, and then copy its snapshot database by entering the following command:

            $ oc cp -c etcd \
              ${CONTROL_PLANE_NAMESPACE}/${ETCD_POD}:/var/lib/data/member/snap/db \
              /tmp/etcd.snapshot.db

3. Scale down the etcd statefulset by entering the following command:

   $ oc scale -n ${CONTROL_PLANE_NAMESPACE} statefulset/etcd --replicas=0

   1. Delete volumes for second and third members by entering the following command:

      $ oc delete -n ${CONTROL_PLANE_NAMESPACE} pvc/data-etcd-1 pvc/data-etcd-2

   2. Create a pod to access the first etcd member’s data:

      1. Get the etcd image by entering the following command:

         $ ETCD_IMAGE=$(oc get -n ${CONTROL_PLANE_NAMESPACE} statefulset/etcd \
           -o jsonpath='{ .spec.template.spec.containers[0].image }')

      2. Create a pod that allows access to etcd data:

         $ cat << EOF | oc apply -n ${CONTROL_PLANE_NAMESPACE} -f -
         apiVersion: apps/v1
         kind: Deployment
         metadata:
           name: etcd-data
         spec:
           replicas: 1
           selector:
             matchLabels:
               app: etcd-data
           template:
             metadata:
               labels:
                 app: etcd-data
             spec:
               containers:
               - name: access
                 image: $ETCD_IMAGE
                 volumeMounts:
                 - name: data
                   mountPath: /var/lib
                 command:
                 - /usr/bin/bash
                 args:
                 - -c
                 - |-
                   while true; do
                     sleep 1000
                   done
               volumes:
               - name: data
                 persistentVolumeClaim:
                   claimName: data-etcd-0
             EOF

      3. Check the status of the etcd-data pod and wait for it to be running by entering the following command:

         $ oc get -n ${CONTROL_PLANE_NAMESPACE} pods -l app=etcd-data

      4. Get the name of the etcd-data pod by entering the following command:

         $ DATA_POD=$(oc get -n ${CONTROL_PLANE_NAMESPACE} pods --no-headers \
           -l app=etcd-data -o name | cut -d/ -f2)

   3. Copy an etcd snapshot into the pod by entering the following command:

      $ oc cp /tmp/etcd.snapshot.db \
        ${CONTROL_PLANE_NAMESPACE}/${DATA_POD}:/var/lib/restored.snap.db

   4. Remove old data from the etcd-data pod by entering the following commands:

      $ oc exec -n ${CONTROL_PLANE_NAMESPACE} ${DATA_POD} -- rm -rf /var/lib/data

      $ oc exec -n ${CONTROL_PLANE_NAMESPACE} ${DATA_POD} -- mkdir -p /var/lib/data

   5. Restore the etcd snapshot by entering the following command:

      $ oc exec -n ${CONTROL_PLANE_NAMESPACE} ${DATA_POD} -- \
           etcdutl snapshot restore /var/lib/restored.snap.db \
           --data-dir=/var/lib/data --skip-hash-check \
           --name etcd-0 \
           --initial-cluster-token=etcd-cluster \
           --initial-cluster etcd-0=https://etcd-0.etcd-discovery.${CONTROL_PLANE_NAMESPACE}.svc:2380,etcd-1=https://etcd-1.etcd-discovery.${CONTROL_PLANE_NAMESPACE}.svc:2380,etcd-2=https://etcd-2.etcd-discovery.${CONTROL_PLANE_NAMESPACE}.svc:2380 \
           --initial-advertise-peer-urls https://etcd-0.etcd-discovery.${CONTROL_PLANE_NAMESPACE}.svc:2380

   6. Remove the temporary etcd snapshot from the pod by entering the following command:

      $ oc exec -n ${CONTROL_PLANE_NAMESPACE} ${DATA_POD} -- \
        rm /var/lib/restored.snap.db

   7. Delete data access deployment by entering the following command:

      $ oc delete -n ${CONTROL_PLANE_NAMESPACE} deployment/etcd-data

   8. Scale up the etcd cluster by entering the following command:

      $ oc scale -n ${CONTROL_PLANE_NAMESPACE} statefulset/etcd --replicas=3

   9. Wait for the etcd member pods to return and report as available by entering the following command:

      $ oc get -n ${CONTROL_PLANE_NAMESPACE} pods -l app=etcd -w

4. Restore reconciliation of the hosted cluster by entering the following command:

   $ oc patch -n ${HOSTED_CLUSTER_NAMESPACE} hostedclusters/${CLUSTER_NAME} \
     -p '{"spec":{"pausedUntil":"null"}}' --type=merge

5. Manually roll out the hosted cluster by entering the following command:

   $ oc annotate hostedcluster -n \
     <hosted_cluster_namespace> <hosted_cluster_name> \
     hypershift.openshift.io/restart-date=$(date --iso-8601=seconds)

   The Multus admission controller and network node identity pods do not start yet.

6. Delete the pods for the second and third members of etcd and their PVCs by entering the following commands:

   $ oc delete -n ${CONTROL_PLANE_NAMESPACE} pvc/data-etcd-1 pod/etcd-1 --wait=false

   $ oc delete -n ${CONTROL_PLANE_NAMESPACE} pvc/data-etcd-2 pod/etcd-2 --wait=false

7. Manually roll out the hosted cluster again by entering the following command:

   $ oc annotate hostedcluster -n \
     <hosted_cluster_namespace> <hosted_cluster_name> \
     hypershift.openshift.io/restart-date=$(date --iso-8601=seconds) \
     --overwrite

   After a few minutes, the control plane pods start running.

8. If your hosted cluster is on AWS and you need to apply OIDC fixes after the restore process, enter the following command:

   $ hcp fix dr-oidc-iam --hc-name <hosted_cluster_name> --hc-namespace <hosted_cluster_namespace> --aws-creds ~/.aws/credentials[4:48 AM]

   This command regenerates the OIDC in S3 in case OIDC is deleted.

Procedure

1. Stop all etcd-writer deployments by entering the following command:

   $ oc scale deployment -n <hosted_cluster_namespace> --replicas=0 \
     kube-apiserver openshift-apiserver openshift-oauth-apiserver

2. To take an etcd snapshot, use the exec command in each etcd container by entering the following command:

   $ oc exec -it <etcd_pod_name> -n <hosted_cluster_namespace> -- \
     env ETCDCTL_API=3 /usr/bin/etcdctl \
     --cacert /etc/etcd/tls/etcd-ca/ca.crt \
     --cert /etc/etcd/tls/client/etcd-client.crt \
     --key /etc/etcd/tls/client/etcd-client.key \
     --endpoints=localhost:2379 \
     snapshot save /var/lib/data/snapshot.db

3. To check the snapshot status, use the exec command in each etcd container by running the following command:

   $ oc exec -it <etcd_pod_name> -n <hosted_cluster_namespace> -- \
     env ETCDCTL_API=3 /usr/bin/etcdctl -w table snapshot status \
     /var/lib/data/snapshot.db

4. Copy the snapshot data to a location where you can retrieve it later, such as an S3 bucket. See the following example.

   Note

   The following example uses signature version 2. If you are in a region that supports signature version 4, such as the us-east-2 region, use signature version 4. Otherwise, when copying the snapshot to an S3 bucket, the upload fails.

   Example

   BUCKET_NAME=somebucket
   CLUSTER_NAME=cluster_name
   FILEPATH="/${BUCKET_NAME}/${CLUSTER_NAME}-snapshot.db"
   CONTENT_TYPE="application/x-compressed-tar"
   DATE_VALUE=`date -R`
   SIGNATURE_STRING="PUT\n\n${CONTENT_TYPE}\n${DATE_VALUE}\n${FILEPATH}"
   ACCESS_KEY=<access_key>
   SECRET_KEY=<secret>
   SIGNATURE_HASH=`echo -en ${SIGNATURE_STRING} | openssl sha1 -hmac ${SECRET_KEY} -binary | base64`
   HOSTED_CLUSTER_NAMESPACE=hosted_cluster_namespace
   
   $ oc exec -it etcd-0 -n ${HOSTED_CLUSTER_NAMESPACE} -- curl -X PUT -T "/var/lib/data/snapshot.db" \
     -H "Host: ${BUCKET_NAME}.s3.amazonaws.com" \
     -H "Date: ${DATE_VALUE}" \
     -H "Content-Type: ${CONTENT_TYPE}" \
     -H "Authorization: AWS ${ACCESS_KEY}:${SIGNATURE_HASH}" \
     https://${BUCKET_NAME}.s3.amazonaws.com/${CLUSTER_NAME}-snapshot.db

5. To restore the snapshot on a new cluster later, save the encryption secret that the hosted cluster references.

   1. Get the secret encryption key by entering the following command:

      $ oc get -n <hosted_cluster_namespace> hostedcluster <hosted_cluster_name> \
        -o=jsonpath='{.spec.secretEncryption.aescbc}'

      Example output

      {"activeKey":{"name":"<hosted_cluster_name>-etcd-encryption-key"}}

   2. Save the secret encryption key by entering the following command:

      $ oc get -n <hosted_cluster_namespace> secret <hosted_cluster_name>-etcd-encryption-key \
        -o=jsonpath='{.data.key}'

      You can decrypt this key when restoring a snapshot on a new cluster.

6. Restart all etcd-writer deployments by entering the following command:

   $ oc scale deployment -n <control_plane_namespace> --replicas=3 \
     kube-apiserver openshift-apiserver openshift-oauth-apiserver

Procedure

1. Delete the hosted cluster that you backed up in "Taking a snapshot of etcd for a hosted cluster" by entering the following command:

   $ hcp destroy cluster <cluster_infra> \
     --name <hosted_cluster_name> \
     --namespace <hosted_cluster_namespace>

2. On the aws command-line interface (CLI), create a pre-signed URL so that you can download your etcd snapshot from S3 without passing credentials to the etcd deployment:

   1. Define the snapshot by entering the following command:

      $ ETCD_SNAPSHOT=${ETCD_SNAPSHOT:-"s3://${BUCKET_NAME}/${CLUSTER_NAME}-snapshot.db"}

   2. Define the snapshot URL by entering the following command:

      $ ETCD_SNAPSHOT_URL=$(aws s3 presign ${ETCD_SNAPSHOT})

3. Create the new hosted cluster by entering the following command:

   $ hcp create cluster <platform> \
     --name <hosted_cluster_name> \
     --namespace <hosted_cluster_namespace> \
     --node-pool-replicas=2 \
     --node-upgrade-type=Replace \
     --pull-secret <path_to_pull_secret> \
     --memory <value_for_memory> \
     --cores <value_for_cpu> \
     --etcd-storage-class=gp3-csi \
     --release-image=<release_image_reference> \
     --etcd-storage-size=8Gi \
     --fips=false \
     --render \
     --render-sensitive

   • <hosted_cluster_name> specifies the name of the new hosted cluster. The name of the new cluster must be identical to the name of the cluster from which the etcd backup was taken.
   • <platform> specifies the platform you are creating the hosted cluster on, such as kubevirt or aws.
   • <hosted_cluster_namespace> specifies the namespace where you are creating the hosted cluster.
   • <path_to_pull_secret> specifies the path to your pull secret; for example, /user/name/pullsecret.
   • <value_for_memory> specifies the memory value, such as 8Gi.
   • <value_for_cpu> specifies the CPU value, such as 2.

   • <release_image_reference> specifies the OpenShift Container Platform release image for the cluster, for example, quay.io/openshift-release-dev/ocp-release:4.20.14-multi. You can use the --release-image flag to set up the hosted cluster with a specific OpenShift Container Platform release.

     Example output

     apiVersion: v1
     kind: Namespace
     metadata:
       name: <hosted_cluster_namespace>
     spec: {}
     status: {}
     ---
     apiVersion: v1
     data:
       .dockerconfigjson: <path_to_pull_secret>
     kind: Secret
     metadata:
       labels:
         hypershift.openshift.io/safe-to-delete-with-cluster: "true"
       name: <hosted_cluster_name_pull_secret>
       namespace: <hosted_cluster_namespace>
     ---
     apiVersion: hypershift.openshift.io/v1beta1
     kind: HostedCluster
     metadata:
       name: <hosted_cluster_name>
       namespace: <hosted_cluster_namespace>
     spec:
       autoscaling: {}
       capabilities: {}
       configuration: {}
       controllerAvailabilityPolicy: HighlyAvailable
       dns:
         baseDomain: ""
       etcd:
         managed:
           storage:
             persistentVolume:
               size: 8Gi
               storageClassName: gp3-csi
             type: PersistentVolume
         managementType: Managed
       fips: false
       infraID: <hosted_cluster_name>-68tlg
       infrastructureAvailabilityPolicy: HighlyAvailable
       networking:
         clusterNetwork:
         - cidr: 10.132.0.0/14
         networkType: OVNKubernetes
         serviceNetwork:
         - cidr: 172.31.0.0/16
       olmCatalogPlacement: guest
       platform:
         kubevirt:
           baseDomainPassthrough: true
         type: KubeVirt
       pullSecret:
         name: <hosted_cluster_name_pull_secret>
       release:
         image: quay.io/openshift-release-dev/ocp-release:4.21.12-multi
       services:
       - service: APIServer
         servicePublishingStrategy:
           type: LoadBalancer
       - service: Ignition
         servicePublishingStrategy:
           type: Route
       - service: Konnectivity
         servicePublishingStrategy:
           type: Route
       - service: OAuthServer
         servicePublishingStrategy:
           type: Route
       sshKey: {}
     status:
       controlPlaneEndpoint:
         host: ""
         port: 0
     ---
     apiVersion: hypershift.openshift.io/v1beta1
     kind: NodePool
     metadata:
       name: <hosted_cluster_name>
       namespace: <hosted_cluster_namespace>
     spec:
       arch: amd64
       clusterName: <hosted_cluster_name>
       management:
         autoRepair: false
         upgradeType: Replace
       nodeDrainTimeout: 0s
       nodeVolumeDetachTimeout: 0s
       platform:
         kubevirt:
           attachDefaultNetwork: true
           compute:
             cores: 2
             memory: 8Gi
           networkInterfaceMultiqueue: Enable
           rootVolume:
             persistent:
               size: 32Gi
             type: Persistent
         type: KubeVirt
       release:
         image: quay.io/openshift-release-dev/ocp-release:<4.x.x>-multi
       replicas: 2
     status:
       replicas: 0

   • <hosted_cluster_namespace> specifies the name of the hosted cluster namespace.
   • <path_to_pull_secret> specifies the path to the pull secret.
   • <hosted_cluster_name_pull_secret> specifies the name of the restored pull secret for the new hosted cluster.
   • <hosted_cluster_name> specifies the name of the new hosted cluster. The name of the new cluster must be identical to the name of the cluster from which the etcd backup was taken.
   • <4.x.x> specifies the version of the release image.

4. Change the HostedCluster specification to refer to the URL:

   spec:
     etcd:
       managed:
         storage:
           persistentVolume:
             size: 8Gi
           type: PersistentVolume
           restoreSnapshotURL:
           - "${ETCD_SNAPSHOT_URL}"
       managementType: Managed

5. Change the HostedCluster specification to include the new etcd encryption key:

   apiVersion: v1
   data:
     key: <pre_generated_etcd_encryption_key>
   kind: Secret
   metadata:
     labels:
       hypershift.openshift.io/safe-to-delete-with-cluster: "true"
     name: <new_hc_etcd_encryption_key>
     namespace: <hosted_cluster_namespace>
   type: Opaque
   ---
   spec:
     secretEncryption:
       aescbc:
         activeKey:
           name: <new_hc_etcd_encryption_key>
       type: aescbc

   • <pre_generated_etcd_encryption_key> specifies the etcd encryption key of original hosted cluster.
   • <new_hc_etcd_encryption_key> specifies the etcd encryption key of the new hosted cluster. Ensure that the secret that you referenced from the spec.secretEncryption.aescbc value has the same Advanced Encryption Standard (AES) key that you saved earlier.

Procedure

1. Create a Velero backup resource by creating a YAML file that is similar to the following example:

   apiVersion: velero.io/v1
   kind: Backup
   metadata:
     name: hc-clusters-hosted-backup
     namespace: openshift-adp
     labels:
       velero.io/storage-location: default
   spec:
     includedNamespaces:
     - clusters
     - clusters-hosted
     includedResources:
     - sa
     - role
     - rolebinding
     - deployment
     - statefulset
     - pv
     - pvc
     - bmh
     - configmap
     - infraenv
     - priorityclasses
     - pdb
     - hostedcluster
     - nodepool
     - secrets
     - hostedcontrolplane
     - cluster
     - datavolume
     - service
     - route
     excludedResources: [ ]
     labelSelector:
       matchExpressions:
       - key: 'hypershift.openshift.io/is-kubevirt-rhcos'
         operator: 'DoesNotExist'
     storageLocation: default
     preserveNodePorts: true
     ttl: 4h0m0s
     snapshotMoveData: true
     datamover: "velero"
     defaultVolumesToFsBackup: false

   where:

   includedNamespaces

   Specifies the namespaces from the objects to back up. Include namespaces from both the hosted cluster and the hosted control plane. In this example, clusters is a namespace from the hosted cluster and clusters-hosted is a namespace from the hosted control plane.

   Important

   If you store all hosted cluster information in a shared namespace and then back up and restore a hosted cluster, you might unintentionally change other hosted clusters. To avoid this issue, do not store all hosted cluster information in a shared namespace. Alternatively, you can back up and restore resources based on labels.

   labelSelector

   Specifies the boot image of the VMs that are used as the hosted cluster nodes are stored in large PVCs. To reduce backup time and storage size, you can filter those PVCs out of the backup by adding this label selector.

   snapshotMoveData

   Along with the datamover field, specifies that the CSI VolumeSnapshots are automatically uploaded to remote cloud storage.

   datamover

   Along with the snapshotMoveData field, specifies that the CSI VolumeSnapshots are automatically uploaded to remote cloud storage.

   defaultVolumesToFsBackup

   Specifies whether pod volume file system backup is used for all volumes by default. Set this value to false to back up the PVCs that you want.

2. Apply the changes to the YAML file by entering the following command:

   $ oc apply -f <backup_file_name>.yaml

   Replace <backup_file_name> with the name of your file.

3. Monitor the backup process in the backup object status and in the Velero logs.

   • To monitor the backup object status, enter the following command:

     $ watch "oc get backups.velero.io -n openshift-adp <backup_file_name> -o jsonpath='{.status}' | jq"

   • To monitor the Velero logs, enter the following command:

     $ oc logs -n openshift-adp -ldeploy=velero -f

Procedure

1. Ensure that no pods or persistent volume claims (PVCs) are running in the HostedControlPlane namespace.

2. Delete the following objects from the management cluster:

   • HostedCluster
   • NodePool
   • PVCs

3. Create a restoration manifest YAML file that is similar to the following example:

   apiVersion: velero.io/v1
   kind: Restore
   metadata:
     name: hc-clusters-hosted-restore
     namespace: openshift-adp
   spec:
     backupName: hc-clusters-hosted-backup
     restorePVs: true
     existingResourcePolicy: update
     excludedResources:
     - nodes
     - events
     - events.events.k8s.io
     - backups.velero.io
     - restores.velero.io
     - resticrepositories.velero.io

   • spec.restorePVs starts the recovery of pods with the included persistent volumes.
   • spec.existingResourcePolicy: update ensures that any existing objects are overwritten with backup content. This action can cause issues with objects that contain immutable fields, which is why you deleted the HostedCluster, node pools, and PVCs. If you do not set this policy, the Velero engine skips the restoration of objects that already exist.

4. Apply the changes to the YAML file by entering the following command:

   $ oc apply -f <restore_resource_file_name>.yaml

   Replace <restore_resource_file_name> with the name of your file.

5. Monitor the restore process by checking the restore status field and the Velero logs.

   • To check the restore status field, enter the following command:

     $ watch "oc get restores.velero.io -n openshift-adp <backup_file_name> -o jsonpath='{.status}' | jq"

   • To check the Velero logs, enter the following command:

     $ oc logs -n openshift-adp -ldeploy=velero -f

1. On management cluster 1, which you can think of as the source management cluster, the control plane and workers interact by using the external DNS API. The external DNS API is accessible, and a load balancer sits between the management clusters.

   

2. You take a snapshot of the hosted cluster, which includes etcd, the control plane, and the worker nodes. During this process, the worker nodes continue to try to access the external DNS API even if it is not accessible, the workloads are running, the control plane is saved in a local manifest file, and etcd is backed up to an S3 bucket. The data plane is active and the control plane is paused.

   

3. On management cluster 2, which you can think of as the destination management cluster, you restore etcd from the S3 bucket and restore the control plane from the local manifest file. During this process, the external DNS API is stopped, the hosted cluster API becomes inaccessible, and any workers that use the API are unable to update their manifest files, but the workloads are still running.

   

4. The external DNS API is accessible again, and the worker nodes use it to move to management cluster 2. The external DNS API can access the load balancer that points to the control plane.

   

5. On management cluster 2, the control plane and worker nodes interact by using the external DNS API. The resources are deleted from management cluster 1, except for the S3 backup of etcd. If you try to set up the hosted cluster again on management cluster 1, it will not work.

   

Procedure

1. Create a config map file to declare the source management cluster by entering the following command:

   $ oc create configmap mgmt-parent-cluster -n default \
     --from-literal=from=${MGMT_CLUSTER_NAME}

2. Shut down the reconciliation in the hosted cluster and in the node pools by entering the following commands:

   $ PAUSED_UNTIL="true"

   $ oc patch -n ${HC_CLUSTER_NS} hostedclusters/${HC_CLUSTER_NAME} \
     -p '{"spec":{"pausedUntil":"'${PAUSED_UNTIL}'"}}' --type=merge

   $ oc patch -n ${HC_CLUSTER_NS} nodepools/${NODEPOOLS} \
     -p '{"spec":{"pausedUntil":"'${PAUSED_UNTIL}'"}}' --type=merge

   $ oc scale deployment -n ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME} --replicas=0 \
     kube-apiserver openshift-apiserver openshift-oauth-apiserver control-plane-operator

3. Back up etcd and upload the data to an S3 bucket by running the following bash script:

   Tip

   Wrap this script in a function and call it from the main function.

   # ETCD Backup
   ETCD_PODS="etcd-0"
   if [ "${CONTROL_PLANE_AVAILABILITY_POLICY}" = "HighlyAvailable" ]; then
     ETCD_PODS="etcd-0 etcd-1 etcd-2"
   fi
   
   for POD in ${ETCD_PODS}; do
     # Create an etcd snapshot
     oc exec -it ${POD} -n ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME} -- env ETCDCTL_API=3 /usr/bin/etcdctl --cacert /etc/etcd/tls/client/etcd-client-ca.crt --cert /etc/etcd/tls/client/etcd-client.crt --key /etc/etcd/tls/client/etcd-client.key --endpoints=localhost:2379 snapshot save /var/lib/data/snapshot.db
     oc exec -it ${POD} -n ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME} -- env ETCDCTL_API=3 /usr/bin/etcdctl -w table snapshot status /var/lib/data/snapshot.db
   
     FILEPATH="/${BUCKET_NAME}/${HC_CLUSTER_NAME}-${POD}-snapshot.db"
     CONTENT_TYPE="application/x-compressed-tar"
     DATE_VALUE=`date -R`
     SIGNATURE_STRING="PUT\n\n${CONTENT_TYPE}\n${DATE_VALUE}\n${FILEPATH}"
   
     set +x
     ACCESS_KEY=$(grep aws_access_key_id ${AWS_CREDS} | head -n1 | cut -d= -f2 | sed "s/ //g")
     SECRET_KEY=$(grep aws_secret_access_key ${AWS_CREDS} | head -n1 | cut -d= -f2 | sed "s/ //g")
     SIGNATURE_HASH=$(echo -en ${SIGNATURE_STRING} | openssl sha1 -hmac "${SECRET_KEY}" -binary | base64)
     set -x
   
     # FIXME: this is pushing to the OIDC bucket
     oc exec -it etcd-0 -n ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME} -- curl -X PUT -T "/var/lib/data/snapshot.db" \
       -H "Host: ${BUCKET_NAME}.s3.amazonaws.com" \
       -H "Date: ${DATE_VALUE}" \
       -H "Content-Type: ${CONTENT_TYPE}" \
       -H "Authorization: AWS ${ACCESS_KEY}:${SIGNATURE_HASH}" \
       https://${BUCKET_NAME}.s3.amazonaws.com/${HC_CLUSTER_NAME}-${POD}-snapshot.db
   done

   For more information about backing up etcd, see "Backing up and restoring etcd on a hosted cluster".

4. Back up Kubernetes and OpenShift Container Platform objects by entering the following commands. You need to back up the following objects:

   • HostedCluster and NodePool objects from the HostedCluster namespace
   • HostedCluster secrets from the HostedCluster namespace
   • HostedControlPlane from the Hosted Control Plane namespace
   • Cluster from the Hosted Control Plane namespace
   • AWSCluster, AWSMachineTemplate, and AWSMachine from the Hosted Control Plane namespace
   • MachineDeployments, MachineSets, and Machines from the Hosted Control Plane namespace

   • ControlPlane secrets from the Hosted Control Plane namespace

     1. Enter the following commands:

        $ mkdir -p ${BACKUP_DIR}/namespaces/${HC_CLUSTER_NS} \
          ${BACKUP_DIR}/namespaces/${HC_CLUSTER_NS}-${HC_CLUSTER_NAME}

        $ chmod 700 ${BACKUP_DIR}/namespaces/

     2. Back up the HostedCluster objects from the HostedCluster namespace by entering the following commands:

        $ echo "Backing Up HostedCluster Objects:"

        $ oc get hc ${HC_CLUSTER_NAME} -n ${HC_CLUSTER_NS} -o yaml > \
          ${BACKUP_DIR}/namespaces/${HC_CLUSTER_NS}/hc-${HC_CLUSTER_NAME}.yaml

        $ echo "--> HostedCluster"

        $ sed -i '' -e '/^status:$/,$d' \
          ${BACKUP_DIR}/namespaces/${HC_CLUSTER_NS}/hc-${HC_CLUSTER_NAME}.yaml

     3. Back up the NodePool objects from the HostedCluster namespace by entering the following commands:

        $ oc get np ${NODEPOOLS} -n ${HC_CLUSTER_NS} -o yaml > \
          ${BACKUP_DIR}/namespaces/${HC_CLUSTER_NS}/np-${NODEPOOLS}.yaml

        $ echo "--> NodePool"

        $ sed -i '' -e '/^status:$/,$ d' \
          ${BACKUP_DIR}/namespaces/${HC_CLUSTER_NS}/np-${NODEPOOLS}.yaml

     4. Back up the secrets in the HostedCluster namespace by running the following shell script:

        $ echo "--> HostedCluster Secrets:"
        for s in $(oc get secret -n ${HC_CLUSTER_NS} | grep "^${HC_CLUSTER_NAME}" | awk '{print $1}'); do
            oc get secret -n ${HC_CLUSTER_NS} $s -o yaml > ${BACKUP_DIR}/namespaces/${HC_CLUSTER_NS}/secret-${s}.yaml
        done

     5. Back up the secrets in the HostedCluster control plane namespace by running the following shell script:

        $ echo "--> HostedCluster ControlPlane Secrets:"
        for s in $(oc get secret -n ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME} | egrep -v "docker|service-account-token|oauth-openshift|NAME|token-${HC_CLUSTER_NAME}" | awk '{print $1}'); do
            oc get secret -n ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME} $s -o yaml > ${BACKUP_DIR}/namespaces/${HC_CLUSTER_NS}-${HC_CLUSTER_NAME}/secret-${s}.yaml
        done

     6. Back up the hosted control plane by entering the following commands:

        $ echo "--> HostedControlPlane:"

        $ oc get hcp ${HC_CLUSTER_NAME} -n ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME} -o yaml > \
          ${BACKUP_DIR}/namespaces/${HC_CLUSTER_NS}-${HC_CLUSTER_NAME}/hcp-${HC_CLUSTER_NAME}.yaml

     7. Back up the cluster by entering the following commands:

        $ echo "--> Cluster:"

        $ CL_NAME=$(oc get hcp ${HC_CLUSTER_NAME} -n ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME} \
          -o jsonpath={.metadata.labels.\*} | grep ${HC_CLUSTER_NAME})

        $ oc get cluster ${CL_NAME} -n ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME} -o yaml > \
          ${BACKUP_DIR}/namespaces/${HC_CLUSTER_NS}-${HC_CLUSTER_NAME}/cl-${HC_CLUSTER_NAME}.yaml

     8. Back up the AWS cluster by entering the following commands:

        $ echo "--> AWS Cluster:"

        $ oc get awscluster ${HC_CLUSTER_NAME} -n ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME} -o yaml > \
          ${BACKUP_DIR}/namespaces/${HC_CLUSTER_NS}-${HC_CLUSTER_NAME}/awscl-${HC_CLUSTER_NAME}.yaml

     9. Back up the AWS MachineTemplate objects by entering the following commands:

        $ echo "--> AWS Machine Template:"

        $ oc get awsmachinetemplate ${NODEPOOLS} -n ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME} -o yaml > \
          ${BACKUP_DIR}/namespaces/${HC_CLUSTER_NS}-${HC_CLUSTER_NAME}/awsmt-${HC_CLUSTER_NAME}.yaml

     10. Back up the AWS Machines objects by running the following shell script:

         $ echo "--> AWS Machine:"

         $ CL_NAME=$(oc get hcp ${HC_CLUSTER_NAME} -n ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME} -o jsonpath={.metadata.labels.\*} | grep ${HC_CLUSTER_NAME})
         for s in $(oc get awsmachines -n ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME} --no-headers | grep ${CL_NAME} | cut -f1 -d\ ); do
             oc get -n ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME} awsmachines $s -o yaml > ${BACKUP_DIR}/namespaces/${HC_CLUSTER_NS}-${HC_CLUSTER_NAME}/awsm-${s}.yaml
         done

     11. Back up the MachineDeployments objects by running the following shell script:

         $ echo "--> HostedCluster MachineDeployments:"
         for s in $(oc get machinedeployment -n ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME} -o name); do
             mdp_name=$(echo ${s} | cut -f 2 -d /)
             oc get -n ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME} $s -o yaml > ${BACKUP_DIR}/namespaces/${HC_CLUSTER_NS}-${HC_CLUSTER_NAME}/machinedeployment-${mdp_name}.yaml
         done

     12. Back up the MachineSets objects by running the following shell script:

         $ echo "--> HostedCluster MachineSets:"
         for s in $(oc get machineset -n ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME} -o name); do
             ms_name=$(echo ${s} | cut -f 2 -d /)
             oc get -n ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME} $s -o yaml > ${BACKUP_DIR}/namespaces/${HC_CLUSTER_NS}-${HC_CLUSTER_NAME}/machineset-${ms_name}.yaml
         done

     13. Back up the Machines objects from the Hosted Control Plane namespace by running the following shell script:

         $ echo "--> HostedCluster Machine:"
         for s in $(oc get machine -n ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME} -o name); do
             m_name=$(echo ${s} | cut -f 2 -d /)
             oc get -n ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME} $s -o yaml > ${BACKUP_DIR}/namespaces/${HC_CLUSTER_NS}-${HC_CLUSTER_NAME}/machine-${m_name}.yaml
         done

5. Clean up the ControlPlane routes by entering the following command:

   $ oc delete routes -n ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME} --all

   By entering that command, you enable the ExternalDNS Operator to delete the Route53 entries.

6. Verify that the Route53 entries are clean by running the following script:

   function clean_routes() {
   
       if [[ -z "${1}" ]];then
           echo "Give me the NS where to clean the routes"
           exit 1
       fi
   
       # Constants
       if [[ -z "${2}" ]];then
           echo "Give me the Route53 zone ID"
           exit 1
       fi
   
       ZONE_ID=${2}
       ROUTES=10
       timeout=40
       count=0
   
       # This allows us to remove the ownership in the AWS for the API route
       oc delete route -n ${1} --all
   
       while [ ${ROUTES} -gt 2 ]
       do
           echo "Waiting for ExternalDNS Operator to clean the DNS Records in AWS Route53 where the zone id is: ${ZONE_ID}..."
           echo "Try: (${count}/${timeout})"
           sleep 10
           if [[ $count -eq timeout ]];then
               echo "Timeout waiting for cleaning the Route53 DNS records"
               exit 1
           fi
           count=$((count+1))
           ROUTES=$(aws route53 list-resource-record-sets --hosted-zone-id ${ZONE_ID} --max-items 10000 --output json | grep -c ${EXTERNAL_DNS_DOMAIN})
       done
   }
   
   # SAMPLE: clean_routes "<HC ControlPlane Namespace>" "<AWS_ZONE_ID>"
   clean_routes "${HC_CLUSTER_NS}-${HC_CLUSTER_NAME}" "${AWS_ZONE_ID}"

Procedure

1. Verify that the new management cluster does not contain any namespaces from the cluster that you are restoring by entering these commands:

   $ export KUBECONFIG=${MGMT2_KUBECONFIG}

   $ BACKUP_DIR=${HC_CLUSTER_DIR}/backup

   Namespace deletion in the destination Management cluster

   $ oc delete ns ${HC_CLUSTER_NS} || true

   $ oc delete ns ${HC_CLUSTER_NS}-{HC_CLUSTER_NAME} || true

2. Re-create the deleted namespaces by entering these commands:

   Namespace creation commands

   $ oc new-project ${HC_CLUSTER_NS}

   $ oc new-project ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME}

3. Restore the secrets in the HC namespace by entering this command:

   $ oc apply -f ${BACKUP_DIR}/namespaces/${HC_CLUSTER_NS}/secret-*

4. Restore the objects in the HostedCluster control plane namespace by entering these commands:

   Restore secret command

   $ oc apply -f ${BACKUP_DIR}/namespaces/${HC_CLUSTER_NS}-${HC_CLUSTER_NAME}/secret-*

   Cluster restore commands

   $ oc apply -f ${BACKUP_DIR}/namespaces/${HC_CLUSTER_NS}-${HC_CLUSTER_NAME}/hcp-*

   $ oc apply -f ${BACKUP_DIR}/namespaces/${HC_CLUSTER_NS}-${HC_CLUSTER_NAME}/cl-*

5. If you are recovering the nodes and the node pool to reuse AWS instances, restore the objects in the HC control plane namespace by entering these commands:

   Commands for AWS

   $ oc apply -f ${BACKUP_DIR}/namespaces/${HC_CLUSTER_NS}-${HC_CLUSTER_NAME}/awscl-*

   $ oc apply -f ${BACKUP_DIR}/namespaces/${HC_CLUSTER_NS}-${HC_CLUSTER_NAME}/awsmt-*

   $ oc apply -f ${BACKUP_DIR}/namespaces/${HC_CLUSTER_NS}-${HC_CLUSTER_NAME}/awsm-*

   Commands for machines

   $ oc apply -f ${BACKUP_DIR}/namespaces/${HC_CLUSTER_NS}-${HC_CLUSTER_NAME}/machinedeployment-*

   $ oc apply -f ${BACKUP_DIR}/namespaces/${HC_CLUSTER_NS}-${HC_CLUSTER_NAME}/machineset-*

   $ oc apply -f ${BACKUP_DIR}/namespaces/${HC_CLUSTER_NS}-${HC_CLUSTER_NAME}/machine-*

6. Restore the etcd data and the hosted cluster by running this bash script:

   ETCD_PODS="etcd-0"
   if [ "${CONTROL_PLANE_AVAILABILITY_POLICY}" = "HighlyAvailable" ]; then
     ETCD_PODS="etcd-0 etcd-1 etcd-2"
   fi
   
   HC_RESTORE_FILE=${BACKUP_DIR}/namespaces/${HC_CLUSTER_NS}/hc-${HC_CLUSTER_NAME}-restore.yaml
   HC_BACKUP_FILE=${BACKUP_DIR}/namespaces/${HC_CLUSTER_NS}/hc-${HC_CLUSTER_NAME}.yaml
   HC_NEW_FILE=${BACKUP_DIR}/namespaces/${HC_CLUSTER_NS}/hc-${HC_CLUSTER_NAME}-new.yaml
   cat ${HC_BACKUP_FILE} > ${HC_NEW_FILE}
   cat > ${HC_RESTORE_FILE} <<EOF
       restoreSnapshotURL:
   EOF
   
   for POD in ${ETCD_PODS}; do
     # Create a pre-signed URL for the etcd snapshot
     ETCD_SNAPSHOT="s3://${BUCKET_NAME}/${HC_CLUSTER_NAME}-${POD}-snapshot.db"
     ETCD_SNAPSHOT_URL=$(AWS_DEFAULT_REGION=${MGMT2_REGION} aws s3 presign ${ETCD_SNAPSHOT})
   
     # FIXME no CLI support for restoreSnapshotURL yet
     cat >> ${HC_RESTORE_FILE} <<EOF
       - "${ETCD_SNAPSHOT_URL}"
   EOF
   done
   
   cat ${HC_RESTORE_FILE}
   
   if ! grep ${HC_CLUSTER_NAME}-snapshot.db ${HC_NEW_FILE}; then
     sed -i '' -e "/type: PersistentVolume/r ${HC_RESTORE_FILE}" ${HC_NEW_FILE}
     sed -i '' -e '/pausedUntil:/d' ${HC_NEW_FILE}
   fi
   
   HC=$(oc get hc -n ${HC_CLUSTER_NS} ${HC_CLUSTER_NAME} -o name || true)
   if [[ ${HC} == "" ]];then
       echo "Deploying HC Cluster: ${HC_CLUSTER_NAME} in ${HC_CLUSTER_NS} namespace"
       oc apply -f ${HC_NEW_FILE}
   else
       echo "HC Cluster ${HC_CLUSTER_NAME} already exists, avoiding step"
   fi

7. If you are recovering the nodes and the node pool to reuse AWS instances, restore the node pool by entering this command:

   $ oc apply -f ${BACKUP_DIR}/namespaces/${HC_CLUSTER_NS}/np-*

Procedure

1. Scale the deployment and statefulset objects by entering these commands:

   Important

   Do not scale the stateful set if the value of its spec.persistentVolumeClaimRetentionPolicy.whenScaled field is set to Delete, because this could lead to a loss of data.

   As a workaround, update the value of the spec.persistentVolumeClaimRetentionPolicy.whenScaled field to Retain. Ensure that no controllers exist that reconcile the stateful set and would return the value back to Delete, which could lead to a loss of data.

   $ export KUBECONFIG=${MGMT_KUBECONFIG}

   Scale down deployment commands

   $ oc scale deployment -n ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME} --replicas=0 --all

   $ oc scale statefulset.apps -n ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME} --replicas=0 --all

   $ sleep 15

2. Delete the NodePool objects by entering these commands:

   NODEPOOLS=$(oc get nodepools -n ${HC_CLUSTER_NS} -o=jsonpath='{.items[?(@.spec.clusterName=="'${HC_CLUSTER_NAME}'")].metadata.name}')
   if [[ ! -z "${NODEPOOLS}" ]];then
       oc patch -n "${HC_CLUSTER_NS}" nodepool ${NODEPOOLS} --type=json --patch='[ { "op":"remove", "path": "/metadata/finalizers" }]'
       oc delete np -n ${HC_CLUSTER_NS} ${NODEPOOLS}
   fi

3. Delete the machine and machineset objects by entering these commands:

   # Machines
   for m in $(oc get machines -n ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME} -o name); do
       oc patch -n ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME} ${m} --type=json --patch='[ { "op":"remove", "path": "/metadata/finalizers" }]' || true
       oc delete -n ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME} ${m} || true
   done

   $ oc delete machineset -n ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME} --all || true

4. Delete the cluster object by entering these commands:

   $ C_NAME=$(oc get cluster -n ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME} -o name)

   $ oc patch -n ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME} ${C_NAME} --type=json --patch='[ { "op":"remove", "path": "/metadata/finalizers" }]'

   $ oc delete cluster.cluster.x-k8s.io -n ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME} --all

5. Delete the AWS machines (Kubernetes objects) by entering these commands. Do not worry about deleting the real AWS machines. The cloud instances will not be affected.

   for m in $(oc get awsmachine.infrastructure.cluster.x-k8s.io -n ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME} -o name)
   do
       oc patch -n ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME} ${m} --type=json --patch='[ { "op":"remove", "path": "/metadata/finalizers" }]' || true
       oc delete -n ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME} ${m} || true
   done

6. Delete the HostedControlPlane and ControlPlane HC namespace objects by entering these commands:

   Delete HostedControlPlane and ControlPlane HC NS commands

   $ oc patch -n ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME} hostedcontrolplane.hypershift.openshift.io ${HC_CLUSTER_NAME} --type=json --patch='[ { "op":"remove", "path": "/metadata/finalizers" }]'

   $ oc delete hostedcontrolplane.hypershift.openshift.io -n ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME} --all

   $ oc delete ns ${HC_CLUSTER_NS}-${HC_CLUSTER_NAME} || true

7. Delete the HostedCluster and HC namespace objects by entering these commands:

   Delete HC and HC Namespace commands

   $ oc -n ${HC_CLUSTER_NS} patch hostedclusters ${HC_CLUSTER_NAME} -p '{"metadata":{"finalizers":null}}' --type merge || true

   $ oc delete hc -n ${HC_CLUSTER_NS} ${HC_CLUSTER_NAME}  || true

   $ oc delete ns ${HC_CLUSTER_NS} || true

1. Load the KUBECONFIG environment variable with the hosted cluster’s kubeconfig path.

2. Enter this command:

   $ oc delete pod -n openshift-ovn-kubernetes --all

Procedure

1. Observe the backup process by running the following command:

   $ watch "oc get backups.velero.io -n openshift-adp <backup_resource_name> -o jsonpath='{.status}'"

2. Observe the restore process by running the following command:

   $ watch "oc get restores.velero.io -n openshift-adp <backup_resource_name> -o jsonpath='{.status}'"

3. Observe the Velero logs by running the following command:

   $ oc logs -n openshift-adp -ldeploy=velero -f

4. Observe the progress of all of the OADP objects by running the following command:

   $ watch "echo BackupRepositories:;echo;oc get backuprepositories.velero.io -A;echo; echo BackupStorageLocations: ;echo; oc get backupstoragelocations.velero.io -A;echo;echo DataUploads: ;echo;oc get datauploads.velero.io -A;echo;echo DataDownloads: ;echo;oc get datadownloads.velero.io -n openshift-adp; echo;echo VolumeSnapshotLocations: ;echo;oc get volumesnapshotlocations.velero.io -A;echo;echo Backups:;echo;oc get backup -A; echo;echo Restores:;echo;oc get restore -A"

Procedure

1. Create an alias to use the velero CLI from a container by running the following command:

   $ alias velero='oc -n openshift-adp exec deployment/velero -c velero -it -- ./velero'

2. Get details of your Restore custom resource (CR) by running the following command:

   $ velero restore describe <restore_resource_name> --details

   Replace <restore_resource_name> with the name of your Restore resource.

3. Get details of your Backup CR by running the following command:

   $ velero restore describe <backup_resource_name> --details

   Replace <backup_resource_name> with the name of your Backup resource.

Procedure

1. Create a YAML file that defines the Backup CR:

   apiVersion: velero.io/v1
   kind: Backup
   metadata:
     name: <backup_resource_name>
     namespace: openshift-adp
     labels:
       velero.io/storage-location: default
   spec:
     hooks: {}
     includedNamespaces:
     - <hosted_cluster_namespace>
     - <hosted_control_plane_namespace>
     includedResources:
     - sa
     - role
     - rolebinding
     - pod
     - pvc
     - pv
     - bmh
     - configmap
     - infraenv
     - priorityclasses
     - pdb
     - agents
     - hostedcluster
     - nodepool
     - secrets
     - services
     - deployments
     - hostedcontrolplane
     - cluster
     - agentcluster
     - agentmachinetemplate
     - agentmachine
     - machinedeployment
     - machineset
     - machine
     - route
     - clusterdeployment
     excludedResources: []
     storageLocation: default
     ttl: 2h0m0s
     snapshotMoveData: true
     datamover: "velero"
     defaultVolumesToFsBackup: false

   • metadata.name specifies the name for your Backup resource.
   • spec.includedNamespaces specifies namespaces to back up objects from. You must replace <hosted_cluster_namespace> with the name of the hosted cluster namespace and replace <hosted_control_plane_namespace> with the name of the hosted control plane namespace.
   • spec.includedResources includes the infraenv value. You must create the infraenv resource in a separate namespace. Do not delete the infraenv resource during the backup process.
   • spec.snapshotMoveData: true and spec.datamover: velero enable the CSI volume snapshots and upload the control plane workload automatically to cloud storage.

   • spec.defaultVolumesToFsBackup specifies that the fs-backup backing up method for persistent volumes (PVs) is not used.

     Note

     If you want to use CSI volume snapshots, you must add the backup.velero.io/backup-volumes-excludes=<pv_name> annotation to your PVs.

2. Apply the Backup CR by running the following command:

   $ oc apply -f backup-control-plane.yaml

Procedure

1. Verify that no pods and persistent volume claims (PVCs) are present in the hosted control plane namespace by running the following command:

   $ oc get pod pvc -n <hosted_control_plane_namespace>

   Expected output

   No resources found

2. Create a YAML file that defines the Restore CR:

   apiVersion: velero.io/v1
   kind: Restore
   metadata:
     name: <restore_resource_name>
     namespace: openshift-adp
   spec:
     backupName: <backup_resource_name>
     restorePVs: true
     existingResourcePolicy: update
     excludedResources:
     - nodes
     - events
     - events.events.k8s.io
     - backups.velero.io
     - restores.velero.io
     - resticrepositories.velero.io

   • metadata.name specifies the name for your Restore resource.
   • spec.backupName specifies the name of your Backup resource.
   • spec.restorePVs: true indicates the recovery of persistent volumes (PVs) and their pods.

   • spec.existingResourcePolicy: update ensures that the existing objects are overwritten with the backed up content.

     Important

     You must create the InfraEnv resource in a separate namespace. Do not delete the InfraEnv resource during the restore process. The InfraEnv resource is mandatory for the new nodes to be reprovisioned.

3. Apply the Restore CR by running the following command:

   $ oc apply -f restore-hosted-cluster.yaml

4. Verify if the value of the status.phase is Completed by running the following command:

   $ oc get hostedcluster <hosted_cluster_name> -n <hosted_cluster_namespace> \
     -o jsonpath='{.status.phase}'

Procedure

1. Observe the backup process by running the following command:

   $ watch "oc get backups.velero.io -n openshift-adp <backup_resource_name> -o jsonpath='{.status}'"

2. Observe the restore process by running the following command:

   $ watch "oc get restores.velero.io -n openshift-adp <backup_resource_name> -o jsonpath='{.status}'"

3. Observe the Velero logs by running the following command:

   $ oc logs -n openshift-adp -ldeploy=velero -f

4. Observe the progress of all of the OADP objects by running the following command:

   $ watch "echo BackupRepositories:;echo;oc get backuprepositories.velero.io -A;echo; echo BackupStorageLocations: ;echo; oc get backupstoragelocations.velero.io -A;echo;echo DataUploads: ;echo;oc get datauploads.velero.io -A;echo;echo DataDownloads: ;echo;oc get datadownloads.velero.io -n openshift-adp; echo;echo VolumeSnapshotLocations: ;echo;oc get volumesnapshotlocations.velero.io -A;echo;echo Backups:;echo;oc get backup -A; echo;echo Restores:;echo;oc get restore -A"

Procedure

1. Create an alias to use the velero CLI from a container by running the following command:

   $ alias velero='oc -n openshift-adp exec deployment/velero -c velero -it -- ./velero'

2. Get details of your Restore custom resource (CR) by running the following command:

   $ velero restore describe <restore_resource_name> --details

   Replace <restore_resource_name> with the name of your Restore resource.

3. Get details of your Backup CR by running the following command:

   $ velero restore describe <backup_resource_name> --details

   Replace <backup_resource_name> with the name of your Backup resource.

Procedure

1. Configure the OADP HyperShift plugin by creating a config map in the OADP namespace and specifying the etcd backup method, as shown in the following example:

   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: hypershift-oadp-plugin-config
     namespace: openshift-adp
   data:
     etcdBackupMethod: "etcdSnapshot"

   where:

   metadata.name

   Specifies the name of the config map. Use hypershift-oadp-plugin-config as the name of the config map.

   metadata.namespace

   Specifies the OADP namespace.

   data.etcdBackupMethod

   Specifies the etcd backup method. The default is volumeSnapshot. Use etcdSnapshot to enable the etcd snapshot method. If the etcdBackupMethod parameter is set to etcdSnapshot but the HCPEtcdBackup custom resource is not installed, the plugin fails.

2. Apply the configuration by entering the following command:

   $ oc apply -f hypershift-oadp-plugin-config.yaml

Verification

1. Check that the etcd pods are running and that the cluster is functioning as expected by entering the following command:

   $ oc get pods -n <my_hosted_cluster_namespace>-<my_hosted_cluster> -l app=etcd

2. Check the restore conditions by entering the following command:

   $ oc get hostedcluster <my_hosted_cluster> -n <my_hosted_cluster_namespace> -o jsonpath='{.status.conditions}' | jq '.[] | select(.type | test("Restore|Etcd"))'

3. On AWS deployments, when you restore to a different management cluster, the OIDC provider might need to be updated. Enter the following command:

   $ hcp fix dr-oidc-iam --hc-name <my_hosted_cluster> --hc-namespace <my_hosted_cluster_namespace>

4. Confirm that the API server of the hosted cluster is accessible by entering the following command:

   $ oc --kubeconfig <hosted_cluster_kubeconfig> get nodes

5. Confirm that workloads are running by entering the following command:

   $ oc --kubeconfig <hosted_cluster_kubeconfig> get clusteroperators