From 975a5e4b1f02c50b41d4f5af315be8f1d12c4025 Mon Sep 17 00:00:00 2001
From: Nathan Coleman <nathan.coleman@hashicorp.com>
Date: Tue, 14 Jun 2022 15:11:28 -0400
Subject: [PATCH] Add docs for ReferencePolicy as it applies to Gateways

---
 .../consul-api-gateway-install.mdx            | 51 ++++++++++++++++++-
 website/content/docs/api-gateway/index.mdx    |  2 +-
 2 files changed, 51 insertions(+), 2 deletions(-)

diff --git a/website/content/docs/api-gateway/consul-api-gateway-install.mdx b/website/content/docs/api-gateway/consul-api-gateway-install.mdx
index 74fd062b03..fb6cbdd71c 100644
--- a/website/content/docs/api-gateway/consul-api-gateway-install.mdx
+++ b/website/content/docs/api-gateway/consul-api-gateway-install.mdx
@@ -244,7 +244,56 @@ spec:
 
 </CodeBlockConfig>
 
-Refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Gateway) for details about configuring gateways:
+For a listener's `certificateRef` to reference a secret in a different namespace, you must also create a [ReferencePolicy](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferencePolicy).
+
+The following example creates a `Gateway` named `example-gateway` in namespace `gateway-namespace`. This `Gateway` has a `certificateRef` in namespace `secret-namespace`.
+The reference is allowed because the `ReferencePolicy`, named `reference-policy` in namespace `secret-namespace`, allows `Gateways` in `gateway-namespace` to reference `Secrets` in `secret-namespace`.
+
+<CodeBlockConfig filename="gateway_with_referencepolicy.yaml">
+
+```yaml
+apiVersion: gateway.networking.k8s.io/v1alpha2
+kind: Gateway
+metadata:
+  name: example-gateway
+  namespace: gateway-namespace
+  annotations:
+    'external-dns.alpha.kubernetes.io/hostname': DNS_HOSTNAME
+spec:
+  gatewayClassName: test-gateway-class
+  listeners:
+    - protocol: HTTPS
+      hostname: DNS_HOSTNAME
+      port: 443
+      name: https
+      allowedRoutes:
+        namespaces:
+          from: Same
+      tls:
+        certificateRefs:
+          - name: gateway-production-certificate
+            namespace: secret-namespace
+---
+
+apiVersion: gateway.networking.k8s.io/v1alpha2
+kind: ReferencePolicy
+metadata:
+  name: reference-policy
+  namespace: secret-namespace
+spec:
+  from:
+    - group: gateway.networking.k8s.io
+      kind: Gateway
+      namespace: gateway-namespace
+  to:
+    - group: ""
+      kind: Secret
+      name: gateway-production-certificate
+```
+
+</CodeBlockConfig>
+
+Refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Gateway) for further details about configuring gateways.
 
 #### Listeners
 
diff --git a/website/content/docs/api-gateway/index.mdx b/website/content/docs/api-gateway/index.mdx
index 5234eac604..d279bc5e69 100644
--- a/website/content/docs/api-gateway/index.mdx
+++ b/website/content/docs/api-gateway/index.mdx
@@ -38,7 +38,7 @@ are used, see the [documentation in our GitHub repo](https://github.com/hashicor
 | [`Gateway`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Gateway) | <ul><li>Supported protocols: `HTTP`, `HTTPS`, `TCP`</li><li>Header-based hostname matching (no SNI support)</li><li>Supported filters: header addition, removal, and setting</li><li>TLS modes supported: `terminate`</li><li>Certificate types supported: `core/v1/Secret`</li><li>Extended options: TLS version and cipher constraints</li></ul> |
 | [`HTTPRoute`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.HTTPRoute) | <ul><li>Weight-based load balancing</li><li>Supported rules: path, header, query, and method-based matching</li><li>Supported filters: header addition, removal, and setting</li><li>Supported backend types: <ol><li>`core/v1/Service` (must map to a registered Consul service)</li><li>`api-gateway.consul.hashicorp.com/v1alpha1/MeshService`</li></ol></li></ul> |
 | [`TCPRoute`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.TCPRoute) | <ul><li>Supported backend types: <ol><li>`core/v1/Service` (must map to a registered Consul service)</li><li>`api-gateway.consul.hashicorp.com/v1alpha1/MeshService`</li></ol></li></ul> |
-| [`ReferencePolicy`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferencePolicy) | <ul><li>Required to allow any reference from an `HTTPRoute` or `TCPRoute` to a Kubernetes `core/v1/Service` in a different namespace.</li><li>A route with an unpermitted BackendRef caused by the lack of a ReferencePolicy sets a `ResolvedRefs` status to `False` with the reason `RefNotPermitted`. The gateway listener rejects routes with an unpermitted BackendRef.</li><li>WARNING: If a route BackendRef becomes unpermitted, the entire route is removed from the gateway listener. <ul><li>A BackendRef can become unpermitted when you delete a Reference Policy or add a new unpermitted BackendRef to an existing route.</li></ul></li></ul> |
+| [`ReferencePolicy`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferencePolicy) | <ul><li>Required to allow any reference from a `Gateway` to a Kubernetes `core/v1/Secret` in a different namespace.</li><li>Required to allow any reference from an `HTTPRoute` or `TCPRoute` to a Kubernetes `core/v1/Service` in a different namespace.</li><li>A route with an unpermitted BackendRef caused by the lack of a ReferencePolicy sets a `ResolvedRefs` status to `False` with the reason `RefNotPermitted`. The gateway listener rejects routes with an unpermitted BackendRef.</li><li>WARNING: If a route BackendRef becomes unpermitted, the entire route is removed from the gateway listener. <ul><li>A BackendRef can become unpermitted when you delete a Reference Policy or add a new unpermitted BackendRef to an existing route.</li></ul></li></ul> |
 
 ## Additional Resources