diff --git a/apis/v1alpha2/policy_types.go b/apis/v1alpha2/policy_types.go
index 9037870509..647b1c7a1e 100644
--- a/apis/v1alpha2/policy_types.go
+++ b/apis/v1alpha2/policy_types.go
@@ -16,7 +16,11 @@ limitations under the License.
package v1alpha2
-// PolicyTargetReference identifies an API object to apply policy to.
+// PolicyTargetReference identifies an API object to apply policy to. This
+// should be used as part of Policy resources that can target Gateway API
+// resources. For more information on how this policy attachment model works,
+// and a sample Policy resource, refer to the policy attachment documentation
+// for Gateway API.
type PolicyTargetReference struct {
// Group is the group of the target resource.
//
diff --git a/site-src/images b/site-src/images
new file mode 120000
index 0000000000..29293e6ead
--- /dev/null
+++ b/site-src/images
@@ -0,0 +1 @@
+v1alpha2/images
\ No newline at end of file
diff --git a/site-src/images/api-model.png b/site-src/images/api-model.png
deleted file mode 100644
index 1a01ac5f6c..0000000000
Binary files a/site-src/images/api-model.png and /dev/null differ
diff --git a/site-src/images/gateway-roles.png b/site-src/images/gateway-roles.png
deleted file mode 100644
index 4848bfa20f..0000000000
Binary files a/site-src/images/gateway-roles.png and /dev/null differ
diff --git a/site-src/images/gateway-route-binding.png b/site-src/images/gateway-route-binding.png
deleted file mode 100644
index a62baf7324..0000000000
Binary files a/site-src/images/gateway-route-binding.png and /dev/null differ
diff --git a/site-src/images/http-routing.png b/site-src/images/http-routing.png
deleted file mode 100644
index 3b9e417bc6..0000000000
Binary files a/site-src/images/http-routing.png and /dev/null differ
diff --git a/site-src/images/httproute-basic-example.svg b/site-src/images/httproute-basic-example.svg
deleted file mode 100644
index a02852868b..0000000000
--- a/site-src/images/httproute-basic-example.svg
+++ /dev/null
@@ -1 +0,0 @@
-
\ No newline at end of file
diff --git a/site-src/images/schema-uml.svg b/site-src/images/schema-uml.svg
deleted file mode 100644
index 11e1e29519..0000000000
--- a/site-src/images/schema-uml.svg
+++ /dev/null
@@ -1,275 +0,0 @@
-
-
diff --git a/site-src/images/simple-split.png b/site-src/images/simple-split.png
deleted file mode 100644
index dba5ac4963..0000000000
Binary files a/site-src/images/simple-split.png and /dev/null differ
diff --git a/site-src/images/single-service-gateway.png b/site-src/images/single-service-gateway.png
deleted file mode 100644
index b0095d117c..0000000000
Binary files a/site-src/images/single-service-gateway.png and /dev/null differ
diff --git a/site-src/images/tls-overview.svg b/site-src/images/tls-overview.svg
deleted file mode 100644
index 8b9e286155..0000000000
--- a/site-src/images/tls-overview.svg
+++ /dev/null
@@ -1,3 +0,0 @@
-
-
-
\ No newline at end of file
diff --git a/site-src/images/traffic-splitting-1.png b/site-src/images/traffic-splitting-1.png
deleted file mode 100644
index 0875d72b5f..0000000000
Binary files a/site-src/images/traffic-splitting-1.png and /dev/null differ
diff --git a/site-src/images/traffic-splitting-2.png b/site-src/images/traffic-splitting-2.png
deleted file mode 100644
index aefb6ca39e..0000000000
Binary files a/site-src/images/traffic-splitting-2.png and /dev/null differ
diff --git a/site-src/images/traffic-splitting-3.png b/site-src/images/traffic-splitting-3.png
deleted file mode 100644
index 22501cde1a..0000000000
Binary files a/site-src/images/traffic-splitting-3.png and /dev/null differ
diff --git a/site-src/v1alpha2/images/policy/hierarchy.png b/site-src/v1alpha2/images/policy/hierarchy.png
new file mode 100644
index 0000000000..77c15e12ee
Binary files /dev/null and b/site-src/v1alpha2/images/policy/hierarchy.png differ
diff --git a/site-src/v1alpha2/images/policy/ingress-attachment.png b/site-src/v1alpha2/images/policy/ingress-attachment.png
new file mode 100644
index 0000000000..dbd4035aab
Binary files /dev/null and b/site-src/v1alpha2/images/policy/ingress-attachment.png differ
diff --git a/site-src/v1alpha2/images/policy/ingress-complex.png b/site-src/v1alpha2/images/policy/ingress-complex.png
new file mode 100644
index 0000000000..2bb3e2541d
Binary files /dev/null and b/site-src/v1alpha2/images/policy/ingress-complex.png differ
diff --git a/site-src/v1alpha2/images/policy/ingress-simple.png b/site-src/v1alpha2/images/policy/ingress-simple.png
new file mode 100644
index 0000000000..62a2317db9
Binary files /dev/null and b/site-src/v1alpha2/images/policy/ingress-simple.png differ
diff --git a/site-src/v1alpha2/images/policy/mesh-complex.png b/site-src/v1alpha2/images/policy/mesh-complex.png
new file mode 100644
index 0000000000..c1a12fd36b
Binary files /dev/null and b/site-src/v1alpha2/images/policy/mesh-complex.png differ
diff --git a/site-src/v1alpha2/images/policy/mesh-simple.png b/site-src/v1alpha2/images/policy/mesh-simple.png
new file mode 100644
index 0000000000..5ab39b567a
Binary files /dev/null and b/site-src/v1alpha2/images/policy/mesh-simple.png differ
diff --git a/site-src/v1alpha2/images/policy/policy-hierarchy.png b/site-src/v1alpha2/images/policy/policy-hierarchy.png
new file mode 100644
index 0000000000..593543d2df
Binary files /dev/null and b/site-src/v1alpha2/images/policy/policy-hierarchy.png differ
diff --git a/site-src/v1alpha2/references/policy-attachment.md b/site-src/v1alpha2/references/policy-attachment.md
index 2d2391ecfc..4a9a8c2e21 100644
--- a/site-src/v1alpha2/references/policy-attachment.md
+++ b/site-src/v1alpha2/references/policy-attachment.md
@@ -1,17 +1,22 @@
# Policy Attachment
-Policies attached to Gateway API resources and implementations should use the
+Many implementations of the API support additional functionality that is not
+covered by the API directly. For example, concepts like timeouts, retries, or
+even CDN configuration are not sufficiently portable to be defined within the
+Gateway API. Instead, implementations may choose to represent these concepts
+with custom Policy resources.
+
+Policies attached to Gateway API resources and implementations must use the
following approach to ensure consistency across implementations of the API.
There are three primary components of this pattern:
-* A shared means of attaching policy to resources.
+* A standardized means of attaching policy to resources.
* Support for configuring both default and override values within policy
resources.
-* A shared hierarchy to illustrate how default and override values should
- interact.
+* A hierarchy to illustrate how default and override values should interact.
-This kind of standardization will not only enable consistent patterns, it will
-enable tooling such as kubectl plugins to be able to visualize all policies that
+This kind of standardization not only enables consistent patterns, it allows
+future tooling such as kubectl plugins to be able to visualize all policies that
have been applied to a given resource.
## Policy Attachment for Ingress
@@ -20,7 +25,7 @@ straightforward. A policy can reference the resource it wants to apply to.
Access is granted with RBAC - anyone that has access to create a RetryPolicy in
a given namespace can attach it to any resource within that namespace.
-
+
To build on that example, it’s possible to attach policies to more resources.
Each policy applies to the referenced resource and everything below it in terms
@@ -28,15 +33,15 @@ of hierarchy. Although this example is likely more complex than many real world
use cases, it helps demonstrate how policy attachment can work across
namespaces.
-
+
## Policy Attachment for Mesh
Although there is a great deal of overlap between ingress and mesh use cases,
-mesh enables more complex policy attachment scenarios. For example, you may want
-to apply policy to requests from a specific namespace to a backend in another
-namespace.
+mesh enables more complex policy attachment scenarios. For example, users may
+want to apply policy to requests from a specific namespace to a backend in
+another namespace.
-
+
Policy attachment can be quite simple with mesh. Policy can be applied to any
resource in any namespace but it can only apply to requests from the same
@@ -47,7 +52,7 @@ workload to a backend in another namespace. A route can be used to intercept
these requests and split them between different backends (foo-a and foo-b in
this case).
-
+
## Target Reference API
@@ -111,13 +116,9 @@ type ACMEServicePolicyStatus struct {
```
### Hierarchy
-Each policy MAY include default or override values. Default values are given
-precedence from the bottom up, while override values are top down. That means
-that a default attached to a Backend will have the highest precedence among
-default values while an override value attached to a GatewayClass will have the
-highest precedence overall.
+Each policy MAY include default or override values.
-
+
To illustrate this, consider 3 resources with the following hierarchy:
A > B > C. When attaching the concept of defaults and overrides to that, the
@@ -141,7 +142,7 @@ be enabled and provides some default configuration for that. The policy attached
to the Route changes the value for one of those fields (includeQueryString).
```yaml
-kind: GKEServicePolicy # Example of implementation specific policy name
+kind: AcmeServicePolicy # Example of implementation specific policy name
spec:
override:
cdn:
@@ -156,7 +157,7 @@ spec:
kind: Gateway
name: example
---
-kind: GKEServicePolicy
+kind: AcmeServicePolicy
spec:
default:
cdn:
@@ -172,13 +173,7 @@ precedence over the default drainTimeout value attached to the Route. At the
same time, we can see that the default connectionTimeout attached to the Route
has precedence over the default attached to the Gateway.
-
-
-#### Supported Resources
-It is important to note that not every implementation will be able to support
-policy attachment to each resource described in the hierarchy above. When that
-is the case, implementations MUST clearly document which resources a policy may
-be attached to.
+
#### Attaching Policy to GatewayClass
GatewayClass may be the trickiest resource to attach policy to. Policy
@@ -193,9 +188,9 @@ easier for some implementations to support. These parameters can similarly be
used to set defaults and requirements for an entire GatewayClass.
### Targeting External Services
-In some cases (likely limited to mesh) we may want to apply policies to requests
-to external services. To accomplish this, implementations can choose to support
-a refernce to a virtual resource type:
+In some cases (likely limited to mesh) users may want to apply policies to
+requests to external services. To accomplish this, implementations can choose to
+support a refernce to a virtual resource type:
```yaml
kind: RetryPolicy
@@ -224,17 +219,14 @@ ties:
* The Policy appearing first in alphabetical order by "/". For
example, foo/bar is given precedence over foo/baz.
-For a better user experience, a validating webhook can be implemented to prevent
-these kinds of conflicts all together.
-
### Kubectl Plugin
To help improve UX and standardization, a kubectl plugin will be developed that
will be capable of describing the computed sum of policy that applies to a given
resource, including policies applied to parent resources.
Each Policy CRD that wants to be supported by this plugin will need to follow
-the API structure defined above and add a `gateway.networking.k8s.io/policy:
-true` label to the CRD.
+the API structure defined above and add a
+`gateway.networking.k8s.io/policy-attachment: true` label to the CRD.
### Status
In the future, we may consider adding a new `Policies` field to status on
@@ -291,4 +283,6 @@ controller implementation:
This policy attachment pattern is associated with an "EXTENDED" conformance
level. The implementations that support this policy attachment model will have
the same behavior and semantics, although they may not be able to support
-attachment of all types of policy at all potential attachment points.
+attachment of all types of policy at all potential attachment points. When that
+is the case, implementations MUST clearly document which resources a policy may
+be attached to.