Procedure

1. Before adding a TLS certificate issuer, create the secret credentials in the cert-manager namespace by running the following command:

   $ oc -n cert-manager create secret generic <dns-provider-credentials> \
     --type=kuadrant.io/aws \
     --from-literal=AWS_ACCESS_KEY_ID=$KUADRANT_AWS_ACCESS_KEY_ID \
     --from-literal=AWS_SECRET_ACCESS_KEY=$KUADRANT_AWS_SECRET_ACCESS_KEY

   Copy code to clipboard

   Replace <dns-provider-credentials> with the secret you want to use. This example uses Amazon Web Services (AWS).

2. Create a TLS certificate issuer resource, such as {KUADRANT_CLUSTER_ISSUER_NAME}.yaml, that has the following information:

   apiVersion: cert-manager.io/v1
   kind: ClusterIssuer
   metadata:
     name: ${KUADRANT_CLUSTER_ISSUER_NAME}
   spec:
     selfSigned: {}

   Copy code to clipboard

3. Apply the ClusterIssuer CR by running the following command:

   $ oc apply -f {KUADRANT_CLUSTER_ISSUER_NAME}.yaml

   Copy code to clipboard

Procedure

1. Create a DNSPolicy custom resource (CR), for example, {KUADRANT_GATEWAY_NAME}-dnspolicy.yaml, that includes the following information:

   apiVersion: kuadrant.io/v1
   kind: DNSPolicy
   metadata:
     name: <${KUADRANT_GATEWAY_NAME}-dnspolicy>
     namespace: <${KUADRANT_GATEWAY_NS}>
   spec:
     healthCheck:
       failureThreshold: 3
       interval: 1m
       path: /health
     loadBalancing:
       defaultGeo: true
       geo: GEO-NA
       weight: 120
     targetRef:
       name: <${KUADRANT_GATEWAY_NAME}>
       group: gateway.networking.k8s.io
       kind: Gateway
     providerRefs:
     - name: <dns_provider_credentials>

   Copy code to clipboard
   • Replace <{KUADRANT_GATEWAY_NAME}-dnspolicy.yaml> with the environment variable you defined.
   • Replace <{KUADRANT_GATEWAY_NS}> with the environment variable you defined.
   • spec.loadBalancing.geo: Defines a geographically relevant load balancer. In this example, GEO-NA is used. Change this to match your requirements.
   • spec.providerRefs: Replace <dns_provider_credentials> with a reference to the OpenShift Container Platform secret containing the credentials for your DNS provider.

2. Apply the DNSPolicy CR by running the following command:

   $ oc apply -f <{KUADRANT_GATEWAY_NAME}-dnspolicy.yaml> -n <gateway-namespace>

   Copy code to clipboard
   • Replace <{KUADRANT_GATEWAY_NAME}-dnspolicy.yaml> with the filename you used.
   • Replace <gateway-namespace> with name of the OpenShift Container Platform namespace that contains the gateway.

Verification

1. Verify that your DNSPolicy object has a status of Accepted and Enforced by running the following command:

   $ oc get dnspolicy <${KUADRANT_GATEWAY_NAME}-dnspolicy> -n <${KUADRANT_GATEWAY_NS}> -o=jsonpath='{.status.conditions[?(@.type=="SubResourcesHealthy")].message}'

   Copy code to clipboard
   • Replace <{KUADRANT_GATEWAY_NAME}-dnspolicy.yaml> with the filename you used.
   • Replace <{KUADRANT_GATEWAY_NS}> with the environment variable you used.
   • This process might take a few minutes.

2. Check the status of the DNS health checks that are enabled on your DNS policy by running the following command:

   $ oc get dnspolicy <${KUADRANT_GATEWAY_NAME}-dnspolicy> -n <${KUADRANT_GATEWAY_NS}> -o=jsonpath='{.status.conditions[?(@.type=="SubResourcesHealthy")].message}'

   Copy code to clipboard
   • Replace <{KUADRANT_GATEWAY_NAME}-dnspolicy.yaml> with the filename you used.
   • Replace <{KUADRANT_GATEWAY_NS}> with the environment variable you used.
   • These health checks flag a published endpoint as healthy or unhealthy based on the defined configuration. When unhealthy, an endpoint is not published if it has not already been published to the DNS provider. An endpoint is only unpublished if it is part of an A record that has multiple values. You can see endpoint status in all cases in the DNSPolicy object status.

Procedure

1. Create a default AuthPolicy CR, such as gateway_name-auth.yaml, with a deny-all setting for your Gateway object:

   Example AuthPolicy CR

   apiVersion: kuadrant.io/v1
   kind: AuthPolicy
   metadata:
     name: ${KUADRANT_GATEWAY_NAME}-auth
     namespace: ${KUADRANT_GATEWAY_NS}
   spec:
     targetRef:
       group: gateway.networking.k8s.io
       kind: Gateway
       name: ${KUADRANT_GATEWAY_NAME}
     defaults:
      when:
        - predicate: "request.path != '/health'"
      rules:
       authorization:
         deny-all:
           opa:
             rego: "allow = false"
       response:
         unauthorized:
           headers:
             "content-type":
               value: application/json
           body:
             value: |
               {
                 "error": "Forbidden",
                 "message": "Access denied by default by the gateway operator. If you are the administrator of the service, create a specific auth policy for the route."
               }

   Copy code to clipboard

2. Apply your AuthPolicy CR by running the following command:

   $ oc apply -f <gateway_name_auth.yaml>

   Copy code to clipboard
   • Replace <gateway_name_auth.yaml> with the name of your AuthPolicy CR.

Verification

1. Check that your AuthPolicy has Accepted and Enforced status by running the following command:

   $ oc get authpolicy ${KUADRANT_GATEWAY_NAME}-auth -n ${KUADRANT_GATEWAY_NS} -o=jsonpath='{.status.conditions[?(@.type=="Accepted")].message}{"\n"}{.status.conditions[?(@.type=="Enforced")].message}'

   Copy code to clipboard

   Example output

   AuthPolicy has been accepted
   AuthPolicy has been successfully enforced

   Copy code to clipboard

2. Test your AuthPolicy CR by running the following curl command:

   $ curl -H 'Authorization: APIKEY ndyBzreUzF4zqDQsqSPMHkRhriEOtcRx' http://talker-api.127.0.0.1.nip.io:8000/hello

   Copy code to clipboard

   Example output

   HTTP/1.1 200 OK

   Copy code to clipboard

Procedure

1. Create a default RateLimitPolicy custom resource (CR), for example, gateway_name-rlp.yaml, that has the following information:

   Example RateLimitPolicy CR

   apiVersion: kuadrant.io/v1
   kind: RateLimitPolicy
   metadata:
     name: ${KUADRANT_GATEWAY_NAME}-rlp
     namespace: ${KUADRANT_GATEWAY_NS}
   spec:
     targetRef:
       group: gateway.networking.k8s.io
       kind: Gateway
       name: ${KUADRANT_GATEWAY_NAME}
     defaults:
       limits:
         "low-limit":
           rates:
           - limit: 1
             window: 10s

   Copy code to clipboard

   • A low-limit value is used in this example for the ease of testing the CR. Configure the spec.defaults.limits: values that makes in your use case.

2. Apply your RateLimitPolicy CR by running the following command:

   $ oc apply -f <gateway_name-rlp.yaml>

   Copy code to clipboard
   • Replace <gateway_name-rlp.yaml> with the name of your RateLimitPolicy YAML.

Verification

1. Check that your RateLimitPolicy has Accepted and Enforced status by running the following command:

   $ oc get ratelimitpolicy ${KUADRANT_GATEWAY_NAME}-rlp -n ${KUADRANT_GATEWAY_NS} -o=jsonpath='{.status.conditions[?(@.type=="Accepted")].message}{"\n"}{.status.conditions[?(@.type=="Enforced")].message}'

   Copy code to clipboard

   Example output

   RateLimitPolicy has been accepted
   RateLimitPolicy has been successfully enforced

   Copy code to clipboard

2. Test your rate-limiting by running the following curl command:

   $ while :; do curl -k --write-out '%{http_code}\n' --silent --output /dev/null  "https://api.$KUADRANT_ZONE_ROOT_DOMAIN/cars" | grep -E --color "\b(429)\b|$"; sleep 1; done

   Copy code to clipboard

   HTTP 403 responses are expected.

Procedure

1. Find the name of the Limitador CR in your cluster by running the following command:

   $ oc get limitador -A

   Copy code to clipboard

2. Apply a patch to add headers to the CR by running the following command:

   $ oc patch limitador limitador -n KUADRANT-NAMESPACE --type=merge -p '{"spec": {"rateLimitHeaders": "DRAFT_VERSION_03"}}'

   Copy code to clipboard

Procedure

1. Set the KUADRANT_SYSTEM_NS environment variable based on where you created the Kuadrant custom resource (CR) by running the following command:

   $ export KUADRANT_SYSTEM_NS=$(oc get kuadrant -A -o jsonpath="{.items[0].metadata.namespace}")

   Copy code to clipboard

2. Create the Secret custom resources (CRs), or API keys, for bob and alice users that contain the following information:

   Example user Secret CRs

   apiVersion: v1
   kind: Secret
   metadata:
     name: bob-key
     namespace: ${KUADRANT_SYSTEM_NS}
     labels:
       authorino.kuadrant.io/managed-by: authorino
       app: toystore
     annotations:
       secret.kuadrant.io/user-id: bob
   stringData:
     api_key: IAMBOB
   type: Opaque
   ---
   apiVersion: v1
   kind: Secret
   metadata:
     name: alice-key
     namespace: ${KUADRANT_SYSTEM_NS}
     labels:
       authorino.kuadrant.io/managed-by: authorino
       app: toystore
     annotations:
       secret.kuadrant.io/user-id: alice
   stringData:
     api_key: IAMALICE
   type: Opaque
   EOF

   Copy code to clipboard

3. Apply the API keys by running the following commands:

   $ oc apply -f <bob-key.yaml>

   Copy code to clipboard

   Replace <bob-key.yaml> with the filename you used.

   $ oc apply -f <alice-key.yaml>

   Copy code to clipboard

   Replace <alice-key.yaml> with the filename you used.

4. Create a new AuthPolicy in a different namespace that overrides the deny-all policy and accepts the API keys. For example, the following toystore-auth.yaml:

   Example user AuthPolicy

   apiVersion: kuadrant.io/v1
   kind: AuthPolicy
   metadata:
     name: toystore-auth
     namespace: ${KUADRANT_DEVELOPER_NS}
   spec:
     targetRef:
       group: gateway.networking.k8s.io
       kind: HTTPRoute
       name: toystore
     defaults:
      when:
        - predicate: "request.path != '/health'"
      rules:
       authentication:
         "api-key-users":
           apiKey:
             selector:
               matchLabels:
                 app: toystore
           credentials:
             authorizationHeader:
               prefix: APIKEY
       response:
         success:
           filters:
             "identity":
               json:
                 properties:
                   "userid":
                     selector: auth.identity.metadata.annotations.secret\.kuadrant\.io/user-id

   Copy code to clipboard

5. Apply the AuthPolicy CR by running the following commands:

   $ oc apply -f <bob-key.yaml>

   Copy code to clipboard

   Replace <bob-key.yaml> with the filename you used.

Procedure

1. Set up your cluster. Set the following environment variables for your cluster context:

   $ export CTX_PRIMARY=$(oc config current-context) \
     export KUBECONFIG=~/.kube/config \
     export PRIMARY_CLUSTER_NAME=local-cluster \
     export ONPREM_DOMAIN=<onprem-domain> \
     export KUADRANT_SUBDOMAIN=""

   Copy code to clipboard

   For the ONPREM_DOMAIN variable value, use your actual root domain. For the KUADRANT_SUBDOMAIN variable value, valid values are empty or kuadrant.

2. Extract the CoreDNS manifests from dns-operator bundle by running the following commands:

   $ podman create --name bundle registry.redhat.io/rhcl-1/dns-operator-bundle:rhcl-1.3.0

   Copy code to clipboard

   $ podman cp bundle:/coredns/manifests.yaml ./coredns-manifests.yaml

   Copy code to clipboard

   $ podman rm bundle

   Copy code to clipboard

3. Apply the manifests to the cluster by running the following command:

   $ oc apply -f ./coredns-manifests.yaml

   Copy code to clipboard

4. Create a ConfigMap to define the authoritative zone for CoreDNS. This minimal configuration enables the kuadrant plugin and GeoIP features.

   $ cat | oc --context $CTX_PRIMARY apply -f -
   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: coredns-kuadrant-config
     namespace: kuadrant-coredns
   data:
     Corefile: |
       ${KUADRANT_SUBDOMAIN}.${ONPREM_DOMAIN}:53 {
           debug
           errors
           health {
               lameduck 5s
           }
           ready
           log
           geoip <GeoIP-database-name>.mmdb {
               edns-subnet
           }
           metadata
           kuadrant
       }

   Copy code to clipboard
   Note

   For production or exact GeoIP routing, mount your licensed MaxMind GeoIP database into the CoreDNS pod and update the filename in the data.Corefile.geoip parameter.

5. Update the CoreDNS deployment to use the new configuration by running the following command:

   $ oc --context $CTX_PRIMARY -n kuadrant-system patch deployment kuadrant-coredns --patch '{"spec":{"template":{"spec":{"volumes":[{"name":"config-volume","configMap":{"name":"coredns-kuadrant-config","items":[{"key":"Corefile","path":"Corefile"}]}}]}}}}'

   Copy code to clipboard

6. Set a watch-and-wait command for the deployment rollout to complete:

   $ oc --context $CTX_PRIMARY -n kuadrant-system rollout status deployment/kuadrant-coredns

   Copy code to clipboard

   Example output

   kuadrant-coredns successfully rolled out

   Copy code to clipboard

7. Create the Kubernetes Secret that Connectivity Link uses to interact with CoreDNS. This secret specifies the zones this provider instance is authoritative for.

   $ oc create secret generic coredns-credentials \
     --namespace=kuadrant-system \
     --type=kuadrant.io/coredns \
     --from-literal=ZONES="${KUADRANT_SUBDOMAIN}.${ONPREM_DOMAIN}" \
     --context ${CTX_PRIMARY}

   Copy code to clipboard

Procedure

1. Set up the primary cluster. Set the following environment variables for your primary cluster context:

   $ export CTX_PRIMARY=<primary_cluster_context_name> \
     export KUBECONFIG=~/.kube/config \
     export PRIMARY_CLUSTER_NAME=<primary_cluster_name> \
     export ONPREM_DOMAIN=<onprem-domain> \
     export KUADRANT_SUBDOMAIN=<kuadrant>

   Copy code to clipboard
   • CTX_PRIMARY: Replace <primary_cluster_context_name> with the namespace of the cluster that you are specifying as primary.
   • KUBECONFIG: Adjust the path to your config directy as needed.
   • PRIMARY_CLUSTER_NAME: Replace <primary_cluster_name> with the name of the cluster that you are specifying as primary.
   • ONPREM_DOMAIN: Replace <onprem-domain> with your actual root domain. *` KUADRANT_SUBDOMAIN`: List the subdomain to delegate.

2. Extract the CoreDNS manifests from the dns-operator bundle by running the following commands:

   $ podman create --name bundle registry.redhat.io/rhcl-1/dns-operator-bundle:rhcl-1.3.0

   Copy code to clipboard

   $ podman cp bundle:/coredns/manifests.yaml ./coredns-manifests.yaml

   Copy code to clipboard

   $ podman rm bundle

   Copy code to clipboard

3. Apply the manifests to the cluster by running the following command:

   $ oc apply -f ./coredns-manifests.yaml

   Copy code to clipboard

4. Wait for the CoreDNS service to get an external IP address. You need the IP address to configure delegation on your authoritative on-premise DNS server. Retrieve and store the IP address by running the following command:

   $ export COREDNS_IP_PRIMARY=$(oc --context $CTX_PRIMARY -n kuadrant-system get service kuadrant-coredns -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
   echo "CoreDNS Primary IP: ${COREDNS_IP_PRIMARY}"

   Copy code to clipboard

5. Create a ConfigMap to define the authoritative zone for CoreDNS on the primary cluster. This minimal configuration enables the kuadrant plugin and GeoIP features.

   $ cat | oc --context $CTX_PRIMARY apply -f -
   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: coredns-kuadrant-config
     namespace: kuadrant-coredns
   data:
     Corefile: |
       ${KUADRANT_SUBDOMAIN}.${ONPREM_DOMAIN}:53 {
           debug
           errors
           health {
               lameduck 5s
           }
           ready
           log
           geoip <GeoIP-database-name>.mmdb {
               edns-subnet
           }
           metadata
           kuadrant
       }

   Copy code to clipboard
   Note

   For production or exact GeoIP routing, mount your licensed MaxMind GeoIP database into the CoreDNS pod and update the filename in the data.Corefile.geoip parameter.

6. Update the CoreDNS deployment to use the new configuration by running the following command:

   $ oc --context $CTX_PRIMARY -n kuadrant-system patch deployment kuadrant-coredns --patch '{"spec":{"template":{"spec":{"volumes":[{"name":"config-volume","configMap":{"name":"coredns-kuadrant-config","items":[{"key":"Corefile","path":"Corefile"}]}}]}}}}'

   Copy code to clipboard

7. Set a watch-and-wait command for the deployment rollout to complete by running the following command:

   $ oc --context $CTX_PRIMARY -n kuadrant-system rollout status deployment/kuadrant-coredns

   Copy code to clipboard

   Example output

   kuadrant-coredns successfully rolled out

   Copy code to clipboard

8. Create the Kubernetes Secret that Connectivity Link uses to interact with CoreDNS. This secret specifies the zones this provider instance is authoritative for.

   $ oc create secret generic coredns-credentials \
     --namespace=kuadrant-system \
     --type=kuadrant.io/coredns \
     --from-literal=ZONES="${KUADRANT_SUBDOMAIN}.${ONPREM_DOMAIN}" \
     --context ${CTX_PRIMARY}

   Copy code to clipboard

9. On your authoritative on-premise DNS server, configure delegation for the ${KUADRANT_SUBDOMAIN}.${ONPREM_DOMAIN} subdomain to the external IP addresses of the CoreDNS services running on your primary and secondary clusters, $COREDNS_IP_PRIMARY and $COREDNS_IP_SECONDARY. The specific steps depend on your DNS server software, for example, BIND, Windows DNS Server. You typically need to add Name Server (NS) records pointing the subdomain to the CoreDNS IP addresses.

   Example delegation

   ; Delegate kuadrant.example.local to CoreDNS instances
   $ORIGIN ${KUADRANT_SUBDOMAIN}.${ONPREM_DOMAIN}.
   @       IN      SOA     ns1.${ONPREM_DOMAIN}. hostmaster.${ONPREM_DOMAIN}. (
                           2023102601 ; serial
                           7200       ; refresh (2 hours)
                           3600       ; retry (1 hour)
                           1209600    ; expire (2 weeks)
                           3600       ; minimum (1 hour)
                           )
           IN      NS      coredns-primary.${KUADRANT_SUBDOMAIN}.${ONPREM_DOMAIN}.
   
   coredns-primary   IN A ${COREDNS_IP_PRIMARY}

   Copy code to clipboard

10. Restart CoreDNS by running the following command:

    $ oc -n kuadrant-coredns rollout restart deployment kuadrant-coredns

    Copy code to clipboard
    Note

    After configuring delegation, you can test that the DNS resolution for the delegated subdomain works correctly by querying your authoritative DNS server for a record within the kuadrant subdomain. One of the CoreDNS instances is expected to refer to and answer the query.

Verification

1. Launch a temporary pod for testing by running the following command:

   $ oc debug node/<node-name>

   Copy code to clipboard

   Replace <node-name> with the node you are testing on.

2. Add transfer to your Corefile by running the following command:

   $ oc patch cm kuadrant-coredns -n kuadrant-coredns --type merge \
      -p "$(oc get cm kuadrant-coredns -n kuadrant-coredns -o jsonpath='{.data.Corefile}' | \
      sed 's/kuadrant/transfer {\n        to *\n    }\n    kuadrant/' | \
      jq -Rs '{data: {Corefile: .}}')"

   Copy code to clipboard

3. Verify zone delegation by running the following command:

   $ dig @${EDGE_NS} -k config/bind9/ddns.key -t AXFR example.com

   Copy code to clipboard

   Example output

   example.com.            30      IN      SOA     example.com. root.example.com. 17 30 30 30 30
   example.com.            30      IN      NS      ns.example.com.
   k.example.com.          300     IN      NS      ns1.k.example.com.
   ns1.k.example.com.      300     IN      A       172.18.0.16
   ns.example.com.         30      IN      A       127.0.0.1
   example.com.            30      IN      SOA     example.com. root.example.com. 17 30 30 30 30

   Copy code to clipboard

   In this example, k.example is the delegated zone and ns1.k.example is the primary zone.

4. Optional. Remove the transfer from your Corefile by running the following command:

   $ oc patch cm kuadrant-coredns -n kuadrant-coredns --type merge \
      -p "$(oc get cm kuadrant-coredns -n kuadrant-coredns -o jsonpath='{.data.Corefile}' | \
      sed '/transfer {/,/}/d' | \
      jq -Rs '{data: {Corefile: .}}')"

   Copy code to clipboard

5. Verify the start of authority (SOA) record for the delegated zone by running the following command:

   $ dig @${EDGE_NS} soa k.example.com

   Copy code to clipboard

   Example output

   ;; ANSWER SECTION:
   k.example.com.          60      IN      SOA     ns1.k.example.com. hostmaster.k.example.com. 12345 7200 1800 86400 60

   Copy code to clipboard

   The SOA record is expected to show the primary name server (NS) as confirmation that CoreDNS is responding authoritatively. In this example the primary NS is ns1.k.example.com.

Procedure

1. On your local host, generate your certificate authority (CA) by running the following command:

   $ openssl req -x509 -sha512 -nodes \
     -days 365 \
     -newkey rsa:4096 \
     -subj "/CN=Test CA/O=Example Org/C=US" \
     -addext basicConstraints=CA:TRUE \
     -addext keyUsage=digitalSignature,keyCertSign \
     -keyout /tmp/ca.key \
     -out /tmp/ca.crt

   Copy code to clipboard

2. On your local host, create X.509 v3 extensions for your client certificate by running the following command:

   $ cat > /tmp/x509v3.ext << EOF
   authorityKeyIdentifier=keyid,issuer
   basicConstraints=CA:FALSE
   keyUsage=digitalSignature,nonRepudiation,keyEncipherment,dataEncipherment
   extendedKeyUsage=clientAuth
   EOF

   Copy code to clipboard

3. Generate the client certificate on your local host by running the following commands:

   1. Generate your Private Key. This is the secret file that stays on the client. Run the following command:

      $ openssl genrsa -out /tmp/client.key 4096

      Copy code to clipboard

   2. Create a Certificate Signing Request (CSR). The following command uses your private key and identity information to create a request for a certificate:

      $ openssl req -new \
        -subj "/CN=test-client/O=Example Org/C=US" \
        -key /tmp/client.key \
        -out /tmp/client.csr

      Copy code to clipboard

   3. Sign the certificate. This command takes your request, looks at your internal CA, and issues the final Public Certificate, the client.crt:

      $ openssl x509 -req -sha512 \
        -days 365 \
        -CA /tmp/ca.crt \
        -CAkey /tmp/ca.key \
        -CAcreateserial \
        -extfile /tmp/x509v3.ext \
        -in /tmp/client.csr \
        -out /tmp/client.crt

      Copy code to clipboard

4. If you do not have a CA that you use to issue and sign client certificates, create the self-signed CA certificate in your cluster by running the following commands:

   1. Create the ConfigMap for Gateway TLS validation by running the following command:

      $ oc create configmap gateway-client-ca \
        -n <gateway_system> \
        --from-file=ca.crt=/tmp/ca.crt

      Copy code to clipboard
      • Replace <gateway_system> with the namespace where your Gateway object is applied.
      • The ConfigMap must be in the same namespace as the Gateway object.

   2. Create the Authorino validation Secret by running the following command:

      $ oc create secret generic authorino-ca-validation \
        -n kuadrant-system \
        --from-file=ca.crt=/tmp/ca.crt

      Copy code to clipboard

      The Secret must be in the same namespace as Authorino.

   3. Label the Secret so that Authorino can find its trusted anchors by running the following command:

      $ oc label secret authorino-ca-validation \
        -n kuadrant-system \
        authorino.kuadrant.io/managed-by=authorino \
        app.kubernetes.io/name=trusted-client

      Copy code to clipboard

Procedure

1. Create the cert-manager Issuer custom resource (CR) by using the following example:

   apiVersion: cert-manager.io/v1
   kind: Issuer
   metadata:
     name: gateway-cert-issuer
     namespace: <gateway_system>
   spec:
     selfSigned: {}

   Copy code to clipboard
   • Replace <gateway_system> with the namespace of your Gateway object.

2. Apply the cert-manager Issuer object by running the following command:

   $ oc apply - f gateway-cert-issuer.yaml

   Copy code to clipboard

3. Create the TLSPolicy object by using the following example:

   apiVersion: kuadrant.io/v1
   kind: TLSPolicy
   metadata:
     name: mtls-gateway-tls
     namespace: <gateway_system>
   spec:
     targetRef:
       group: gateway.networking.k8s.io
       kind: Gateway
       name: mtls-gateway
       sectionName: https
     issuerRef:
       group: cert-manager.io
       kind: Issuer
       name: gateway-cert-issuer

   Copy code to clipboard
   • Replace the value of the metadata.namespace parameter with the namespace where your Gateway object is applied.

4. Apply the TLSPolicy object by running the following command:

   $ oc apply -f mtls-gateway-tls.yaml

   Copy code to clipboard

5. On your local host, create an infrastructure customization ConfigMap CR to inject the client CA volume mounts into the managed Istio proxy pods by using the following example:

   Example ConfigMap CR for use with an X.509 Gateway object

   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: mtls-gateway-config
     namespace: <gateway_system>
   data:
     deployment: |
       spec:
         template:
           spec:
             volumes:
             - name: client-ca
               configMap:
                 name: gateway-client-ca
             containers:
             - name: istio-proxy
               volumeMounts:
               - name: client-ca
                 mountPath: /etc/certs
                 readOnly: true

   Copy code to clipboard

   • Replace the value of the metadata.namespace parameter with the namespace where your Gateway object is applied.

6. Apply the infrastructure customization ConfigMap CR by running the following command:

   $ oc apply -f mtls-gateway-config.yaml

   Copy code to clipboard

7. Create the mTLS Gateway object by using the following example:

   apiVersion: gateway.networking.k8s.io/v1
   kind: Gateway
   metadata:
     name: mtls-gateway
     namespace: <gateway_system>
   spec:
     gatewayClassName: openshift-default
     infrastructure:
       parametersRef:
         group: ""
         kind: ConfigMap
         name: mtls-gateway-config
     listeners:
     - name: https
       protocol: HTTPS
       port: 443
       hostname: "<gateway_hostname>"
       allowedRoutes:
         namespaces:
           from: All
       tls:
         mode: Terminate
         certificateRefs:
         - name: <gateway_name>-<listener_name>-tls
           kind: Secret

   Copy code to clipboard
   • Replace the value of the metadata.namespace parameter with the namespace where your Gateway object is applied.
   • Replace the value of the spec.listeners.hostname parameter with the name of your Gateway object hostname.
   • Replace spec.listeners.tls.certificateRefs.name with the name of your Gateway object and the name of your mTLS listener in the <gateway_name>-<listener_name>-tls format.

8. Apply the mTLS Gateway CR by running the following command:

   $ oc apply -f mtls-gateway.yaml

   Copy code to clipboard

9. Create an EnvoyFilter CR to configure mutual TLS validation by using the following example:

   Example mutual TLS EnvoyFilter CR

   apiVersion: networking.istio.io/v1alpha3
   kind: EnvoyFilter
   metadata:
     name: mtls-validation
     namespace: <gateway_system>
   spec:
     targetRefs:
     - group: gateway.networking.k8s.io
       kind: Gateway
       name: mtls-gateway
     configPatches:
     - applyTo: FILTER_CHAIN
       match:
         context: GATEWAY
         listener:
           portNumber: 443
       patch:
         operation: MERGE
         value:
           transport_socket:
             name: envoy.transport_sockets.tls
             typed_config:
               "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext
               commonTlsContext:
                 validationContext:
                   trustedCa:
                     filename: /etc/certs/ca.crt
               requireClientCertificate: true

   Copy code to clipboard

   • Replace the value of the metadata.namespace parameter with the namespace where your Gateway object is applied.

10. Apply the EnvoyFilter CR by running the following command:

    $ oc apply -f mtls-envoyfilter.yaml

    Copy code to clipboard

Procedure

1. Deploy the sample application by using the following resources:

   Example httpbin application

   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: httpbin
   ---
   apiVersion: v1
   kind: Service
   metadata:
     name: httpbin
     labels:
       app: httpbin
       service: httpbin
   spec:
     ports:
     - name: http
       port: 80
     selector:
       app: httpbin
   ---
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: httpbin
   spec:
     replicas: 1
     selector:
       matchLabels:
         app: httpbin
         version: v1
     template:
       metadata:
         labels:
           app: httpbin
           version: v1
       spec:
         serviceAccountName: httpbin
         securityContext:
           runAsNonRoot: true
           seccompProfile:
             type: RuntimeDefault
         containers:
         - name: httpbin
           image: quay.io/kuadrant/httpbin@sha256:2865a9ac6596340135fc3cd82cbc543c4050124afb10361e36f727abe4f71900
           imagePullPolicy: IfNotPresent
           securityContext:
             runAsUser: 1000
             allowPrivilegeEscalation: false
             readOnlyRootFilesystem: true
             capabilities:
               drop:
               - ALL
           ports:
           - containerPort: 80
           volumeMounts:
           - name: tmp
             mountPath: /tmp
         volumes:
         - name: tmp
           emptyDir: {}

   Copy code to clipboard

2. Apply the application objects by running the following command:

   $ oc apply -f httpbin.yaml

   Copy code to clipboard

Procedure

1. Create your HTTPRoute CR by using the following example:

   apiVersion: gateway.networking.k8s.io/v1
   kind: HTTPRoute
   metadata:
     name: <httpbin_route>
     namespace: <default>
     labels:
       app: <httpbin>
   spec:
     parentRefs:
     - name: mtls-gateway
       namespace: <gateway_system>
     rules:
     - matches:
       - path:
           type: PathPrefix
           value: /
       backendRefs:
       - name: httpbin
         port: 80

   Copy code to clipboard
   • Replace the metadata.name parameter value with the name of your application route.
   • Replace the metadata.namespace parameter with the namespace where your Gateway object is applied.
   • Replace the metadata.labels.app value with the name of the application.
   • Replace the spec.parentRefs.namespace value with the namespace where your Gateway object is applied.

2. Apply your HTTPRoute custom resource by running the following command:

   $ oc apply -f <app_http_route.yaml>

   Copy code to clipboard

   Replace <app_http_route.yaml> with the name of your HTTPRoute YAML.

Procedure

1. Create your X.509 AuthPolicy CR by using the following example:

   Example X.509 AuthPolicy CR

   apiVersion: kuadrant.io/v1
   kind: AuthPolicy
   metadata:
     name: x509-auth-policy
     namespace: default
   spec:
     targetRef:
       group: gateway.networking.k8s.io
       kind: HTTPRoute
       name: httpbin-route
     rules:
       authentication:
         "x509-client-cert":
           x509:
             source:
               xfccHeader: "x-forwarded-client-cert"
             selector:
               matchLabels:
                 app.kubernetes.io/name: trusted-client
       authorization:
         "certificate-attributes":
           patternMatching:
             patterns:
             - predicate: "size(auth.identity.Organization) > 0 && auth.identity.Organization[0] == 'Example Org'"
       response:
         success:
           headers:
             "x-client-common-name":
               plain:
                 expression: auth.identity.CommonName
             "x-client-org":
               plain:
                 expression: auth.identity.Organization[0]

   Copy code to clipboard

   • The spec.rules.authentication."x509-client-cert".x509 parameter causes the policy to extract the certificate from the X-Forwarded-Client-Cert standard (XFCC) header. The Gateway object populates this header after validating the client certificate.
   • The spec.rules.authentication."x509-client-cert".x509.source.xfccHeader parameter value is the name of the XFCC header. This is the default header name.
   • Set the spec.rules.response.success.headers."x-client-common-name".plain.expression parameter value to ensure that the policy extracts the common name (CN) from the certificate.
   • Set the spec.rules.response.success.headers"x-client-org".plain.expression parameter value to ensure that the policy extracts the organization (O) from the certificate.

2. Apply your AuthPolicy custom resource by running the following command:

   $ oc apply -f <app_authpolicy.yaml>

   Copy code to clipboard

   Replace <app_authpolicy.yaml> with the name of your AuthPolicy YAML.

Procedure

1. Retrieve the Gateway object hostname by running the following command:

   $ export GATEWAY_HOSTNAME=$(oc get gateway mtls-gateway -n <gateway_system> -o jsonpath='{.status.addresses[0].value}')

   Copy code to clipboard

   Replace <gateway_system> with the namespace where your Gateway object is applied.

2. Test with a valid certificate by running the following command:

   $ curl -ik https://httpbin.${GATEWAY_HOSTNAME}/get \
     --cert /tmp/client.crt \
     --key /tmp/client.key

   Copy code to clipboard

   Expected output

   HTTP 200

   Copy code to clipboard

3. Verify that the TLS handshake fails when there is no certificate by running the following command:

   $ curl -ik https://httpbin.${GATEWAY_HOSTNAME}/get

   Copy code to clipboard

   Expected output

   curl: (56) OpenSSL SSL_read: OpenSSL/3.6.2: error:0A00045C:SSL routines::tlsv13 alert certificate required, errno 0

   Copy code to clipboard

4. Verify that the TLS handshake fails when there is an untrusted certificate by running the following commands:

   1. Generate an untrusted certificate by running the following command:

      $ openssl req -x509 -sha512 -nodes \
        -days 365 \
        -newkey rsa:4096 \
        -subj "/CN=Untrusted CA/O=Untrusted Org/C=US" \
        -keyout /tmp/untrusted-ca.key \
        -out /tmp/untrusted-ca.crt

      Copy code to clipboard

   2. Generate an untrusted private key by running the following command:

      $ openssl genrsa -out /tmp/untrusted-client.key 4096

      Copy code to clipboard

   3. Create a Certificate Signing Request (CSR) for the untrusted client by running the following command:

      $ openssl req -new \
        -subj "/CN=untrusted-client/O=Untrusted Org/C=US" \
        -key /tmp/untrusted-client.key \
        -out /tmp/untrusted-client.csr

      Copy code to clipboard

   4. Sign the request using your untrusted authority to issue the client certificate by running the following command:

      $ openssl x509 -req -sha512 \
        -days 365 \
        -CA /tmp/untrusted-ca.crt \
        -CAkey /tmp/untrusted-ca.key \
        -CAcreateserial \
        -extfile /tmp/x509v3.ext \
        -in /tmp/untrusted-client.csr \
        -out /tmp/untrusted-client.crt

      Copy code to clipboard

   5. Test the untrusted certificate by running the following command:

      $ curl -ik https://httpbin.${GATEWAY_HOSTNAME}/get \
        --cert /tmp/untrusted-client.crt \
        --key /tmp/untrusted-client.key

      Copy code to clipboard

      Expected output

      curl: (56) OpenSSL SSL_read: OpenSSL/3.6.2: error:0A000418:SSL routines::tlsv1 alert unknown ca, errno 0

      Copy code to clipboard

Procedure

1. Retrieve the gateway hostname by running the following command:

   $ export GATEWAY_HOSTNAME=$(oc get gateway mtls-gateway -n <gateway_system> -o jsonpath='{.status.addresses[0].value}')

   Copy code to clipboard

   Replace <gateway_system> with the namespace where your Gateway object is applied.

2. Verify a connection failure when there is a valid certificate, but wrong attributes by running the following commands:

   1. Generate a certificate with a different organization by running the following command:

      $ openssl genrsa -out /tmp/unauthorized-client.key 4096

      Copy code to clipboard

   2. Create a Certificate Signing Request (CSR) with unauthorized attributes by running the following command:

      $ openssl req -new \
        -subj "/CN=unauthorized-client/O=Unauthorized Org/C=US" \
        -key /tmp/unauthorized-client.key \
        -out /tmp/unauthorized-client.csr

      Copy code to clipboard

   3. Sign the request using your trusted certificate authority by running the following command:

      $ openssl x509 -req -sha512 \
        -days 365 \
        -CA /tmp/ca.crt \
        -CAkey /tmp/ca.key \
        -CAcreateserial \
        -extfile /tmp/x509v3.ext \
        -in /tmp/unauthorized-client.csr \
        -out /tmp/unauthorized-client.crt

      Copy code to clipboard

   4. Test the unauthorized certificate by running the following command:

      $ curl -ik https://httpbin.${GATEWAY_HOSTNAME}/get \
        --cert /tmp/unauthorized-client.crt \
        --key /tmp/unauthorized-client.key

      Copy code to clipboard

      Expected output

      HTTP 403

      Copy code to clipboard

Procedure

1. If the TLS handshake succeeds without client certificate, the Envoy filter might not be properly applied. Troubleshoot this situation by taking the following steps:

   1. Verify that the EnvoyFilter exists by running the following command:

      $ oc get envoyfilter mtls-validation -n <gateway_system>

      Copy code to clipboard

      Replace <gateway_system> with the namespace where your Gateway object is applied.

   2. Check that the targetRef in the Envoy filter points to the Gateway object by running the following command:

      $ oc get envoyfilter mtls-validation -n <gateway_system> -o yaml | grep -A 3 targetRefs

      Copy code to clipboard

      Replace <gateway_system> with the namespace where your Gateway object is applied.

   3. Check that the Envoy configuration has the correct configuration by running the following command:

      $ oc exec -n <gateway_system> \
        $(oc get pod -n <gateway_system> -l gateway.networking.k8s.io/gateway-name=mtls-gateway -o jsonpath='{.items[0].metadata.name}') \
        -- curl -s localhost:15000/config_dump?include_eds | grep -A 20 validation_context

      Copy code to clipboard

      Replace <gateway_system> with the namespace where your Gateway object is applied.

2. If the Gateway object logs show failed to load trusted CA, the certificate authority (CA) might not be mounted. Use the following steps to check the CA:

   1. Verify that the ConfigMap exists by running the following command:

      $ oc get configmap gateway-client-ca -n <gateway_system>

      Copy code to clipboard

      Replace <gateway_system> with the namespace where your Gateway object is applied.

   2. Check that the volume mount in the Gateway pod by running the following command:

      $ oc describe pod -n <gateway_system> -l gateway.networking.k8s.io/gateway-name=mtls-gateway | grep -A 5 Mounts

      Copy code to clipboard

      Replace <gateway_system> with the namespace where your Gateway object is applied.

   3. Verify that the CA file exists in the Gateway pod by running the following command:

      $ oc exec -n <gateway_system> \
        $(oc get pod -n <gateway_system> -l gateway.networking.k8s.io/gateway-name=mtls-gateway -o jsonpath='{.items[0].metadata.name}') \
        -- cat /etc/certs/ca.crt

      Copy code to clipboard

      Replace <gateway_system> with the namespace where your Gateway object is applied.

3. If Authorino rejects requests with a certificate not found error, the XFCC header might not be set correctly. Check the configuration and logs to help resolve this issue as follows:

   1. Verify the forward_client_cert_details configuration by running the following command:

      $ oc exec -n <gateway_system> \
        $(oc get pod -n <gateway_system> -l gateway.networking.k8s.io/gateway-name=mtls-gateway -o jsonpath='{.items[0].metadata.name}') \
        -- curl -s localhost:15000/config_dump?include_eds | grep -i forward_client_cert

      Copy code to clipboard

      Replace <gateway_system> with the namespace where your Gateway object is applied.

   2. Check the Envoy access logs for the XFCC header by running the following command:

      $ oc logs -n <gateway_system> -l gateway.networking.k8s.io/gateway-name=mtls-gateway | grep XFCC

      Copy code to clipboard

      Replace <gateway_system> with the namespace where your Gateway object is applied.