Address comments

site-src/geps/gep-1867.md

@@ -1,15 +1,14 @@
 # GEP-1867: Per-Gateway Infrastructure
 
 * Status: Provisional
+* Issue: [#1876](https://github.com/kubernetes-sigs/gateway-api/issues/1876)
 
 ## Overview
 
-Gateways represent a piece of infrastructure, whether this is  implemented by cloud load balancers, in-cluster deployments, or other mechanisms.
-These often need vendor-configuration outside the scope of existing APIs.
-For example, the "size" or "version" of the infrastructure to provision.
+`Gateway`s represent a piece of infrastructure implemented by cloud load balancers, in-cluster deployments, or other mechanisms.
+These often need vendor-specific configuration outside the scope of existing APIs (e.g. "size" or "version" of the infrastructure to provision).
 
-Today, this is configurable via `GatewayClass.spec.parametersRef`, which offers the ability to attach arbitrary configuration
-to a GatewayClass.
+Today `GatewayClass.spec.parametersRef` is available to attach arbitrary configuration to a `GatewayClass`.
 
 This GEP will explain why that is not sufficient to meet common use cases, and introduce a new field - `infrastructure` - to address these cases.
 
@@ -22,8 +21,8 @@ Related discussions:
 
 ## Goals
 
-* Provide the ability to configure arbitrary (implementation specific) attributes about a specific Gateway.
-* Provide the ability to configure a standardized set attributes about a specific Gateway.
+* Provide the ability to configure arbitrary (implementation specific) attributes about a **specific Gateway**.
+* Provide the ability to configure a standardized set of attributes about a **specific Gateway**.
 
 ## Challenges with GatewayClass
 
@@ -32,17 +31,11 @@ However, this introduces operational challenges when configuring Gateways.
 
 ### Scope
 
-GatewayClass is a cluster scoped resource. This effectively limits customization to either:
-1. Cluster admin pre-provisions a few classes, lower-privilege Gateway admins select them.
-2. Gateway admin and Cluster admin are the same.
+As a `Gateway` manager (with RBAC permissions to a specific `Gateway`) I should be able to declaratively make changes to that `Gateway` without the need for access to cluster-scoped resources (`GatewayClass`) and without affecting other `Gateways` managed by the same `GatewayClass`.
 
-Case 1 works great when there are only a handful of customizations needed.
-For example, you could have a "public" vs "private" class, or a "big" and "small" class.
-This doesn't scale beyond simple cases, however; even the example above requires 4 classes and exponentially grows as more use cases are needed.
-
-Case 2 works fine, but greatly limits use cases, such as [Support namespace scoped implementations](https://github.com/kubernetes-sigs/gateway-api/issues/567).
-Rather than having 1 big ingress for the entire cluster, it is common for clusters to have multiple smaller gateways ([example](https://istio.io/latest/docs/setup/additional-setup/gateway/#gateway-deployment-topologies).
-This can be A gateway per app, per namespace,  per "tenant", or any mix of these.
+As a cluster scoped resource, `GatewayClass` does not meet this requirement.
+This restricts customization use cases to either a few pre-provisioned classes by the admin, or running in an environment where the "Infrastructure Provider" and "Cluster Operator" are the same roles.
+The distinction between these roles is explicitly called out on the homepage: https://gateway-api.sigs.k8s.io/#what-is-the-gateway-api.
 
 ### Custom Resource
 
@@ -56,7 +49,7 @@ Additionally, there is hesitancy to use a CRD (which leads to CRD proliferation)
 
 ### Separation of concerns
 
-While these is value out of providing class-wide options as defaults, there is also value in providing these on the object (Gateway) directly.
+While there is value out of providing class-wide options as defaults, there is also value in providing these options on the object (Gateway) directly.
 
 Some parallels in existing APIs:
 
@@ -76,8 +69,6 @@ Changes to it are not expected to change deployed `Gateway`s.
 This makes usage problematic in a declarative way.
 For example, if I wanted to represent a `version` field and change that to trigger an upgrade, I would need to create an entirely new `Gateway`.
 
-
-
 ## API
 
 In order to address the concerns above, I propose a standard `infrastructure` API is added to `Gateway` and `GatewayClass`.
@@ -90,7 +81,7 @@ However, they are shown below to give a sense of the use cases the field can sup
 ```go
 type GatewaySpec struct {
   // Infrastructure defines infrastructure level attributes about this Gateway instance.
-	Infrastructure GatewayInfrastructure `json:"infrastructure"`
+  Infrastructure GatewayInfrastructure `json:"infrastructure"`
   // ...
 }
 
@@ -99,7 +90,7 @@ type GatewayClassSpec struct {
   // Infrastructure defines infrastructure level attributes for all Gateways in this class.
   // A Gateway may provide configuration for the same values; as all fields in GatewayInfrastructure are implementation specific,
   // the merging logic between these is as well.
-	Infrastructure GatewayInfrastructure `json:"infrastructure"`
+  Infrastructure GatewayInfrastructure `json:"infrastructure"`
   // ...
 }