From 697aa10a9f28e640889a4384c104765c0e130ff0 Mon Sep 17 00:00:00 2001 From: Guy Daich Date: Fri, 3 May 2024 17:18:01 -0500 Subject: [PATCH] fix review comments, change ApplicationProto scope and enum Signed-off-by: Guy Daich --- api/v1alpha1/backend_types.go | 44 +++++++++++++------ api/v1alpha1/zz_generated.deepcopy.go | 10 ++--- .../gateway.envoyproxy.io_backends.yaml | 42 ++++++++++++------ .../en/contributions/design/backend.md | 20 ++++----- site/content/en/latest/api/extension_types.md | 33 ++++++++++---- 5 files changed, 97 insertions(+), 52 deletions(-) diff --git a/api/v1alpha1/backend_types.go b/api/v1alpha1/backend_types.go index caa4ab88b12..26f5a75eaa3 100644 --- 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 index e5dacb940a1..53de2e2488d 100644 --- a/api/v1alpha1/zz_generated.deepcopy.go +++ b/api/v1alpha1/zz_generated.deepcopy.go @@ -216,11 +216,6 @@ func (in *BackendAddress) DeepCopyInto(out *BackendAddress) { *out = new(UnixDomainSocketAddress) **out = **in } - if in.ApplicationProtocol != nil { - in, out := &in.ApplicationProtocol, &out.ApplicationProtocol - *out = new(ApplicationProtocolType) - **out = **in - } } // DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new BackendAddress. @@ -259,6 +254,11 @@ func (in *BackendSpec) DeepCopyInto(out *BackendSpec) { (*in)[i].DeepCopyInto(&(*out)[i]) } } + if in.ApplicationProtocol != nil { + in, out := &in.ApplicationProtocol, &out.ApplicationProtocol + *out = new(ApplicationProtocolType) + **out = **in + } } // DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new BackendSpec. diff --git a/charts/gateway-helm/crds/generated/gateway.envoyproxy.io_backends.yaml b/charts/gateway-helm/crds/generated/gateway.envoyproxy.io_backends.yaml index 6288193e287..33bf4bc3a2e 100644 --- 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 index 50470ba3f12..3a4ffc5b569 100644 --- 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 index 182ba55f6c3..1943fc47fdf 100644 --- 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.
| -#### 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.
| +| `HTTP2` | ApplicationProtocolTypeHTTP2 defines the HTTP/2 application protocol.
| | `WS` | ApplicationProtocolTypeWS defines the WebSocket over HTTP protocol.
| @@ -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.
| +| `UDS` | AddressTypeUDS defines the unix domain socket address type.
| +| `IPv4` | AddressTypeIPv4 defines the IPv4 address type.
| +| `IPv6` | AddressTypeIPv6 defines the IPv4 address type.
| | `TCP` | ProtocolTypeTCP defines the TCP address protocol.
| | `UDP` | ProtocolTypeUDP defines the UDP address protocol.
| @@ -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. |