Replacing an unhealthy etcd member

To restore etcd quorum when a single member is unhealthy, identify the member and determine whether its machine is stopped, its node is not ready, or its pod is crashlooping. You can then follow the replacement procedure that matches that state.

note

If you have lost the majority of your control plane hosts, follow the steps in "Restoring to an earlier cluster state" instead of this procedure.

If the control plane certificates are not valid on the member being replaced, then you must follow the steps in "Recovering from expired control plane certificates" instead of this procedure.

If a control plane node is lost and a new one is created, the etcd cluster Operator handles generating the new TLS certificates and adding the node as an etcd member.

Identifying an unhealthy etcd member

You can identify an unhealthy etcd member by checking the EtcdMembersAvailable status condition to see how many members are available and which member is unhealthy.

Prerequisites

You have access to the cluster as a user with the cluster-admin role.
You created an etcd backup.

Procedure

Check the status of the EtcdMembersAvailable status condition by running the following command:

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

Example output
2 of 3 members are available, ip-10-0-131-183.ec2.internal is unhealthy

Determining the state of the unhealthy etcd member

Determine whether the unhealthy etcd member has a stopped machine, an unready node, or a crashlooping etcd pod. Knowing the failure state enables you to follow the correct replacement procedure.

Depending on the state of your unhealthy etcd member, use one of the following procedures:

Machine not running or node not ready. For more information, see "Replacing an unhealthy etcd member whose machine is not running or whose node is not ready".
Bare-metal machine not running or node not ready on installer-provisioned bare metal. For more information, see "Replacing an unhealthy bare metal etcd member whose machine is not running or whose node is not ready".
Crashlooping etcd pod. For more information, see "Replacing an unhealthy etcd member whose etcd pod is crashlooping".

note

If the machine is not running or the node is not ready, you might expect either to recover soon. In that case, you do not need to replace the etcd member. The etcd cluster Operator automatically syncs when the machine or node returns to a healthy state.

Prerequisites

You confirmed access to the cluster as a user with the cluster-admin role.
You identified an unhealthy etcd member.

Procedure

Determine if the machine is not running by running the following command:
```
$ oc get machines -A -ojsonpath='{range .items[*]}{@.status.nodeRef.name}{"\t"}{@.status.providerStatus.instanceState}{"\n"}' | grep -v running
```
Example output
```
ip-10-0-131-183.ec2.internal  stopped
```
This output lists the node and the status of the machine of the node. If the status is anything other than running, then the machine is not running.
Determine if the status of the node is NotReady. If either of the following scenarios are true, then the node is not ready.
1. If the machine is running, then check whether the node has an unreachable taint by running the following command:
```
$ oc get nodes -o jsonpath='{range .items[*]}{"\n"}{.metadata.name}{"\t"}{range .spec.taints[*]}{.key}{" "}' | grep unreachable
```
  Example output
```
ip-10-0-131-183.ec2.internal	node-role.kubernetes.io/master node.kubernetes.io/unreachable node.kubernetes.io/unreachable
```
  If the node is listed with an unreachable taint, then the node is not ready.
2. If the node is still reachable, then check whether the node is listed as NotReady by running the following command:
```
$ oc get nodes -l node-role.kubernetes.io/master | grep "NotReady"
```
  Example output
```
ip-10-0-131-183.ec2.internal   NotReady   master   122m   v1.35.4
```
  If the node is listed as NotReady, then the node is not ready.
  
  If the node is not ready, then follow the "Replacing an unhealthy etcd member whose machine is not running or whose node is not ready" procedure.

Determine if the etcd pod is crashlooping. If the machine is running and the node status is Ready, check the status of the etcd pod.

Verify that all control plane nodes are listed as Ready by running the following command:

$ oc get nodes -l node-role.kubernetes.io/master

Example output
NAME                           STATUS   ROLES    AGE     VERSION
ip-10-0-131-183.ec2.internal   Ready    master   6h13m   v1.35.4
ip-10-0-164-97.ec2.internal    Ready    master   6h13m   v1.35.4
ip-10-0-154-204.ec2.internal   Ready    master   6h13m   v1.35.4

Check whether the status of an etcd pod is either Error or CrashloopBackoff 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
```
The etcd pod crashloops because the etcd-ip-10-0-131-183.ec2.internal is Error.

If the etcd pod is crashlooping, then follow the steps in "Replacing an unhealthy etcd member whose etcd pod is crashlooping".

Replacing an unhealthy etcd member whose machine is not running or whose node is not ready

Replace an unhealthy etcd member when the member machine is stopped or the node is not ready. Restoring the member returns the control plane to a healthy state.

note

If your cluster uses a control plane machine set, see "Recovering a degraded etcd Operator" in "Troubleshooting the control plane machine set" for an etcd recovery procedure.

Prerequisites

You identified the unhealthy etcd member.
You verified that either the machine is not running or the node is not ready.
Do not power on other control plane nodes until the unhealthy etcd member replacement is complete.
You confirmed access to the cluster as a user with the cluster-admin role.
You created an etcd backup before replacing the unhealthy etcd member.

warning
Without a recent etcd backup, you might not be able to restore the cluster if replacement fails.

Procedure

Remove the unhealthy member.

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.

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

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.

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

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.

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.

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

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

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

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

Delete the peer secret by running the following command:

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

Delete the serving secret by running the following command:

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

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

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.

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.

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.

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.

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.

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.

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

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

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

Remove the spec.providerID field:

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

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.

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

Create the new machine by using the new-master-machine.yaml file by running the following command:
```
$ oc apply -f new-master-machine.yaml
```

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.

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

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

You can verify that the unsupportedConfigOverrides section is removed from the object by running the following command:
```
$ oc get etcd/cluster -oyaml
```

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

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

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.

Verify that 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 by running the following command:
```
$ oc rsh -n openshift-etcd etcd-ip-10-0-154-204.ec2.internal
```

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.

Additional resources

Replacing an unhealthy etcd member whose etcd pod is crashlooping

Replace an unhealthy etcd member when the etcd pod is crashlooping. Restoring the member returns the control plane to a healthy state.

Prerequisites

You identified the unhealthy etcd member.
You verified that the etcd pod is crashlooping.
You confirmed access to the cluster as a user with the cluster-admin role.
You created an etcd backup before replacing the unhealthy etcd member.

warning
It is important to take an etcd backup before performing this procedure so that your cluster can be restored if you encounter any issues.

Procedure

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

Remove the unhealthy member.

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

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

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.

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

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.

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

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

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

Verify that the unsupportedConfigOverrides section is removed from the object by running the following command:
```
$ oc get etcd/cluster -oyaml
```

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

Verify that the new member is available and healthy.

Connect to the running etcd container by running the following command:
```
$ oc rsh -n openshift-etcd etcd-ip-10-0-154-204.ec2.internal
```

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

sh-4.2# etcdctl endpoint health

Example output
https://10.0.131.183:2379 is healthy: successfully committed proposal: took = 16.671434ms
https://10.0.154.204:2379 is healthy: successfully committed proposal: took = 16.698331ms
https://10.0.164.97:2379 is healthy: successfully committed proposal: took = 16.621645ms

Replacing an unhealthy bare metal etcd member whose machine is not running or whose node is not ready

Replace an unhealthy bare metal etcd member when the machine is not running or the node is not ready. Restoring the member returns the control plane to a healthy state.

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 node using the same method that was used to originally create it.

Prerequisites

You identified the unhealthy bare metal etcd member.
You verified that either the machine is not running or the node is not ready.
You confirmed access to the cluster as a user with the cluster-admin role.
You created an etcd backup.

warning
You must take an etcd backup before performing this procedure so that your cluster can be restored if you encounter any issues.

Procedure

Verify and remove the unhealthy member.

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>

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

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.

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

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.

warning

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

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.

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

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

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

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

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

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.

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

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

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.

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

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

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

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.

warning

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.

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

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

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

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

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

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

You can verify that the unsupportedConfigOverrides section is removed from the object by running the following command:
```
$ oc get etcd/cluster -oyaml
```

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

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

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.

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

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

Additional resources

Identifying an unhealthy etcd member​

Determining the state of the unhealthy etcd member​

Replacing an unhealthy etcd member whose machine is not running or whose node is not ready​

Replacing an unhealthy etcd member whose etcd pod is crashlooping​

Replacing an unhealthy bare metal etcd member whose machine is not running or whose node is not ready​

Identifying an unhealthy etcd member

Determining the state of the unhealthy etcd member

Replacing an unhealthy etcd member whose machine is not running or whose node is not ready

Replacing an unhealthy etcd member whose etcd pod is crashlooping

Replacing an unhealthy bare metal etcd member whose machine is not running or whose node is not ready