Chapter 5. Control plane backup and restore

Procedure

1. Create a FeatureGate custom resource (CR) file named enable-tech-preview-no-upgrade.yaml with the following contents:

   apiVersion: config.openshift.io/v1
   kind: FeatureGate
   metadata:
     name: cluster
   spec:
     featureSet: TechPreviewNoUpgrade

   Copy to Clipboard Toggle word wrap

2. Apply the CR and enable automated backups:

   $ oc apply -f enable-tech-preview-no-upgrade.yaml

   Copy to Clipboard Toggle word wrap

3. It takes time to enable the related APIs. Verify the creation of the custom resource definition (CRD) by running the following command:

   $ oc get crd | grep backup

   Copy to Clipboard Toggle word wrap

   Example output

   backups.config.openshift.io 2023-10-25T13:32:43Z
   etcdbackups.operator.openshift.io 2023-10-25T13:32:04Z

   Copy to Clipboard Toggle word wrap

Procedure

1. 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: etcd-backup-pvc 

   1

   Copy to Clipboard Toggle word wrap

   1

   The name of the persistent volume claim (PVC) to save the backup to. Adjust this value according to your environment.

2. Apply the CR to start a single backup:

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

   Copy to Clipboard Toggle word wrap

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 

      1

      
        storageClassName: standard-csi 

      2

      
        volumeMode: Filesystem

      Copy to Clipboard Toggle word wrap

      1

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

      2

      The name of the StorageClass required by the claim. Adjust this value according to your environment.

      Note

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

      Expand

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

      Show more

   2. Apply the PVC by running the following command:

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

      Copy to Clipboard Toggle word wrap

   3. Verify the creation of the PVC by running the following command:

      $ oc get pvc

      Copy to Clipboard Toggle word wrap

      Example output

      NAME              STATUS    VOLUME   CAPACITY   ACCESS MODES   STORAGECLASS   AGE
      etcd-backup-pvc   Pending                                      standard-csi   51s

      Copy to Clipboard Toggle word wrap

      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: WaitForFirstConsumer

      Copy to Clipboard Toggle word wrap

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

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

      Copy to Clipboard Toggle word wrap

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

      apiVersion: v1
      kind: PersistentVolume
      metadata:
        name: etcd-backup-pv-fs
      spec:
        capacity:
          storage: 100Gi 

      1

      
        volumeMode: Filesystem
        accessModes:
        - ReadWriteMany
        persistentVolumeReclaimPolicy: Delete
        storageClassName: local-storage
        local:
          path: /mnt/
        nodeAffinity:
          required:
            nodeSelectorTerms:
            - matchExpressions:
              - key: kubernetes.io/hostname
                operator: In
                values:
                - <example-master-node> 

      2

      Copy to Clipboard Toggle word wrap

      1

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

      2

      Replace this value with the node to attach this PV to.

      Tip

      Run the following command to list the available nodes:

      $ oc get nodes

      Copy to Clipboard Toggle word wrap

   4. Verify the creation of the PV by running the following command:

      $ oc get pv

      Copy to Clipboard Toggle word wrap

      Example output

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

      Copy to Clipboard Toggle word wrap

   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 

      1

      
        storageClassName: local-storage

      Copy to Clipboard Toggle word wrap

      1

      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

      Copy to Clipboard Toggle word wrap

3. Create a custom resource definition (CRD) file named etcd-recurring-backups.yaml. The contents of the created CRD 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 * * *" 

   1

   
       timeZone: "UTC"
       pvcName: etcd-backup-pvc

   Copy to Clipboard Toggle word wrap

   1

   The CronTab schedule for recurring backups. Adjust this value for your needs.

   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 

   1

   
         retentionNumber:
           maxNumberOfBackups: 5 

   2

   Copy to Clipboard Toggle word wrap

   1

   The retention type. Defaults to RetentionNumber if unspecified.

   2

   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.

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

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

   1

   Copy to Clipboard Toggle word wrap

   1

   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

   Copy to Clipboard Toggle word wrap

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

   $ oc get cronjob -n openshift-etcd

   Copy to Clipboard Toggle word wrap

Procedure

1. Remove the unhealthy member.

   1. Choose a pod that is not on the affected node:

      In a terminal that has access to the cluster as a cluster-admin user, run the following command:

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

      Copy to Clipboard Toggle word wrap

      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

      Copy to Clipboard Toggle word wrap

   2. Connect to the running etcd container, passing in the name of a pod that is 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-ip-10-0-154-204.ec2.internal

      Copy to Clipboard Toggle word wrap

   3. View the member list:

      sh-4.2# etcdctl member list -w table

      Copy to Clipboard Toggle word wrap

      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 |
      +------------------+---------+------------------------------+---------------------------+---------------------------+

      Copy to Clipboard Toggle word wrap

      Take note of the ID and the name of the unhealthy etcd member because these values are needed later in the procedure. The $ etcdctl endpoint health command will list the removed member until the procedure of replacement is finished and a new member is added.

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

      sh-4.2# etcdctl member remove 6fc1e7c9db35841d

      Copy to Clipboard Toggle word wrap

      Example output

      Member 6fc1e7c9db35841d removed from cluster ead669ce1fbfb346

      Copy to Clipboard Toggle word wrap

   5. View the member list again and verify that the member was removed:

      sh-4.2# etcdctl member list -w table

      Copy to Clipboard Toggle word wrap

      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 |
      +------------------+---------+------------------------------+---------------------------+---------------------------+

      Copy to Clipboard Toggle word wrap

      You can now exit the node shell.

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

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

   Copy to Clipboard Toggle word wrap

   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 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>

   Copy to Clipboard Toggle word wrap

   Example command

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

   Copy to Clipboard Toggle word wrap

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.

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

      1

      Copy to Clipboard Toggle word wrap

      1

      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:

      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

      Copy to Clipboard Toggle word wrap

   2. Delete the secrets for the unhealthy etcd member that was removed.

      1. Delete the peer secret:

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

         Copy to Clipboard Toggle word wrap

      2. Delete the serving secret:

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

         Copy to Clipboard Toggle word wrap

      3. Delete the metrics secret:

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

         Copy to Clipboard Toggle word wrap

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

   $ oc -n openshift-machine-api get controlplanemachineset

   Copy to Clipboard Toggle word wrap

   • 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.

        In a terminal that has access to the cluster as a cluster-admin user, run the following command:

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

        Copy to Clipboard Toggle word wrap

        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 

        1

        
        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

        Copy to Clipboard Toggle word wrap

        1

        This is the control plane machine for the unhealthy node, ip-10-0-131-183.ec2.internal.

     2. Delete the machine of the unhealthy member:

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

        1

        Copy to Clipboard Toggle word wrap

        1

        Specify 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:

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

        Copy to Clipboard Toggle word wrap

        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 

        1

        
        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

        Copy to Clipboard Toggle word wrap

        1

        The new machine, clustername-8qw5l-master-3 is being created and is ready once 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.

     1. Obtain the machine for the unhealthy member.

        In a terminal that has access to the cluster as a cluster-admin user, run the following command:

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

        Copy to Clipboard Toggle word wrap

        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 

        1

        
        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

        Copy to Clipboard Toggle word wrap

        1

        This is the control plane machine for the unhealthy node, ip-10-0-131-183.ec2.internal.

     2. Save the machine configuration to a file on your file system:

        $ oc get machine clustername-8qw5l-master-0 \ 

        1

        
            -n openshift-machine-api \
            -o yaml \
            > new-master-machine.yaml

        Copy to Clipboard Toggle word wrap

        1

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

     3. 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

           Copy to Clipboard Toggle word wrap

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

           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.

           For example:

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

           Copy to Clipboard Toggle word wrap

        3. Remove the spec.providerID field:

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

           Copy to Clipboard Toggle word wrap

     4. Delete the machine of the unhealthy member:

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

        1

        Copy to Clipboard Toggle word wrap

        1

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

     5. Verify that the machine was deleted:

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

        Copy to Clipboard Toggle word wrap

        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

        Copy to Clipboard Toggle word wrap

     6. Create the new machine by using the new-master-machine.yaml file:

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

        Copy to Clipboard Toggle word wrap

     7. Verify that the new machine was created:

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

        Copy to Clipboard Toggle word wrap

        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 

        1

        
        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

        Copy to Clipboard Toggle word wrap

        1

        The new machine, clustername-8qw5l-master-3 is being created and is ready once 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.

6. Turn the quorum guard back on by entering the following command:

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

   Copy to Clipboard Toggle word wrap

7. You can verify that the unsupportedConfigOverrides section is removed from the object by entering this command:

   $ oc get etcd/cluster -oyaml

   Copy to Clipboard Toggle word wrap

8. 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]

   Copy to Clipboard Toggle word wrap

Verification

1. Verify that all etcd pods are running properly.

   In a terminal that has access to the cluster as a cluster-admin user, run the following command:

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

   Copy to Clipboard Toggle word wrap

   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

   Copy to Clipboard Toggle word wrap

   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 

   1

   Copy to Clipboard Toggle word wrap

   1

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

2. 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:

      In a terminal that has access to the cluster as a cluster-admin user, run the following command:

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

      Copy to Clipboard Toggle word wrap

   2. View the member list:

      sh-4.2# etcdctl member list -w table

      Copy to Clipboard Toggle word wrap

      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 |
      +------------------+---------+------------------------------+---------------------------+---------------------------+

      Copy to Clipboard Toggle word wrap

      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.

      In a terminal that has access to the cluster as a cluster-admin user, run the following command:

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

      1

      Copy to Clipboard Toggle word wrap

      1

      Replace this with the name of the unhealthy node.

   2. Change your root directory to /host:

      sh-4.2# chroot /host

      Copy to Clipboard Toggle word wrap

   3. Move the existing etcd pod file out of the kubelet manifest directory:

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

      Copy to Clipboard Toggle word wrap

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

      Copy to Clipboard Toggle word wrap

   4. Move the etcd data directory to a different location:

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

      Copy to Clipboard Toggle word wrap

      You can now exit the node shell.

2. Remove the unhealthy member.

   1. Choose a pod that is not on the affected node.

      In a terminal that has access to the cluster as a cluster-admin user, run the following command:

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

      Copy to Clipboard Toggle word wrap

      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

      Copy to Clipboard Toggle word wrap

   2. Connect to the running etcd container, passing in the name of a pod that is 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-ip-10-0-154-204.ec2.internal

      Copy to Clipboard Toggle word wrap

   3. View the member list:

      sh-4.2# etcdctl member list -w table

      Copy to Clipboard Toggle word wrap

      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 |
      +------------------+---------+------------------------------+---------------------------+---------------------------+

      Copy to Clipboard Toggle word wrap

      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

      Copy to Clipboard Toggle word wrap

      Example output

      Member 62bcf33650a7170a removed from cluster ead669ce1fbfb346

      Copy to Clipboard Toggle word wrap

   5. View the member list again and verify that the member was removed:

      sh-4.2# etcdctl member list -w table

      Copy to Clipboard Toggle word wrap

      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 |
      +------------------+---------+------------------------------+---------------------------+---------------------------+

      Copy to Clipboard Toggle word wrap

      You can now exit the node shell.

3. Turn off the quorum guard by entering the following command:

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

   Copy to Clipboard Toggle word wrap

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

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.

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

      1

      Copy to Clipboard Toggle word wrap

      1

      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:

      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

      Copy to Clipboard Toggle word wrap

   2. Delete the secrets for the unhealthy etcd member that was removed.

      1. Delete the peer secret:

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

         Copy to Clipboard Toggle word wrap

      2. Delete the serving secret:

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

         Copy to Clipboard Toggle word wrap

      3. Delete the metrics secret:

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

         Copy to Clipboard Toggle word wrap

5. Force 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": "single-master-recovery-'"$( date --rfc-3339=ns )"'"}}' --type=merge 

   1

   Copy to Clipboard Toggle word wrap

   1

   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.

6. Turn the quorum guard back on by entering the following command:

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

   Copy to Clipboard Toggle word wrap

7. You can verify that the unsupportedConfigOverrides section is removed from the object by entering this command:

   $ oc get etcd/cluster -oyaml

   Copy to Clipboard Toggle word wrap

8. 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]

   Copy to Clipboard Toggle word wrap

Procedure

1. Verify and remove the unhealthy member.

   1. Choose a pod that is not on the affected node:

      In a terminal that has access to the cluster as a cluster-admin user, run the following command:

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

      Copy to Clipboard Toggle word wrap

      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>

      Copy to Clipboard Toggle word wrap

   2. Connect to the running etcd container, passing in the name of a pod that is 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

      Copy to Clipboard Toggle word wrap

   3. View the member list:

      sh-4.2# etcdctl member list -w table

      Copy to Clipboard Toggle word wrap

      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 |
      +------------------+---------+--------------------+---------------------------+---------------------------+---------------------+

      Copy to Clipboard Toggle word wrap

      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 will list the removed member until the replacement procedure is completed and the new member is added.

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

      Warning

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

      sh-4.2# etcdctl member remove 7a8197040a5126c8

      Copy to Clipboard Toggle word wrap

      Example output

      Member 7a8197040a5126c8 removed from cluster b23536c33f2cdd1b

      Copy to Clipboard Toggle word wrap

   5. View the member list again and verify that the member was removed:

      sh-4.2# etcdctl member list -w table

      Copy to Clipboard Toggle word wrap

      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 |
      +------------------+---------+--------------------+---------------------------+---------------------------+-------------------------+

      Copy to Clipboard Toggle word wrap

      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 entering the following command:

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

   Copy to Clipboard Toggle word wrap

   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 by running the following commands.

   1. List the secrets for the unhealthy etcd member that was removed.

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

      Copy to Clipboard Toggle word wrap

      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

      Copy to Clipboard Toggle word wrap

   2. Delete the secrets for the unhealthy etcd member that was removed.

      1. Delete the peer secret:

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

         Copy to Clipboard Toggle word wrap

      2. Delete the serving secret:

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

         Copy to Clipboard Toggle word wrap

      3. Delete the metrics secret:

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

         Copy to Clipboard Toggle word wrap

4. Obtain the machine for the unhealthy member.

   In a terminal that has access to the cluster as a cluster-admin user, run the following command:

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

   Copy to Clipboard Toggle word wrap

   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 

   1

   
   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

   Copy to Clipboard Toggle word wrap

   1

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

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

   $ oc get clusteroperator baremetal

   Copy to Clipboard Toggle word wrap

   Example output

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

   Copy to Clipboard Toggle word wrap

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

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

   Copy to Clipboard Toggle word wrap

   Example output

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

   Copy to Clipboard Toggle word wrap

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

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

   Copy to Clipboard Toggle word wrap

   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

      Copy to Clipboard Toggle word wrap

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

      finalizers:
      - machine.machine.openshift.io

      Copy to Clipboard Toggle word wrap

      Example output

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

      Copy to Clipboard Toggle word wrap

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

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

   Copy to Clipboard Toggle word wrap

   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

   Copy to Clipboard Toggle word wrap

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

   $ oc get nodes
   
   NAME                     STATUS ROLES   AGE   VERSION
   openshift-control-plane-0 Ready master 3h24m v1.27.3
   openshift-control-plane-1 Ready master 3h24m v1.27.3
   openshift-compute-0       Ready worker 176m v1.27.3
   openshift-compute-1       Ready worker 176m v1.27.3

   Copy to Clipboard Toggle word wrap

10. Create the new BareMetalHost object and the secret to store the BMC credentials:

    $ 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

    Copy to Clipboard Toggle word wrap
    Note

    The username and password can be found from the other bare metal host’s secrets. 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:

    $ oc get bmh -n openshift-machine-api
    
    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 available              examplecluster-control-plane-3 true         47m
    openshift-compute-0       provisioned            examplecluster-compute-0       true         4h48m
    openshift-compute-1       provisioned            examplecluster-compute-1       true         4h48m

    Copy to Clipboard Toggle word wrap

    1. Verify that a new machine has been created:

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

       Copy to Clipboard Toggle word wrap

       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 

       1

       
       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

       Copy to Clipboard Toggle word wrap

       1

       The new machine, clustername-8qw5l-master-3 is being created and is ready after the phase changes from Provisioning to Running.

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

    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

       Copy to Clipboard Toggle word wrap

       Example output

       $ oc get bmh -n openshift-machine-api
       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

       Copy to Clipboard Toggle word wrap

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

       $ oc get nodes

       Copy to Clipboard Toggle word wrap

       Example output

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

       Copy to Clipboard Toggle word wrap

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

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

    Copy to Clipboard Toggle word wrap

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

    $ oc get etcd/cluster -oyaml

    Copy to Clipboard Toggle word wrap

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]

    Copy to Clipboard Toggle word wrap

Verification

1. Verify that all etcd pods are running properly.

   In a terminal that has access to the cluster as a cluster-admin user, run the following command:

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

   Copy to Clipboard Toggle word wrap

   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

   Copy to Clipboard Toggle word wrap

   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 

   1

   Copy to Clipboard Toggle word wrap

   1

   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

   Copy to Clipboard Toggle word wrap

2. View the member list:

   sh-4.2# etcdctl member list -w table

   Copy to Clipboard Toggle word wrap

   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 |
   +------------------+---------+--------------------+---------------------------+---------------------------+-----------------+

   Copy to Clipboard Toggle word wrap

   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

   Copy to Clipboard Toggle word wrap

   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

   Copy to Clipboard Toggle word wrap

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"}'

   Copy to Clipboard Toggle word wrap

   AllNodesAtLatestRevision

   Copy to Clipboard Toggle word wrap

Procedure

1. Select a control plane host to use as the recovery host. This is the host that you will 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. For this reason, it is recommended to establish SSH connectivity to each control plane host in a separate terminal.

   Important

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

3. 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.

4. Stop the static pods on any other control plane nodes.

   Note

   You do not need to stop the static pods on the recovery host.

   1. Access a control plane host that is not the recovery host.

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

      $ sudo mv -v /etc/kubernetes/manifests/etcd-pod.yaml /tmp

      Copy to Clipboard Toggle word wrap

   3. Verify that the etcd pods are stopped by using:

      $ sudo crictl ps | grep etcd | egrep -v "operator|etcd-guard"

      Copy to Clipboard Toggle word wrap

      If the output of this command is not empty, wait a few minutes and check again.

   4. Move the existing kube-apiserver file out of the kubelet manifest directory by running:

      $ sudo mv -v /etc/kubernetes/manifests/kube-apiserver-pod.yaml /tmp

      Copy to Clipboard Toggle word wrap

   5. Verify that the kube-apiserver containers are stopped by running:

      $ sudo crictl ps | grep kube-apiserver | egrep -v "operator|guard"

      Copy to Clipboard Toggle word wrap

      If the output of this command is not empty, wait a few minutes and check again.

   6. Move the existing kube-controller-manager file out of the kubelet manifest directory by using:

      $ sudo mv -v /etc/kubernetes/manifests/kube-controller-manager-pod.yaml /tmp

      Copy to Clipboard Toggle word wrap

   7. Verify that the kube-controller-manager containers are stopped by running:

      $ sudo crictl ps | grep kube-controller-manager | egrep -v "operator|guard"

      Copy to Clipboard Toggle word wrap

      If the output of this command is not empty, wait a few minutes and check again.

   8. Move the existing kube-scheduler file out of the kubelet manifest directory by using:

      $ sudo mv -v /etc/kubernetes/manifests/kube-scheduler-pod.yaml /tmp

      Copy to Clipboard Toggle word wrap

   9. Verify that the kube-scheduler containers are stopped by using:

      $ sudo crictl ps | grep kube-scheduler | egrep -v "operator|guard"

      Copy to Clipboard Toggle word wrap

      If the output of this command is not empty, wait a few minutes and check again.

   10. Move the etcd data directory to a different location with the following example:

       $ sudo mv -v /var/lib/etcd/ /tmp

       Copy to Clipboard Toggle word wrap

   11. If the /etc/kubernetes/manifests/keepalived.yaml file exists and the node is deleted, follow these steps:

       1. Move the /etc/kubernetes/manifests/keepalived.yaml file out of the kubelet manifest directory:

          $ sudo mv -v /etc/kubernetes/manifests/keepalived.yaml /tmp

          Copy to Clipboard Toggle word wrap

       2. Verify that any containers managed by the keepalived daemon are stopped:

          $ sudo crictl ps --name keepalived

          Copy to Clipboard Toggle word wrap

          The output of this command should be empty. If it is not empty, wait a few minutes and check again.

       3. Check if the control plane has any Virtual IPs (VIPs) assigned to it:

          $ ip -o address | egrep '<api_vip>|<ingress_vip>'

          Copy to Clipboard Toggle word wrap

       4. For each reported VIP, run the following command to remove it:

          $ sudo ip address del <reported_vip> dev <reported_vip_device>

          Copy to Clipboard Toggle word wrap
   12. Repeat this step on each of the other control plane hosts that is not the recovery host.
5. Access the recovery control plane host.

6. If the keepalived daemon is in use, verify that the recovery control plane node owns the VIP:

   $ ip -o address | grep <api_vip>

   Copy to Clipboard Toggle word wrap

   The address of the VIP is highlighted in the output if it exists. This command returns an empty string if the VIP is not set or configured incorrectly.

7. If the cluster-wide proxy is enabled, be sure that you have exported the NO_PROXY, HTTP_PROXY, and HTTPS_PROXY environment variables.

   Tip

   You can check whether the proxy is enabled by reviewing the output of oc get proxy cluster -o yaml. The proxy is enabled if the httpProxy, httpsProxy, and noProxy fields have values set.

8. Run the restore script on the recovery control plane host and pass in the path to the etcd backup directory:

   $ sudo -E /usr/local/bin/cluster-restore.sh /home/core/assets/backup

   Copy to Clipboard Toggle word wrap

   Example script output

   ...stopping kube-scheduler-pod.yaml
   ...stopping kube-controller-manager-pod.yaml
   ...stopping etcd-pod.yaml
   ...stopping kube-apiserver-pod.yaml
   Waiting for container etcd to stop
   .complete
   Waiting for container etcdctl to stop
   .............................complete
   Waiting for container etcd-metrics to stop
   complete
   Waiting for container kube-controller-manager to stop
   complete
   Waiting for container kube-apiserver to stop
   ..........................................................................................complete
   Waiting for container kube-scheduler to stop
   complete
   Moving etcd data-dir /var/lib/etcd/member to /var/lib/etcd-backup
   starting restore-etcd static pod
   starting kube-apiserver-pod.yaml
   static-pod-resources/kube-apiserver-pod-7/kube-apiserver-pod.yaml
   starting kube-controller-manager-pod.yaml
   static-pod-resources/kube-controller-manager-pod-7/kube-controller-manager-pod.yaml
   starting kube-scheduler-pod.yaml
   static-pod-resources/kube-scheduler-pod-8/kube-scheduler-pod.yaml

   Copy to Clipboard Toggle word wrap

   The cluster-restore.sh script must show that etcd, kube-apiserver, kube-controller-manager, and kube-scheduler pods are stopped and then started at the end of the restore process.

   Note

   The restore process can cause nodes to enter the NotReady state if the node certificates were updated after the last etcd backup.

9. Check the nodes to ensure they are in the Ready state.

   1. Run the following command:

      $ oc get nodes -w

      Copy to Clipboard Toggle word wrap

      Sample output

      NAME                STATUS  ROLES          AGE     VERSION
      host-172-25-75-28   Ready   master         3d20h   v1.27.3
      host-172-25-75-38   Ready   infra,worker   3d20h   v1.27.3
      host-172-25-75-40   Ready   master         3d20h   v1.27.3
      host-172-25-75-65   Ready   master         3d20h   v1.27.3
      host-172-25-75-74   Ready   infra,worker   3d20h   v1.27.3
      host-172-25-75-79   Ready   worker         3d20h   v1.27.3
      host-172-25-75-86   Ready   worker         3d20h   v1.27.3
      host-172-25-75-98   Ready   infra,worker   3d20h   v1.27.3

      Copy to Clipboard Toggle word wrap

      It can take several minutes for all nodes to report their state.

   2. If any nodes are in the NotReady state, log in to the nodes and remove all of the PEM files from the /var/lib/kubelet/pki directory on each node. You can SSH into the nodes or use the terminal window in the web console.

      $  ssh -i <ssh-key-path> core@<master-hostname>

      Copy to Clipboard Toggle word wrap

      Sample pki directory

      sh-4.4# pwd
      /var/lib/kubelet/pki
      sh-4.4# ls
      kubelet-client-2022-04-28-11-24-09.pem  kubelet-server-2022-04-28-11-24-15.pem
      kubelet-client-current.pem              kubelet-server-current.pem

      Copy to Clipboard Toggle word wrap

10. Restart the kubelet service on all control plane hosts.

    1. From the recovery host, run:

       $ sudo systemctl restart kubelet.service

       Copy to Clipboard Toggle word wrap
    2. Repeat this step on all other control plane hosts.

11. Approve the pending Certificate Signing Requests (CSRs):

    Note

    Clusters with no worker nodes, such as single-node clusters or clusters consisting of three schedulable control plane nodes, will not have any pending CSRs to approve. You can skip all the commands listed in this step.

    1. Get the list of current CSRs by running:

       $ oc get csr

       Copy to Clipboard Toggle word wrap

       Example output

       NAME        AGE    SIGNERNAME                                    REQUESTOR                                                                   CONDITION
       csr-2s94x   8m3s   kubernetes.io/kubelet-serving                 system:node:<node_name>                                                     Pending 

       1

       
       csr-4bd6t   8m3s   kubernetes.io/kubelet-serving                 system:node:<node_name>                                                     Pending 

       2

       
       csr-4hl85   13m    kubernetes.io/kube-apiserver-client-kubelet   system:serviceaccount:openshift-machine-config-operator:node-bootstrapper   Pending 

       3

       
       csr-zhhhp   3m8s   kubernetes.io/kube-apiserver-client-kubelet   system:serviceaccount:openshift-machine-config-operator:node-bootstrapper   Pending 

       4

       
       ...

       Copy to Clipboard Toggle word wrap

       1 2

       A pending kubelet serving CSR, requested by the node for the kubelet serving endpoint.

       3 4

       A pending kubelet client CSR, requested with the node-bootstrapper node bootstrap credentials.

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

       $ oc describe csr <csr_name> 

       1

       Copy to Clipboard Toggle word wrap

       1

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

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

       $ oc adm certificate approve <csr_name>

       Copy to Clipboard Toggle word wrap

    4. For user-provisioned installations, approve each valid kubelet service CSR by running:

       $ oc adm certificate approve <csr_name>

       Copy to Clipboard Toggle word wrap

12. Verify that the single member control plane has started successfully.

    1. From the recovery host, verify that the etcd container is running by using:

       $ sudo crictl ps | grep etcd | egrep -v "operator|etcd-guard"

       Copy to Clipboard Toggle word wrap

       Example output

       3ad41b7908e32       36f86e2eeaaffe662df0d21041eb22b8198e0e58abeeae8c743c3e6e977e8009                                                         About a minute ago   Running             etcd                                          0                   7c05f8af362f0

       Copy to Clipboard Toggle word wrap

    2. From the recovery host, verify that the etcd pod is running by using:

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

       Copy to Clipboard Toggle word wrap

       Example output

       NAME                                             READY   STATUS      RESTARTS   AGE
       etcd-ip-10-0-143-125.ec2.internal                1/1     Running     1          2m47s

       Copy to Clipboard Toggle word wrap

       If the status is Pending, or the output lists more than one running etcd pod, wait a few minutes and check again.

13. If you are using the OVNKubernetes network plugin, you must restart ovnkube-controlplane pods.

    1. Delete all of the ovnkube-controlplane pods by running:

       $ oc -n openshift-ovn-kubernetes delete pod -l app=ovnkube-control-plane

       Copy to Clipboard Toggle word wrap

    2. Verify that all of the ovnkube-controlplane pods were redeployed by using:

       $ oc -n openshift-ovn-kubernetes get pod -l app=ovnkube-control-plane

       Copy to Clipboard Toggle word wrap

14. If you are using the OVN-Kubernetes network plugin, restart the Open Virtual Network (OVN) Kubernetes pods on all the nodes one by one. Use the following steps to restart OVN-Kubernetes pods on each node:

    Important

    Restart OVN-Kubernetes pods in the following order:

    1. The recovery control plane host
    2. The other control plane hosts (if available)
    3. The other nodes
    Note

    Validating and mutating admission webhooks can reject pods. If you add any additional webhooks with the failurePolicy set to Fail, then they can reject pods and the restoration process can fail. You can avoid this by saving and deleting webhooks while restoring the cluster state. After the cluster state is restored successfully, you can enable the webhooks again.

    Alternatively, you can temporarily set the failurePolicy to Ignore while restoring the cluster state. After the cluster state is restored successfully, you can set the failurePolicy to Fail.