Merge pull request #14288 from hashicorp/apigw-docs-x-namespace-cert

Add example code for cross-namespace certificateRefs

website/content/docs/api-gateway/configuration/gateway.mdx

@@ -174,7 +174,7 @@ In the following example, `tls` settings are configured to use a secret named `c
 
 tls:
   certificateRefs:
-    name: consul-server-cert
+  - name: consul-server-cert
     group: ""
     kind: Secret
   mode: Terminate
@@ -183,3 +183,49 @@ tls:
 
 ```
 
+#### Example cross-namespace certificateRef
+
+The following example creates a `Gateway` named `example-gateway` in namespace `gateway-namespace` (lines 2-4). The gateway has a `certificateRef` in namespace `secret-namespace` (lines 16-18). The reference is allowed because the `ReferenceGrant` configuration, named `reference-grant` in namespace `secret-namespace` (lines 24-27), allows `Gateways` in `gateway-namespace` to reference `Secrets` in `secret-namespace` (lines 31-35).
+
+<CodeBlockConfig filename="gateway_with_referencegrant.yaml" lineNumbers highlight="2-4,16-18,24-27,31-35">
+
+  ```yaml
+  apiVersion: gateway.networking.k8s.io/v1beta1
+  kind: Gateway
+  metadata:
+    name: example-gateway
+    namespace: gateway-namespace
+  spec:
+    gatewayClassName: consul-api-gateway
+    listeners:
+    - protocol: HTTPS
+      port: 443
+      name: https
+      allowedRoutes:
+        namespaces:
+          from: Same
+      tls:
+        certificateRefs:
+          - name: cert
+            namespace: secret-namespace
+            group: ""
+            kind: Secret
+  ---
+
+  apiVersion: gateway.networking.k8s.io/v1alpha2
+  kind: ReferenceGrant
+  metadata:
+    name: reference-grant
+    namespace: secret-namespace
+  spec:
+    from:
+    - group: gateway.networking.k8s.io
+      kind: Gateway
+      namespace: gateway-namespace
+      to:
+      - group: ""
+        kind: Secret
+        name: cert
+  ```
+
+</CodeBlockConfig>