Chapter 6. Control plane backup and restore

Procedure

1. If dynamically-provisioned storage is available, complete the following steps to create a single automated etcd backup:

   1. Create a persistent volume claim (PVC) named etcd-backup-pvc.yaml with contents such as the following example:

      kind: PersistentVolumeClaim
      apiVersion: v1
      metadata:
        name: etcd-backup-pvc
        namespace: openshift-etcd
      spec:
        accessModes:
          - ReadWriteOnce
        resources:
          requests:
            storage: <storage_amount>
        volumeMode: Filesystem

      where:

      <storage_amount>

      Specifies the amount of storage available to the PVC. Adjust this value for your requirements, such as 200Gi.

   2. Apply the PVC by running the following command:

      $ oc apply -f etcd-backup-pvc.yaml

   3. Verify that the PVC was created by running the following command:

      $ oc get pvc

      Example output

      NAME              STATUS    VOLUME   CAPACITY   ACCESS MODES   STORAGECLASS   AGE
      etcd-backup-pvc   Bound                                                       51s

      Note

      Dynamic PVCs stay in the Pending state until they are mounted.

   4. Create a CR file named etcd-single-backup.yaml with contents such as the following example:

      apiVersion: operator.openshift.io/v1alpha1
      kind: EtcdBackup
      metadata:
        name: etcd-single-backup
        namespace: openshift-etcd
      spec:
        pvcName: <pvc_name>

      where:

      <pvc_name>

      Specifies the name of the PVC to save the backup to. Adjust this value according to your environment, such as etcd-backup-pvc.

   5. Apply the CR to start a single backup by running the following command:

      $ oc apply -f etcd-single-backup.yaml

2. If dynamically-provisioned storage is not available, complete the following steps to create a single automated etcd backup:

   1. Create a StorageClass CR file named etcd-backup-local-storage.yaml with the following contents:

      apiVersion: storage.k8s.io/v1
      kind: StorageClass
      metadata:
        name: etcd-backup-local-storage
      provisioner: kubernetes.io/no-provisioner
      volumeBindingMode: Immediate

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

      $ oc apply -f etcd-backup-local-storage.yaml

   3. Create a PV named etcd-backup-pv-fs.yaml with contents such as the following example:

      apiVersion: v1
      kind: PersistentVolume
      metadata:
        name: etcd-backup-pv-fs
      spec:
        capacity:
          storage: <storage_amount>
        volumeMode: Filesystem
        accessModes:
        - ReadWriteOnce
        persistentVolumeReclaimPolicy: Retain
        storageClassName: etcd-backup-local-storage
        local:
          path: /mnt
        nodeAffinity:
          required:
            nodeSelectorTerms:
            - matchExpressions:
            - key: kubernetes.io/hostname
               operator: In
               values:
               - <node_name>

      where:

      <storage_amount>

      Specifies the amount of storage available to the PV. Adjust this value for your requirements, such as 100Gi.

      <node_name>

      Specifies the control plane node to attach this PV to. Replace with the actual node name.

   4. Verify that the PV was created by running the following command:

      $ oc get pv

      Example output

      NAME                    CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS      CLAIM   STORAGECLASS                REASON   AGE
      etcd-backup-pv-fs       100Gi      RWO            Retain           Available           etcd-backup-local-storage            10s

   5. Create a PVC named etcd-backup-pvc.yaml with contents such as the following example:

      kind: PersistentVolumeClaim
      apiVersion: v1
      metadata:
        name: etcd-backup-pvc
        namespace: openshift-etcd
      spec:
        accessModes:
        - ReadWriteOnce
        volumeMode: Filesystem
        resources:
          requests:
            storage: <storage_amount>

      where:

      <storage_amount>

      Specifies the amount of storage available to the PVC. Adjust this value for your requirements, such as 10Gi.

   6. Apply the PVC by running the following command:

      $ oc apply -f etcd-backup-pvc.yaml

   7. Create a CR file named etcd-single-backup.yaml with contents such as the following example:

      apiVersion: operator.openshift.io/v1alpha1
      kind: EtcdBackup
      metadata:
        name: etcd-single-backup
        namespace: openshift-etcd
      spec:
        pvcName: <pvc_name>

      where:

      <pvc_name>

      Specifies the name of the PVC to save the backup to. Adjust this value according to your environment, such as etcd-backup-pvc.

   8. Apply the CR to start a single backup by running the following command:

      $ oc apply -f etcd-single-backup.yaml

Procedure

1. If dynamically-provisioned storage is available, complete the following steps to create automated recurring backups:

   1. Create a persistent volume claim (PVC) named etcd-backup-pvc.yaml with contents such as the following example:

      kind: PersistentVolumeClaim
      apiVersion: v1
      metadata:
        name: etcd-backup-pvc
        namespace: openshift-etcd
      spec:
        accessModes:
          - ReadWriteOnce
        resources:
          requests:
            storage: 200Gi
        volumeMode: Filesystem
        storageClassName: etcd-backup-local-storage

      where:

      spec.resources.requests.storage

      Specifies the amount of storage available to the PVC. Adjust this value for your requirements.

      Note

      Each of the following providers requires changes to the accessModes and storageClassName keys:

      Provider	accessModes value	storageClassName value
      AWS with the versioned-installer-efc_operator-ci profile	- ReadWriteMany	efs-sc
      Google Cloud	- ReadWriteMany	filestore-csi
      Microsoft Azure	- ReadWriteMany	azurefile-csi

   2. Apply the PVC by running the following command:

      $ oc apply -f etcd-backup-pvc.yaml

   3. Verify that the PVC was created by running the following command:

      $ oc get pvc

      Example output

      NAME              STATUS    VOLUME   CAPACITY   ACCESS MODES   STORAGECLASS   AGE
      etcd-backup-pvc   Bound                                                       51s

      Note

      Dynamic PVCs stay in the Pending state until they are mounted.

2. If dynamically-provisioned storage is unavailable, create a local storage PVC by completing the following steps:

   Warning

   If you delete or otherwise lose access to the node that contains the stored backup data, you can lose data.

   1. Create a StorageClass CR file named etcd-backup-local-storage.yaml with the following contents:

      apiVersion: storage.k8s.io/v1
      kind: StorageClass
      metadata:
        name: etcd-backup-local-storage
      provisioner: kubernetes.io/no-provisioner
      volumeBindingMode: Immediate

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

      $ oc apply -f etcd-backup-local-storage.yaml

   3. Create a PV named etcd-backup-pv-fs.yaml from the applied StorageClass with contents such as the following example:

      apiVersion: v1
      kind: PersistentVolume
      metadata:
        name: etcd-backup-pv-fs
      spec:
        capacity:
          storage: 100Gi
        volumeMode: Filesystem
        accessModes:
        - ReadWriteMany
        persistentVolumeReclaimPolicy: Delete
        storageClassName: etcd-backup-local-storage
        local:
          path: /mnt/
        nodeAffinity:
          required:
            nodeSelectorTerms:
            - matchExpressions:
              - key: kubernetes.io/hostname
                operator: In
                values:
                - <example_control_plane_node>

      where:

      spec.capacity.storage

      Specifies the amount of storage available to the PV. Adjust this value for your requirements.

      spec.nodeAffinity.required.nodeSelectorTerms.matchExpressions.values

      Specifies the control plane node to attach this PV to. Replace with the actual node name.

      Tip

      List the available nodes by running the following command:

      $ oc get nodes

   4. Verify that the PV was created by running the following command:

      $ oc get pv

      Example output

      NAME                    CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS      CLAIM   STORAGECLASS                REASON   AGE
      etcd-backup-pv-fs       100Gi      RWX            Delete           Available           etcd-backup-local-storage            10s

   5. Create a PVC named etcd-backup-pvc.yaml with contents such as the following example:

      kind: PersistentVolumeClaim
      apiVersion: v1
      metadata:
        name: etcd-backup-pvc
      spec:
        accessModes:
        - ReadWriteMany
        volumeMode: Filesystem
        resources:
          requests:
            storage: 10Gi
        storageClassName: etcd-backup-local-storage

      where:

      spec.resources.requests.storage

      Specifies the amount of storage available to the PVC. Adjust this value for your requirements.

   6. Apply the PVC by running the following command:

      $ oc apply -f etcd-backup-pvc.yaml

3. Create a CR file named etcd-recurring-backups.yaml. The contents of the CR define the schedule and retention type of automated backups.

   • For the default retention type of RetentionNumber with 15 retained backups, use contents such as the following example:

     apiVersion: config.openshift.io/v1alpha1
     kind: Backup
     metadata:
       name: etcd-recurring-backup
     spec:
       etcd:
         schedule: "20 4 * * *"
         timeZone: "UTC"
         pvcName: etcd-backup-pvc

     where:

     spec.etcd.schedule

     Specifies the CronTab schedule for recurring backups. Adjust this value for your needs.

     1. To use retention based on the maximum number of backups, add the following key-value pairs to the etcd key:

        spec:
          etcd:
            retentionPolicy:
              retentionType: RetentionNumber
              retentionNumber:
                maxNumberOfBackups: 5

        where:

     spec.etcd.retentionPolicy.retentionType

     Specifies the retention type. Defaults to RetentionNumber if unspecified.

     spec.etcd.retentionPolicy.retentionNumber.maxNumberOfBackups

     Specifies the maximum number of backups to retain. Adjust this value for your needs. Defaults to 15 backups if unspecified.

     Warning

     A known issue causes the number of retained backups to be one greater than the configured value.

     1. For retention based on the file size of backups, use the following:

        spec:
          etcd:
            retentionPolicy:
              retentionType: RetentionSize
              retentionSize:
                maxSizeOfBackupsGb: 20

        where:

     spec.etcd.retentionPolicy.retentionSize.maxSizeOfBackupsGb

     Specifies the maximum file size of the retained backups in gigabytes. Adjust this value for your needs. Defaults to 10 GB if unspecified.

     Warning

     A known issue causes the maximum size of retained backups to be up to 10 GB greater than the configured value.

4. Create the cron job defined by the CRD by running the following command:

   $ oc create -f etcd-recurring-backup.yaml

5. To find the created cron job, run the following command:

   $ oc get cronjob -n openshift-etcd

Procedure

1. Remove the unhealthy member.

   1. List etcd pods and choose one that is not on the affected node by running the following command:

      $ oc -n openshift-etcd get pods -l k8s-app=etcd

      Example output

      etcd-ip-10-0-131-183.ec2.internal                3/3     Running     0          123m
      etcd-ip-10-0-164-97.ec2.internal                 3/3     Running     0          123m
      etcd-ip-10-0-154-204.ec2.internal                3/3     Running     0          124m

      From the output, note a pod that is not on the affected node. In this example, the unhealthy member is ip-10-0-131-183.ec2.internal, so you could use etcd-ip-10-0-154-204.ec2.internal.

   2. Connect to the running etcd container on the pod you chose by running the following command:

      $ oc rsh -n openshift-etcd etcd-ip-10-0-154-204.ec2.internal

   3. View the member list by running the following command:

      sh-4.2# etcdctl member list -w table

      Example output

      +------------------+---------+------------------------------+---------------------------+---------------------------+
      |        ID        | STATUS  |             NAME             |        PEER ADDRS         |       CLIENT ADDRS        |
      +------------------+---------+------------------------------+---------------------------+---------------------------+
      | 6fc1e7c9db35841d | started | ip-10-0-131-183.ec2.internal | https://10.0.131.183:2380 | https://10.0.131.183:2379 |
      | 757b6793e2408b6c | started |  ip-10-0-164-97.ec2.internal |  https://10.0.164.97:2380 |  https://10.0.164.97:2379 |
      | ca8c2990a0aa29d1 | started | ip-10-0-154-204.ec2.internal | https://10.0.154.204:2380 | https://10.0.154.204:2379 |
      +------------------+---------+------------------------------+---------------------------+---------------------------+

      Take note of the ID and the name of the unhealthy etcd member because you need these values later in the procedure. The etcdctl endpoint health command continues to list the removed member until replacement is complete and a new member is added.

   4. Remove the unhealthy etcd member by providing the ID to the etcdctl member remove command by running the following command:

      sh-4.2# etcdctl member remove <etcd_member_id>

      Example output

      Member 6fc1e7c9db35841d removed from cluster ead669ce1fbfb346

   5. View the member list again and verify that the member was removed by running the following command:

      sh-4.2# etcdctl member list -w table

      Example output

      +------------------+---------+------------------------------+---------------------------+---------------------------+
      |        ID        | STATUS  |             NAME             |        PEER ADDRS         |       CLIENT ADDRS        |
      +------------------+---------+------------------------------+---------------------------+---------------------------+
      | 757b6793e2408b6c | started |  ip-10-0-164-97.ec2.internal |  https://10.0.164.97:2380 |  https://10.0.164.97:2379 |
      | ca8c2990a0aa29d1 | started | ip-10-0-154-204.ec2.internal | https://10.0.154.204:2380 | https://10.0.154.204:2379 |
      +------------------+---------+------------------------------+---------------------------+---------------------------+

      You can now exit the node shell.

2. Turn off the quorum guard by running the following command:

   $ oc patch etcd/cluster --type=merge -p '{"spec": {"unsupportedConfigOverrides": {"useUnsupportedUnsafeNonHANonProductionUnstableEtcd": true}}}'

   This command ensures that you can successfully re-create secrets and roll out the static pods.

   Important

   After you turn off the quorum guard, the cluster might be unreachable for a short period of time while the remaining etcd instances reboot to reflect the configuration change.

   Note

   etcd cannot tolerate any additional member failure when running with two members. Restarting either remaining member breaks the quorum and causes downtime in your cluster. The quorum guard protects etcd from restarts due to configuration changes that could cause downtime, so it must be disabled to complete this procedure.

3. Delete the affected node by running the following command:

   $ oc delete node <node_name>

   Example command

   $ oc delete node ip-10-0-131-183.ec2.internal

4. Remove the old secrets for the unhealthy etcd member that was removed.

   1. List the secrets for the unhealthy etcd member that was removed by running the following command:

      $ oc get secrets -n openshift-etcd | grep ip-10-0-131-183.ec2.internal

      Replace ip-10-0-131-183.ec2.internal in the command with the name of the unhealthy etcd member that you noted earlier in this procedure.

      There is a peer, serving, and metrics secret as shown in the following output:

      Example output

      etcd-peer-ip-10-0-131-183.ec2.internal              kubernetes.io/tls                     2      47m
      etcd-serving-ip-10-0-131-183.ec2.internal           kubernetes.io/tls                     2      47m
      etcd-serving-metrics-ip-10-0-131-183.ec2.internal   kubernetes.io/tls                     2      47m

   2. Delete the peer secret by running the following command:

      $ oc delete secret -n openshift-etcd etcd-peer-ip-10-0-131-183.ec2.internal

   3. Delete the serving secret by running the following command:

      $ oc delete secret -n openshift-etcd etcd-serving-ip-10-0-131-183.ec2.internal

   4. Delete the metrics secret by running the following command:

      $ oc delete secret -n openshift-etcd etcd-serving-metrics-ip-10-0-131-183.ec2.internal

5. Check whether a control plane machine set exists by running the following command:

   $ oc -n openshift-machine-api get controlplanemachineset

   If the control plane machine set exists, delete and re-create the control plane machine. After this machine is re-created, a new revision is forced and etcd scales up automatically. For more information, see "Replacing an unhealthy etcd member whose machine is not running or whose node is not ready".

   If you are running installer-provisioned infrastructure, or you used the Machine API to create your machines, follow these steps. Otherwise, you must create the new control plane by using the same method that was used to originally create it.

   1. Obtain the machine for the unhealthy member by running the following command.

      $ oc get machines -n openshift-machine-api -o wide

      Example output

      NAME                                        PHASE     TYPE        REGION      ZONE         AGE     NODE                           PROVIDERID                              STATE
      clustername-8qw5l-master-0                  Running   m4.xlarge   us-east-1   us-east-1a   3h37m   ip-10-0-131-183.ec2.internal   aws:///us-east-1a/i-0ec2782f8287dfb7e   stopped
      clustername-8qw5l-master-1                  Running   m4.xlarge   us-east-1   us-east-1b   3h37m   ip-10-0-154-204.ec2.internal   aws:///us-east-1b/i-096c349b700a19631   running
      clustername-8qw5l-master-2                  Running   m4.xlarge   us-east-1   us-east-1c   3h37m   ip-10-0-164-97.ec2.internal    aws:///us-east-1c/i-02626f1dba9ed5bba   running
      clustername-8qw5l-worker-us-east-1a-wbtgd   Running   m4.large    us-east-1   us-east-1a   3h28m   ip-10-0-129-226.ec2.internal   aws:///us-east-1a/i-010ef6279b4662ced   running
      clustername-8qw5l-worker-us-east-1b-lrdxb   Running   m4.large    us-east-1   us-east-1b   3h28m   ip-10-0-144-248.ec2.internal   aws:///us-east-1b/i-0cb45ac45a166173b   running
      clustername-8qw5l-worker-us-east-1c-pkg26   Running   m4.large    us-east-1   us-east-1c   3h28m   ip-10-0-170-181.ec2.internal   aws:///us-east-1c/i-06861c00007751b0a   running

      In the example output, clustername-8qw5l-master-0 is the control plane machine for the unhealthy node ip-10-0-131-183.ec2.internal. Its STATE is stopped.

   2. Delete the machine of the unhealthy member by running the following command:

      $ oc delete machine -n openshift-machine-api clustername-8qw5l-master-0

      Replace clustername-8qw5l-master-0 with the name of the control plane machine for the unhealthy node.

      A new machine is automatically provisioned after deleting the machine of the unhealthy member.

   3. Verify that a new machine was created by running the following command:

      $ oc get machines -n openshift-machine-api -o wide

      Example output

      NAME                                        PHASE          TYPE        REGION      ZONE         AGE     NODE                           PROVIDERID                              STATE
      clustername-8qw5l-master-1                  Running        m4.xlarge   us-east-1   us-east-1b   3h37m   ip-10-0-154-204.ec2.internal   aws:///us-east-1b/i-096c349b700a19631   running
      clustername-8qw5l-master-2                  Running        m4.xlarge   us-east-1   us-east-1c   3h37m   ip-10-0-164-97.ec2.internal    aws:///us-east-1c/i-02626f1dba9ed5bba   running
      clustername-8qw5l-master-3                  Provisioning   m4.xlarge   us-east-1   us-east-1a   85s     ip-10-0-133-53.ec2.internal    aws:///us-east-1a/i-015b0888fe17bc2c8   running
      clustername-8qw5l-worker-us-east-1a-wbtgd   Running        m4.large    us-east-1   us-east-1a   3h28m   ip-10-0-129-226.ec2.internal   aws:///us-east-1a/i-010ef6279b4662ced   running
      clustername-8qw5l-worker-us-east-1b-lrdxb   Running        m4.large    us-east-1   us-east-1b   3h28m   ip-10-0-144-248.ec2.internal   aws:///us-east-1b/i-0cb45ac45a166173b   running
      clustername-8qw5l-worker-us-east-1c-pkg26   Running        m4.large    us-east-1   us-east-1c   3h28m   ip-10-0-170-181.ec2.internal   aws:///us-east-1c/i-06861c00007751b0a   running

      In the example output, clustername-8qw5l-master-3 is the new control plane machine. The machine is ready when the PHASE changes from Provisioning to Running.

      It might take a few minutes for the new machine to be created. The etcd cluster Operator automatically syncs when the machine or node returns to a healthy state.

      Note

      Verify the subnet IDs that you are using for your machine sets to ensure that they end up in the correct availability zone.

      If the control plane machine set does not exist, delete and re-create the control plane machine. After this machine is re-created, a new revision is forced and etcd scales up automatically.

      If you are running installer-provisioned infrastructure, or you used the Machine API to create your machines, follow these steps. Otherwise, you must create the new control plane by using the same method that was used to originally create it.

   4. Obtain the machine for the unhealthy member by running the following command:

      $ oc get machines -n openshift-machine-api -o wide

      Example output

      NAME                                        PHASE     TYPE        REGION      ZONE         AGE     NODE                           PROVIDERID                              STATE
      clustername-8qw5l-master-0                  Running   m4.xlarge   us-east-1   us-east-1a   3h37m   ip-10-0-131-183.ec2.internal   aws:///us-east-1a/i-0ec2782f8287dfb7e   stopped
      clustername-8qw5l-master-1                  Running   m4.xlarge   us-east-1   us-east-1b   3h37m   ip-10-0-154-204.ec2.internal   aws:///us-east-1b/i-096c349b700a19631   running
      clustername-8qw5l-master-2                  Running   m4.xlarge   us-east-1   us-east-1c   3h37m   ip-10-0-164-97.ec2.internal    aws:///us-east-1c/i-02626f1dba9ed5bba   running
      clustername-8qw5l-worker-us-east-1a-wbtgd   Running   m4.large    us-east-1   us-east-1a   3h28m   ip-10-0-129-226.ec2.internal   aws:///us-east-1a/i-010ef6279b4662ced   running
      clustername-8qw5l-worker-us-east-1b-lrdxb   Running   m4.large    us-east-1   us-east-1b   3h28m   ip-10-0-144-248.ec2.internal   aws:///us-east-1b/i-0cb45ac45a166173b   running
      clustername-8qw5l-worker-us-east-1c-pkg26   Running   m4.large    us-east-1   us-east-1c   3h28m   ip-10-0-170-181.ec2.internal   aws:///us-east-1c/i-06861c00007751b0a   running

      In the example output, clustername-8qw5l-master-0 is the control plane machine for the unhealthy node ip-10-0-131-183.ec2.internal. Its STATE is stopped.

   5. Save the machine configuration to a file on your file system by running the following command:

      $ oc get machine clustername-8qw5l-master-0 \
          -n openshift-machine-api \
          -o yaml \
          > new-master-machine.yaml

      Replace clustername-8qw5l-master-0 with the name of the control plane machine for the unhealthy node.

6. Edit the new-master-machine.yaml file that was created in the previous step to assign a new name and remove unnecessary fields:

   1. Remove the entire status section:

      status:
        addresses:
        - address: 10.0.131.183
          type: InternalIP
        - address: ip-10-0-131-183.ec2.internal
          type: InternalDNS
        - address: ip-10-0-131-183.ec2.internal
          type: Hostname
        lastUpdated: "2020-04-20T17:44:29Z"
        nodeRef:
          kind: Node
          name: ip-10-0-131-183.ec2.internal
          uid: acca4411-af0d-4387-b73e-52b2484295ad
        phase: Running
        providerStatus:
          apiVersion: awsproviderconfig.openshift.io/v1beta1
          conditions:
          - lastProbeTime: "2020-04-20T16:53:50Z"
            lastTransitionTime: "2020-04-20T16:53:50Z"
            message: machine successfully created
            reason: MachineCreationSucceeded
            status: "True"
            type: MachineCreation
          instanceId: i-0fdb85790d76d0c3f
          instanceState: stopped
          kind: AWSMachineProviderStatus

   2. Change the metadata.name field to a new name.

      For example:

      apiVersion: machine.openshift.io/v1beta1
      kind: Machine
      metadata:
        ...
        name: clustername-8qw5l-master-3
        ...

      Keep the same base name as the old machine and change the ending number to the next available number. In this example, clustername-8qw5l-master-0 is changed to clustername-8qw5l-master-3

   3. Remove the spec.providerID field:

        providerID: aws:///us-east-1a/i-0fdb85790d76d0c3f

7. Delete the machine of the unhealthy member by running the following command:

   $ oc delete machine -n openshift-machine-api clustername-8qw5l-master-0

   In the command, replace clustername-8qw5l-master-0 with the control plane machine name for the unhealthy node that you identified in the example output above.

8. Verify that the machine was deleted by running the following command:

   $ oc get machines -n openshift-machine-api -o wide

   Example output

   NAME                                        PHASE     TYPE        REGION      ZONE         AGE     NODE                           PROVIDERID                              STATE
   clustername-8qw5l-master-1                  Running   m4.xlarge   us-east-1   us-east-1b   3h37m   ip-10-0-154-204.ec2.internal   aws:///us-east-1b/i-096c349b700a19631   running
   clustername-8qw5l-master-2                  Running   m4.xlarge   us-east-1   us-east-1c   3h37m   ip-10-0-164-97.ec2.internal    aws:///us-east-1c/i-02626f1dba9ed5bba   running
   clustername-8qw5l-worker-us-east-1a-wbtgd   Running   m4.large    us-east-1   us-east-1a   3h28m   ip-10-0-129-226.ec2.internal   aws:///us-east-1a/i-010ef6279b4662ced   running
   clustername-8qw5l-worker-us-east-1b-lrdxb   Running   m4.large    us-east-1   us-east-1b   3h28m   ip-10-0-144-248.ec2.internal   aws:///us-east-1b/i-0cb45ac45a166173b   running
   clustername-8qw5l-worker-us-east-1c-pkg26   Running   m4.large    us-east-1   us-east-1c   3h28m   ip-10-0-170-181.ec2.internal   aws:///us-east-1c/i-06861c00007751b0a   running

9. Create the new machine by using the new-master-machine.yaml file by running the following command:

   $ oc apply -f new-master-machine.yaml

10. Verify that the new machine was created by running the following command:

    $ oc get machines -n openshift-machine-api -o wide

    Example output

    NAME                                        PHASE          TYPE        REGION      ZONE         AGE     NODE                           PROVIDERID                              STATE
    clustername-8qw5l-master-1                  Running        m4.xlarge   us-east-1   us-east-1b   3h37m   ip-10-0-154-204.ec2.internal   aws:///us-east-1b/i-096c349b700a19631   running
    clustername-8qw5l-master-2                  Running        m4.xlarge   us-east-1   us-east-1c   3h37m   ip-10-0-164-97.ec2.internal    aws:///us-east-1c/i-02626f1dba9ed5bba   running
    clustername-8qw5l-master-3                  Provisioning   m4.xlarge   us-east-1   us-east-1a   85s     ip-10-0-133-53.ec2.internal    aws:///us-east-1a/i-015b0888fe17bc2c8   running
    clustername-8qw5l-worker-us-east-1a-wbtgd   Running        m4.large    us-east-1   us-east-1a   3h28m   ip-10-0-129-226.ec2.internal   aws:///us-east-1a/i-010ef6279b4662ced   running
    clustername-8qw5l-worker-us-east-1b-lrdxb   Running        m4.large    us-east-1   us-east-1b   3h28m   ip-10-0-144-248.ec2.internal   aws:///us-east-1b/i-0cb45ac45a166173b   running
    clustername-8qw5l-worker-us-east-1c-pkg26   Running        m4.large    us-east-1   us-east-1c   3h28m   ip-10-0-170-181.ec2.internal   aws:///us-east-1c/i-06861c00007751b0a   running

    In the example output, clustername-8qw5l-master-3 is the new control plane machine. The machine is ready when the PHASE changes from Provisioning to Running.

    It might take a few minutes for the new machine to be created. The etcd cluster Operator automatically syncs when the machine or node returns to a healthy state.

11. Turn the quorum guard back on by running the following command:

    $ oc patch etcd/cluster --type=merge -p '{"spec": {"unsupportedConfigOverrides": null}}'

12. You can verify that the unsupportedConfigOverrides section is removed from the object by running the following command:

    $ oc get etcd/cluster -oyaml

13. If you are using single-node OpenShift, restart the node. Otherwise, you might experience the following error in the etcd cluster Operator:

    Example output

    EtcdCertSignerControllerDegraded: [Operation cannot be fulfilled on secrets "etcd-peer-sno-0": the object has been modified; please apply your changes to the latest version and try again, Operation cannot be fulfilled on secrets "etcd-serving-sno-0": the object has been modified; please apply your changes to the latest version and try again, Operation cannot be fulfilled on secrets "etcd-serving-metrics-sno-0": the object has been modified; please apply your changes to the latest version and try again]

Verification

1. Verify that all etcd pods are running properly by running the following command:

   $ oc -n openshift-etcd get pods -l k8s-app=etcd

   Example output

   etcd-ip-10-0-133-53.ec2.internal                 3/3     Running     0          7m49s
   etcd-ip-10-0-164-97.ec2.internal                 3/3     Running     0          123m
   etcd-ip-10-0-154-204.ec2.internal                3/3     Running     0          124m

2. If the output from the previous command lists only two pods, force an etcd redeployment by running the following command:

   $ oc patch etcd cluster -p='{"spec": {"forceRedeploymentReason": "recovery-'"$( date --rfc-3339=ns )"'"}}' --type=merge

   The forceRedeploymentReason value must be unique, which is why a timestamp is appended in the example.

3. Verify that there are exactly three etcd members.

   1. Connect to the running etcd container, passing in the name of a pod that was not on the affected node by running the following command:

      $ oc rsh -n openshift-etcd etcd-ip-10-0-154-204.ec2.internal

   2. View the member list by running the following command:

      sh-4.2# etcdctl member list -w table

      Example output

      +------------------+---------+------------------------------+---------------------------+---------------------------+
      |        ID        | STATUS  |             NAME             |        PEER ADDRS         |       CLIENT ADDRS        |
      +------------------+---------+------------------------------+---------------------------+---------------------------+
      | 5eb0d6b8ca24730c | started |  ip-10-0-133-53.ec2.internal |  https://10.0.133.53:2380 |  https://10.0.133.53:2379 |
      | 757b6793e2408b6c | started |  ip-10-0-164-97.ec2.internal |  https://10.0.164.97:2380 |  https://10.0.164.97:2379 |
      | ca8c2990a0aa29d1 | started | ip-10-0-154-204.ec2.internal | https://10.0.154.204:2380 | https://10.0.154.204:2379 |
      +------------------+---------+------------------------------+---------------------------+---------------------------+

      If the output from the previous command lists more than three etcd members, you must carefully remove the unwanted member.

      Warning

      Be sure to remove the correct etcd member; removing a good etcd member might lead to quorum loss.

Procedure

1. Stop the crashlooping etcd pod.

   1. Debug the node that is crashlooping by running the following command:

      $ oc debug node/<unhealthy_node>

      Replace <unhealthy_node> with the name of the unhealthy etcd member.

   2. Change your root directory to /host by running the following command:

      sh-4.2# chroot /host

   3. Create a backup directory by running the following command:

      sh-4.2# mkdir /var/lib/etcd-backup

2. Move the existing etcd pod file out of the kubelet manifest directory by running the following commands:

   sh-4.2# mv /etc/kubernetes/manifests/etcd-pod.yaml /var/lib/etcd-backup/

   1. Move the etcd data directory to a different location by running the following command:

      sh-4.2# mv /var/lib/etcd/ /tmp

      You can now exit the node shell.

3. Remove the unhealthy member.

   1. Choose a pod that is not on the affected node by running the following command:

      $ oc -n openshift-etcd get pods -l k8s-app=etcd

      Example output

      etcd-ip-10-0-131-183.ec2.internal                2/3     Error       7          6h9m
      etcd-ip-10-0-164-97.ec2.internal                 3/3     Running     0          6h6m
      etcd-ip-10-0-154-204.ec2.internal                3/3     Running     0          6h6m

   2. Connect to the running etcd container, passing in the name of a pod that is not on the affected node by running the following command:

      $ oc rsh -n openshift-etcd etcd-ip-10-0-154-204.ec2.internal

   3. View the member list by running the following command:

      sh-4.2# etcdctl member list -w table

      Example output

      +------------------+---------+------------------------------+---------------------------+---------------------------+
      |        ID        | STATUS  |             NAME             |        PEER ADDRS         |       CLIENT ADDRS        |
      +------------------+---------+------------------------------+---------------------------+---------------------------+
      | 62bcf33650a7170a | started | ip-10-0-131-183.ec2.internal | https://10.0.131.183:2380 | https://10.0.131.183:2379 |
      | b78e2856655bc2eb | started |  ip-10-0-164-97.ec2.internal |  https://10.0.164.97:2380 |  https://10.0.164.97:2379 |
      | d022e10b498760d5 | started | ip-10-0-154-204.ec2.internal | https://10.0.154.204:2380 | https://10.0.154.204:2379 |
      +------------------+---------+------------------------------+---------------------------+---------------------------+

      Take note of the ID and the name of the unhealthy etcd member, because these values are needed later in the procedure.

   4. Remove the unhealthy etcd member by providing the ID to the etcdctl member remove command:

      sh-4.2# etcdctl member remove 62bcf33650a7170a

      Example output

      Member 62bcf33650a7170a removed from cluster ead669ce1fbfb346

   5. View the member list again and verify that the member was removed by running the following command:

      sh-4.2# etcdctl member list -w table

      Example output

      +------------------+---------+------------------------------+---------------------------+---------------------------+
      |        ID        | STATUS  |             NAME             |        PEER ADDRS         |       CLIENT ADDRS        |
      +------------------+---------+------------------------------+---------------------------+---------------------------+
      | b78e2856655bc2eb | started |  ip-10-0-164-97.ec2.internal |  https://10.0.164.97:2380 |  https://10.0.164.97:2379 |
      | d022e10b498760d5 | started | ip-10-0-154-204.ec2.internal | https://10.0.154.204:2380 | https://10.0.154.204:2379 |
      +------------------+---------+------------------------------+---------------------------+---------------------------+

      You can now exit the node shell.

4. Turn off the quorum guard by running the following command:

   $ oc patch etcd/cluster --type=merge -p '{"spec": {"unsupportedConfigOverrides": {"useUnsupportedUnsafeNonHANonProductionUnstableEtcd": true}}}'

   This command ensures that you can successfully re-create secrets and roll out the static pods.

5. Remove the old secrets for the unhealthy etcd member that was removed.

   1. List the secrets for the unhealthy etcd member that was removed by running the following command:

      $ oc get secrets -n openshift-etcd | grep <unhealthy_node>

      Replace <unhealthy_node> in the command with the name of the unhealthy etcd member that you noted earlier in this procedure.

      There is a peer, serving, and metrics secret as shown in the following output:

      Example output

      etcd-peer-ip-10-0-131-183.ec2.internal              kubernetes.io/tls                     2      47m
      etcd-serving-ip-10-0-131-183.ec2.internal           kubernetes.io/tls                     2      47m
      etcd-serving-metrics-ip-10-0-131-183.ec2.internal   kubernetes.io/tls                     2      47m

   2. Delete the peer secret for the unhealthy etcd member that was removed by running the following command:

      $ oc delete secret -n openshift-etcd etcd-peer-ip-10-0-131-183.ec2.internal

   3. Delete the serving secret by running the following command:

      $ oc delete secret -n openshift-etcd etcd-serving-ip-10-0-131-183.ec2.internal

   4. Delete the metrics secret by running the following command:

      $ oc delete secret -n openshift-etcd etcd-serving-metrics-ip-10-0-131-183.ec2.internal

6. Force etcd redeployment by running the following command:

   $ oc patch etcd cluster -p='{"spec": {"forceRedeploymentReason": "single-master-recovery-'"$( date --rfc-3339=ns )"'"}}' --type=merge

   The forceRedeploymentReason value must be unique, which is why a timestamp is appended.

   When the etcd cluster Operator performs a redeployment, it ensures that all control plane nodes have a functioning etcd pod.

7. Turn the quorum guard back on by running the following command:

   $ oc patch etcd/cluster --type=merge -p '{"spec": {"unsupportedConfigOverrides": null}}'

8. Verify that the unsupportedConfigOverrides section is removed from the object by running the following command:

   $ oc get etcd/cluster -oyaml

9. If you are using single-node OpenShift, restart the node. Otherwise, you might encounter the following error in the etcd cluster Operator:

   Example output

   EtcdCertSignerControllerDegraded: [Operation cannot be fulfilled on secrets "etcd-peer-sno-0": the object has been modified; please apply your changes to the latest version and try again, Operation cannot be fulfilled on secrets "etcd-serving-sno-0": the object has been modified; please apply your changes to the latest version and try again, Operation cannot be fulfilled on secrets "etcd-serving-metrics-sno-0": the object has been modified; please apply your changes to the latest version and try again]

Procedure

1. Verify and remove the unhealthy member.

   1. Choose a pod that is not on the affected node by running the following command:

      $ oc -n openshift-etcd get pods -l k8s-app=etcd -o wide

      Example output

      etcd-openshift-control-plane-0   5/5   Running   11   3h56m   192.168.10.9   openshift-control-plane-0  <none>           <none>
      etcd-openshift-control-plane-1   5/5   Running   0    3h54m   192.168.10.10   openshift-control-plane-1   <none>           <none>
      etcd-openshift-control-plane-2   5/5   Running   0    3h58m   192.168.10.11   openshift-control-plane-2   <none>           <none>

   2. Connect to the running etcd container, passing in the name of a pod that is not on the affected node by running the following command:

      $ oc rsh -n openshift-etcd etcd-openshift-control-plane-0

   3. View the member list by running the following command:

      sh-4.2# etcdctl member list -w table

      Example output

      +------------------+---------+--------------------+---------------------------+---------------------------+---------------------+
      | ID               | STATUS  | NAME                      | PEER ADDRS                  | CLIENT ADDRS                | IS LEARNER |
      +------------------+---------+--------------------+---------------------------+---------------------------+---------------------+
      | 7a8197040a5126c8 | started | openshift-control-plane-2 | https://192.168.10.11:2380/ | https://192.168.10.11:2379/ | false |
      | 8d5abe9669a39192 | started | openshift-control-plane-1 | https://192.168.10.10:2380/ | https://192.168.10.10:2379/ | false |
      | cc3830a72fc357f9 | started | openshift-control-plane-0 | https://192.168.10.9:2380/ | https://192.168.10.9:2379/   | false |
      +------------------+---------+--------------------+---------------------------+---------------------------+---------------------+

      Take note of the ID and the name of the unhealthy etcd member, because these values are required later in the procedure. The etcdctl endpoint health command lists the removed member until the replacement procedure is completed and the new member is added.

      Warning

      Be sure to remove the correct etcd member. Removing a good etcd member might lead to quorum loss.

   4. Remove the unhealthy etcd member by providing the ID to the etcdctl member remove command:

      sh-4.2# etcdctl member remove 7a8197040a5126c8

      Example output

      Member 7a8197040a5126c8 removed from cluster b23536c33f2cdd1b

   5. View the member list again and verify that the member was removed by running the following command:

      sh-4.2# etcdctl member list -w table

      Example output

      +------------------+---------+--------------------+---------------------------+---------------------------+-------------------------+
      | ID               | STATUS  | NAME                      | PEER ADDRS                  | CLIENT ADDRS                | IS LEARNER |
      +------------------+---------+--------------------+---------------------------+---------------------------+-------------------------+
      | cc3830a72fc357f9 | started | openshift-control-plane-2 | https://192.168.10.11:2380/ | https://192.168.10.11:2379/ | false |
      | 8d5abe9669a39192 | started | openshift-control-plane-1 | https://192.168.10.10:2380/ | https://192.168.10.10:2379/ | false |
      +------------------+---------+--------------------+---------------------------+---------------------------+-------------------------+

      You can now exit the node shell.

      Important

      After you remove the member, the cluster might be unreachable for a short time while the remaining etcd instances reboot.

2. Turn off the quorum guard by running the following command:

   $ oc patch etcd/cluster --type=merge -p '{"spec": {"unsupportedConfigOverrides": {"useUnsupportedUnsafeNonHANonProductionUnstableEtcd": true}}}'

   This command ensures that you can successfully re-create secrets and roll out the static pods.

3. Remove the old secrets for the unhealthy etcd member that was removed.

   1. List the secrets for the unhealthy etcd member that was removed by running the following command:

      $ oc get secrets -n openshift-etcd | grep openshift-control-plane-2

      Pass in the name of the unhealthy etcd member that you took note of earlier in this procedure.

      There is a peer, serving, and metrics secret as shown in the following output:

      etcd-peer-openshift-control-plane-2             kubernetes.io/tls   2   134m
      etcd-serving-metrics-openshift-control-plane-2  kubernetes.io/tls   2   134m
      etcd-serving-openshift-control-plane-2          kubernetes.io/tls   2   134m

   2. Delete the secrets for the unhealthy etcd member by running the following command:

      $ oc delete secret etcd-peer-openshift-control-plane-2 -n openshift-etcd

      Example output

      secret "etcd-peer-openshift-control-plane-2" deleted

   3. Delete the serving secret by running the following command:

      $ oc delete secret etcd-serving-metrics-openshift-control-plane-2 -n openshift-etcd

      Example output

      secret "etcd-serving-metrics-openshift-control-plane-2" deleted

   4. Delete the metrics secret by running the following command:

      $ oc delete secret etcd-serving-openshift-control-plane-2 -n openshift-etcd

      Example output

      secret "etcd-serving-openshift-control-plane-2" deleted

4. Obtain the machine for the unhealthy member by running the following command:

   $ oc get machines -n openshift-machine-api -o wide

   Example output

   NAME                              PHASE     TYPE   REGION   ZONE   AGE     NODE                               PROVIDERID                                                                                              STATE
   examplecluster-control-plane-0    Running                          3h11m   openshift-control-plane-0   baremetalhost:///openshift-machine-api/openshift-control-plane-0/da1ebe11-3ff2-41c5-b099-0aa41222964e   externally provisioned
   examplecluster-control-plane-1    Running                          3h11m   openshift-control-plane-1   baremetalhost:///openshift-machine-api/openshift-control-plane-1/d9f9acbc-329c-475e-8d81-03b20280a3e1   externally provisioned
   examplecluster-control-plane-2    Running                          3h11m   openshift-control-plane-2   baremetalhost:///openshift-machine-api/openshift-control-plane-2/3354bdac-61d8-410f-be5b-6a395b056135   externally provisioned
   examplecluster-compute-0          Running                          165m    openshift-compute-0         baremetalhost:///openshift-machine-api/openshift-compute-0/3d685b81-7410-4bb3-80ec-13a31858241f         provisioned
   examplecluster-compute-1          Running                          165m    openshift-compute-1         baremetalhost:///openshift-machine-api/openshift-compute-1/0fdae6eb-2066-4241-91dc-e7ea72ab13b9         provisioned

   examplecluster-control-plane-2 is the control plane machine for the unhealthy node openshift-control-plane-2.

5. Ensure that the Bare Metal Operator is available by running the following command:

   $ oc get clusteroperator baremetal

   Example output

   NAME        VERSION   AVAILABLE   PROGRESSING   DEGRADED   SINCE   MESSAGE
   baremetal   4.22.0    True        False         False      3d15h

6. Remove the old BareMetalHost object by running the following command:

   $ oc delete bmh openshift-control-plane-2 -n openshift-machine-api

   Example output

   baremetalhost.metal3.io "openshift-control-plane-2" deleted

7. Delete the machine of the unhealthy member by running the following command:

   $ oc delete machine -n openshift-machine-api examplecluster-control-plane-2

   After you remove the BareMetalHost and Machine objects, then the Machine controller automatically deletes the Node object.

   If deletion of the machine is delayed for any reason or the command is obstructed and delayed, you can force deletion by removing the machine object finalizer field.

   Important

   Do not interrupt machine deletion by pressing Ctrl+c. You must allow the command to proceed to completion. Open a new terminal window to edit and delete the finalizer fields.

   A new machine is automatically provisioned after deleting the machine of the unhealthy member.

   1. Edit the machine configuration by running the following command:

      $ oc edit machine -n openshift-machine-api examplecluster-control-plane-2

   2. Delete the following fields in the Machine custom resource, and then save the updated file:

      finalizers:
      - machine.machine.openshift.io

      Example output

      machine.machine.openshift.io/examplecluster-control-plane-2 edited

8. Verify that the machine was deleted by running the following command:

   $ oc get machines -n openshift-machine-api -o wide

   Example output

   NAME                              PHASE     TYPE   REGION   ZONE   AGE     NODE                                 PROVIDERID                                                                                       STATE
   examplecluster-control-plane-0    Running                          3h11m   openshift-control-plane-0   baremetalhost:///openshift-machine-api/openshift-control-plane-0/da1ebe11-3ff2-41c5-b099-0aa41222964e   externally provisioned
   examplecluster-control-plane-1    Running                          3h11m   openshift-control-plane-1   baremetalhost:///openshift-machine-api/openshift-control-plane-1/d9f9acbc-329c-475e-8d81-03b20280a3e1   externally provisioned
   examplecluster-compute-0          Running                          165m    openshift-compute-0         baremetalhost:///openshift-machine-api/openshift-compute-0/3d685b81-7410-4bb3-80ec-13a31858241f         provisioned
   examplecluster-compute-1          Running                          165m    openshift-compute-1         baremetalhost:///openshift-machine-api/openshift-compute-1/0fdae6eb-2066-4241-91dc-e7ea72ab13b9         provisioned

9. Verify that the node has been deleted by running the following command:

   $ oc get nodes

   Example output

   NAME                     STATUS ROLES   AGE   VERSION
   openshift-control-plane-0 Ready master 3h24m v1.35.4
   openshift-control-plane-1 Ready master 3h24m v1.35.4
   openshift-compute-0       Ready worker 176m v1.35.4
   openshift-compute-1       Ready worker 176m v1.35.4

10. Create the new BareMetalHost object and the secret to store the Baseboard Management Controller (BMC) credentials by running the following command:

    $ cat <<EOF | oc apply -f -
    apiVersion: v1
    kind: Secret
    metadata:
      name: openshift-control-plane-2-bmc-secret
      namespace: openshift-machine-api
    data:
      password: <password>
      username: <username>
    type: Opaque
    ---
    apiVersion: metal3.io/v1alpha1
    kind: BareMetalHost
    metadata:
      name: openshift-control-plane-2
      namespace: openshift-machine-api
    spec:
      automatedCleaningMode: disabled
      bmc:
        address: redfish://10.46.61.18:443/redfish/v1/Systems/1
        credentialsName: openshift-control-plane-2-bmc-secret
        disableCertificateVerification: true
      bootMACAddress: 48:df:37:b0:8a:a0
      bootMode: UEFI
      externallyProvisioned: false
      online: true
      rootDeviceHints:
        deviceName: /dev/disk/by-id/scsi-<serial_number>
      userData:
        name: master-user-data-managed
        namespace: openshift-machine-api
    EOF

    Note

    The username and password can be found from the secrets of the other bare-metal host. The protocol to use in bmc:address can be taken from other bmh objects.

    Important

    If you reuse the BareMetalHost object definition from an existing control plane host, do not leave the externallyProvisioned field set to true.

    Existing control plane BareMetalHost objects may have the externallyProvisioned flag set to true if they were provisioned by the OpenShift Container Platform installation program.

    After the inspection is complete, the BareMetalHost object is created and available to be provisioned.

11. Verify the creation process using available BareMetalHost objects by completing the following steps:

    1. Verify that a new machine has been created by running the following command:

       $ oc get machines -n openshift-machine-api -o wide

       The new machine is ready when the phase changes from Provisioning to Running.

       It should take a few minutes for the new machine to be created. The etcd cluster Operator automatically syncs when the machine or node returns to a healthy state.

       Example output

       NAME                                   PHASE     TYPE   REGION   ZONE   AGE     NODE                              PROVIDERID                                                                                            STATE
       examplecluster-control-plane-0         Running                          3h11m   openshift-control-plane-0   baremetalhost:///openshift-machine-api/openshift-control-plane-0/da1ebe11-3ff2-41c5-b099-0aa41222964e   externally provisioned
       examplecluster-control-plane-1         Running                          3h11m   openshift-control-plane-1   baremetalhost:///openshift-machine-api/openshift-control-plane-1/d9f9acbc-329c-475e-8d81-03b20280a3e1   externally provisioned
       examplecluster-control-plane-3         Running                          11m     openshift-control-plane-2   baremetalhost:///openshift-machine-api/openshift-control-plane-2/dac4335b-5c81-a641-395b-5631f0a9a545   externally provisioned
       examplecluster-compute-0               Running                          165m    openshift-compute-0         baremetalhost:///openshift-machine-api/openshift-compute-0/3d685b81-7410-4bb3-80ec-13a31858241f         provisioned
       examplecluster-compute-1               Running                          165m    openshift-compute-1         baremetalhost:///openshift-machine-api/openshift-compute-1/0fdae6eb-2066-4241-91dc-e7ea72ab13b9         provisioned

    2. Verify that the bare metal host becomes provisioned and no error reported by running the following command:

       $ oc get bmh -n openshift-machine-api

       Example output

       NAME                      STATE                  CONSUMER                       ONLINE ERROR AGE
       openshift-control-plane-0 externally provisioned examplecluster-control-plane-0 true         4h48m
       openshift-control-plane-1 externally provisioned examplecluster-control-plane-1 true         4h48m
       openshift-control-plane-2 provisioned            examplecluster-control-plane-3 true          47m
       openshift-compute-0       provisioned            examplecluster-compute-0       true         4h48m
       openshift-compute-1       provisioned            examplecluster-compute-1       true         4h48m

    3. Verify that the new node is added and in a ready state by running the following command:

       $ oc get nodes

       Example output

       NAME                     STATUS ROLES   AGE   VERSION
       openshift-control-plane-0 Ready master 4h26m v1.35.4
       openshift-control-plane-1 Ready master 4h26m v1.35.4
       openshift-control-plane-2 Ready master 12m   v1.35.4
       openshift-compute-0       Ready worker 3h58m v1.35.4
       openshift-compute-1       Ready worker 3h58m v1.35.4

12. Turn the quorum guard back on by running the following command:

    $ oc patch etcd/cluster --type=merge -p '{"spec": {"unsupportedConfigOverrides": null}}'

13. You can verify that the unsupportedConfigOverrides section is removed from the object by running the following command:

    $ oc get etcd/cluster -oyaml

14. If you are using single-node OpenShift, restart the node. Otherwise, you might encounter the following error in the etcd cluster Operator:

    Example output

    EtcdCertSignerControllerDegraded: [Operation cannot be fulfilled on secrets "etcd-peer-sno-0": the object has been modified; please apply your changes to the latest version and try again, Operation cannot be fulfilled on secrets "etcd-serving-sno-0": the object has been modified; please apply your changes to the latest version and try again, Operation cannot be fulfilled on secrets "etcd-serving-metrics-sno-0": the object has been modified; please apply your changes to the latest version and try again]

Verification

1. Verify that all etcd pods are running properly by running the following command:

   $ oc -n openshift-etcd get pods -l k8s-app=etcd

   Example output

   etcd-openshift-control-plane-0      5/5     Running     0     105m
   etcd-openshift-control-plane-1      5/5     Running     0     107m
   etcd-openshift-control-plane-2      5/5     Running     0     103m

   If the output from the previous command only lists two pods, you can manually force an etcd redeployment. In a terminal that has access to the cluster as a cluster-admin user, run the following command:

   $ oc patch etcd cluster -p='{"spec": {"forceRedeploymentReason": "recovery-'"$( date --rfc-3339=ns )"'"}}' --type=merge

   The forceRedeploymentReason value must be unique, which is why a timestamp is appended.

   To verify there are exactly three etcd members, connect to the running etcd container, passing in the name of a pod that was not on the affected node. In a terminal that has access to the cluster as a cluster-admin user, run the following command:

   $ oc rsh -n openshift-etcd etcd-openshift-control-plane-0

2. View the member list by running the following command:

   sh-4.2# etcdctl member list -w table

   Example output

   +------------------+---------+--------------------+---------------------------+---------------------------+-----------------+
   |        ID        | STATUS  |        NAME        |        PEER ADDRS         |       CLIENT ADDRS        |    IS LEARNER    |
   +------------------+---------+--------------------+---------------------------+---------------------------+-----------------+
   | 7a8197040a5126c8 | started | openshift-control-plane-2 | https://192.168.10.11:2380 | https://192.168.10.11:2379 |   false |
   | 8d5abe9669a39192 | started | openshift-control-plane-1 | https://192.168.10.10:2380 | https://192.168.10.10:2379 |   false |
   | cc3830a72fc357f9 | started | openshift-control-plane-0 | https://192.168.10.9:2380 | https://192.168.10.9:2379 |     false |
   +------------------+---------+--------------------+---------------------------+---------------------------+-----------------+

   Note

   If the output from the previous command lists more than three etcd members, you must carefully remove the unwanted member.

3. Verify that all etcd members are healthy by running the following command:

   # etcdctl endpoint health --cluster

   Example output

   https://192.168.10.10:2379 is healthy: successfully committed proposal: took = 8.973065ms
   https://192.168.10.9:2379 is healthy: successfully committed proposal: took = 11.559829ms
   https://192.168.10.11:2379 is healthy: successfully committed proposal: took = 11.665203ms

4. Validate that all nodes are at the latest revision by running the following command:

   $ oc get etcd -o=jsonpath='{range.items[0].status.conditions[?(@.type=="NodeInstallerProgressing")]}{.reason}{"\n"}{.message}{"\n"}'

   AllNodesAtLatestRevision

Procedure

1. Select a control plane host to use as the recovery host. You run the restore operation on this host.

2. Using SSH, connect to the chosen recovery node and run the following command to restore etcd quorum:

   $ sudo -E /usr/local/bin/quorum-restore.sh

   After a few minutes, the nodes that went down are automatically synchronized with the node that the recovery script was run on. Any remaining online nodes automatically rejoin the new etcd cluster created by the quorum-restore.sh script. This process takes a few minutes.

3. Verify that the local etcd container is running on the host by using the container runtime CLI:

   $ sudo crictl ps --name '^etcd$'

4. Exit the SSH session.

5. Return to a three-node configuration if any nodes are offline. Repeat the following steps for each node that is offline to delete and re-create them. After the machines are re-created, a new revision is forced and etcd automatically scales up.

   Warning

   For installer-provisioned infrastructure and user-provisioned infrastructure, do not delete and re-create the machine for the recovery host.

   • If you use a user-provisioned bare-metal installation, you can re-create a control plane machine by using the same method that you used to originally create it.

     Important

     Before starting the newly provisioned node, you must delete the existing node object from the cluster by running the oc delete node <node_name> command. Failing to delete the node object before reinstallating the node can cause conflicts and issues during the reinstallation process.

     For more information, see "Installing a user-provisioned cluster on bare metal".

     • If you are running installer-provisioned infrastructure, or you used the Machine API to create your machines, follow these steps:

       Important

       For bare-metal installations on installer-provisioned infrastructure, control plane machines are not re-created. For more information, see "Replacing a bare-metal control plane node".

       1. In a terminal that has access to the cluster as a cluster-admin user, obtain the machine for one of the offline nodes by running the following command:

          $ oc get machines -n openshift-machine-api -o wide

          Example output

          NAME                                        PHASE     TYPE        REGION      ZONE         AGE     NODE                           PROVIDERID                              STATE
          clustername-8qw5l-master-0                  Running   m4.xlarge   us-east-1   us-east-1a   3h37m   ip-10-0-131-183.ec2.internal   aws:///us-east-1a/i-0ec2782f8287dfb7e   stopped
          clustername-8qw5l-master-1                  Running   m4.xlarge   us-east-1   us-east-1b   3h37m   ip-10-0-143-125.ec2.internal   aws:///us-east-1b/i-096c349b700a19631   running
          clustername-8qw5l-master-2                  Running   m4.xlarge   us-east-1   us-east-1c   3h37m   ip-10-0-154-194.ec2.internal    aws:///us-east-1c/i-02626f1dba9ed5bba  running
          clustername-8qw5l-worker-us-east-1a-wbtgd   Running   m4.large    us-east-1   us-east-1a   3h28m   ip-10-0-129-226.ec2.internal   aws:///us-east-1a/i-010ef6279b4662ced   running
          clustername-8qw5l-worker-us-east-1b-lrdxb   Running   m4.large    us-east-1   us-east-1b   3h28m   ip-10-0-144-248.ec2.internal   aws:///us-east-1b/i-0cb45ac45a166173b   running
          clustername-8qw5l-worker-us-east-1c-pkg26   Running   m4.large    us-east-1   us-east-1c   3h28m   ip-10-0-170-181.ec2.internal   aws:///us-east-1c/i-06861c00007751b0a   running

          In the example output, clustername-8qw5l-master-0 is the control plane machine for the offline node, ip-10-0-131-183.ec2.internal.

       2. Delete the machine of the offline node by running the following command:

          $ oc delete machine -n openshift-machine-api clustername-8qw5l-master-0

          Specify the name of the control plane machine for the offline node.

          A new machine is automatically provisioned after deleting the machine of the offline node.

6. Verify that a new machine has been created by running the following command:

   $ oc get machines -n openshift-machine-api -o wide

   Example output

   NAME                                        PHASE          TYPE        REGION      ZONE         AGE     NODE                           PROVIDERID                              STATE
   clustername-8qw5l-master-1                  Running        m4.xlarge   us-east-1   us-east-1b   3h37m   ip-10-0-143-125.ec2.internal   aws:///us-east-1b/i-096c349b700a19631   running
   clustername-8qw5l-master-2                  Running        m4.xlarge   us-east-1   us-east-1c   3h37m   ip-10-0-154-194.ec2.internal    aws:///us-east-1c/i-02626f1dba9ed5bba  running
   clustername-8qw5l-master-3                  Provisioning   m4.xlarge   us-east-1   us-east-1a   85s     ip-10-0-173-171.ec2.internal    aws:///us-east-1a/i-015b0888fe17bc2c8  running
   clustername-8qw5l-worker-us-east-1a-wbtgd   Running        m4.large    us-east-1   us-east-1a   3h28m   ip-10-0-129-226.ec2.internal   aws:///us-east-1a/i-010ef6279b4662ced   running
   clustername-8qw5l-worker-us-east-1b-lrdxb   Running        m4.large    us-east-1   us-east-1b   3h28m   ip-10-0-144-248.ec2.internal   aws:///us-east-1b/i-0cb45ac45a166173b   running
   clustername-8qw5l-worker-us-east-1c-pkg26   Running        m4.large    us-east-1   us-east-1c   3h28m   ip-10-0-170-181.ec2.internal   aws:///us-east-1c/i-06861c00007751b0a   running

   In the example output, clustername-8qw5l-master-3 is being created and is ready after the phase changes from Provisioning to Running.

   It might take a few minutes for the new machine to be created. The etcd cluster Operator automatically synchronizes when the machine or node returns to a healthy state.

7. For each node that is offline, repeat the previous steps to delete and re-create the node.

8. Wait until the control plane recovers by running the following command:

   $ oc adm wait-for-stable-cluster

   Note

   It can take up to 15 minutes for the control plane to recover.

Procedure

1. Use SSH to connect to the single node and copy the etcd backup to the /home/core directory by running the following command:

   $ cp <etcd_backup_directory> /home/core

2. To restore the cluster from an earlier backup on the single node, run the following command:

   $ sudo -E /usr/local/bin/cluster-restore.sh /home/core/<etcd_backup_directory>

3. Exit the SSH session.

4. Monitor the recovery progress of the control plane by running the following command:

   $ oc adm wait-for-stable-cluster

   Note

   It can take up to 15 minutes for the control plane to recover.

Procedure

1. Select a control plane host to use as the recovery host. This is the host that you run the restore operation on.

2. Establish SSH connectivity to each of the control plane nodes, including the recovery host.

   kube-apiserver becomes inaccessible after the restore process starts, so you cannot access the control plane nodes. Establish SSH connectivity to each control plane host in a separate terminal.

   Important

   If you do not complete this step, you cannot access the control plane hosts to complete the restore procedure, and you cannot recover your cluster from this state.

3. Using SSH, connect to each control plane node to disable etcd by running the following command:

   $ sudo -E /usr/local/bin/disable-etcd.sh

4. Copy the etcd backup directory to the recovery control plane host.

   This procedure assumes that you copied the backup directory containing the etcd snapshot and the resources for the static pods to the /home/core/ directory of your recovery control plane host.

5. Use SSH to connect to the recovery host. Restore the cluster from an earlier backup by running the following command:

   $ sudo -E /usr/local/bin/cluster-restore.sh /home/core/<etcd-backup-directory>

6. Exit the SSH session.

7. When the API responds, turn off the etcd Operator quorum guard by running the following command:

   $ oc patch etcd/cluster --type=merge -p '{"spec": {"unsupportedConfigOverrides": {"useUnsupportedUnsafeNonHANonProductionUnstableEtcd": true}}}'

   Important

   For a TNF setup, do not:

   • Change the etcd Operator quorum setting.
   • Turn the etcd Operator quorum off.
   • Turn the etcd Operator quorum back on.

8. Monitor the recovery progress of the control plane by running the following command:

   $ oc adm wait-for-stable-cluster

   Note

   It can take up to 15 minutes for the control plane to recover. Wait for the control plane to recover before using the next step.

9. Enable the quorum guard by running the following command:

   $ oc patch etcd/cluster --type=merge -p '{"spec": {"unsupportedConfigOverrides": null}}'

Procedure

1. Get the list of current CSRs by running the following command:

   $ oc get csr

   Example output

   NAME        AGE    SIGNERNAME                                    REQUESTOR                                                                   CONDITION
   csr-2s94x   8m3s   kubernetes.io/kubelet-serving                 system:node:<node_name>                                                     Pending
   csr-4bd6t   8m3s   kubernetes.io/kubelet-serving                 system:node:<node_name>                                                     Pending
   csr-4hl85   13m    kubernetes.io/kube-apiserver-client-kubelet   system:serviceaccount:openshift-machine-config-operator:node-bootstrapper   Pending
   csr-zhhhp   3m8s   kubernetes.io/kube-apiserver-client-kubelet   system:serviceaccount:openshift-machine-config-operator:node-bootstrapper   Pending
   ...

   In the example output, CSRs with a SIGNERNAME of kubernetes.io/kubelet-serving are kubelet serving CSRs. You see this CSR type on user-provisioned installations. CSRs with a SIGNERNAME of kubernetes.io/kube-apiserver-client-kubelet and a node-bootstrapper requestor are node-bootstrapper CSRs that you must approve to restore kubelet certificates.

2. Review the details of a CSR to verify that it is valid by running the following command:

   $ oc describe csr <csr_name>

   <csr_name> is the name of a CSR from the list of current CSRs.

3. Approve each valid node-bootstrapper CSR by running the following command:

   $ oc adm certificate approve <csr_name>

4. For user-provisioned installations, approve each valid kubelet serving CSR by running the following command:

   $ oc adm certificate approve <csr_name>

Procedure

1. Use SSH to connect to each of your nonrecovery nodes to disable etcd and the kubelet service:

   1. Disable etcd by running the following command:

      $ sudo /usr/local/bin/disable-etcd.sh

   2. Delete variable data for etcd by running the following command:

      $ sudo rm -rf /var/lib/etcd

   3. Disable the kubelet service by running the following command:

      $ sudo systemctl disable kubelet.service --now

2. Exit every SSH session.

3. Ensure that your nonrecovery nodes are in a NOT READY state by running the following command:

   $ oc get nodes

4. Restore your cluster to an earlier cluster state by using an etcd backup. For more information, see "Restoring to an earlier cluster state".

5. After you restore the cluster and the API responds, use SSH to connect to each nonrecovery node and enable the kubelet service by running the following command:

   $ sudo systemctl enable kubelet.service --now

6. Exit every SSH session.

7. Verify that your nodes return to the READY state by running the following command:

   $ oc get nodes

8. Verify that etcd is available by running the following command:

   $ oc get pods -n openshift-etcd

Procedure

1. Select a control plane host to use as the recovery host. You run the restore operation on this host.

2. Using SSH, connect to the chosen recovery node and run the following command to restore etcd quorum:

   $ sudo -E /usr/local/bin/quorum-restore.sh

   After a few minutes, the nodes that went down are automatically synchronized with the node that the recovery script was run on. Any remaining online nodes automatically rejoin the new etcd cluster created by the quorum-restore.sh script. This process takes a few minutes.

3. Verify that the local etcd container is running on the host by using the container runtime CLI:

   $ sudo crictl ps --name '^etcd$'

4. Exit the SSH session.

5. Return to a three-node configuration if any nodes are offline. Repeat the following steps for each node that is offline to delete and re-create them. After the machines are re-created, a new revision is forced and etcd automatically scales up.

   Warning

   For installer-provisioned infrastructure and user-provisioned infrastructure, do not delete and re-create the machine for the recovery host.

   • If you use a user-provisioned bare-metal installation, you can re-create a control plane machine by using the same method that you used to originally create it.

     Important

     Before starting the newly provisioned node, you must delete the existing node object from the cluster by running the oc delete node <node_name> command. Failing to delete the node object before reinstallating the node can cause conflicts and issues during the reinstallation process.

     For more information, see "Installing a user-provisioned cluster on bare metal".

     • If you are running installer-provisioned infrastructure, or you used the Machine API to create your machines, follow these steps:

       Important

       For bare-metal installations on installer-provisioned infrastructure, control plane machines are not re-created. For more information, see "Replacing a bare-metal control plane node".

       1. In a terminal that has access to the cluster as a cluster-admin user, obtain the machine for one of the offline nodes by running the following command:

          $ oc get machines -n openshift-machine-api -o wide

          Example output

          NAME                                        PHASE     TYPE        REGION      ZONE         AGE     NODE                           PROVIDERID                              STATE
          clustername-8qw5l-master-0                  Running   m4.xlarge   us-east-1   us-east-1a   3h37m   ip-10-0-131-183.ec2.internal   aws:///us-east-1a/i-0ec2782f8287dfb7e   stopped
          clustername-8qw5l-master-1                  Running   m4.xlarge   us-east-1   us-east-1b   3h37m   ip-10-0-143-125.ec2.internal   aws:///us-east-1b/i-096c349b700a19631   running
          clustername-8qw5l-master-2                  Running   m4.xlarge   us-east-1   us-east-1c   3h37m   ip-10-0-154-194.ec2.internal    aws:///us-east-1c/i-02626f1dba9ed5bba  running
          clustername-8qw5l-worker-us-east-1a-wbtgd   Running   m4.large    us-east-1   us-east-1a   3h28m   ip-10-0-129-226.ec2.internal   aws:///us-east-1a/i-010ef6279b4662ced   running
          clustername-8qw5l-worker-us-east-1b-lrdxb   Running   m4.large    us-east-1   us-east-1b   3h28m   ip-10-0-144-248.ec2.internal   aws:///us-east-1b/i-0cb45ac45a166173b   running
          clustername-8qw5l-worker-us-east-1c-pkg26   Running   m4.large    us-east-1   us-east-1c   3h28m   ip-10-0-170-181.ec2.internal   aws:///us-east-1c/i-06861c00007751b0a   running

          In the example output, clustername-8qw5l-master-0 is the control plane machine for the offline node, ip-10-0-131-183.ec2.internal.

       2. Delete the machine of the offline node by running the following command:

          $ oc delete machine -n openshift-machine-api clustername-8qw5l-master-0

          Specify the name of the control plane machine for the offline node.

          A new machine is automatically provisioned after deleting the machine of the offline node.

6. Verify that a new machine has been created by running the following command:

   $ oc get machines -n openshift-machine-api -o wide

   Example output

   NAME                                        PHASE          TYPE        REGION      ZONE         AGE     NODE                           PROVIDERID                              STATE
   clustername-8qw5l-master-1                  Running        m4.xlarge   us-east-1   us-east-1b   3h37m   ip-10-0-143-125.ec2.internal   aws:///us-east-1b/i-096c349b700a19631   running
   clustername-8qw5l-master-2                  Running        m4.xlarge   us-east-1   us-east-1c   3h37m   ip-10-0-154-194.ec2.internal    aws:///us-east-1c/i-02626f1dba9ed5bba  running
   clustername-8qw5l-master-3                  Provisioning   m4.xlarge   us-east-1   us-east-1a   85s     ip-10-0-173-171.ec2.internal    aws:///us-east-1a/i-015b0888fe17bc2c8  running
   clustername-8qw5l-worker-us-east-1a-wbtgd   Running        m4.large    us-east-1   us-east-1a   3h28m   ip-10-0-129-226.ec2.internal   aws:///us-east-1a/i-010ef6279b4662ced   running
   clustername-8qw5l-worker-us-east-1b-lrdxb   Running        m4.large    us-east-1   us-east-1b   3h28m   ip-10-0-144-248.ec2.internal   aws:///us-east-1b/i-0cb45ac45a166173b   running
   clustername-8qw5l-worker-us-east-1c-pkg26   Running        m4.large    us-east-1   us-east-1c   3h28m   ip-10-0-170-181.ec2.internal   aws:///us-east-1c/i-06861c00007751b0a   running

   In the example output, clustername-8qw5l-master-3 is being created and is ready after the phase changes from Provisioning to Running.

   It might take a few minutes for the new machine to be created. The etcd cluster Operator automatically synchronizes when the machine or node returns to a healthy state.

7. For each node that is offline, repeat the previous steps to delete and re-create the node.

8. Wait until the control plane recovers by running the following command:

   $ oc adm wait-for-stable-cluster

   Note

   It can take up to 15 minutes for the control plane to recover.

Procedure

1. Use SSH to connect to the single node and copy the etcd backup to the /home/core directory by running the following command:

   $ cp <etcd_backup_directory> /home/core

2. To restore the cluster from an earlier backup on the single node, run the following command:

   $ sudo -E /usr/local/bin/cluster-restore.sh /home/core/<etcd_backup_directory>

3. Exit the SSH session.

4. Monitor the recovery progress of the control plane by running the following command:

   $ oc adm wait-for-stable-cluster

   Note

   It can take up to 15 minutes for the control plane to recover.

Procedure

1. Select a control plane host to use as the recovery host. This is the host that you run the restore operation on.

2. Establish SSH connectivity to each of the control plane nodes, including the recovery host.

   kube-apiserver becomes inaccessible after the restore process starts, so you cannot access the control plane nodes. Establish SSH connectivity to each control plane host in a separate terminal.

   Important

   If you do not complete this step, you cannot access the control plane hosts to complete the restore procedure, and you cannot recover your cluster from this state.

3. Using SSH, connect to each control plane node to disable etcd by running the following command:

   $ sudo -E /usr/local/bin/disable-etcd.sh

4. Copy the etcd backup directory to the recovery control plane host.

   This procedure assumes that you copied the backup directory containing the etcd snapshot and the resources for the static pods to the /home/core/ directory of your recovery control plane host.

5. Use SSH to connect to the recovery host. Restore the cluster from an earlier backup by running the following command:

   $ sudo -E /usr/local/bin/cluster-restore.sh /home/core/<etcd-backup-directory>

6. Exit the SSH session.

7. When the API responds, turn off the etcd Operator quorum guard by running the following command:

   $ oc patch etcd/cluster --type=merge -p '{"spec": {"unsupportedConfigOverrides": {"useUnsupportedUnsafeNonHANonProductionUnstableEtcd": true}}}'

   Important

   For a TNF setup, do not:

   • Change the etcd Operator quorum setting.
   • Turn the etcd Operator quorum off.
   • Turn the etcd Operator quorum back on.

8. Monitor the recovery progress of the control plane by running the following command:

   $ oc adm wait-for-stable-cluster

   Note

   It can take up to 15 minutes for the control plane to recover. Wait for the control plane to recover before using the next step.

9. Enable the quorum guard by running the following command:

   $ oc patch etcd/cluster --type=merge -p '{"spec": {"unsupportedConfigOverrides": null}}'

Procedure

1. Get the list of current CSRs by running the following command:

   $ oc get csr

   Example output

   NAME        AGE    SIGNERNAME                                    REQUESTOR                                                                   CONDITION
   csr-2s94x   8m3s   kubernetes.io/kubelet-serving                 system:node:<node_name>                                                     Pending
   csr-4bd6t   8m3s   kubernetes.io/kubelet-serving                 system:node:<node_name>                                                     Pending
   csr-4hl85   13m    kubernetes.io/kube-apiserver-client-kubelet   system:serviceaccount:openshift-machine-config-operator:node-bootstrapper   Pending
   csr-zhhhp   3m8s   kubernetes.io/kube-apiserver-client-kubelet   system:serviceaccount:openshift-machine-config-operator:node-bootstrapper   Pending
   ...

   In the example output, CSRs with a SIGNERNAME of kubernetes.io/kubelet-serving are kubelet serving CSRs. You see this CSR type on user-provisioned installations. CSRs with a SIGNERNAME of kubernetes.io/kube-apiserver-client-kubelet and a node-bootstrapper requestor are node-bootstrapper CSRs that you must approve to restore kubelet certificates.

2. Review the details of a CSR to verify that it is valid by running the following command:

   $ oc describe csr <csr_name>

   <csr_name> is the name of a CSR from the list of current CSRs.

3. Approve each valid node-bootstrapper CSR by running the following command:

   $ oc adm certificate approve <csr_name>

4. For user-provisioned installations, approve each valid kubelet serving CSR by running the following command:

   $ oc adm certificate approve <csr_name>