fix review comments, change ApplicationProto scope and enum

Signed-off-by: Guy Daich <guy.daich@sap.com>
guydc · May 3, 2024 · 697aa10 · 697aa10
1 parent 6356e5e
commit 697aa10
Show file tree

Hide file tree

Showing 5 changed files with 97 additions and 52 deletions.
diff --git a/api/v1alpha1/backend_types.go b/api/v1alpha1/backend_types.go
@@ -14,6 +14,21 @@ const (
 	KindBackend = "Backend"
 )
 
+// +kubebuilder:validation:Enum=FQDN;UDS;IPv4;IPv6
+type AddressType string
+
+const (
+	// AddressTypeFQDN defines the RFC-1123 compliant fully qualified domain name address type.
+	AddressTypeFQDN ProtocolType = "FQDN"
+	// AddressTypeUDS defines the unix domain socket address type.
+	AddressTypeUDS ProtocolType = "UDS"
+	// AddressTypeIPv4 defines the IPv4 address type.
+	AddressTypeIPv4 ProtocolType = "IPv4"
+	// AddressTypeIPv6 defines the IPv4 address type.
+	AddressTypeIPv6 ProtocolType = "IPv6"
+)
+
+// +kubebuilder:validation:Enum=TCP;UDP
 type ProtocolType string
 
 const (
@@ -23,11 +38,12 @@ const (
 	ProtocolTypeUDP ProtocolType = "UDP"
 )
 
+// +kubebuilder:validation:Enum=HTTP2;WS
 type ApplicationProtocolType string
 
 const (
-	// ApplicationProtocolTypeH2C defines the HTTP/2 prior knowledge application protocol.
-	ApplicationProtocolTypeH2C ApplicationProtocolType = "H2C"
+	// ApplicationProtocolTypeHTTP2 defines the HTTP/2 application protocol.
+	ApplicationProtocolTypeHTTP2 ApplicationProtocolType = "HTTP2"
 	// ApplicationProtocolTypeWS defines the WebSocket over HTTP protocol.
 	ApplicationProtocolTypeWS ApplicationProtocolType = "WS"
 )
@@ -57,30 +73,26 @@ type Backend struct {
 // +kubebuilder:validation:XValidation:rule="(has(self.socketAddress) || has(self.unixDomainSocketAddress))",message="one of socketAddress or unixDomainSocketAddress must be specified"
 // +kubebuilder:validation:XValidation:rule="(has(self.socketAddress) && !has(self.unixDomainSocketAddress)) || (!has(self.socketAddress) && has(self.unixDomainSocketAddress))",message="only one of socketAddress or unixDomainSocketAddress can be specified"
 type BackendAddress struct {
-	// Name is the unique name of the backend address
-	Name string `json:"name,omitempty"`
+	// Type is the the type name of the backend address: FQDN, UDS, IPv4, IPv6
+	Type AddressType `json:"type"`
 
-	// SocketAddress is a [FQDN|IP]:[Port] address
+	// SocketAddress defines a FQDN, IPv4 or IPv6 address
 	SocketAddress *SocketAddress `json:"socketAddress,omitempty"`
 
-	// UnixDomainSocketAddress is a unix domain socket path
+	// UnixDomainSocketAddress defines the unix domain socket path
 	UnixDomainSocketAddress *UnixDomainSocketAddress `json:"unixDomainSocketAddress,omitempty"`
-
-	// ApplicationProtocol determines the application protocol to be used, e.g. HTTP2.
-	ApplicationProtocol *ApplicationProtocolType `json:"applicationProtocol,omitempty"`
 }
 
 // SocketAddress describes TCP/UDP socket address, corresponding to Envoy's SocketAddress
 // https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/address.proto#config-core-v3-socketaddress
 type SocketAddress struct {
-
-	// Address refers to the FQDN or IP address of the backend service.
+	// Address defines to the FQDN or IP address of the backend service.
 	Address string `json:"address"`
 
-	// Address refers to the FQDN or IP address of the backend service.
+	// Port defines to the port of of the backend service.
 	Port int32 `json:"port"`
 
-	// +kubebuilder:validation:Enum=TCP;UDP
+	// Protocol defines to the the transport protocol to use for communication with the backend.
 	Protocol *ProtocolType `json:"protocol,omitempty"`
 }
 
@@ -92,8 +104,12 @@ type UnixDomainSocketAddress struct {
 
 // BackendSpec describes the desired state of BackendSpec.
 type BackendSpec struct {
-	// +kubebuilder:validation:MaxItems=1
+	// +kubebuilder:validation:MinItems=1
+	// +kubebuilder:validation:MaxItems=4
 	BackendAddresses []BackendAddress `json:"addresses,omitempty"`
+
+	// ApplicationProtocol defines the application protocol to be used, e.g. HTTP2.
+	ApplicationProtocol *ApplicationProtocolType `json:"applicationProtocol,omitempty"`
 }
 
 // BackendStatus defines the state of Backend

diff --git a/api/v1alpha1/zz_generated.deepcopy.go b/api/v1alpha1/zz_generated.deepcopy.go
diff --git a/charts/gateway-helm/crds/generated/gateway.envoyproxy.io_backends.yaml b/charts/gateway-helm/crds/generated/gateway.envoyproxy.io_backends.yaml
@@ -58,26 +58,21 @@ spec:
                     BackendAddress describes are backend address, which is can be either a TCP/UDP socket or a Unix Domain Socket
                     corresponding to Envoy's Address: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/address.proto#config-core-v3-address
                   properties:
-                    applicationProtocol:
-                      description: ApplicationProtocol determines the application
-                        protocol to be used, e.g. HTTP2.
-                      type: string
-                    name:
-                      description: Name is the unique name of the backend address
-                      type: string
                     socketAddress:
-                      description: SocketAddress is a [FQDN|IP]:[Port] address
+                      description: SocketAddress defines a FQDN, IPv4 or IPv6 address
                       properties:
                         address:
-                          description: Address refers to the FQDN or IP address of
+                          description: Address defines to the FQDN or IP address of
                             the backend service.
                           type: string
                         port:
-                          description: Address refers to the FQDN or IP address of
-                            the backend service.
+                          description: Port defines to the port of of the backend
+                            service.
                           format: int32
                           type: integer
                         protocol:
+                          description: Protocol defines to the the transport protocol
+                            to use for communication with the backend.
                           enum:
                           - TCP
                           - UDP
@@ -86,15 +81,26 @@ spec:
                       - address
                       - port
                       type: object
+                    type:
+                      description: 'Type is the the type name of the backend address:
+                        FQDN, UDS, IPv4, IPv6'
+                      enum:
+                      - FQDN
+                      - UDS
+                      - IPv4
+                      - IPv6
+                      type: string
                     unixDomainSocketAddress:
-                      description: UnixDomainSocketAddress is a unix domain socket
-                        path
+                      description: UnixDomainSocketAddress defines the unix domain
+                        socket path
                       properties:
                         path:
                           type: string
                       required:
                       - path
                       type: object
+                  required:
+                  - type
                   type: object
                   x-kubernetes-validations:
                   - message: one of socketAddress or unixDomainSocketAddress must
@@ -104,8 +110,16 @@ spec:
                       can be specified
                     rule: (has(self.socketAddress) && !has(self.unixDomainSocketAddress))
                       || (!has(self.socketAddress) && has(self.unixDomainSocketAddress))
-                maxItems: 1
+                maxItems: 4
+                minItems: 1
                 type: array
+              applicationProtocol:
+                description: ApplicationProtocol defines the application protocol
+                  to be used, e.g. HTTP2.
+                enum:
+                - HTTP2
+                - WS
+                type: string
             type: object
           status:
             description: status defines the current status of Backend.

diff --git a/site/content/en/contributions/design/backend.md b/site/content/en/contributions/design/backend.md
@@ -53,15 +53,15 @@ kind: Backend
 metadata:
   name: backend-mixed-ip-uds
 spec:
+  applicationProtocol: H2C
   addresses:
-    - unixDomainSocketAddress:
+    - type: UDS
+      unixDomainSocketAddress:
         path: /var/run/backend.sock
-      applicationProtocol: HTTP2
-      name: uds-be
-    - socketAddress:
+    - type: IPv4  
+      socketAddress:
         address: 10.244.0.28
         port: 3000
-      name: ip-be
 ---
 apiVersion: gateway.networking.k8s.io/v1
 kind: HTTPRoute
@@ -114,11 +114,11 @@ spec:
   As such, all `BackendAdresses` are treated as equivalent endpoints with identical weights, TLS settings, etc.  
 * Gateway-API and Envoy Gateway policies that attach to Services ([BackendTLSPolicy][], [BackendLBPolicy][]) 
   MUST support attachment to the `Backend` resource in Envoy Gateway. 
-* Policy attachment to a named section of the `Backend` resource (the `backendAddress.name` field) is not supported at 
-  this time. Currently, `BackendObjectReference` can only select ports, and not generic section names. Hence, a named 
-  section of `Backend` cannot be referenced by routes, and so attachment of policies to named sections will create 
-  translation ambiguity. Users that wish to attach policies to some of the `BackendAddresses` in a `Backend` resource 
-  can use multiple `Backend` resources and pluralized `BackendRefs` instead. 
+* Policy attachment to a named section of the `Backend` resource is not supported at this time. Currently, 
+  `BackendObjectReference` can only select ports, and not generic section names. Hence, a named section of `Backend` 
+  cannot be referenced by routes, and so attachment of policies to named sections will create translation ambiguity. 
+  Users that wish to attach policies to some of the `BackendAddresses` in a `Backend` resource can use multiple `Backend` 
+  resources and pluralized `BackendRefs` instead. 
 * The `Backend` API SHOULD support other Gateway-API backend features, such as [Backend Protocol Selection][]. 
   Translation of explicit upstream application protocol setting MUST be consistent with the existing implementation for
   `Service` resources. 

diff --git a/site/content/en/latest/api/extension_types.md b/site/content/en/latest/api/extension_types.md
@@ -172,7 +172,7 @@ _Appears in:_
 | `TCP` | ActiveHealthCheckerTypeTCP defines the TCP type of health checking.<br /> | 
 
 
-#### ApplicationProtocolType
+#### AddressType
 
 _Underlying type:_ _string_
 
@@ -181,9 +181,20 @@ _Underlying type:_ _string_
 _Appears in:_
 - [BackendAddress](#backendaddress)
 
+
+
+#### ApplicationProtocolType
+
+_Underlying type:_ _string_
+
+
+
+_Appears in:_
+- [BackendSpec](#backendspec)
+
 | Value | Description |
 | ----- | ----------- |
-| `H2C` | ApplicationProtocolTypeH2C defines the HTTP/2 prior knowledge application protocol.<br /> | 
+| `HTTP2` | ApplicationProtocolTypeHTTP2 defines the HTTP/2 application protocol.<br /> | 
 | `WS` | ApplicationProtocolTypeWS defines the WebSocket over HTTP protocol.<br /> | 
 
 
@@ -231,10 +242,9 @@ _Appears in:_
 
 | Field | Type | Required | Description |
 | ---   | ---  | ---      | ---         |
-| `name` | _string_ |  true  | Name is the unique name of the backend address |
-| `socketAddress` | _[SocketAddress](#socketaddress)_ |  true  | SocketAddress is a [FQDN\|IP]:[Port] address |
-| `unixDomainSocketAddress` | _[UnixDomainSocketAddress](#unixdomainsocketaddress)_ |  true  | UnixDomainSocketAddress is a unix domain socket path |
-| `applicationProtocol` | _[ApplicationProtocolType](#applicationprotocoltype)_ |  true  | ApplicationProtocol determines the application protocol to be used, e.g. HTTP2. |
+| `type` | _[AddressType](#addresstype)_ |  true  | Type is the the type name of the backend address: FQDN, UDS, IPv4, IPv6 |
+| `socketAddress` | _[SocketAddress](#socketaddress)_ |  true  | SocketAddress defines a FQDN, IPv4 or IPv6 address |
+| `unixDomainSocketAddress` | _[UnixDomainSocketAddress](#unixdomainsocketaddress)_ |  true  | UnixDomainSocketAddress defines the unix domain socket path |
 
 
 #### BackendRef
@@ -271,6 +281,7 @@ _Appears in:_
 | Field | Type | Required | Description |
 | ---   | ---  | ---      | ---         |
 | `addresses` | _[BackendAddress](#backendaddress) array_ |  true  |  |
+| `applicationProtocol` | _[ApplicationProtocolType](#applicationprotocoltype)_ |  true  | ApplicationProtocol defines the application protocol to be used, e.g. HTTP2. |
 
 
 
@@ -2326,6 +2337,10 @@ _Appears in:_
 
 | Value | Description |
 | ----- | ----------- |
+| `FQDN` | AddressTypeFQDN defines the RFC-1123 compliant fully qualified domain name address type.<br /> | 
+| `UDS` | AddressTypeUDS defines the unix domain socket address type.<br /> | 
+| `IPv4` | AddressTypeIPv4 defines the IPv4 address type.<br /> | 
+| `IPv6` | AddressTypeIPv6 defines the IPv4 address type.<br /> | 
 | `TCP` | ProtocolTypeTCP defines the TCP address protocol.<br /> | 
 | `UDP` | ProtocolTypeUDP defines the UDP address protocol.<br /> | 
 
@@ -3074,9 +3089,9 @@ _Appears in:_
 
 | Field | Type | Required | Description |
 | ---   | ---  | ---      | ---         |
-| `address` | _string_ |  true  | Address refers to the FQDN or IP address of the backend service. |
-| `port` | _integer_ |  true  | Address refers to the FQDN or IP address of the backend service. |
-| `protocol` | _[ProtocolType](#protocoltype)_ |  true  |  |
+| `address` | _string_ |  true  | Address defines to the FQDN or IP address of the backend service. |
+| `port` | _integer_ |  true  | Port defines to the port of of the backend service. |
+| `protocol` | _[ProtocolType](#protocoltype)_ |  true  | Protocol defines to the the transport protocol to use for communication with the backend. |