# The Definitive Debugging Guide for the cert-manager Webhook Pod > ✨ This page will be copied over to cert-manager.io to gain visibility, see the pull request [#1002](https://github.com/cert-manager/website/pull/1002 "Validation webhook troubleshooting: add a step by step guide"). This page was last updated on 5 Sept 2022 (cert-manager 1.9). The cert-manager webhook is a pod that runs as part of your cert-manager installation. When applying a manifest with `kubectl`, the Kubernetes API server calls the cert-manager webhook over TLS to validate your manifests. This guide helps you debug connectivity issues between the Kubernetes API server and the cert-manager webhook pod. The error messages listed in this page are encountered while installing or upgrading cert-manager, or shortly after installing or upgrading cert-manager when trying to create a Certificate, Issuer, or any other cert-manager custom resource. > Last updated on 7 Sept 2022 (cert-manager 1.9). In the below diagram, we show the common pattern when debugging an issue with the cert-manager webhook: when creating a cert-manager custom resource, the API server connects over TLS to the cert-manager webhook pod. The red cross indicates that the API server fails talking to the webhook. <img alt="Diagram that shows a kubectl command that aims to create an issuer resource, and an arrow towards the Kubernetes apiserver, and an arrow between the apiserver and the webhook that indicates that the apiserver tries to connect to the webhook. This last arrow is crossed in red." src="https://i.imgur.com/9rIBMeC.png" width="500"/> The rest of this document presents the known error messages that you may encounter. ## Error 1: `connect: connection refused` > This issue was reported in 4 GitHub issues ([#2736](https://github.com/jetstack/cert-manager/issues/2736 "Getting WebHook Connection Refused error when using Azure DevOps Pipelines"), [#3133](https://github.com/jetstack/cert-manager/issues/3133 "Failed calling webhook webhook.cert-manager.io: connect: connection refused"), [#3445](https://github.com/jetstack/cert-manager/issues/3445 "Connection refused for cert-manager-webhook service"), [#4425](https://github.com/cert-manager/cert-manager/issues/4425 "Webhook error")), was reported in 1 GitHub issue in an external project ([`aws-load-balancer-controller#1563`](https://github.com/kubernetes-sigs/aws-load-balancer-controller/issues/1563 "Internal error occurred: failed calling webhook webhook.cert-manager.io, no endpoints available")), on Stack Overflow ([`serverfault#1076563`](https://web.archive.org/web/20210903183221/https://serverfault.com/questions/1076563/creating-issuer-for-kubernetes-cert-manager-is-causing-404-and-500-error "Creating issuer for kubernetes cert-manager is causing 404 and 500 error")), and was mentioned in 13 Slack messages that can be listed with the search `in:#cert-manager in:#cert-manager-dev ":443: connect: connection refused"`. This error message can also be found in other projects that are building webhooks ([`kubewarden-controller#110`](https://github.com/kubewarden/kubewarden-controller/issues/110 "Investigate failure on webhooks not ready when installing cert-manager from helm chart: connection refused")). Shortly after installing or upgrading cert-manager, you may hit this error when creating a Certificate, Issuer, or any other cert-manager custom resource. For example, creating an Issuer resource with the following command: ```sh kubectl apply -f- <<EOF apiVersion: cert-manager.io/v1 kind: Issuer metadata: name: example spec: selfSigned: {} EOF ``` shows the following error message: ```text Error from server (InternalError): error when creating "STDIN": Internal error occurred: failed calling webhook "webhook.cert-manager.io": failed to call webhook: Post "https://cert-manager-webhook.cert-manager.svc:443/mutate?timeout=10s": dial tcp 10.96.20.99:443: connect: connection refused ``` When installing or upgrading cert-manager 1.5.0 and above with Helm, a very similar error message may appear when running `helm install` or `helm upgrade`: ```text Error: INSTALLATION FAILED: Internal error occurred: failed calling webhook "webhook.cert-manager.io": failed to call webhook: Post "https://cert-manager-webhook.cert-manager.svc:443/mutate?timeout=10s": dial tcp 10.96.20.99:443: connect: connection refused ``` The message "connection refused" happens when the API server tries to establish a TCP connection with the cert-manager-webhook. In TCP terms, the API server sent the `SYN` packet to start the TCP handshake, and received an `RST` packet in return. If we were to use [`tcpdump`](https://www.tcpdump.org/manpages/tcpdump.1.html) inside the control plane node where the API server is running, we would see a packet returned to the API server: ```text 192.168.1.43 (apiserver) -> 10.96.20.99 (webhook pod) TCP 59466 → 443 [SYN] 10.96.20.99 (webhook pod) -> 192.168.1.43 (apiserver) TCP 443 → 59466 [RST, ACK] ``` The `RST` packet is sent by the Linux kernel when nothing is listening to the requested port. The `RST` packet can also be returned by one of the TCP hops, e.g., a firewall, as detailed in the Stack Overflow page [What can be the reasons of connection refused errors?](https://stackoverflow.com/a/2333446/3808537). Note that firewalls usually don't return an `RST` packet; they usually drop the `SYN` packet entirely, and you end up with the error message `i/o timeout` or `context deadline exceeded`. If that is the case, continue your investigation with the section [Error 2: `i/o timeout` (connectivity issue)](#io-timeout) and [Error 8: `context deadline exceeded`](#context-deadline-exceeded) respectively. Let's eliminate the possible causes from the closest to the source of the TCP connection (the API server) to its destination (the pod `cert-manager-webhook`). Let's imagine that the name `cert-manager-webhook.cert-manager.svc` was resolved to 10.43.183.232. This is a cluster IP. The control plane node, in which the API server process runs, uses its iptables to rewrite the IP destination using the pod IP. That might be the first problem: sometimes, no pod IP is associated with a given cluster IP because the kubelet doesn't fill in the Endpoint resource with pod IPs as long as the readiness probe doesn't work. Let us first check whether it is a problem with the Endpoint resource: ```sh kubectl get endpoints -n cert-manager cert-manager-webhook ``` A valid output would look like this: ```text NAME ENDPOINTS AGE cert-manager-webhook 10.244.0.2:10250 27d ✅ ``` If you have this valid output and have the `connect: connection refused`, then the issue is deeper in the networking stack. We won't dig into this case, but you might want to use `tcpdump` and Wireshark to see whether traffic properly flows from the API server to the node's host namespace. The traffic from the host namespace to the pod's namespace already works fine since the kubelet was already able to reach the readiness endpoint. Common issues include firewall dropping traffic from the control plane to workers; for example, the API server on GKE is only allowed to talk to worker nodes (which is where the cert-manager webhook is running) over port 10250. In EKS, your security groups might deny traffic from your control plane VPC towards your workers VPC over TCP 10250. If you see `<none>`, it indicates that the cert-manager webhook is properly running but its readiness endpoint can't be reached: ```text NAME ENDPOINTS AGE cert-manager-webhook <none> 236d ❌ ``` To fix `<none>`, you will have to check whether the cert-manager-webhook deployment is healthy. The endpoints stays to `<none>` as long as cert-manager-webhook isn't marked as "healthy". ```sh kubectl get pod -n cert-manager -l app.kubernetes.io/name=webhook ``` You should see that the pod is `Running`, and that the number of containers that are ready is `0/1`: ```text NAME READY STATUS RESTARTS AGE cert-manager-76578c9687-24kmr 0/1 Running 7 (8h ago) 28d ❌ ``` We won't be detailing the case where you get `1/1` and `Running`, since it would indicate an inconsistent state in Kubernetes. Continuing with `0/1`, that means the readiness endpoint isn't answering. When that happens, no endpoint is created. The next step is to figure out why the readiness endpoint isn't answering. Let us see which port the kubelet is using when hitting the readiness endpoint: ```sh kubectl -n cert-manager get deploy cert-manager-webhook -oyaml | grep -A5 readiness ``` In our example, the port that the kubelet will try to hit is 6080: ```yaml readinessProbe: failureThreshold: 3 httpGet: path: /healthz port: 6080 # ✨ scheme: HTTP ``` Now, let us port-forward to that port and see if `/healthz` works. In a shell session, run: ```sh kubectl -n cert-manager port-forward deploy/cert-manager-webhook 6080 ``` In another shell session, run: ```sh curl -sS --dump-header - 127.0.0.1:6080/healthz ``` The happy output is: ```http HTTP/1.1 200 OK ✅ Date: Tue, 07 Jun 2022 17:16:56 GMT Content-Length: 0 ``` If the readiness endpoint doesn't work, you will see: ```text curl: (7) Failed to connect to 127.0.0.1 port 6080 after 0 ms: Connection refused ❌ ``` At this point, verify that the readiness endpoint is configured on that same port. Let us see the logs to check that our webhook is listening on 6080 for its readiness endpoint: ```console $ kubectl logs -n cert-manager -l app.kubernetes.io/name=webhook | head -10 I0607 webhook.go:129] "msg"="using dynamic certificate generating using CA stored in Secret resource" I0607 server.go:133] "msg"="listening for insecure healthz connections" "address"=":6081" ❌ I0607 server.go:197] "msg"="listening for secure connections" "address"=":10250" I0607 dynamic_source.go:267] "msg"="Updated serving TLS certificate" ... ``` In the above example, the issue was a misconfiguration of the readiness port. In the webhook deployment, the argument `--healthz-port=6081` was mismatched with the readiness configuration. <a id="io-timeout"></a> ## Error 2: `i/o timeout` (connectivity issue) > This error message was reported 26 times on Slack. To list these messages, do a search with `in:#cert-manager in:#cert-manager-dev "443: i/o timeout"`. The error message was reported X times in GitHub issues ([#2811](https://github.com/cert-manager/cert-manager/issues/2811 "i/o timeout from apiserver when connecting to webhook on k3s"), [#4073](https://github.com/cert-manager/cert-manager/issues/4073 "Internal error occurred: failed calling webhook")) ```text Error from server (InternalError): error when creating "STDIN": Internal error occurred: failed calling webhook "webhook.cert-manager.io": failed to call webhook: Post "https://cert-manager-webhook.cert-manager.svc:443/mutate?timeout=10s": dial tcp 10.0.0.69:443: i/o timeout ``` When the API server tries to talk to the cert-manager webhook, the `SYN` packet is never answered, and the connection times out. If we were to run tcpdump inside the webhook's net namespace, we would see: ```text 192.168.1.43 (apiserver) -> 10.0.0.69 (webhook pod) TCP 44772 → 443 [SYN] 192.168.1.43 (apiserver) -> 10.0.0.69 (webhook pod) TCP [TCP Retransmission] 44772 → 443 [SYN] 192.168.1.43 (apiserver) -> 10.0.0.69 (webhook pod) TCP [TCP Retransmission] 44772 → 443 [SYN] 192.168.1.43 (apiserver) -> 10.0.0.69 (webhook pod) TCP [TCP Retransmission] 44772 → 443 [SYN] ``` This issue is caused by the `SYN` packet being dropped somewhere. <a id="gke-private-cluster"></a> ### Cause 1: GKE Private Cluster The default Helm configuration should work with GKE private clusters, but changing `securePort` might break it. For context, unlike public GKE clusters where the control plane can freely talk to pods over any TCP port, the control plane in private GKE clusters can only talk to the pods in worker nodes over TCP port 10250 and 443. These two open ports refer to the `containerPort` inside the pod, not the port called `port` in the Service resource. For it to work, the `containerPort` inside the Deployment must match either 10250 or 443; `containerPort` is configured by the Helm value `webhook.securePort`. By default, `webhook.securePort` is set to 10250. To see if something is off with the `containerPort`, let us start looking at the Service resource: ```sh kubectl get svc -n cert-manager cert-manager-webhook -oyaml ``` Looking at the output, we see that the `targetPort` is set to `"https"`: ```yaml apiVersion: v1 kind: Service metadata: name: cert-manager-webhook spec: ports: - name: https port: 443 # ❌ This port is not the cause. protocol: TCP targetPort: "https" # 🌟 This port might be the cause. ``` The reason the above `port: 443` can't be the cause is because kube-proxy, which also runs on the control plane node, translates the webhook's cluster IP to a pod IP, and also translates the above `port: 443` to the value in `containerPort`. To see how what is behind the target port `"https"`, we look at the Deployment resource: ```sh kubectl get deploy -n cert-manager cert-manager-webhook -oyaml | grep -A3 ports: ``` The output shows that the `containerPort` is not set to 10250, meaning that a new firewall rule will have to be added in Google Cloud. ```yaml ports: - containerPort: 12345 # 🌟 This port doesn't match 10250 nor 443. name: https protocol: TCP ``` To recap, if the above `containerPort` doesn't say 443 or 10250 and that you prefer not changing `containerPort` to 10250, you will have to add a new firewall rule. You can read the section [Adding a firewall rule in a GKE private cluster](https://cloud.google.com/kubernetes-engine/docs/how-to/private-clusters#add_firewall_rules) in the Google documentation. For context, the reason we did not default `securePort` to 443 is because binding to 443 requires one additional Linux capability (`NET_BIND_SERVICE`); on the other side, 10250 doesn't require any additional capability. ### Cause 2: EKS on a custom CNI If you are on EKS and you are using a custom CNI such as Weave or Calico, the Kubernetes API server (which is in its own node) might not be able to reach the webhook pod. This happens because the control plane cannot be configured to run on a custom CNI on EKS, meaning that the CNIs cannot enable connectivity between the API server and the pods running in the worker nodes. Supposing that you are using Helm, the workaround is to add the following value in your `values.yaml` file: ```yaml webhook: hostNetwork: true securePort: 10260 ``` Or if you are using Helm from the command-line, use the following flag: ```sh --set webhook.hostNetwork=true --set webhook.securePort=10260 ``` By setting `hostNetwork` to `true`, the webhook pod will be run in the host's network namespace. By running in the host's network namespace, the webhook pod becomes accessible over the node's IP, which means you will work around the fact that kube-apiserver can't reach any pod IPs nor cluster IPs. By setting `securePort` to 10260 instead of relying on the default value (which is 10250), you will prevent a conflict between the webhook and the kubelet. The kubelet, which is an agent that runs on every Kubernetes worker node and that runs directly on the host, uses the port 10250 to expose its internal API to kube-apiserver. To understand how `hostnetwork` and `securePort` interact, we have to look at how the TCP connection is established. When the kube-apiserver process tries to connect to the webhook pod, kube-proxy (which also runs on control plane nodes, even without a CNI) kicks in and translates the webhook's cluster IP to the webhook's host IP: ```diagram https://cert-manager-webhook.cert-manager.svc:443/validate | |Step 1: resolve to the cluster IP v https://10.43.103.211:443/validate | |Step 2: send TCP packet v src: 172.28.0.1:43021 dst: 10.43.103.211:443 | |Step 3: kube-proxy rewrite (cluster IP to host IP) v src: 172.28.0.1:43021 dst: 172.28.0.2:10260 | | control-plane node | (host IP: 172.28.0.1) ------------|-------------------------------------------------- | (host IP: 172.28.0.2) v worker node +-------------------+ | webhook pod | | listens on | | 172.28.0.2:10260 | +-------------------+ ``` The reason 10250 is used as the default `securePort` is because it works around another limitation with GKE Private Clusters, as detailed in the above section [GKE Private Cluster](#gke-private-cluster). ### Cause 3: Network Policies, Calico Assuming that you are using the Helm chart and that you are using the default value of `webhook.securePort` (which is 10250), and that you are using a network policy controller such as Calico, check that there exists a policy allowing traffic from the API server to the webhook pod over TCP port 10250. ### Cause 4: EKS and Security Groups Assuming that you are using the Helm chart and that you are using the default value of `webhook.securePort` (which is 10250), you might want to check that your AWS Security Groups allow TCP traffic over 10250 from the control plane's VPC to the workers VPC. ### Other causes If none of the above causes apply, you will need to figure out why the webhook is unreachable. To debug reachability issues (i.e., packets being dropped), we advise to use `tcpdump` along with Wireshark at every TCP hop. You can follow the article [Debugging Kubernetes Networking: my `kube-dns` is not working!](https://maelvls.dev/debugging-kubernetes-networking/) to learn how to use `tcpdump` with Wireshark to debug networking issues. ## Error 3: `x509: certificate is valid for xxx.internal, not cert-manager-webhook.cert-manager.svc` (EKS with Fargate pods) ```text Internal error occurred: failed calling webhook "webhook.cert-manager.io": Post https://cert-manager-webhook.cert-manager.svc:443/mutate?timeout=30s: x509: certificate is valid for ip-192-168-xxx-xxx.xxx.compute.internal, not cert-manager-webhook.cert-manager.svc ``` > This issue was first reported in > [#3237](https://github.com/cert-manager/cert-manager/issues/3237 "Can't > create an issuer when cert-manager runs on EKS in Fargate pods (AWS)"). This is most probably because you are running on EKS with Fargate enabled. Fargate creates a microVM per pod, and the VM's kernel is used to run the container in its own namespace. The problem is that each microVM gets its own kubelet. As for any Kubernetes node, the VM's port 10250 is listened to by a kubelet process. And 10250 is also the port that the cert-manager webhook listens on. But that's not a problem: the kubelet process and the cert-manager webhook process are running in two separate network namespaces, and ports don't clash. That's the case both in traditional Kubernetes nodes, as well as inside a Fargate microVM. The problem arises when the API server tries hitting the Fargate pod: the microVM's host net namespace is configured to port-forward every possible port for maximum compatibility with traditional pods, as demonstrated in the Stack Overflow page [EKS Fargate connect to local kubelet][66445207]. But the port 10250 is already used by the microVM's kubelet, so anything hitting this port won't be port-forwarded and will hit the kubelet instead. [66445207]: https://stackoverflow.com/questions/66445207 "EKS Fargate connect to local kubelet" To sum up, the cert-manager webhook looks healthy and is able to listen to port 10250 as per its logs, but the microVM's host does not port-forward 10250 to the webhook's net namespace. That's the reason you see a message about an unexpected domain showing up when doing the TLS handshake: although the cert-manager webhook is properly running, the kubelet is the one responding to the API server. This is a limitation of Fargate's microVMs: the IP of the pod and the IP of the node are the same. It gives you the same experience as traditional pods, but it poses networking challenges. To fix the issue, the trick is to change the port the cert-manager webhook is listening on. Using Helm, we can use the parameter `webhook.securePort`: ```sh helm install \ cert-manager jetstack/cert-manager \ --namespace cert-manager \ --create-namespace \ --version v1.8.0 \ --set webhook.securePort=10260 ``` ## Error 4: `service "cert-managercert-manager-webhook" not found` ```text Error from server (InternalError): error when creating "test-resources.yaml": Internal error occurred: failed calling webhook "webhook.cert-manager.io": failed to call webhook: Post "https://cert-managercert-manager-webhook.cert-manager.svc:443/mutate?timeout=10s": service "cert-managercert-manager-webhook" not found ``` > This error was reported in 2 GitHub issues ([#3195](https://github.com/jetstack/cert-manager/issues/3195 "service cert-manager-webhook not found"), > [#4999](https://github.com/cert-manager/cert-manager/issues/4999 "Verification on 1.7.2 fails (Kubectl apply), service cert-manager-webhook not found")). We are unsure about the cause of this error, please comment on one of the GitHub issues above if you happen to come across the issue. ## Error 5: `no endpoints available for service "cert-manager-webhook"` (OVHCloud) ```text Error: INSTALLATION FAILED: Internal error occurred: failed calling webhook "webhook.cert-manager.io": Post https://cert-manager-webhook.cert-manager.svc:443/mutate?timeout=30s: no endpoints available for service "cert-manager-webhook" ``` > This issue was first reported once in Slack > ([1](https://kubernetes.slack.com/archives/C4NV3DWUC/p1634118489064400?thread_ts=1592676867.472700&cid=C4NV3DWUC)). This error is rare and was only seen in OVHcloud managed Kubernetes clusters, where the etcd resource quota is quite low. etcd is the database where your Kubernetes resources (such as pods and deployments) are stored. OVHCloud limits the disk space used by your resources in etcd. When the limit is reached, the whole cluster starts behaving erratically and one symptom is that Endpoint resources aren't created by the kubelet. To verify that it is in fact a problem of quota, you should be able to see the following messages in your kube-apiserver logs: ```sh rpc error: code = Unknown desc = ETCD storage quota exceeded rpc error: code = Unknown desc = quota computation: etcdserver: not capable rpc error: code = Unknown desc = The OVHcloud storage quota has been reached ``` The workaround is to remove some resources such as CertificateRequest resources to get under the limit, as explained in OVHCloud's [ETCD Quotas error, troubleshooting](https://docs.ovh.com/gb/en/kubernetes/etcd-quota-error/) page. ## Error 6: `x509: certificate has expired or is not yet valid` > This error message was reported once in Slack: > [1](https://kubernetes.slack.com/archives/C4NV3DWUC/p1618579222346800). When using `kubectl apply`: ```text Internal error occurred: failed calling webhook "webhook.cert-manager.io": Post https://kubernetes.default.svc:443/apis/webhook.cert-manager.io/v1beta1/mutations?timeout=30s: x509: certificate has expired or is not yet valid ``` > This error was reported in 1 Slack message ([1](https://kubernetes.slack.com/archives/C4NV3DWUC/p1618579222346800)). Please answer to the above Slack message since we are still unsure as to what may cause this issue; to get access to the Kubernetes Slack, visit [https://slack.k8s.io/](https://slack.k8s.io/). ## Error 7: `net/http: request canceled while waiting for connection` ```text Error from server (InternalError): error when creating "STDIN": Internal error occurred: failed calling webhook "webhook.cert-manager.io": Post https://cert-manager-webhook.cert-manager.svc:443/mutate?timeout=30s: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers) ``` > This error was reported in 1 Slack message: [1](https://kubernetes.slack.com/archives/C4NV3DWUC/p1632849763397100). This <a id="context-deadline-exceeded"></a> ## Error 8: `context deadline exceeded` > This error message was reported in GitHub issues ([2319](https://github.com/cert-manager/cert-manager/issues/2319 "Documenting context deadline exceeded errors relating to the webhook, on bare metal"), [2706](https://github.com/cert-manager/cert-manager/issues/2706 "") [5189](https://github.com/cert-manager/cert-manager/issues/5189 "Post https://cert-manager-webhook.cert-manager.svc:443/mutate?timeout=10s: context deadline exceeded"), [5004](https://github.com/cert-manager/cert-manager/issues/5004 "After installing cert-manager using kubectl, cmctl check api fails with https://cert-manager-webhook.cert-manager.svc:443/mutate?timeout=10s: context deadline exceeded")), and once [on Stack Overflow](https://stackoverflow.com/questions/72059332/how-can-i-fix-failed-calling-webhook-webhook-cert-manager-io). This error appears with cert-manager 0.12 and above when trying to apply an Issuer or any other cert-manager custom resource after having installed or upgraded cert-manager: ```text Error from server (InternalError): error when creating "STDIN": Internal error occurred: failed calling webhook "webhook.cert-manager.io": Post https://cert-manager-webhook.cert-manager.svc:443/mutate?timeout=30s: context deadline exceeded ``` > ℹ️ In older releases of cert-manager (0.11 and below), the webhook relied on > the [APIService > mechanism](https://kubernetes.io/docs/tasks/extend-kubernetes/setup-extension-api-server/), > and the message looked a bit different but the cause was the same: > > ```text > Error from server (InternalError): error when creating "STDIN": > Internal error occurred: failed calling webhook "webhook.certmanager.k8s.io": > Post https://kubernetes.default.svc:443/apis/webhook.certmanager.k8s.io/v1beta1/mutations?timeout=30s: > context deadline exceeded > ``` > ℹ️ The message `context deadline exceeded` also appears when using `cmctl > check api`. The cause is identical, you can continue reading this section to > debug it. > > ```text > Not ready: Internal error occurred: failed calling webhook "webhook.cert-manager.io": failed to call webhook: > Post "https://cert-manager-webhook.cert-manager.svc:443/mutate?timeout=10s": > context deadline exceeded > ``` The trouble with the message `context deadline exceeded` is that it obfuscates the part of the HTTP connection that timed out. When this message appears, we can't tell which part of the HTTP interaction timed out. It might be the DNS resolution, the TCP handshake, the TLS handshake, sending the HTTP request or receiving the HTTP response. > ℹ️ For context, the query parameter `?timeout=30s` that you can see in the > above error messages is a timeout that the API server decides when calling the > webhook. It is often set to 10 or 30 seconds. The following diagram shows what are the three errors that may be hidden behind the all-catching "context deadline exceeded" error message, represented by the outer box, that is usually thrown after 30 seconds: <a id="diagram"></a> ```diagram context deadline exceeded | 30 seconds | timeout v +-------------------------------------------------------------------------+ | | | i/o timeout | | | net/http: TLS handshake timeout | | 10 seconds | | | | timeout v | | |------------+ 30 seconds | net/http: request canceled | |TCP | timeout v while awaiting headers | |handshake +---------------------+ | | |------------| TLS | | | | | handshake +------------+ 10 seconds | | | +---------------------| sending | timeout v | | | request +------------+ | | +------------|receiving |------+ | | |resp. header| recv.| | | +------------+ resp.| | | | body +-----+ | +------|other| | |logic| | +-----+ +-------------------------------------------------------------------------+ <----------> <----------------------------------------------> connectivity webhook-side issue issue ``` In the rest of the section, we will be trying to trigger one of the three "more specific" errors: - `i/o timeout` is the TCP handshake timeout and comes from [`DialTimeout`](https://pkg.go.dev/net#DialTimeout) in the Kubernetes apiserver. The name resolution may be the cause, but usually, this message appears after the API server sent the `SYN` packet and waited for 10 seconds for the `SYN-ACK` packet to be received from the cert-manager webhook. - `net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)` is the HTTP response timeout and comes from [here](https://github.com/kubernetes/kubernetes/blob/abba1492f/staging/src/k8s.io/apiserver/pkg/util/webhook/webhook.go#L96-L101) and is configured to [30 seconds](https://github.com/kubernetes/kubernetes/blob/abba1492f/staging/src/k8s.io/apiserver/pkg/util/webhook/webhook.go#L36-L38). The Kubernetes API server already sent the HTTP request is is waiting for the HTTP response headers (e.g., `HTTP/1.1 200 OK`). - `net/http: TLS handshake timeout` is when the TCP handshake is done, and the Kubernetes API server sent the initial TLS handshake packet (`ClientHello`) and waited for 10 seconds for the cert-manager webhook to answer with the `ServerHello` packet. We can sort these three messages in two categories: either it is a connectivity issue (`SYN` is dropped), or it is a webhook issue (i.e., the TLS certificate is wrong, or the webhook is not returning any HTTP response): | Timeout message | Category | |-----------------------------------------------------|--------------------| | `i/o timeout` | connectivity issue | | `net/http: TLS handshake timeout` | webhook-side issue | | `net/http: request canceled while awaiting headers` | webhook-side issue | The first step is to rule out a webhook-side issue. In your shell session, run the following: ```sh kubectl -n cert-manager port-forward deploy/cert-manager-webhook 10250 ``` In another shell session, check that you can reach the webhook: ```sh curl -vsS --resolve cert-manager-webhook.cert-manager.svc:10250:127.0.0.1 \ --service-name cert-manager-webhook-ca \ --cacert <(kubectl -n cert-manager get secret cert-manager-webhook-ca -ojsonpath='{.data.ca\.crt}' | base64 -d) \ https://cert-manager-webhook.cert-manager.svc:10250/validate 2>&1 -d@- <<'EOF' | sed '/^* /d; /bytes data]$/d; s/> //; s/< //' {"kind":"AdmissionReview","apiVersion":"admission.k8s.io/v1","request":{"requestKind":{"group":"cert-manager.io","version":"v1","kind":"Certificate"},"requestResource":{"group":"cert-manager.io","version":"v1","resource":"certificates"},"name":"foo","namespace":"default","operation":"CREATE","object":{"apiVersion":"cert-manager.io/v1","kind":"Certificate","spec":{"dnsNames":["foo"],"issuerRef":{"group":"cert-manager.io","kind":"Issuer","name":"letsencrypt"},"secretName":"foo","usages":["digital signature"]}}}} EOF ``` The happy output looks like this: ```http POST /validate HTTP/1.1 Host: cert-manager-webhook.cert-manager.svc:10250 User-Agent: curl/7.83.0 Accept: */* Content-Length: 1299 Content-Type: application/x-www-form-urlencoded HTTP/1.1 200 OK Date: Wed, 08 Jun 2022 14:52:21 GMT Content-Length: 2029 Content-Type: text/plain; charset=utf-8 ... "response": { "uid": "", "allowed": true } ``` If the response shows `200 OK`, we can rule out a webhook-side issue. Since the initial error message was `context deadline exceeded` and not an apiserver-side issue such as `x509: certificate signed by unknown authority` or `x509: certificate has expired or is not yet valid`, we can conclude that the problem is a connectivity issue: the Kubernetes API server isn't able to establish a TCP connection to the cert-manager webhook. Please follow the instructions in the section [Error 2: `i/o timeout` (connectivity issue)](#io-timeout) above to continue debugging. ## Error 8: `net/http: TLS handshake timeout` > This error message was reported in 1 GitHub issue ([#2602](https://github.com/cert-manager/cert-manager/issues/2602 "Internal error occurred: failed calling webhook webhook.cert-manager.io: Post https://cert-manager-webhook.cert-manager.svc:443/mutate?timeout=30s: net/http: TLS handshake timeout")). ```text Error from server (InternalError): error when creating "STDIN": Internal error occurred: failed calling webhook "webhook.cert-manager.io": Post https://cert-manager-webhook.cert-manager.svc:443/mutate?timeout=30s: net/http: TLS handshake timeout ``` Looking at the [above diagram](#diagram), this error message indicates that the Kubernetes API server successfully established a TCP connection to the pod IP associated with the cert-manager webhook. The TLS handshake timeout means that the cert-manager webhook process isn't the one ending the TCP connection: there is some HTTP proxy in between that is probably waiting for a plain HTTP request instead a `ClientHello` packet. We are unsure of the cause of this error. Please comment on the above GitHub issue if you notice this error. ## Error 9: `HTTP probe failed with statuscode: 500` > This error message was reported in 2 GitHub issue ([#3185](https://github.com/cert-manager/cert-manager/issues/3185 "kubectl install cert-manager: Readiness probe failed: HTTP probe failed with statuscode: 500"), [#4557](https://github.com/cert-manager/cert-manager/issues/4557 "kubectl install cert-manager: Readiness probe failed: HTTP probe failed with statuscode: 500")). The error message is visible as an event on the cert-manager webhook: ```text Warning Unhealthy <invalid> (x13 over 15s) kubelet, node83 Readiness probe failed: HTTP probe failed with statuscode: 500 ``` We are unsure of the cause of this error. Please comment on the above GitHub issue if you notice this error. ## Error 10: `Service Unavailable` > This error was reported in 1 GitHub issue ([#4281](https://github.com/cert-manager/cert-manager/issues/4281 "Can't deploy Issuer, Service Unavailable")) ```text Error from server (InternalError): error when creating "STDIN": Internal error occurred: failed calling webhook "webhook.cert-manager.io": Post "https://my-cert-manager-webhook.default.svc:443/mutate?timeout=10s": Service Unavailable ``` The above message appears in Kubernetes clusters using the Weave CNI. We are unsure of the cause of this error. Please comment on the above GitHub issue if you notice this error. ## Error 11: `failed calling admission webhook: the server is currently unable to handle the request` > This issue was reported in 4 GitHub issues ([1369](https://github.com/cert-manager/cert-manager/issues/1369 "the server is currently unable to handle the request"), [1425](https://github.com/cert-manager/cert-manager/issues/1425 "Verifying Install: failed calling admission webhook (Azure, GKE private cluster)") [3542](https://github.com/cert-manager/cert-manager/issues/3542 "SSL Certificate Manager has got expired, we need to renew SSL certificate in existing ClusterIssuer Kubernetes Service (AKS)"), [4852](https://github.com/cert-manager/cert-manager/issues/4852 "error: unable to retrieve the complete list of server APIs: webhook.cert-manager.io/v1beta1: the server is currently unable to handle the request (AKS)")) ```text Error from server (InternalError): error when creating "test-resources.yaml": Internal error occurred: failed calling admission webhook "issuers.admission.certmanager.k8s.io": the server is currently unable to handle the request ``` We are unsure of the cause of this error. Please comment in one of the above GitHub issues if you are able to reproduce this error. ## Error 12: `x509: certificate signed by unknown authority` > Reported in GitHub issues > ([2602](https://github.com/cert-manager/cert-manager/issues/2602#issuecomment-606474055 "x509: certificate signed by unknown authority")) When installing or upgrading cert-manager and using a namespace that is not `cert-manager`: ```text Error: UPGRADE FAILED: release core-l7 failed, and has been rolled back due to atomic being set: failed to create resource: conversion webhook for cert-manager.io/v1alpha3, Kind=ClusterIssuer failed: Post https://cert-manager-webhook.core-l7.svc:443/convert?timeout=30s: x509: certificate signed by unknown authority ``` A very similar error message may show when creating an Issuer or any other cert-manager custom resource: ```text Internal error occurred: failed calling webhook "webhook.cert-manager.io": Post https://cert-manager-webhook.cert-manager.svc:443/mutate?timeout=30s: x509: certificate signed by unknown authority` ``` With `cmctl install` and `cmctl check api`, you might see the following error message: ```text 2022/06/06 15:36:30 Not ready: the cert-manager webhook CA bundle is not injected yet (Internal error occurred: conversion webhook for cert-manager.io/v1alpha2, Kind=Certificate failed: Post "https://<company_name>-cert-manager-webhook.cert-manager.svc:443/convert?timeout=30s": x509: certificate signed by unknown authority) ``` If you are using cert-manager 0.14 and below with Helm, and that you are installing in a namespace different from `cert-manager`, the CRD manifest had the namespace name `cert-manager` hardcoded. You can see the hardcoded namespace in the following annotation: ```sh kubectl get crd issuers.cert-manager.io -oyaml | grep inject ``` You will see the following: ```yaml cert-manager.io/inject-ca-from-secret: cert-manager/cert-manager-webhook-ca # ^^^^^^^^^^^^ # hardcoded ``` > **Note 1:** this bug in the cert-manager Helm chart was [was fixed](https://github.com/cert-manager/cert-manager/commit/f33beefc) in cert-manager 0.15. > > **Note 2:** since cert-manager 1.6, this annotation is [not being > used](https://github.com/cert-manager/cert-manager/pull/4841) anymore on the > cert-manager CRDs since there is no need for conversion anymore. The solution, if you are still using cert-manager 0.14 or below, is to render the manifest using `helm template`, then edit the annotation to use the correct namespace, and then use `kubectl apply` to install cert-manager. If you are using cert-manager 1.6 and below, the issue might be due to the cainjector being stuck trying to inject the self-signed certificate that the cert-manager webhook created and stored in the Secret resource `cert-manager-webhook-ca` into the `spec.caBundle` field of the cert-manager CRDs. The first step is to check whether the cainjector is running with no problem: ```console $ kubectl -n cert-manager get pods -l app.kubernetes.io/name=cainjector NAME READY STATUS RESTARTS AGE cert-manager-cainjector-5c55bb7cb4-6z4cf 1/1 Running 11 (31h ago) 28d ``` Looking at the logs, you will be able to tell if the leader election worked. It can take up to one minute for the leader election work to complete. ```console I0608 start.go:126] "starting" version="v1.8.0" revision="e466a521bc5455def8c224599c6edcd37e86410c" I0608 leaderelection.go:248] attempting to acquire leader lease kube-system/cert-manager-cainjector-leader-election... I0608 leaderelection.go:258] successfully acquired lease kube-system/cert-manager-cainjector-leader-election I0608 controller.go:186] cert-manager/secret/customresourcedefinition/controller/controller-for-secret-customresourcedefinition "msg"="Starting Controller" I0608 controller.go:186] cert-manager/certificate/customresourcedefinition/controller/controller-for-certificate-customresourcedefinition "msg"="Starting Controller" I0608 controller.go:220] cert-manager/secret/customresourcedefinition/controller/controller-for-secret-customresourcedefinition "msg"="Starting workers" "worker count"=1 I0608 controller.go:220] cert-manager/certificate/customresourcedefinition/controller/controller-for-certificate-customresourcedefinition "msg"="Starting workers" "worker count"=1 ``` The happy output contains lines like this: ```console I0608 sources.go:184] cert-manager/secret/customresourcedefinition/generic-inject-reconciler "msg"="Extracting CA from Secret resource" "resource_name"="issuers.cert-manager.io" "secret"="cert-manager/cert-manager-webhook-ca" I0608 controller.go:178] cert-manager/secret/customresourcedefinition/generic-inject-reconciler "msg"="updated object" "resource_name"="issuers.cert-manager.io" ``` Now, look for any message that indicates that the Secret resource that the cert-manager webhook created can't be loaded. The two error messages that might show up are: ```text E0608 sources.go:201] cert-manager/secret/customresourcedefinition/generic-inject-reconciler "msg"="unable to fetch associated secret" "error"="Secret \"cert-manager-webhook-caq\" not found" ``` The following message indicates that the given CRD has been skipped because the annotation is missing. You can ignore these messages: ```text I0608 controller.go:156] cert-manager/secret/customresourcedefinition/generic-inject-reconciler "msg"="failed to determine ca data source for injectable" "resource_name"="challenges.acme.cert-manager.io" ``` If nothing seems wrong with the cainjector logs, you will want to check that the `spec.caBundle` field in the validation, mutation, and conversion configurations are correct. The Kubernetes API server uses the contents of that field to trust the cert-manager webhook. The `caBundle` contains the self-signed CA created by the cert-manager webhook when it started. ```console $ kubectl get validatingwebhookconfigurations cert-manager-webhook -ojson | jq '.webhooks[].clientConfig' { "caBundle": "LS0tLS1...LS0tLS0K", "service": { "name": "cert-manager-webhook", "namespace": "cert-manager", "path": "/validate", "port": 443 } } ``` ```console $ kubectl get mutatingtingwebhookconfigurations cert-manager-webhook -ojson | jq '.webhooks[].clientConfig' { "caBundle": "LS0tLS1...RFLS0tLS0K", "service": { "name": "cert-manager-webhook", "namespace": "cert-manager", "path": "/validate", "port": 443 } } ``` Let us see the contents of the `caBundle`: ```console $ kubectl get mutatingwebhookconfigurations cert-manager-webhook -ojson \ | jq '.webhooks[].clientConfig.caBundle' -r | base64 -d \ | openssl x509 -noout -text -in - Certificate: Data: Version: 3 (0x2) Serial Number: ee:8f:4f:c8:55:7b:16:76:d8:6a:a2:e5:94:bc:7c:6b Signature Algorithm: ecdsa-with-SHA384 Issuer: CN = cert-manager-webhook-ca Validity Not Before: May 10 16:13:37 2022 GMT Not After : May 10 16:13:37 2023 GMT Subject: CN = cert-manager-webhook-ca ``` Let us check that the contents of `caBundle` works for connecting to the webhook: ```console $ kubectl -n cert-manager get secret cert-manager-webhook-ca -ojsonpath='{.data.ca\.crt}' \ | base64 -d | openssl x509 -noout -text -in - Certificate: Data: Version: 3 (0x2) Serial Number: ee:8f:4f:c8:55:7b:16:76:d8:6a:a2:e5:94:bc:7c:6b Signature Algorithm: ecdsa-with-SHA384 Issuer: CN = cert-manager-webhook-ca Validity Not Before: May 10 16:13:37 2022 GMT Not After : May 10 16:13:37 2023 GMT Subject: CN = cert-manager-webhook-ca ``` Our final test is to try to connect to the webhook using this trust bundle. Let us port-forward to the webhook pod: ```sh kubectl -n cert-manager port-forward deploy/cert-manager-webhook 10250 ``` In another shell session, send a `/validate` HTTP request with the following command: ```sh curl -vsS --resolve cert-manager-webhook.cert-manager.svc:10250:127.0.0.1 \ --service-name cert-manager-webhook-ca \ --cacert <(kubectl get validatingwebhookconfigurations cert-manager-webhook -ojson | jq '.webhooks[].clientConfig.caBundle' -r | base64 -d) \ https://cert-manager-webhook.cert-manager.svc:10250/validate 2>&1 -d@- <<'EOF' | sed '/^* /d; /bytes data]$/d; s/> //; s/< //' {"kind":"AdmissionReview","apiVersion":"admission.k8s.io/v1","request":{"requestKind":{"group":"cert-manager.io","version":"v1","kind":"Certificate"},"requestResource":{"group":"cert-manager.io","version":"v1","resource":"certificates"},"name":"foo","namespace":"default","operation":"CREATE","object":{"apiVersion":"cert-manager.io/v1","kind":"Certificate","spec":{"dnsNames":["foo"],"issuerRef":{"group":"cert-manager.io","kind":"Issuer","name":"letsencrypt"},"secretName":"foo","usages":["digital signature"]}}}} EOF ``` You should see a successful HTTP request and response: ```http POST /validate HTTP/1.1 Host: cert-manager-webhook.cert-manager.svc:10250 User-Agent: curl/7.83.0 Accept: */* Content-Length: 1299 Content-Type: application/x-www-form-urlencoded HTTP/1.1 200 OK Date: Wed, 08 Jun 2022 16:20:45 GMT Content-Length: 2029 Content-Type: text/plain; charset=utf-8 ... ``` ## Error 13: `cluster scoped resource "mutatingwebhookconfigurations/" is managed and access is denied` > This message was reported in GitHub issue > [3717](https://github.com/cert-manager/cert-manager/issues/3717 "Cannot > install on GKE autopilot cluster due to mutatingwebhookconfigurations access > denied"). While installing cert-manager on GKE Autopilot, you will see the following message: ```text Error: rendered manifests contain a resource that already exists. Unable to continue with install: could not get information about the resource: mutatingwebhookconfigurations.admissionregistration.k8s.io "cert-manager-webhook" is forbidden: User "XXXX" cannot get resource "mutatingwebhookconfigurations" in API group "admissionregistration.k8s.io" at the cluster scope: GKEAutopilot authz: cluster scoped resource "mutatingwebhookconfigurations/" is managed and access is denied ``` This error message will appear when using Kubernetes 1.20 and below with GKE Autopilot. It is due to a [restriction on mutating admission webhooks in GKE Autopilot](https://github.com/cert-manager/cert-manager/issues/3717). As of October 2021, the "rapid" Autopilot release channel has rolled out version 1.21 for Kubernetes masters. Installation via the Helm chart may end in an error message but cert-manager is reported to be working by some users. Feedback and PRs are welcome. ## Error 14: `the namespace "kube-system" is managed and the request's verb "create" is denied` When installing cert-manager on GKE Autopilot with Helm, you will see the following error message: ```text Not ready: the cert-manager webhook CA bundle is not injected yet ``` After this failure, you should still see the three pods happily running: ```console $ kubectl get pods -n cert-manager NAME READY STATUS RESTARTS AGE cert-manager-76578c9687-24kmr 1/1 Running 0 47m cert-manager-cainjector-b7d47f746-4799n 1/1 Running 0 47m cert-manager-webhook-7f788c5b6-mspnt 1/1 Running 0 47m ``` But looking at either of the logs, you will see the following error message: ```text E0425 leaderelection.go:334] error initially creating leader election record: leases.coordination.k8s.io is forbidden: User "system:serviceaccount:cert-manager:cert-manager-webhook" cannot create resource "leases" in API group "coordination.k8s.io" in the namespace "kube-system": GKEAutopilot authz: the namespace "kube-system" is managed and the request's verb "create" is denied ``` That is due to a limitation of GKE Autopilot. It is not possible to create resources in the `kube-system` namespace, and cert-manager uses the well-known `kube-system` to manage the leader election. To get around the limitation, you can tell Helm to use a different namespace for the leader election: ```sh helm install cert-manager jetstack/cert-manager --version 1.8.0 \ --namespace cert-manager --create-namespace \ --set global.leaderElection.namespace=cert-manager ``` ## Error 15: `x509: certificate is valid for cert-manager-webhook.cert-manager.svc, not cert-manager-webhook.somenamespace.svc` > This error was reported in 1 GitHub issue ([#2602](https://github.com/cert-manager/cert-manager/issues/2602#issuecomment-603912166)). ```text Internal error occurred: failed calling webhook "webhook.cert-manager.io": Post https://cert-manager-webhook.slr-system.svc:443/mutate?timeout=30s: x509: certificate is valid for cert-manager-webhook, cert-manager-webhook.cert-manager, cert-manager-webhook.cert-manager.svc, not cert-manager-webhook.slr-system.svc ``` If you installed cert-manager using Helm