kic: add translation failures troubleshooting section

.github/styles/kong/auto-ignore.txt

@@ -17,6 +17,9 @@ datastores
 endpoint_key
 foogineer
 if_version
+ingress_controller_configuration_push_count
+ingress_controller_configuration_push_duration_milliseconds
+ingress_controller_translation_count
 kuma
 max_args
 max_headers

src/kubernetes-ingress-controller/references/prometheus.md

@@ -30,7 +30,8 @@ This metric provides the following labels:
 ### ingress_controller_translation_count
 `ingress_controller_translation_count` (type: `counter`) provides the number of translations from the Kubernetes state to the {{site.base_gateway}} state. 
 
-This metric provides the `success` label. `success` logs the status of configuration updates. If `success` is `false`, an unrecoverable error occurred.  If `success` is `true`, the translation succeeded with no errors.
+This metric provides the `success` label. `success` logs the status of configuration updates. If `success` is `false`, an unrecoverable error occurred. 
+If `success` is `true`, the translation succeeded with no errors.
 
 ### ingress_controller_configuration_push_duration_milliseconds
 `ingress_controller_configuration_push_duration_milliseconds` (type: `histogram`) is the amount of time, in milliseconds, that it takes to push the configuration to {{site.base_gateway}}. 

src/kubernetes-ingress-controller/troubleshooting.md

@@ -293,3 +293,60 @@ To enable profiling and access it, set `CONTROLLER_PROFILING=true` in the
 controller container environment (`ingressController.env.profiling: true` using
 the Helm chart), wait for the Deployment to restart, run `kubectl
 port-forward <POD_NAME> 10256:10256`, and visit `http://localhost:10256/debug/pprof/`.
+
+{% if_version gte:2.8.x %}
+## Translation failures
+
+{{site.kic_product_name}} translates Kubernetes resources into {{site.base_gateway}} configuration.
+It implements a set of validation rules that prevent a faulty {{site.base_gateway}} configuration from being created.
+In most cases, once the validation fails, the Kubernetes object that caused the failure is excluded
+from the translation and a corresponding translation failure warning event is recorded.
+
+To determine if there are any translation failures that you might want to fix, you
+can monitor the `ingress_controller_translation_count` [Prometheus metric](/kubernetes-ingress-controller/{{page.kong_version}}/references/prometheus).
+
+To get a deeper insight into what went wrong during the translation, you can look into Kubernetes
+events with a `KongConfigurationTranslationFailed` reason. There's one event created for every
+object that was associated with the failure. An event's message is populated with an
+explanation of the exact reason for the failure, which should help you identify the root cause.
+
+### Example
+In the following example, we create a service with a single port number `80`. In the Ingress definition, we specify a backend
+service that refers to a port number `8080` which does not match the one defined in the service.
+{{site.kic_product_name}} will skip the affected path and record warning events for both the service and Ingress objects.
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: my-service
+spec:
+  ports:
+    - port: 80
+---
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: my-ingress
+  annotations:
+    kubernetes.io/ingress.class: "kong"
+spec:
+  rules:
+    - http:
+        paths:
+          - path: /
+            pathType: Prefix
+            backend:
+              service:
+                name: my-service
+                port:
+                  number: 8080 # doesn't match the port in my-service
+```
+
+```console
+kubectl get events --sort-by='.lastTimestamp' --field-selector=reason=KongConfigurationTranslationFailed
+LAST SEEN   TYPE      REASON                               OBJECT               MESSAGE
+4s          Warning   KongConfigurationTranslationFailed   ingress/my-ingress   can't find port for backend kubernetes service: no suitable port found
+4s          Warning   KongConfigurationTranslationFailed   service/my-service   can't find port for backend kubernetes service: no suitable port found
+```
+{% endif_version %}