docs(kic): add upstream TLS verification guide

.github/styles/kong/dictionary.txt

@@ -262,6 +262,7 @@ Github
 glibc
 globbing
 Gluu
+goecho
 gojira
 Golang
 Goroutine

app/_data/docs_nav_kic_3.4.x.yml

@@ -145,6 +145,8 @@ items:
             url: /guides/security/client-ip
           - text: Kubernetes Secrets in Plugins
             url: /guides/security/plugin-secrets
+          - text: Verifying Upstream TLS
+            url: /guides/security/verify-upstream-tls
       #- text: Service Mesh
       #  items:
       #    - text: Kong Mesh

app/_includes/md/kic/ca-certificates-note.md

@@ -0,0 +1,13 @@
+{:.note}
+> CA certificates in Kong are provisioned by creating `Secret` or `ConfigMap` resource in Kubernetes.
+> Resources holding CA certificates must have the following properties:
+> - the `konghq.com/ca-cert: "true"` label applied.
+> - a `cert` or `ca.crt` data property which contains a valid CA certificate in PEM format.
+> - a `kubernetes.io/ingress.class` annotation whose value matches the value of the controller's `--ingress-class`
+    argument. By default, that value is `kong`.
+> - an `id` data property which contains a random UUID.
+>
+> Each CA certificate that you create needs a unique ID. Any random UUID should suffice here and it doesn't have a
+> security implication. You can use [uuidgen](https://linux.die.net/man/1/uuidgen) (Linux, OS X)
+> or [New-Guid](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/new-guid) (Windows) to
+> generate an ID.

app/_includes/md/kic/http-test-routing-resource.md

@@ -5,6 +5,7 @@
 {%- assign service = include.service | default: 'echo' %}
 {%- assign port = include.port | default: '1027' %}
 {%- assign ingress_class = include.ingress_class | default: 'kong' %}
+{%- assign route_type = include.route_type | default: 'PathPrefix' %}
 
 {% capture the_code %}
 {% navtabs api %}
@@ -32,7 +33,7 @@ spec:
 {% endunless %}  rules:
   - matches:
     - path:
-        type: {{ include.route_type }}
+        type: {{ route_type }}
         value: {{ path }}
     backendRefs:
     - name: {{ service }}
@@ -57,7 +58,7 @@ spec:
   - {% unless include.skip_host %}host: {{ hostname }}
     {% endunless %}http:
       paths:
-      - path: {% if include.route_type == 'RegularExpression' %}/~{% endif %}{{ path }}
+      - path: {% if route_type == 'RegularExpression' %}/~{% endif %}{{ path }}
         pathType: ImplementationSpecific
         backend:
           service:

app/_includes/md/kic/prerequisites.md

@@ -16,20 +16,23 @@
 
 ### Install the Gateway APIs
 
-1. Install the Gateway API CRDs before installing {{ site.kic_product_name }}.
+   {% if include.gateway_api_experimental %}
+
+1. Install the experimental Gateway API CRDs before installing {{ site.kic_product_name }}.
 
     ```bash
-    kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/{{ gw_api_crd_version}}/standard-install.yaml
+    kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/{{ gw_api_crd_version}}/experimental-install.yaml
     ```
 
-    {% if include.gateway_api_experimental %}
+   {% else %}
 
-1. Install the experimental Gateway API CRDs to test this feature.
+1. Install the Gateway API CRDs before installing {{ site.kic_product_name }}.
 
     ```bash
-    kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/{{ gw_api_crd_version}}/experimental-install.yaml
+    kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/{{ gw_api_crd_version}}/standard-install.yaml
     ```
-    {% endif %}
+
+   {% endif %}
 
 1. Create a `Gateway` and `GatewayClass` instance to use.
 

app/_includes/md/kic/verify-upstream-tls-backendtlspolicy.md

@@ -0,0 +1,19 @@
+```shell
+echo 'apiVersion: gateway.networking.k8s.io/v1alpha3
+kind: BackendTLSPolicy
+metadata:
+  name: goecho-tls-policy
+spec:
+  options:
+    tls-verify-depth: "1"
+  targetRefs:
+  - group: core
+    kind: Service
+    name: echo
+  validation:
+    caCertificateRefs:
+    - group: core
+      kind: {{ include.ref_kind }}
+      name: root-ca
+    hostname: kong.example' | kubectl apply -f -
+```

app/_includes/md/kic/verify-upstream-tls-ca.md

@@ -0,0 +1,42 @@
+{% assign source_type = include.ca_source_kind | downcase %}
+{% assign kind = include.ca_source_kind %}
+{% assign id = "bf6e0f14-78cd-45ad-9325-87ec7ef7b891" %}
+{% if include.ca_source_kind == "Secret" %}
+{% assign id = "bf6e0f14-78cd-45ad-9325-87ec7ef7b892" %}
+{% endif %}
+
+First, create a {{ kind }} with the root CA certificate.
+
+```shell
+kubectl create {{ source_type }} {% if source_type == "secret" %}generic {%endif%}root-ca \
+  --from-file=ca.crt=./certs/root.crt \
+  --from-literal=id={{ id }} # An arbitrary ID for the certificate
+kubectl label {{ source_type }} root-ca konghq.com/ca-cert=true # This label is required for the CA certificate to be recognized by Kong
+kubectl annotate {{ source_type }} root-ca kubernetes.io/ingress.class=kong
+```
+
+The results should look like this.
+
+```text
+{{ source_type }}/root-ca created
+{{ source_type }}/root-ca labeled
+{{ source_type }}/root-ca annotated
+```
+
+{% if include.associate_with_service %}
+Now, associate the root CA certificate with the `Service` passing its name to `konghq.com/ca-certificates-{{ source_type }}s` annotation.
+
+{:.note}
+> The `konghq.com/ca-certificates-{{ source_type }}s` annotation is a comma-separated list of `{{ kind }}`s holding CA certificates.
+> You can add multiple `{{ kind }}`s to the list.
+
+```shell
+kubectl annotate service echo konghq.com/ca-certificates-{{ source_type }}s='root-ca'
+```
+
+The result should look like this.
+
+```text
+service/echo annotated
+```
+{% endif %}