Project: Contour (Orchestration & Management / Service Proxy)
File: troubleshooting.md

This document contains suggestions for debugging issues with your Contour installation. Contour does not configure Envoy to listen on a port unless there is traffic to be served. For example, if you have not configured any TLS ingress objects then Contour does not command Envoy to open port 8443 (443 in the service object). Because the HTTP and HTTPS listeners both use the same code, if you have no ingress objects deployed in your cluster, or if no ingress objects are permitted to talk on HTTP, then Envoy does not listen on port 8080 (80 in the service object). To test whether Contour is correctly deployed you can deploy the kuard example service: ```sh $ kubectl apply -f https://projectcontour.io/examples/kuard.yaml ``` Getting access to the Envoy admin interface can be useful for diagnosing issues with routing or cluster health. The Envoy admin interface is bound by default to `http://127.0.0.1:9001`. To access it from your workstation use `kubectl port-forward` like so, ```sh ENVOY_POD=$(kubectl -n projectcontour get pod -l app=envoy -o name | head -1) kubectl -n projectcontour port-forward $ENVOY_POD 9001 ``` Then navigate to `http://127.0.0.1:9001/` to access the admin interface for the Envoy container running on that pod. Contour exposes the handlers for `go tool pprof` and `go tool trace` by default on `127.0.0.1:6060`. This service is useful for profiling Contour. To access it from your workstation use `kubectl port-forward` like so, ```sh CONTOUR_POD=$(kubectl -n projectcontour get pod -l app=contour -o name | head -1) kubectl -n projectcontour port-forward $CONTOUR_POD 6060 ``` Contour models its configuration using a DAG, which can be visualized through a debug endpoint that outputs the DAG in format. To visualize the graph, you must have installed on your system. To download the graph and save it as a PNG: ```sh CONTOUR_POD=$(kubectl -n projectcontour get pod -l app=contour -o name | head -1) kubectl -n projectcontour port-forward $CONTOUR_POD 6060 curl localhost:6060/debug/dag | dot -T png > contour-dag.png ``` The following is an example of a DAG that maps `http://kuard.local:80/` to the `kuard` service in the `default` namespace: ! Sometimes it's helpful to be able to interrogate Contour to find out exactly the data it is sending to Envoy. Contour ships with a `contour cli` subcommand which can be used for this purpose. Because Contour secures its communications with Envoy using Secrets in the cluster, the easiest way is to run `contour cli` commands inside the pod. Do this is via `kubectl exec`: ```sh CONTOUR_POD=$(kubectl -n projectcontour get pod -l app=contour -o jsonpath='{.items[0].metadata.name}') kubectl -n projectcontour exec $CONTOUR_POD -c contour -- contour cli lds --cafile=/ca/cacert.pem --cert-file=/certs/tls.crt --key-file=/certs/tls.key ``` Which will stream changes to the LDS api endpoint to your terminal. Replace `contour cli lds` with `contour cli rds` for RDS, `contour cli cds` for CDS, and `contour cli eds` for EDS. See for some tips on using these two deployment options successfully. The `contour serve` subcommand has two command-line flags that can be helpful for debugging. The `--debug` flag enables general Contour debug logging, which logs more information about how Contour is processing API resources. The `--kubernetes-debug` flag enables verbose logging in the Kubernetes client API, which can help debug interactions between Contour and the Kubernetes API server. This flag requires an integer log level argument, where higher number indicates more detailed logging. The `envoy` command has a `--log-level` flag that can be useful for debugging. By default, it's set to `info`. To change it to `debug`, edit the `envoy` DaemonSet in the `projectcontour` namespace and replace the `--log-level info` flag with `--log-level debug`.