// Module included in the following assemblies:
//
// * support/troubleshooting/troubleshooting-installations.adoc

:_mod-docs-content-type: PROCEDURE
[id="investigating-etcd-installation-issues_{context}"]
= Investigating etcd installation issues

[role="_abstract"]
If you experience etcd issues during installation, you can check etcd pod status and collect etcd pod logs. You can also verify etcd DNS records and check DNS availability on control plane nodes.

.Prerequisites

ifndef::openshift-rosa,openshift-dedicated[]
* You have access to the cluster as a user with the `cluster-admin` role.
endif::openshift-rosa,openshift-dedicated[]
ifdef::openshift-rosa,openshift-dedicated[]
* You have access to the cluster as a user with the `dedicated-admin` role.
endif::openshift-rosa,openshift-dedicated[]
* You have installed the OpenShift CLI (`oc`).
* You have SSH access to your hosts.
* You have the fully qualified domain names of the control plane nodes.

.Procedure

. Check the status of etcd pods.
.. Review the status of pods in the `openshift-etcd` namespace:
+
[source,terminal]
----
$ oc get pods -n openshift-etcd
----
+
.. Review the status of pods in the `openshift-etcd-operator` namespace:
+
[source,terminal]
----
$ oc get pods -n openshift-etcd-operator
----

. If any of the pods listed by the previous commands are not showing a `Running` or a `Completed` status, gather diagnostic information for the pod.
.. Review events for the pod:
+
[source,terminal]
----
$ oc describe pod/<pod_name> -n <namespace>
----
+
.. Inspect the pod's logs:
+
[source,terminal]
----
$ oc logs pod/<pod_name> -n <namespace>
----
+
.. If the pod has more than one container, the preceding command will create an error, and the container names will be provided in the error message. Inspect logs for each container:
+
[source,terminal]
----
$ oc logs pod/<pod_name> -c <container_name> -n <namespace>
----

. If the API is not functional, review etcd pod and container logs on each control plane node by using SSH instead. Replace `<master-node>.<cluster_name>.<base_domain>` with appropriate values.
.. List etcd pods on each control plane node:
+
[source,terminal]
----
$ ssh core@<master-node>.<cluster_name>.<base_domain> sudo crictl pods --name=etcd-
----
+
.. For any pods not showing `Ready` status, inspect pod status in detail. Replace `<pod_id>` with the pod's ID listed in the output of the preceding command:
+
[source,terminal]
----
$ ssh core@<master-node>.<cluster_name>.<base_domain> sudo crictl inspectp <pod_id>
----
+
.. List containers related to a pod:
+
// TODO: Once https://bugzilla.redhat.com/show_bug.cgi?id=1858239 has been resolved, replace the `grep` command below:
//[source,terminal]
//----
//$ ssh core@<master-node>.<cluster_name>.<base_domain> sudo crictl ps --pod=<pod_id>
//----
+
[source,terminal]
----
$ ssh core@<master-node>.<cluster_name>.<base_domain> sudo crictl ps | grep '<pod_id>'
----
+
.. For any containers not showing `Ready` status, inspect container status in detail. Replace `<container_id>` with container IDs listed in the output of the preceding command:
+
[source,terminal]
----
$ ssh core@<master-node>.<cluster_name>.<base_domain> sudo crictl inspect <container_id>
----
+
.. Review the logs for any containers not showing a `Ready` status. Replace `<container_id>` with the container IDs listed in the output of the preceding command:
+
[source,terminal]
----
$ ssh core@<master-node>.<cluster_name>.<base_domain> sudo crictl logs -f <container_id>
----
+
[NOTE]
====
{product-title} {product-version} cluster nodes running {op-system-first} are immutable and rely on Operators to apply cluster changes. Accessing cluster nodes by using SSH is not recommended. Before attempting to collect diagnostic data over SSH, review whether the data collected by running `oc adm must gather` and other `oc` commands is sufficient instead. However, if the {product-title} API is not available, or the kubelet is not properly functioning on the target node, `oc` operations will be impacted. In such situations, it is possible to access nodes using `ssh core@<node>.<cluster_name>.<base_domain>`.
====
+
. Validate primary and secondary DNS server connectivity from control plane nodes.
