diff --git a/src/apis/experimental/gatewayclasses.rs b/src/apis/experimental/gatewayclasses.rs index 90f2824..06313af 100644 --- a/src/apis/experimental/gatewayclasses.rs +++ b/src/apis/experimental/gatewayclasses.rs @@ -1,6 +1,6 @@ // WARNING: generated by kopium - manual changes will be overwritten // kopium command: kopium -Af - -// kopium version: 0.15.0 +// kopium version: 0.16.1 use kube::CustomResource; use schemars::JsonSchema; @@ -8,7 +8,7 @@ use serde::{Serialize, Deserialize}; /// Spec defines the desired state of GatewayClass. #[derive(CustomResource, Serialize, Deserialize, Clone, Debug, JsonSchema)] -#[kube(group = "gateway.networking.k8s.io", version = "v1beta1", kind = "GatewayClass", plural = "gatewayclasses")] +#[kube(group = "gateway.networking.k8s.io", version = "v1", kind = "GatewayClass", plural = "gatewayclasses")] #[kube(status = "GatewayClassStatus")] pub struct GatewayClassSpec { /// ControllerName is the name of the controller that is managing Gateways of this class. The value of this field MUST be a domain prefixed path. @@ -53,6 +53,9 @@ pub struct GatewayClassStatus { /// Controllers should prefer to publish conditions using values of GatewayClassConditionType for the type of each Condition. #[serde(default, skip_serializing_if = "Option::is_none")] pub conditions: Option>, + /// SupportedFeatures is the set of features the GatewayClass support. It MUST be sorted in ascending alphabetical order. + #[serde(default, skip_serializing_if = "Option::is_none", rename = "supportedFeatures")] + pub supported_features: Option>, } /// Condition contains details for one aspect of the current state of this API Resource. --- This struct is intended for direct use as an array at the field path .status.conditions. For example, diff --git a/src/apis/experimental/gateways.rs b/src/apis/experimental/gateways.rs index 01d02a1..efd13af 100644 --- a/src/apis/experimental/gateways.rs +++ b/src/apis/experimental/gateways.rs @@ -1,6 +1,6 @@ // WARNING: generated by kopium - manual changes will be overwritten // kopium command: kopium -Af - -// kopium version: 0.15.0 +// kopium version: 0.16.1 use kube::CustomResource; use schemars::JsonSchema; @@ -9,13 +9,12 @@ use std::collections::BTreeMap; /// Spec defines the desired state of Gateway. #[derive(CustomResource, Serialize, Deserialize, Clone, Debug, JsonSchema)] -#[kube(group = "gateway.networking.k8s.io", version = "v1beta1", kind = "Gateway", plural = "gateways")] +#[kube(group = "gateway.networking.k8s.io", version = "v1", kind = "Gateway", plural = "gateways")] #[kube(namespaced)] #[kube(status = "GatewayStatus")] pub struct GatewaySpec { /// Addresses requested for this Gateway. This is optional and behavior can depend on the implementation. If a value is set in the spec and the requested address is invalid or unavailable, the implementation MUST indicate this in the associated entry in GatewayStatus.Addresses. /// The Addresses field represents a request for the address(es) on the "outside of the Gateway", that traffic bound for this Gateway will use. This could be the IP address or hostname of an external load balancer or other networking infrastructure, or some other address that traffic will be sent to. - /// The .listener.hostname field is used to route traffic that has already arrived at the Gateway to the correct in-cluster destination. /// If no Addresses are specified, the implementation MAY schedule the Gateway in an implementation-specific manner, assigning an appropriate set of Addresses. /// The implementation MUST bind all Listeners to every GatewayAddress that it assigns to the Gateway and add a corresponding entry in GatewayStatus.Addresses. /// Support: Extended @@ -25,20 +24,38 @@ pub struct GatewaySpec { /// GatewayClassName used for this Gateway. This is the name of a GatewayClass resource. #[serde(rename = "gatewayClassName")] pub gateway_class_name: String, + /// Infrastructure defines infrastructure level attributes about this Gateway instance. + /// Support: Core + /// + #[serde(default, skip_serializing_if = "Option::is_none")] + pub infrastructure: Option, /// Listeners associated with this Gateway. Listeners define logical endpoints that are bound on this Gateway's addresses. At least one Listener MUST be specified. - /// Each listener in a Gateway must have a unique combination of Hostname, Port, and Protocol. - /// Within the HTTP Conformance Profile, the below combinations of port and protocol are considered Core and MUST be supported: - /// 1. Port: 80, Protocol: HTTP 2. Port: 443, Protocol: HTTPS - /// Within the TLS Conformance Profile, the below combinations of port and protocol are considered Core and MUST be supported: - /// 1. Port: 443, Protocol: TLS - /// Port and protocol combinations not listed above are considered Extended. - /// An implementation MAY group Listeners by Port and then collapse each group of Listeners into a single Listener if the implementation determines that the Listeners in the group are "compatible". An implementation MAY also group together and collapse compatible Listeners belonging to different Gateways. - /// For example, an implementation might consider Listeners to be compatible with each other if all of the following conditions are met: - /// 1. Either each Listener within the group specifies the "HTTP" Protocol or each Listener within the group specifies either the "HTTPS" or "TLS" Protocol. - /// 2. Each Listener within the group specifies a Hostname that is unique within the group. - /// 3. As a special case, one Listener within a group may omit Hostname, in which case this Listener matches when no other Listener matches. - /// If the implementation does collapse compatible Listeners, the hostname provided in the incoming client request MUST be matched to a Listener to find the correct set of Routes. The incoming hostname MUST be matched using the Hostname field for each Listener in order of most to least specific. That is, exact matches must be processed before wildcard matches. - /// If this field specifies multiple Listeners that have the same Port value but are not compatible, the implementation must raise a "Conflicted" condition in the Listener status. + /// Each Listener in a set of Listeners (for example, in a single Gateway) MUST be _distinct_, in that a traffic flow MUST be able to be assigned to exactly one listener. (This section uses "set of Listeners" rather than "Listeners in a single Gateway" because implementations MAY merge configuration from multiple Gateways onto a single data plane, and these rules _also_ apply in that case). + /// Practically, this means that each listener in a set MUST have a unique combination of Port, Protocol, and, if supported by the protocol, Hostname. + /// Some combinations of port, protocol, and TLS settings are considered Core support and MUST be supported by implementations based on their targeted conformance profile: + /// HTTP Profile + /// 1. HTTPRoute, Port: 80, Protocol: HTTP 2. HTTPRoute, Port: 443, Protocol: HTTPS, TLS Mode: Terminate, TLS keypair provided + /// TLS Profile + /// 1. TLSRoute, Port: 443, Protocol: TLS, TLS Mode: Passthrough + /// "Distinct" Listeners have the following property: + /// The implementation can match inbound requests to a single distinct Listener. When multiple Listeners share values for fields (for example, two Listeners with the same Port value), the implementation can match requests to only one of the Listeners using other Listener fields. + /// For example, the following Listener scenarios are distinct: + /// 1. Multiple Listeners with the same Port that all use the "HTTP" Protocol that all have unique Hostname values. 2. Multiple Listeners with the same Port that use either the "HTTPS" or "TLS" Protocol that all have unique Hostname values. 3. A mixture of "TCP" and "UDP" Protocol Listeners, where no Listener with the same Protocol has the same Port value. + /// Some fields in the Listener struct have possible values that affect whether the Listener is distinct. Hostname is particularly relevant for HTTP or HTTPS protocols. + /// When using the Hostname value to select between same-Port, same-Protocol Listeners, the Hostname value must be different on each Listener for the Listener to be distinct. + /// When the Listeners are distinct based on Hostname, inbound request hostnames MUST match from the most specific to least specific Hostname values to choose the correct Listener and its associated set of Routes. + /// Exact matches must be processed before wildcard matches, and wildcard matches must be processed before fallback (empty Hostname value) matches. For example, `"foo.example.com"` takes precedence over `"*.example.com"`, and `"*.example.com"` takes precedence over `""`. + /// Additionally, if there are multiple wildcard entries, more specific wildcard entries must be processed before less specific wildcard entries. For example, `"*.foo.example.com"` takes precedence over `"*.example.com"`. The precise definition here is that the higher the number of dots in the hostname to the right of the wildcard character, the higher the precedence. + /// The wildcard character will match any number of characters _and dots_ to the left, however, so `"*.example.com"` will match both `"foo.bar.example.com"` _and_ `"bar.example.com"`. + /// If a set of Listeners contains Listeners that are not distinct, then those Listeners are Conflicted, and the implementation MUST set the "Conflicted" condition in the Listener Status to "True". + /// Implementations MAY choose to accept a Gateway with some Conflicted Listeners only if they only accept the partial Listener set that contains no Conflicted Listeners. To put this another way, implementations may accept a partial Listener set only if they throw out *all* the conflicting Listeners. No picking one of the conflicting listeners as the winner. This also means that the Gateway must have at least one non-conflicting Listener in this case, otherwise it violates the requirement that at least one Listener must be present. + /// The implementation MUST set a "ListenersNotValid" condition on the Gateway Status when the Gateway contains Conflicted Listeners whether or not they accept the Gateway. That Condition SHOULD clearly indicate in the Message which Listeners are conflicted, and which are Accepted. Additionally, the Listener status for those listeners SHOULD indicate which Listeners are conflicted and not Accepted. + /// A Gateway's Listeners are considered "compatible" if: + /// 1. They are distinct. 2. The implementation can serve them in compliance with the Addresses requirement that all Listeners are available on all assigned addresses. + /// Compatible combinations in Extended support are expected to vary across implementations. A combination that is compatible for one implementation may not be compatible for another. + /// For example, an implementation that cannot serve both TCP and UDP listeners on the same address, or cannot mix HTTPS and generic TLS listens on the same port would not consider those cases compatible, even though they are distinct. + /// Note that requests SHOULD match at most one Listener. For example, if Listeners are defined for "foo.example.com" and "*.example.com", a request to "foo.example.com" SHOULD only be routed using routes attached to the "foo.example.com" Listener (and not the "*.example.com" Listener). This concept is known as "Listener Isolation". Implementations that do not support Listener Isolation MUST clearly document this. + /// Implementations MAY merge separate Gateways onto a single set of Addresses if all Listeners across all Gateways are compatible. /// Support: Core pub listeners: Vec, } @@ -54,6 +71,25 @@ pub struct GatewayAddresses { pub value: String, } +/// Infrastructure defines infrastructure level attributes about this Gateway instance. +/// Support: Core +/// +#[derive(Serialize, Deserialize, Clone, Debug, JsonSchema)] +pub struct GatewayInfrastructure { + /// Annotations that SHOULD be applied to any resources created in response to this Gateway. + /// For implementations creating other Kubernetes objects, this should be the `metadata.annotations` field on resources. For other implementations, this refers to any relevant (implementation specific) "annotations" concepts. + /// An implementation may chose to add additional implementation-specific annotations as they see fit. + /// Support: Extended + #[serde(default, skip_serializing_if = "Option::is_none")] + pub annotations: Option>, + /// Labels that SHOULD be applied to any resources created in response to this Gateway. + /// For implementations creating other Kubernetes objects, this should be the `metadata.labels` field on resources. For other implementations, this refers to any relevant (implementation specific) "labels" concepts. + /// An implementation may chose to add additional implementation-specific labels as they see fit. + /// Support: Extended + #[serde(default, skip_serializing_if = "Option::is_none")] + pub labels: Option>, +} + /// Listener embodies the concept of a logical endpoint where a Gateway accepts network connections. #[derive(Serialize, Deserialize, Clone, Debug, JsonSchema)] pub struct GatewayListeners { @@ -205,7 +241,7 @@ pub struct GatewayListenersTlsCertificateRefs { pub kind: Option, /// Name is the name of the referent. pub name: String, - /// Namespace is the namespace of the backend. When unspecified, the local namespace is inferred. + /// Namespace is the namespace of the referenced object. When unspecified, the local namespace is inferred. /// Note that when a namespace different than the local namespace is specified, a ReferenceGrant object is required in the referent namespace to allow that namespace's owner to accept the reference. See the ReferenceGrant documentation for details. /// Support: Core #[serde(default, skip_serializing_if = "Option::is_none")] @@ -225,7 +261,9 @@ pub enum GatewayListenersTlsMode { /// Status defines the current state of Gateway. #[derive(Serialize, Deserialize, Clone, Debug, JsonSchema)] pub struct GatewayStatus { - /// Addresses lists the IP addresses that have actually been bound to the Gateway. These addresses may differ from the addresses in the Spec, e.g. if the Gateway automatically assigns an address from a reserved pool. + /// Addresses lists the network addresses that have been bound to the Gateway. + /// This list may differ from the addresses provided in the spec under some conditions: + /// * no addresses are specified, all addresses are dynamically assigned * a combination of specified and dynamic addresses are assigned * a specified address was unusable (e.g. already in use) /// #[serde(default, skip_serializing_if = "Option::is_none")] pub addresses: Option>, @@ -240,7 +278,7 @@ pub struct GatewayStatus { pub listeners: Option>, } -/// GatewayStatusAddress describes an address that is bound to a Gateway. +/// GatewayStatusAddress describes a network address that is bound to a Gateway. #[derive(Serialize, Deserialize, Clone, Debug, JsonSchema)] pub struct GatewayStatusAddresses { /// Type of the address. @@ -286,7 +324,9 @@ pub enum GatewayStatusConditionsStatus { /// ListenerStatus is the status associated with a Listener. #[derive(Serialize, Deserialize, Clone, Debug, JsonSchema)] pub struct GatewayStatusListeners { - /// AttachedRoutes represents the total number of accepted Routes that have been successfully attached to this Listener. + /// AttachedRoutes represents the total number of Routes that have been successfully attached to this Listener. + /// Successful attachment of a Route to a Listener is based solely on the combination of the AllowedRoutes field on the corresponding Listener and the Route's ParentRefs field. A Route is successfully attached to a Listener when it is selected by the Listener's AllowedRoutes field AND the Route has a valid ParentRef selecting the whole Gateway resource or a specific Listener as a parent resource (more detail on attachment semantics can be found in the documentation on the various Route kinds ParentRefs fields). Listener or Route status does not impact successful attachment, i.e. the AttachedRoutes field count MUST be set for Listeners with condition Accepted: false and MUST count successfully attached Routes that may themselves have Accepted: false conditions. + /// Uses for this field include troubleshooting Route attachment and measuring blast radius/impact of changes to a Listener. #[serde(rename = "attachedRoutes")] pub attached_routes: i32, /// Conditions describe the current condition of this listener. diff --git a/src/apis/experimental/grpcroutes.rs b/src/apis/experimental/grpcroutes.rs index 0915609..deed0e0 100644 --- a/src/apis/experimental/grpcroutes.rs +++ b/src/apis/experimental/grpcroutes.rs @@ -1,6 +1,6 @@ // WARNING: generated by kopium - manual changes will be overwritten // kopium command: kopium -Af - -// kopium version: 0.15.0 +// kopium version: 0.16.1 use kube::CustomResource; use schemars::JsonSchema; @@ -27,13 +27,15 @@ pub struct GRPCRouteSpec { pub hostnames: Option>, /// ParentRefs references the resources (usually Gateways) that a Route wants to be attached to. Note that the referenced parent resource needs to allow this for the attachment to be complete. For Gateways, that means the Gateway needs to allow attachment from Routes of this kind and namespace. For Services, that means the Service must either be in the same namespace for a "producer" route, or the mesh implementation must support and allow "consumer" routes for the referenced Service. ReferenceGrant is not applicable for governing ParentRefs to Services - it is not possible to create a "producer" route for a Service in a different namespace from the Route. /// There are two kinds of parent resources with "Core" support: - /// * Gateway (Gateway conformance profile) * Service (Mesh conformance profile, experimental, ClusterIP Services only) - /// This API may be extended in the future to support additional kinds of parent resources. - /// It is invalid to reference an identical parent more than once. It is valid to reference multiple distinct sections within the same parent resource, such as two separate Listeners on the same Gateway or two separate ports on the same Service. + /// * Gateway (Gateway conformance profile) * Service (Mesh conformance profile, experimental, ClusterIP Services only) This API may be extended in the future to support additional kinds of parent resources. + /// ParentRefs must be _distinct_. This means either that: + /// * They select different objects. If this is the case, then parentRef entries are distinct. In terms of fields, this means that the multi-part key defined by `group`, `kind`, `namespace`, and `name` must be unique across all parentRef entries in the Route. * They do not select different objects, but for each optional field used, each ParentRef that selects the same object must set the same set of optional fields to different values. If one ParentRef sets a combination of optional fields, all must set the same combination. + /// Some examples: + /// * If one ParentRef sets `sectionName`, all ParentRefs referencing the same object must also set `sectionName`. * If one ParentRef sets `port`, all ParentRefs referencing the same object must also set `port`. * If one ParentRef sets `sectionName` and `port`, all ParentRefs referencing the same object must also set `sectionName` and `port`. /// It is possible to separately reference multiple distinct objects that may be collapsed by an implementation. For example, some implementations may choose to merge compatible Gateway Listeners together. If that is the case, the list of routes attached to those resources should also be merged. /// Note that for ParentRefs that cross namespace boundaries, there are specific rules. Cross-namespace references are only valid if they are explicitly allowed by something in the namespace they are referring to. For example, Gateway has the AllowedRoutes field, and ReferenceGrant provides a generic way to enable other kinds of cross-namespace reference. - /// ParentRefs from a Route to a Service in the same namespace are "producer" routes, which apply default routing rules to inbound connections from any namespace to the Service. - /// ParentRefs from a Route to a Service in a different namespace are "consumer" routes, and these routing rules are only applied to outbound connections originating from the same namespace as the Route, for which the intended destination of the connections are a Service targeted as a ParentRef of the Route. + /// ParentRefs from a Route to a Service in the same namespace are "producer" routes, which apply default routing rules to inbound connections from any namespace to the Service. + /// ParentRefs from a Route to a Service in a different namespace are "consumer" routes, and these routing rules are only applied to outbound connections originating from the same namespace as the Route, for which the intended destination of the connections are a Service targeted as a ParentRef of the Route. /// #[serde(default, skip_serializing_if = "Option::is_none", rename = "parentRefs")] pub parent_refs: Option>, @@ -63,14 +65,14 @@ pub struct GRPCRouteParentRefs { pub name: String, /// Namespace is the namespace of the referent. When unspecified, this refers to the local namespace of the Route. /// Note that there are specific rules for ParentRefs which cross namespace boundaries. Cross-namespace references are only valid if they are explicitly allowed by something in the namespace they are referring to. For example: Gateway has the AllowedRoutes field, and ReferenceGrant provides a generic way to enable any other kind of cross-namespace reference. - /// ParentRefs from a Route to a Service in the same namespace are "producer" routes, which apply default routing rules to inbound connections from any namespace to the Service. - /// ParentRefs from a Route to a Service in a different namespace are "consumer" routes, and these routing rules are only applied to outbound connections originating from the same namespace as the Route, for which the intended destination of the connections are a Service targeted as a ParentRef of the Route. + /// ParentRefs from a Route to a Service in the same namespace are "producer" routes, which apply default routing rules to inbound connections from any namespace to the Service. + /// ParentRefs from a Route to a Service in a different namespace are "consumer" routes, and these routing rules are only applied to outbound connections originating from the same namespace as the Route, for which the intended destination of the connections are a Service targeted as a ParentRef of the Route. /// Support: Core #[serde(default, skip_serializing_if = "Option::is_none")] pub namespace: Option, /// Port is the network port this Route targets. It can be interpreted differently based on the type of parent resource. /// When the parent resource is a Gateway, this targets all listeners listening on the specified port that also support this kind of Route(and select this Route). It's not recommended to set `Port` unless the networking behaviors specified in a Route must apply to a specific port as opposed to a listener(s) whose port(s) may be changed. When both Port and SectionName are specified, the name and port of the selected listener must match both specified values. - /// When the parent resource is a Service, this targets a specific port in the Service spec. When both Port (experimental) and SectionName are specified, the name and port of the selected port must match both specified values. + /// When the parent resource is a Service, this targets a specific port in the Service spec. When both Port (experimental) and SectionName are specified, the name and port of the selected port must match both specified values. /// Implementations MAY choose to support other parent resources. Implementations supporting other types of parent resources MUST clearly document how/if Port is interpreted. /// For the purpose of status, an attachment is considered successful as long as the parent resource accepts it partially. For example, Gateway listeners can restrict which Routes can attach to them by Route kind, namespace, or hostname. If 1 of 2 Gateway listeners accept attachment from the referencing Route, the Route MUST be considered successfully attached. If no Gateway listeners accept attachment from this Route, the Route MUST be considered detached from the Gateway. /// Support: Extended @@ -125,7 +127,14 @@ pub struct GRPCRouteRules { pub matches: Option>, } -/// GRPCBackendRef defines how a GRPCRoute forwards a gRPC request. +/// GRPCBackendRef defines how a GRPCRoute forwards a gRPC request. +/// Note that when a namespace different than the local namespace is specified, a ReferenceGrant object is required in the referent namespace to allow that namespace's owner to accept the reference. See the ReferenceGrant documentation for details. +/// +/// When the BackendRef points to a Kubernetes Service, implementations SHOULD honor the appProtocol field if it is set for the target Service Port. +/// Implementations supporting appProtocol SHOULD recognize the Kubernetes Standard Application Protocols defined in KEP-3726. +/// If a Service appProtocol isn't specified, an implementation MAY infer the backend protocol through its own means. Implementations MAY infer the protocol from the Route type referring to the backend Service. +/// If a Route is not able to send traffic to the backend using the specified protocol then the backend is considered invalid. Implementations MUST set the "ResolvedRefs" condition to "False" with the "UnsupportedProtocol" reason. +/// #[derive(Serialize, Deserialize, Clone, Debug, JsonSchema)] pub struct GRPCRouteRulesBackendRefs { /// Filters defined at this level MUST be executed if and only if the request is being forwarded to the backend defined here. @@ -676,14 +685,14 @@ pub struct GRPCRouteStatusParentsParentRef { pub name: String, /// Namespace is the namespace of the referent. When unspecified, this refers to the local namespace of the Route. /// Note that there are specific rules for ParentRefs which cross namespace boundaries. Cross-namespace references are only valid if they are explicitly allowed by something in the namespace they are referring to. For example: Gateway has the AllowedRoutes field, and ReferenceGrant provides a generic way to enable any other kind of cross-namespace reference. - /// ParentRefs from a Route to a Service in the same namespace are "producer" routes, which apply default routing rules to inbound connections from any namespace to the Service. - /// ParentRefs from a Route to a Service in a different namespace are "consumer" routes, and these routing rules are only applied to outbound connections originating from the same namespace as the Route, for which the intended destination of the connections are a Service targeted as a ParentRef of the Route. + /// ParentRefs from a Route to a Service in the same namespace are "producer" routes, which apply default routing rules to inbound connections from any namespace to the Service. + /// ParentRefs from a Route to a Service in a different namespace are "consumer" routes, and these routing rules are only applied to outbound connections originating from the same namespace as the Route, for which the intended destination of the connections are a Service targeted as a ParentRef of the Route. /// Support: Core #[serde(default, skip_serializing_if = "Option::is_none")] pub namespace: Option, /// Port is the network port this Route targets. It can be interpreted differently based on the type of parent resource. /// When the parent resource is a Gateway, this targets all listeners listening on the specified port that also support this kind of Route(and select this Route). It's not recommended to set `Port` unless the networking behaviors specified in a Route must apply to a specific port as opposed to a listener(s) whose port(s) may be changed. When both Port and SectionName are specified, the name and port of the selected listener must match both specified values. - /// When the parent resource is a Service, this targets a specific port in the Service spec. When both Port (experimental) and SectionName are specified, the name and port of the selected port must match both specified values. + /// When the parent resource is a Service, this targets a specific port in the Service spec. When both Port (experimental) and SectionName are specified, the name and port of the selected port must match both specified values. /// Implementations MAY choose to support other parent resources. Implementations supporting other types of parent resources MUST clearly document how/if Port is interpreted. /// For the purpose of status, an attachment is considered successful as long as the parent resource accepts it partially. For example, Gateway listeners can restrict which Routes can attach to them by Route kind, namespace, or hostname. If 1 of 2 Gateway listeners accept attachment from the referencing Route, the Route MUST be considered successfully attached. If no Gateway listeners accept attachment from this Route, the Route MUST be considered detached from the Gateway. /// Support: Extended diff --git a/src/apis/experimental/httproutes.rs b/src/apis/experimental/httproutes.rs index 504597c..d4f47b8 100644 --- a/src/apis/experimental/httproutes.rs +++ b/src/apis/experimental/httproutes.rs @@ -1,6 +1,6 @@ // WARNING: generated by kopium - manual changes will be overwritten // kopium command: kopium -Af - -// kopium version: 0.15.0 +// kopium version: 0.16.1 use kube::CustomResource; use schemars::JsonSchema; @@ -8,7 +8,7 @@ use serde::{Serialize, Deserialize}; /// Spec defines the desired state of HTTPRoute. #[derive(CustomResource, Serialize, Deserialize, Clone, Debug, JsonSchema)] -#[kube(group = "gateway.networking.k8s.io", version = "v1beta1", kind = "HTTPRoute", plural = "httproutes")] +#[kube(group = "gateway.networking.k8s.io", version = "v1", kind = "HTTPRoute", plural = "httproutes")] #[kube(namespaced)] #[kube(status = "HTTPRouteStatus")] pub struct HTTPRouteSpec { @@ -28,13 +28,15 @@ pub struct HTTPRouteSpec { pub hostnames: Option>, /// ParentRefs references the resources (usually Gateways) that a Route wants to be attached to. Note that the referenced parent resource needs to allow this for the attachment to be complete. For Gateways, that means the Gateway needs to allow attachment from Routes of this kind and namespace. For Services, that means the Service must either be in the same namespace for a "producer" route, or the mesh implementation must support and allow "consumer" routes for the referenced Service. ReferenceGrant is not applicable for governing ParentRefs to Services - it is not possible to create a "producer" route for a Service in a different namespace from the Route. /// There are two kinds of parent resources with "Core" support: - /// * Gateway (Gateway conformance profile) * Service (Mesh conformance profile, experimental, ClusterIP Services only) - /// This API may be extended in the future to support additional kinds of parent resources. - /// It is invalid to reference an identical parent more than once. It is valid to reference multiple distinct sections within the same parent resource, such as two separate Listeners on the same Gateway or two separate ports on the same Service. + /// * Gateway (Gateway conformance profile) * Service (Mesh conformance profile, experimental, ClusterIP Services only) This API may be extended in the future to support additional kinds of parent resources. + /// ParentRefs must be _distinct_. This means either that: + /// * They select different objects. If this is the case, then parentRef entries are distinct. In terms of fields, this means that the multi-part key defined by `group`, `kind`, `namespace`, and `name` must be unique across all parentRef entries in the Route. * They do not select different objects, but for each optional field used, each ParentRef that selects the same object must set the same set of optional fields to different values. If one ParentRef sets a combination of optional fields, all must set the same combination. + /// Some examples: + /// * If one ParentRef sets `sectionName`, all ParentRefs referencing the same object must also set `sectionName`. * If one ParentRef sets `port`, all ParentRefs referencing the same object must also set `port`. * If one ParentRef sets `sectionName` and `port`, all ParentRefs referencing the same object must also set `sectionName` and `port`. /// It is possible to separately reference multiple distinct objects that may be collapsed by an implementation. For example, some implementations may choose to merge compatible Gateway Listeners together. If that is the case, the list of routes attached to those resources should also be merged. /// Note that for ParentRefs that cross namespace boundaries, there are specific rules. Cross-namespace references are only valid if they are explicitly allowed by something in the namespace they are referring to. For example, Gateway has the AllowedRoutes field, and ReferenceGrant provides a generic way to enable other kinds of cross-namespace reference. - /// ParentRefs from a Route to a Service in the same namespace are "producer" routes, which apply default routing rules to inbound connections from any namespace to the Service. - /// ParentRefs from a Route to a Service in a different namespace are "consumer" routes, and these routing rules are only applied to outbound connections originating from the same namespace as the Route, for which the intended destination of the connections are a Service targeted as a ParentRef of the Route. + /// ParentRefs from a Route to a Service in the same namespace are "producer" routes, which apply default routing rules to inbound connections from any namespace to the Service. + /// ParentRefs from a Route to a Service in a different namespace are "consumer" routes, and these routing rules are only applied to outbound connections originating from the same namespace as the Route, for which the intended destination of the connections are a Service targeted as a ParentRef of the Route. /// #[serde(default, skip_serializing_if = "Option::is_none", rename = "parentRefs")] pub parent_refs: Option>, @@ -64,14 +66,14 @@ pub struct HTTPRouteParentRefs { pub name: String, /// Namespace is the namespace of the referent. When unspecified, this refers to the local namespace of the Route. /// Note that there are specific rules for ParentRefs which cross namespace boundaries. Cross-namespace references are only valid if they are explicitly allowed by something in the namespace they are referring to. For example: Gateway has the AllowedRoutes field, and ReferenceGrant provides a generic way to enable any other kind of cross-namespace reference. - /// ParentRefs from a Route to a Service in the same namespace are "producer" routes, which apply default routing rules to inbound connections from any namespace to the Service. - /// ParentRefs from a Route to a Service in a different namespace are "consumer" routes, and these routing rules are only applied to outbound connections originating from the same namespace as the Route, for which the intended destination of the connections are a Service targeted as a ParentRef of the Route. + /// ParentRefs from a Route to a Service in the same namespace are "producer" routes, which apply default routing rules to inbound connections from any namespace to the Service. + /// ParentRefs from a Route to a Service in a different namespace are "consumer" routes, and these routing rules are only applied to outbound connections originating from the same namespace as the Route, for which the intended destination of the connections are a Service targeted as a ParentRef of the Route. /// Support: Core #[serde(default, skip_serializing_if = "Option::is_none")] pub namespace: Option, /// Port is the network port this Route targets. It can be interpreted differently based on the type of parent resource. /// When the parent resource is a Gateway, this targets all listeners listening on the specified port that also support this kind of Route(and select this Route). It's not recommended to set `Port` unless the networking behaviors specified in a Route must apply to a specific port as opposed to a listener(s) whose port(s) may be changed. When both Port and SectionName are specified, the name and port of the selected listener must match both specified values. - /// When the parent resource is a Service, this targets a specific port in the Service spec. When both Port (experimental) and SectionName are specified, the name and port of the selected port must match both specified values. + /// When the parent resource is a Service, this targets a specific port in the Service spec. When both Port (experimental) and SectionName are specified, the name and port of the selected port must match both specified values. /// Implementations MAY choose to support other parent resources. Implementations supporting other types of parent resources MUST clearly document how/if Port is interpreted. /// For the purpose of status, an attachment is considered successful as long as the parent resource accepts it partially. For example, Gateway listeners can restrict which Routes can attach to them by Route kind, namespace, or hostname. If 1 of 2 Gateway listeners accept attachment from the referencing Route, the Route MUST be considered successfully attached. If no Gateway listeners accept attachment from this Route, the Route MUST be considered detached from the Gateway. /// Support: Extended @@ -127,9 +129,21 @@ pub struct HTTPRouteRules { /// When no rules matching a request have been successfully attached to the parent a request is coming from, a HTTP 404 status code MUST be returned. #[serde(default, skip_serializing_if = "Option::is_none")] pub matches: Option>, + /// Timeouts defines the timeouts that can be configured for an HTTP request. + /// Support: Extended + /// + #[serde(default, skip_serializing_if = "Option::is_none")] + pub timeouts: Option, } -/// HTTPBackendRef defines how a HTTPRoute should forward an HTTP request. +/// HTTPBackendRef defines how a HTTPRoute forwards a HTTP request. +/// Note that when a namespace different than the local namespace is specified, a ReferenceGrant object is required in the referent namespace to allow that namespace's owner to accept the reference. See the ReferenceGrant documentation for details. +/// +/// When the BackendRef points to a Kubernetes Service, implementations SHOULD honor the appProtocol field if it is set for the target Service Port. +/// Implementations supporting appProtocol SHOULD recognize the Kubernetes Standard Application Protocols defined in KEP-3726. +/// If a Service appProtocol isn't specified, an implementation MAY infer the backend protocol through its own means. Implementations MAY infer the protocol from the Route type referring to the backend Service. +/// If a Route is not able to send traffic to the backend using the specified protocol then the backend is considered invalid. Implementations MUST set the "ResolvedRefs" condition to "False" with the "UnsupportedProtocol" reason. +/// #[derive(Serialize, Deserialize, Clone, Debug, JsonSchema)] pub struct HTTPRouteRulesBackendRefs { /// Filters defined at this level should be executed if and only if the request is being forwarded to the backend defined here. @@ -935,6 +949,26 @@ pub enum HTTPRouteRulesMatchesQueryParamsType { RegularExpression, } +/// Timeouts defines the timeouts that can be configured for an HTTP request. +/// Support: Extended +/// +#[derive(Serialize, Deserialize, Clone, Debug, JsonSchema)] +pub struct HTTPRouteRulesTimeouts { + /// BackendRequest specifies a timeout for an individual request from the gateway to a backend. This covers the time from when the request first starts being sent from the gateway to when the full response has been received from the backend. + /// An entire client HTTP transaction with a gateway, covered by the Request timeout, may result in more than one call from the gateway to the destination backend, for example, if automatic retries are supported. + /// Because the Request timeout encompasses the BackendRequest timeout, the value of BackendRequest must be <= the value of Request timeout. + /// Support: Extended + #[serde(default, skip_serializing_if = "Option::is_none", rename = "backendRequest")] + pub backend_request: Option, + /// Request specifies the maximum duration for a gateway to respond to an HTTP request. If the gateway has not been able to respond before this deadline is met, the gateway MUST return a timeout error. + /// For example, setting the `rules.timeouts.request` field to the value `10s` in an `HTTPRoute` will cause a timeout if a client request is taking longer than 10 seconds to complete. + /// This timeout is intended to cover as close to the whole request-response transaction as possible although an implementation MAY choose to start the timeout after the entire request stream has been received instead of immediately after the transaction is initiated by the client. + /// When this field is unspecified, request timeout behavior is implementation-specific. + /// Support: Extended + #[serde(default, skip_serializing_if = "Option::is_none")] + pub request: Option, +} + /// Status defines the current state of HTTPRoute. #[derive(Serialize, Deserialize, Clone, Debug, JsonSchema)] pub struct HTTPRouteStatus { @@ -1015,14 +1049,14 @@ pub struct HTTPRouteStatusParentsParentRef { pub name: String, /// Namespace is the namespace of the referent. When unspecified, this refers to the local namespace of the Route. /// Note that there are specific rules for ParentRefs which cross namespace boundaries. Cross-namespace references are only valid if they are explicitly allowed by something in the namespace they are referring to. For example: Gateway has the AllowedRoutes field, and ReferenceGrant provides a generic way to enable any other kind of cross-namespace reference. - /// ParentRefs from a Route to a Service in the same namespace are "producer" routes, which apply default routing rules to inbound connections from any namespace to the Service. - /// ParentRefs from a Route to a Service in a different namespace are "consumer" routes, and these routing rules are only applied to outbound connections originating from the same namespace as the Route, for which the intended destination of the connections are a Service targeted as a ParentRef of the Route. + /// ParentRefs from a Route to a Service in the same namespace are "producer" routes, which apply default routing rules to inbound connections from any namespace to the Service. + /// ParentRefs from a Route to a Service in a different namespace are "consumer" routes, and these routing rules are only applied to outbound connections originating from the same namespace as the Route, for which the intended destination of the connections are a Service targeted as a ParentRef of the Route. /// Support: Core #[serde(default, skip_serializing_if = "Option::is_none")] pub namespace: Option, /// Port is the network port this Route targets. It can be interpreted differently based on the type of parent resource. /// When the parent resource is a Gateway, this targets all listeners listening on the specified port that also support this kind of Route(and select this Route). It's not recommended to set `Port` unless the networking behaviors specified in a Route must apply to a specific port as opposed to a listener(s) whose port(s) may be changed. When both Port and SectionName are specified, the name and port of the selected listener must match both specified values. - /// When the parent resource is a Service, this targets a specific port in the Service spec. When both Port (experimental) and SectionName are specified, the name and port of the selected port must match both specified values. + /// When the parent resource is a Service, this targets a specific port in the Service spec. When both Port (experimental) and SectionName are specified, the name and port of the selected port must match both specified values. /// Implementations MAY choose to support other parent resources. Implementations supporting other types of parent resources MUST clearly document how/if Port is interpreted. /// For the purpose of status, an attachment is considered successful as long as the parent resource accepts it partially. For example, Gateway listeners can restrict which Routes can attach to them by Route kind, namespace, or hostname. If 1 of 2 Gateway listeners accept attachment from the referencing Route, the Route MUST be considered successfully attached. If no Gateway listeners accept attachment from this Route, the Route MUST be considered detached from the Gateway. /// Support: Extended diff --git a/src/apis/experimental/referencegrants.rs b/src/apis/experimental/referencegrants.rs index 0da8b00..421e6dc 100644 --- a/src/apis/experimental/referencegrants.rs +++ b/src/apis/experimental/referencegrants.rs @@ -1,6 +1,6 @@ // WARNING: generated by kopium - manual changes will be overwritten // kopium command: kopium -Af - -// kopium version: 0.15.0 +// kopium version: 0.16.1 use kube::CustomResource; use schemars::JsonSchema; diff --git a/src/apis/experimental/tcproutes.rs b/src/apis/experimental/tcproutes.rs index 17a224b..2f34b3b 100644 --- a/src/apis/experimental/tcproutes.rs +++ b/src/apis/experimental/tcproutes.rs @@ -1,6 +1,6 @@ // WARNING: generated by kopium - manual changes will be overwritten // kopium command: kopium -Af - -// kopium version: 0.15.0 +// kopium version: 0.16.1 use kube::CustomResource; use schemars::JsonSchema; @@ -14,13 +14,15 @@ use serde::{Serialize, Deserialize}; pub struct TCPRouteSpec { /// ParentRefs references the resources (usually Gateways) that a Route wants to be attached to. Note that the referenced parent resource needs to allow this for the attachment to be complete. For Gateways, that means the Gateway needs to allow attachment from Routes of this kind and namespace. For Services, that means the Service must either be in the same namespace for a "producer" route, or the mesh implementation must support and allow "consumer" routes for the referenced Service. ReferenceGrant is not applicable for governing ParentRefs to Services - it is not possible to create a "producer" route for a Service in a different namespace from the Route. /// There are two kinds of parent resources with "Core" support: - /// * Gateway (Gateway conformance profile) * Service (Mesh conformance profile, experimental, ClusterIP Services only) - /// This API may be extended in the future to support additional kinds of parent resources. - /// It is invalid to reference an identical parent more than once. It is valid to reference multiple distinct sections within the same parent resource, such as two separate Listeners on the same Gateway or two separate ports on the same Service. + /// * Gateway (Gateway conformance profile) * Service (Mesh conformance profile, experimental, ClusterIP Services only) This API may be extended in the future to support additional kinds of parent resources. + /// ParentRefs must be _distinct_. This means either that: + /// * They select different objects. If this is the case, then parentRef entries are distinct. In terms of fields, this means that the multi-part key defined by `group`, `kind`, `namespace`, and `name` must be unique across all parentRef entries in the Route. * They do not select different objects, but for each optional field used, each ParentRef that selects the same object must set the same set of optional fields to different values. If one ParentRef sets a combination of optional fields, all must set the same combination. + /// Some examples: + /// * If one ParentRef sets `sectionName`, all ParentRefs referencing the same object must also set `sectionName`. * If one ParentRef sets `port`, all ParentRefs referencing the same object must also set `port`. * If one ParentRef sets `sectionName` and `port`, all ParentRefs referencing the same object must also set `sectionName` and `port`. /// It is possible to separately reference multiple distinct objects that may be collapsed by an implementation. For example, some implementations may choose to merge compatible Gateway Listeners together. If that is the case, the list of routes attached to those resources should also be merged. /// Note that for ParentRefs that cross namespace boundaries, there are specific rules. Cross-namespace references are only valid if they are explicitly allowed by something in the namespace they are referring to. For example, Gateway has the AllowedRoutes field, and ReferenceGrant provides a generic way to enable other kinds of cross-namespace reference. - /// ParentRefs from a Route to a Service in the same namespace are "producer" routes, which apply default routing rules to inbound connections from any namespace to the Service. - /// ParentRefs from a Route to a Service in a different namespace are "consumer" routes, and these routing rules are only applied to outbound connections originating from the same namespace as the Route, for which the intended destination of the connections are a Service targeted as a ParentRef of the Route. + /// ParentRefs from a Route to a Service in the same namespace are "producer" routes, which apply default routing rules to inbound connections from any namespace to the Service. + /// ParentRefs from a Route to a Service in a different namespace are "consumer" routes, and these routing rules are only applied to outbound connections originating from the same namespace as the Route, for which the intended destination of the connections are a Service targeted as a ParentRef of the Route. /// #[serde(default, skip_serializing_if = "Option::is_none", rename = "parentRefs")] pub parent_refs: Option>, @@ -49,14 +51,14 @@ pub struct TCPRouteParentRefs { pub name: String, /// Namespace is the namespace of the referent. When unspecified, this refers to the local namespace of the Route. /// Note that there are specific rules for ParentRefs which cross namespace boundaries. Cross-namespace references are only valid if they are explicitly allowed by something in the namespace they are referring to. For example: Gateway has the AllowedRoutes field, and ReferenceGrant provides a generic way to enable any other kind of cross-namespace reference. - /// ParentRefs from a Route to a Service in the same namespace are "producer" routes, which apply default routing rules to inbound connections from any namespace to the Service. - /// ParentRefs from a Route to a Service in a different namespace are "consumer" routes, and these routing rules are only applied to outbound connections originating from the same namespace as the Route, for which the intended destination of the connections are a Service targeted as a ParentRef of the Route. + /// ParentRefs from a Route to a Service in the same namespace are "producer" routes, which apply default routing rules to inbound connections from any namespace to the Service. + /// ParentRefs from a Route to a Service in a different namespace are "consumer" routes, and these routing rules are only applied to outbound connections originating from the same namespace as the Route, for which the intended destination of the connections are a Service targeted as a ParentRef of the Route. /// Support: Core #[serde(default, skip_serializing_if = "Option::is_none")] pub namespace: Option, /// Port is the network port this Route targets. It can be interpreted differently based on the type of parent resource. /// When the parent resource is a Gateway, this targets all listeners listening on the specified port that also support this kind of Route(and select this Route). It's not recommended to set `Port` unless the networking behaviors specified in a Route must apply to a specific port as opposed to a listener(s) whose port(s) may be changed. When both Port and SectionName are specified, the name and port of the selected listener must match both specified values. - /// When the parent resource is a Service, this targets a specific port in the Service spec. When both Port (experimental) and SectionName are specified, the name and port of the selected port must match both specified values. + /// When the parent resource is a Service, this targets a specific port in the Service spec. When both Port (experimental) and SectionName are specified, the name and port of the selected port must match both specified values. /// Implementations MAY choose to support other parent resources. Implementations supporting other types of parent resources MUST clearly document how/if Port is interpreted. /// For the purpose of status, an attachment is considered successful as long as the parent resource accepts it partially. For example, Gateway listeners can restrict which Routes can attach to them by Route kind, namespace, or hostname. If 1 of 2 Gateway listeners accept attachment from the referencing Route, the Route MUST be considered successfully attached. If no Gateway listeners accept attachment from this Route, the Route MUST be considered detached from the Gateway. /// Support: Extended @@ -85,7 +87,14 @@ pub struct TCPRouteRules { } /// BackendRef defines how a Route should forward a request to a Kubernetes resource. -/// Note that when a namespace different than the local namespace is specified, a ReferenceGrant object is required in the referent namespace to allow that namespace's owner to accept the reference. See the ReferenceGrant documentation for details. +/// Note that when a namespace different than the local namespace is specified, a ReferenceGrant object is required in the referent namespace to allow that namespace's owner to accept the reference. See the ReferenceGrant documentation for details. +/// +/// When the BackendRef points to a Kubernetes Service, implementations SHOULD honor the appProtocol field if it is set for the target Service Port. +/// Implementations supporting appProtocol SHOULD recognize the Kubernetes Standard Application Protocols defined in KEP-3726. +/// If a Service appProtocol isn't specified, an implementation MAY infer the backend protocol through its own means. Implementations MAY infer the protocol from the Route type referring to the backend Service. +/// If a Route is not able to send traffic to the backend using the specified protocol then the backend is considered invalid. Implementations MUST set the "ResolvedRefs" condition to "False" with the "UnsupportedProtocol" reason. +/// +/// Note that when the BackendTLSPolicy object is enabled by the implementation, there are some extra rules about validity to consider here. See the fields where this struct is used for more information about the exact behavior. #[derive(Serialize, Deserialize, Clone, Debug, JsonSchema)] pub struct TCPRouteRulesBackendRefs { /// Group is the group of the referent. For example, "gateway.networking.k8s.io". When unspecified or empty string, core API group is inferred. @@ -195,14 +204,14 @@ pub struct TCPRouteStatusParentsParentRef { pub name: String, /// Namespace is the namespace of the referent. When unspecified, this refers to the local namespace of the Route. /// Note that there are specific rules for ParentRefs which cross namespace boundaries. Cross-namespace references are only valid if they are explicitly allowed by something in the namespace they are referring to. For example: Gateway has the AllowedRoutes field, and ReferenceGrant provides a generic way to enable any other kind of cross-namespace reference. - /// ParentRefs from a Route to a Service in the same namespace are "producer" routes, which apply default routing rules to inbound connections from any namespace to the Service. - /// ParentRefs from a Route to a Service in a different namespace are "consumer" routes, and these routing rules are only applied to outbound connections originating from the same namespace as the Route, for which the intended destination of the connections are a Service targeted as a ParentRef of the Route. + /// ParentRefs from a Route to a Service in the same namespace are "producer" routes, which apply default routing rules to inbound connections from any namespace to the Service. + /// ParentRefs from a Route to a Service in a different namespace are "consumer" routes, and these routing rules are only applied to outbound connections originating from the same namespace as the Route, for which the intended destination of the connections are a Service targeted as a ParentRef of the Route. /// Support: Core #[serde(default, skip_serializing_if = "Option::is_none")] pub namespace: Option, /// Port is the network port this Route targets. It can be interpreted differently based on the type of parent resource. /// When the parent resource is a Gateway, this targets all listeners listening on the specified port that also support this kind of Route(and select this Route). It's not recommended to set `Port` unless the networking behaviors specified in a Route must apply to a specific port as opposed to a listener(s) whose port(s) may be changed. When both Port and SectionName are specified, the name and port of the selected listener must match both specified values. - /// When the parent resource is a Service, this targets a specific port in the Service spec. When both Port (experimental) and SectionName are specified, the name and port of the selected port must match both specified values. + /// When the parent resource is a Service, this targets a specific port in the Service spec. When both Port (experimental) and SectionName are specified, the name and port of the selected port must match both specified values. /// Implementations MAY choose to support other parent resources. Implementations supporting other types of parent resources MUST clearly document how/if Port is interpreted. /// For the purpose of status, an attachment is considered successful as long as the parent resource accepts it partially. For example, Gateway listeners can restrict which Routes can attach to them by Route kind, namespace, or hostname. If 1 of 2 Gateway listeners accept attachment from the referencing Route, the Route MUST be considered successfully attached. If no Gateway listeners accept attachment from this Route, the Route MUST be considered detached from the Gateway. /// Support: Extended diff --git a/src/apis/experimental/tlsroutes.rs b/src/apis/experimental/tlsroutes.rs index 6186980..81cf16f 100644 --- a/src/apis/experimental/tlsroutes.rs +++ b/src/apis/experimental/tlsroutes.rs @@ -1,6 +1,6 @@ // WARNING: generated by kopium - manual changes will be overwritten // kopium command: kopium -Af - -// kopium version: 0.15.0 +// kopium version: 0.16.1 use kube::CustomResource; use schemars::JsonSchema; @@ -23,13 +23,15 @@ pub struct TLSRouteSpec { pub hostnames: Option>, /// ParentRefs references the resources (usually Gateways) that a Route wants to be attached to. Note that the referenced parent resource needs to allow this for the attachment to be complete. For Gateways, that means the Gateway needs to allow attachment from Routes of this kind and namespace. For Services, that means the Service must either be in the same namespace for a "producer" route, or the mesh implementation must support and allow "consumer" routes for the referenced Service. ReferenceGrant is not applicable for governing ParentRefs to Services - it is not possible to create a "producer" route for a Service in a different namespace from the Route. /// There are two kinds of parent resources with "Core" support: - /// * Gateway (Gateway conformance profile) * Service (Mesh conformance profile, experimental, ClusterIP Services only) - /// This API may be extended in the future to support additional kinds of parent resources. - /// It is invalid to reference an identical parent more than once. It is valid to reference multiple distinct sections within the same parent resource, such as two separate Listeners on the same Gateway or two separate ports on the same Service. + /// * Gateway (Gateway conformance profile) * Service (Mesh conformance profile, experimental, ClusterIP Services only) This API may be extended in the future to support additional kinds of parent resources. + /// ParentRefs must be _distinct_. This means either that: + /// * They select different objects. If this is the case, then parentRef entries are distinct. In terms of fields, this means that the multi-part key defined by `group`, `kind`, `namespace`, and `name` must be unique across all parentRef entries in the Route. * They do not select different objects, but for each optional field used, each ParentRef that selects the same object must set the same set of optional fields to different values. If one ParentRef sets a combination of optional fields, all must set the same combination. + /// Some examples: + /// * If one ParentRef sets `sectionName`, all ParentRefs referencing the same object must also set `sectionName`. * If one ParentRef sets `port`, all ParentRefs referencing the same object must also set `port`. * If one ParentRef sets `sectionName` and `port`, all ParentRefs referencing the same object must also set `sectionName` and `port`. /// It is possible to separately reference multiple distinct objects that may be collapsed by an implementation. For example, some implementations may choose to merge compatible Gateway Listeners together. If that is the case, the list of routes attached to those resources should also be merged. /// Note that for ParentRefs that cross namespace boundaries, there are specific rules. Cross-namespace references are only valid if they are explicitly allowed by something in the namespace they are referring to. For example, Gateway has the AllowedRoutes field, and ReferenceGrant provides a generic way to enable other kinds of cross-namespace reference. - /// ParentRefs from a Route to a Service in the same namespace are "producer" routes, which apply default routing rules to inbound connections from any namespace to the Service. - /// ParentRefs from a Route to a Service in a different namespace are "consumer" routes, and these routing rules are only applied to outbound connections originating from the same namespace as the Route, for which the intended destination of the connections are a Service targeted as a ParentRef of the Route. + /// ParentRefs from a Route to a Service in the same namespace are "producer" routes, which apply default routing rules to inbound connections from any namespace to the Service. + /// ParentRefs from a Route to a Service in a different namespace are "consumer" routes, and these routing rules are only applied to outbound connections originating from the same namespace as the Route, for which the intended destination of the connections are a Service targeted as a ParentRef of the Route. /// #[serde(default, skip_serializing_if = "Option::is_none", rename = "parentRefs")] pub parent_refs: Option>, @@ -58,14 +60,14 @@ pub struct TLSRouteParentRefs { pub name: String, /// Namespace is the namespace of the referent. When unspecified, this refers to the local namespace of the Route. /// Note that there are specific rules for ParentRefs which cross namespace boundaries. Cross-namespace references are only valid if they are explicitly allowed by something in the namespace they are referring to. For example: Gateway has the AllowedRoutes field, and ReferenceGrant provides a generic way to enable any other kind of cross-namespace reference. - /// ParentRefs from a Route to a Service in the same namespace are "producer" routes, which apply default routing rules to inbound connections from any namespace to the Service. - /// ParentRefs from a Route to a Service in a different namespace are "consumer" routes, and these routing rules are only applied to outbound connections originating from the same namespace as the Route, for which the intended destination of the connections are a Service targeted as a ParentRef of the Route. + /// ParentRefs from a Route to a Service in the same namespace are "producer" routes, which apply default routing rules to inbound connections from any namespace to the Service. + /// ParentRefs from a Route to a Service in a different namespace are "consumer" routes, and these routing rules are only applied to outbound connections originating from the same namespace as the Route, for which the intended destination of the connections are a Service targeted as a ParentRef of the Route. /// Support: Core #[serde(default, skip_serializing_if = "Option::is_none")] pub namespace: Option, /// Port is the network port this Route targets. It can be interpreted differently based on the type of parent resource. /// When the parent resource is a Gateway, this targets all listeners listening on the specified port that also support this kind of Route(and select this Route). It's not recommended to set `Port` unless the networking behaviors specified in a Route must apply to a specific port as opposed to a listener(s) whose port(s) may be changed. When both Port and SectionName are specified, the name and port of the selected listener must match both specified values. - /// When the parent resource is a Service, this targets a specific port in the Service spec. When both Port (experimental) and SectionName are specified, the name and port of the selected port must match both specified values. + /// When the parent resource is a Service, this targets a specific port in the Service spec. When both Port (experimental) and SectionName are specified, the name and port of the selected port must match both specified values. /// Implementations MAY choose to support other parent resources. Implementations supporting other types of parent resources MUST clearly document how/if Port is interpreted. /// For the purpose of status, an attachment is considered successful as long as the parent resource accepts it partially. For example, Gateway listeners can restrict which Routes can attach to them by Route kind, namespace, or hostname. If 1 of 2 Gateway listeners accept attachment from the referencing Route, the Route MUST be considered successfully attached. If no Gateway listeners accept attachment from this Route, the Route MUST be considered detached from the Gateway. /// Support: Extended @@ -94,7 +96,14 @@ pub struct TLSRouteRules { } /// BackendRef defines how a Route should forward a request to a Kubernetes resource. -/// Note that when a namespace different than the local namespace is specified, a ReferenceGrant object is required in the referent namespace to allow that namespace's owner to accept the reference. See the ReferenceGrant documentation for details. +/// Note that when a namespace different than the local namespace is specified, a ReferenceGrant object is required in the referent namespace to allow that namespace's owner to accept the reference. See the ReferenceGrant documentation for details. +/// +/// When the BackendRef points to a Kubernetes Service, implementations SHOULD honor the appProtocol field if it is set for the target Service Port. +/// Implementations supporting appProtocol SHOULD recognize the Kubernetes Standard Application Protocols defined in KEP-3726. +/// If a Service appProtocol isn't specified, an implementation MAY infer the backend protocol through its own means. Implementations MAY infer the protocol from the Route type referring to the backend Service. +/// If a Route is not able to send traffic to the backend using the specified protocol then the backend is considered invalid. Implementations MUST set the "ResolvedRefs" condition to "False" with the "UnsupportedProtocol" reason. +/// +/// Note that when the BackendTLSPolicy object is enabled by the implementation, there are some extra rules about validity to consider here. See the fields where this struct is used for more information about the exact behavior. #[derive(Serialize, Deserialize, Clone, Debug, JsonSchema)] pub struct TLSRouteRulesBackendRefs { /// Group is the group of the referent. For example, "gateway.networking.k8s.io". When unspecified or empty string, core API group is inferred. @@ -204,14 +213,14 @@ pub struct TLSRouteStatusParentsParentRef { pub name: String, /// Namespace is the namespace of the referent. When unspecified, this refers to the local namespace of the Route. /// Note that there are specific rules for ParentRefs which cross namespace boundaries. Cross-namespace references are only valid if they are explicitly allowed by something in the namespace they are referring to. For example: Gateway has the AllowedRoutes field, and ReferenceGrant provides a generic way to enable any other kind of cross-namespace reference. - /// ParentRefs from a Route to a Service in the same namespace are "producer" routes, which apply default routing rules to inbound connections from any namespace to the Service. - /// ParentRefs from a Route to a Service in a different namespace are "consumer" routes, and these routing rules are only applied to outbound connections originating from the same namespace as the Route, for which the intended destination of the connections are a Service targeted as a ParentRef of the Route. + /// ParentRefs from a Route to a Service in the same namespace are "producer" routes, which apply default routing rules to inbound connections from any namespace to the Service. + /// ParentRefs from a Route to a Service in a different namespace are "consumer" routes, and these routing rules are only applied to outbound connections originating from the same namespace as the Route, for which the intended destination of the connections are a Service targeted as a ParentRef of the Route. /// Support: Core #[serde(default, skip_serializing_if = "Option::is_none")] pub namespace: Option, /// Port is the network port this Route targets. It can be interpreted differently based on the type of parent resource. /// When the parent resource is a Gateway, this targets all listeners listening on the specified port that also support this kind of Route(and select this Route). It's not recommended to set `Port` unless the networking behaviors specified in a Route must apply to a specific port as opposed to a listener(s) whose port(s) may be changed. When both Port and SectionName are specified, the name and port of the selected listener must match both specified values. - /// When the parent resource is a Service, this targets a specific port in the Service spec. When both Port (experimental) and SectionName are specified, the name and port of the selected port must match both specified values. + /// When the parent resource is a Service, this targets a specific port in the Service spec. When both Port (experimental) and SectionName are specified, the name and port of the selected port must match both specified values. /// Implementations MAY choose to support other parent resources. Implementations supporting other types of parent resources MUST clearly document how/if Port is interpreted. /// For the purpose of status, an attachment is considered successful as long as the parent resource accepts it partially. For example, Gateway listeners can restrict which Routes can attach to them by Route kind, namespace, or hostname. If 1 of 2 Gateway listeners accept attachment from the referencing Route, the Route MUST be considered successfully attached. If no Gateway listeners accept attachment from this Route, the Route MUST be considered detached from the Gateway. /// Support: Extended diff --git a/src/apis/experimental/udproutes.rs b/src/apis/experimental/udproutes.rs index e83f650..8481357 100644 --- a/src/apis/experimental/udproutes.rs +++ b/src/apis/experimental/udproutes.rs @@ -1,6 +1,6 @@ // WARNING: generated by kopium - manual changes will be overwritten // kopium command: kopium -Af - -// kopium version: 0.15.0 +// kopium version: 0.16.1 use kube::CustomResource; use schemars::JsonSchema; @@ -14,13 +14,15 @@ use serde::{Serialize, Deserialize}; pub struct UDPRouteSpec { /// ParentRefs references the resources (usually Gateways) that a Route wants to be attached to. Note that the referenced parent resource needs to allow this for the attachment to be complete. For Gateways, that means the Gateway needs to allow attachment from Routes of this kind and namespace. For Services, that means the Service must either be in the same namespace for a "producer" route, or the mesh implementation must support and allow "consumer" routes for the referenced Service. ReferenceGrant is not applicable for governing ParentRefs to Services - it is not possible to create a "producer" route for a Service in a different namespace from the Route. /// There are two kinds of parent resources with "Core" support: - /// * Gateway (Gateway conformance profile) * Service (Mesh conformance profile, experimental, ClusterIP Services only) - /// This API may be extended in the future to support additional kinds of parent resources. - /// It is invalid to reference an identical parent more than once. It is valid to reference multiple distinct sections within the same parent resource, such as two separate Listeners on the same Gateway or two separate ports on the same Service. + /// * Gateway (Gateway conformance profile) * Service (Mesh conformance profile, experimental, ClusterIP Services only) This API may be extended in the future to support additional kinds of parent resources. + /// ParentRefs must be _distinct_. This means either that: + /// * They select different objects. If this is the case, then parentRef entries are distinct. In terms of fields, this means that the multi-part key defined by `group`, `kind`, `namespace`, and `name` must be unique across all parentRef entries in the Route. * They do not select different objects, but for each optional field used, each ParentRef that selects the same object must set the same set of optional fields to different values. If one ParentRef sets a combination of optional fields, all must set the same combination. + /// Some examples: + /// * If one ParentRef sets `sectionName`, all ParentRefs referencing the same object must also set `sectionName`. * If one ParentRef sets `port`, all ParentRefs referencing the same object must also set `port`. * If one ParentRef sets `sectionName` and `port`, all ParentRefs referencing the same object must also set `sectionName` and `port`. /// It is possible to separately reference multiple distinct objects that may be collapsed by an implementation. For example, some implementations may choose to merge compatible Gateway Listeners together. If that is the case, the list of routes attached to those resources should also be merged. /// Note that for ParentRefs that cross namespace boundaries, there are specific rules. Cross-namespace references are only valid if they are explicitly allowed by something in the namespace they are referring to. For example, Gateway has the AllowedRoutes field, and ReferenceGrant provides a generic way to enable other kinds of cross-namespace reference. - /// ParentRefs from a Route to a Service in the same namespace are "producer" routes, which apply default routing rules to inbound connections from any namespace to the Service. - /// ParentRefs from a Route to a Service in a different namespace are "consumer" routes, and these routing rules are only applied to outbound connections originating from the same namespace as the Route, for which the intended destination of the connections are a Service targeted as a ParentRef of the Route. + /// ParentRefs from a Route to a Service in the same namespace are "producer" routes, which apply default routing rules to inbound connections from any namespace to the Service. + /// ParentRefs from a Route to a Service in a different namespace are "consumer" routes, and these routing rules are only applied to outbound connections originating from the same namespace as the Route, for which the intended destination of the connections are a Service targeted as a ParentRef of the Route. /// #[serde(default, skip_serializing_if = "Option::is_none", rename = "parentRefs")] pub parent_refs: Option>, @@ -49,14 +51,14 @@ pub struct UDPRouteParentRefs { pub name: String, /// Namespace is the namespace of the referent. When unspecified, this refers to the local namespace of the Route. /// Note that there are specific rules for ParentRefs which cross namespace boundaries. Cross-namespace references are only valid if they are explicitly allowed by something in the namespace they are referring to. For example: Gateway has the AllowedRoutes field, and ReferenceGrant provides a generic way to enable any other kind of cross-namespace reference. - /// ParentRefs from a Route to a Service in the same namespace are "producer" routes, which apply default routing rules to inbound connections from any namespace to the Service. - /// ParentRefs from a Route to a Service in a different namespace are "consumer" routes, and these routing rules are only applied to outbound connections originating from the same namespace as the Route, for which the intended destination of the connections are a Service targeted as a ParentRef of the Route. + /// ParentRefs from a Route to a Service in the same namespace are "producer" routes, which apply default routing rules to inbound connections from any namespace to the Service. + /// ParentRefs from a Route to a Service in a different namespace are "consumer" routes, and these routing rules are only applied to outbound connections originating from the same namespace as the Route, for which the intended destination of the connections are a Service targeted as a ParentRef of the Route. /// Support: Core #[serde(default, skip_serializing_if = "Option::is_none")] pub namespace: Option, /// Port is the network port this Route targets. It can be interpreted differently based on the type of parent resource. /// When the parent resource is a Gateway, this targets all listeners listening on the specified port that also support this kind of Route(and select this Route). It's not recommended to set `Port` unless the networking behaviors specified in a Route must apply to a specific port as opposed to a listener(s) whose port(s) may be changed. When both Port and SectionName are specified, the name and port of the selected listener must match both specified values. - /// When the parent resource is a Service, this targets a specific port in the Service spec. When both Port (experimental) and SectionName are specified, the name and port of the selected port must match both specified values. + /// When the parent resource is a Service, this targets a specific port in the Service spec. When both Port (experimental) and SectionName are specified, the name and port of the selected port must match both specified values. /// Implementations MAY choose to support other parent resources. Implementations supporting other types of parent resources MUST clearly document how/if Port is interpreted. /// For the purpose of status, an attachment is considered successful as long as the parent resource accepts it partially. For example, Gateway listeners can restrict which Routes can attach to them by Route kind, namespace, or hostname. If 1 of 2 Gateway listeners accept attachment from the referencing Route, the Route MUST be considered successfully attached. If no Gateway listeners accept attachment from this Route, the Route MUST be considered detached from the Gateway. /// Support: Extended @@ -85,7 +87,14 @@ pub struct UDPRouteRules { } /// BackendRef defines how a Route should forward a request to a Kubernetes resource. -/// Note that when a namespace different than the local namespace is specified, a ReferenceGrant object is required in the referent namespace to allow that namespace's owner to accept the reference. See the ReferenceGrant documentation for details. +/// Note that when a namespace different than the local namespace is specified, a ReferenceGrant object is required in the referent namespace to allow that namespace's owner to accept the reference. See the ReferenceGrant documentation for details. +/// +/// When the BackendRef points to a Kubernetes Service, implementations SHOULD honor the appProtocol field if it is set for the target Service Port. +/// Implementations supporting appProtocol SHOULD recognize the Kubernetes Standard Application Protocols defined in KEP-3726. +/// If a Service appProtocol isn't specified, an implementation MAY infer the backend protocol through its own means. Implementations MAY infer the protocol from the Route type referring to the backend Service. +/// If a Route is not able to send traffic to the backend using the specified protocol then the backend is considered invalid. Implementations MUST set the "ResolvedRefs" condition to "False" with the "UnsupportedProtocol" reason. +/// +/// Note that when the BackendTLSPolicy object is enabled by the implementation, there are some extra rules about validity to consider here. See the fields where this struct is used for more information about the exact behavior. #[derive(Serialize, Deserialize, Clone, Debug, JsonSchema)] pub struct UDPRouteRulesBackendRefs { /// Group is the group of the referent. For example, "gateway.networking.k8s.io". When unspecified or empty string, core API group is inferred. @@ -195,14 +204,14 @@ pub struct UDPRouteStatusParentsParentRef { pub name: String, /// Namespace is the namespace of the referent. When unspecified, this refers to the local namespace of the Route. /// Note that there are specific rules for ParentRefs which cross namespace boundaries. Cross-namespace references are only valid if they are explicitly allowed by something in the namespace they are referring to. For example: Gateway has the AllowedRoutes field, and ReferenceGrant provides a generic way to enable any other kind of cross-namespace reference. - /// ParentRefs from a Route to a Service in the same namespace are "producer" routes, which apply default routing rules to inbound connections from any namespace to the Service. - /// ParentRefs from a Route to a Service in a different namespace are "consumer" routes, and these routing rules are only applied to outbound connections originating from the same namespace as the Route, for which the intended destination of the connections are a Service targeted as a ParentRef of the Route. + /// ParentRefs from a Route to a Service in the same namespace are "producer" routes, which apply default routing rules to inbound connections from any namespace to the Service. + /// ParentRefs from a Route to a Service in a different namespace are "consumer" routes, and these routing rules are only applied to outbound connections originating from the same namespace as the Route, for which the intended destination of the connections are a Service targeted as a ParentRef of the Route. /// Support: Core #[serde(default, skip_serializing_if = "Option::is_none")] pub namespace: Option, /// Port is the network port this Route targets. It can be interpreted differently based on the type of parent resource. /// When the parent resource is a Gateway, this targets all listeners listening on the specified port that also support this kind of Route(and select this Route). It's not recommended to set `Port` unless the networking behaviors specified in a Route must apply to a specific port as opposed to a listener(s) whose port(s) may be changed. When both Port and SectionName are specified, the name and port of the selected listener must match both specified values. - /// When the parent resource is a Service, this targets a specific port in the Service spec. When both Port (experimental) and SectionName are specified, the name and port of the selected port must match both specified values. + /// When the parent resource is a Service, this targets a specific port in the Service spec. When both Port (experimental) and SectionName are specified, the name and port of the selected port must match both specified values. /// Implementations MAY choose to support other parent resources. Implementations supporting other types of parent resources MUST clearly document how/if Port is interpreted. /// For the purpose of status, an attachment is considered successful as long as the parent resource accepts it partially. For example, Gateway listeners can restrict which Routes can attach to them by Route kind, namespace, or hostname. If 1 of 2 Gateway listeners accept attachment from the referencing Route, the Route MUST be considered successfully attached. If no Gateway listeners accept attachment from this Route, the Route MUST be considered detached from the Gateway. /// Support: Extended diff --git a/src/apis/standard/gatewayclasses.rs b/src/apis/standard/gatewayclasses.rs index 90f2824..d1f7255 100644 --- a/src/apis/standard/gatewayclasses.rs +++ b/src/apis/standard/gatewayclasses.rs @@ -1,6 +1,6 @@ // WARNING: generated by kopium - manual changes will be overwritten // kopium command: kopium -Af - -// kopium version: 0.15.0 +// kopium version: 0.16.1 use kube::CustomResource; use schemars::JsonSchema; @@ -8,7 +8,7 @@ use serde::{Serialize, Deserialize}; /// Spec defines the desired state of GatewayClass. #[derive(CustomResource, Serialize, Deserialize, Clone, Debug, JsonSchema)] -#[kube(group = "gateway.networking.k8s.io", version = "v1beta1", kind = "GatewayClass", plural = "gatewayclasses")] +#[kube(group = "gateway.networking.k8s.io", version = "v1", kind = "GatewayClass", plural = "gatewayclasses")] #[kube(status = "GatewayClassStatus")] pub struct GatewayClassSpec { /// ControllerName is the name of the controller that is managing Gateways of this class. The value of this field MUST be a domain prefixed path. diff --git a/src/apis/standard/gateways.rs b/src/apis/standard/gateways.rs index 01d02a1..3fe1b64 100644 --- a/src/apis/standard/gateways.rs +++ b/src/apis/standard/gateways.rs @@ -1,6 +1,6 @@ // WARNING: generated by kopium - manual changes will be overwritten // kopium command: kopium -Af - -// kopium version: 0.15.0 +// kopium version: 0.16.1 use kube::CustomResource; use schemars::JsonSchema; @@ -9,13 +9,12 @@ use std::collections::BTreeMap; /// Spec defines the desired state of Gateway. #[derive(CustomResource, Serialize, Deserialize, Clone, Debug, JsonSchema)] -#[kube(group = "gateway.networking.k8s.io", version = "v1beta1", kind = "Gateway", plural = "gateways")] +#[kube(group = "gateway.networking.k8s.io", version = "v1", kind = "Gateway", plural = "gateways")] #[kube(namespaced)] #[kube(status = "GatewayStatus")] pub struct GatewaySpec { /// Addresses requested for this Gateway. This is optional and behavior can depend on the implementation. If a value is set in the spec and the requested address is invalid or unavailable, the implementation MUST indicate this in the associated entry in GatewayStatus.Addresses. /// The Addresses field represents a request for the address(es) on the "outside of the Gateway", that traffic bound for this Gateway will use. This could be the IP address or hostname of an external load balancer or other networking infrastructure, or some other address that traffic will be sent to. - /// The .listener.hostname field is used to route traffic that has already arrived at the Gateway to the correct in-cluster destination. /// If no Addresses are specified, the implementation MAY schedule the Gateway in an implementation-specific manner, assigning an appropriate set of Addresses. /// The implementation MUST bind all Listeners to every GatewayAddress that it assigns to the Gateway and add a corresponding entry in GatewayStatus.Addresses. /// Support: Extended @@ -26,19 +25,32 @@ pub struct GatewaySpec { #[serde(rename = "gatewayClassName")] pub gateway_class_name: String, /// Listeners associated with this Gateway. Listeners define logical endpoints that are bound on this Gateway's addresses. At least one Listener MUST be specified. - /// Each listener in a Gateway must have a unique combination of Hostname, Port, and Protocol. - /// Within the HTTP Conformance Profile, the below combinations of port and protocol are considered Core and MUST be supported: - /// 1. Port: 80, Protocol: HTTP 2. Port: 443, Protocol: HTTPS - /// Within the TLS Conformance Profile, the below combinations of port and protocol are considered Core and MUST be supported: - /// 1. Port: 443, Protocol: TLS - /// Port and protocol combinations not listed above are considered Extended. - /// An implementation MAY group Listeners by Port and then collapse each group of Listeners into a single Listener if the implementation determines that the Listeners in the group are "compatible". An implementation MAY also group together and collapse compatible Listeners belonging to different Gateways. - /// For example, an implementation might consider Listeners to be compatible with each other if all of the following conditions are met: - /// 1. Either each Listener within the group specifies the "HTTP" Protocol or each Listener within the group specifies either the "HTTPS" or "TLS" Protocol. - /// 2. Each Listener within the group specifies a Hostname that is unique within the group. - /// 3. As a special case, one Listener within a group may omit Hostname, in which case this Listener matches when no other Listener matches. - /// If the implementation does collapse compatible Listeners, the hostname provided in the incoming client request MUST be matched to a Listener to find the correct set of Routes. The incoming hostname MUST be matched using the Hostname field for each Listener in order of most to least specific. That is, exact matches must be processed before wildcard matches. - /// If this field specifies multiple Listeners that have the same Port value but are not compatible, the implementation must raise a "Conflicted" condition in the Listener status. + /// Each Listener in a set of Listeners (for example, in a single Gateway) MUST be _distinct_, in that a traffic flow MUST be able to be assigned to exactly one listener. (This section uses "set of Listeners" rather than "Listeners in a single Gateway" because implementations MAY merge configuration from multiple Gateways onto a single data plane, and these rules _also_ apply in that case). + /// Practically, this means that each listener in a set MUST have a unique combination of Port, Protocol, and, if supported by the protocol, Hostname. + /// Some combinations of port, protocol, and TLS settings are considered Core support and MUST be supported by implementations based on their targeted conformance profile: + /// HTTP Profile + /// 1. HTTPRoute, Port: 80, Protocol: HTTP 2. HTTPRoute, Port: 443, Protocol: HTTPS, TLS Mode: Terminate, TLS keypair provided + /// TLS Profile + /// 1. TLSRoute, Port: 443, Protocol: TLS, TLS Mode: Passthrough + /// "Distinct" Listeners have the following property: + /// The implementation can match inbound requests to a single distinct Listener. When multiple Listeners share values for fields (for example, two Listeners with the same Port value), the implementation can match requests to only one of the Listeners using other Listener fields. + /// For example, the following Listener scenarios are distinct: + /// 1. Multiple Listeners with the same Port that all use the "HTTP" Protocol that all have unique Hostname values. 2. Multiple Listeners with the same Port that use either the "HTTPS" or "TLS" Protocol that all have unique Hostname values. 3. A mixture of "TCP" and "UDP" Protocol Listeners, where no Listener with the same Protocol has the same Port value. + /// Some fields in the Listener struct have possible values that affect whether the Listener is distinct. Hostname is particularly relevant for HTTP or HTTPS protocols. + /// When using the Hostname value to select between same-Port, same-Protocol Listeners, the Hostname value must be different on each Listener for the Listener to be distinct. + /// When the Listeners are distinct based on Hostname, inbound request hostnames MUST match from the most specific to least specific Hostname values to choose the correct Listener and its associated set of Routes. + /// Exact matches must be processed before wildcard matches, and wildcard matches must be processed before fallback (empty Hostname value) matches. For example, `"foo.example.com"` takes precedence over `"*.example.com"`, and `"*.example.com"` takes precedence over `""`. + /// Additionally, if there are multiple wildcard entries, more specific wildcard entries must be processed before less specific wildcard entries. For example, `"*.foo.example.com"` takes precedence over `"*.example.com"`. The precise definition here is that the higher the number of dots in the hostname to the right of the wildcard character, the higher the precedence. + /// The wildcard character will match any number of characters _and dots_ to the left, however, so `"*.example.com"` will match both `"foo.bar.example.com"` _and_ `"bar.example.com"`. + /// If a set of Listeners contains Listeners that are not distinct, then those Listeners are Conflicted, and the implementation MUST set the "Conflicted" condition in the Listener Status to "True". + /// Implementations MAY choose to accept a Gateway with some Conflicted Listeners only if they only accept the partial Listener set that contains no Conflicted Listeners. To put this another way, implementations may accept a partial Listener set only if they throw out *all* the conflicting Listeners. No picking one of the conflicting listeners as the winner. This also means that the Gateway must have at least one non-conflicting Listener in this case, otherwise it violates the requirement that at least one Listener must be present. + /// The implementation MUST set a "ListenersNotValid" condition on the Gateway Status when the Gateway contains Conflicted Listeners whether or not they accept the Gateway. That Condition SHOULD clearly indicate in the Message which Listeners are conflicted, and which are Accepted. Additionally, the Listener status for those listeners SHOULD indicate which Listeners are conflicted and not Accepted. + /// A Gateway's Listeners are considered "compatible" if: + /// 1. They are distinct. 2. The implementation can serve them in compliance with the Addresses requirement that all Listeners are available on all assigned addresses. + /// Compatible combinations in Extended support are expected to vary across implementations. A combination that is compatible for one implementation may not be compatible for another. + /// For example, an implementation that cannot serve both TCP and UDP listeners on the same address, or cannot mix HTTPS and generic TLS listens on the same port would not consider those cases compatible, even though they are distinct. + /// Note that requests SHOULD match at most one Listener. For example, if Listeners are defined for "foo.example.com" and "*.example.com", a request to "foo.example.com" SHOULD only be routed using routes attached to the "foo.example.com" Listener (and not the "*.example.com" Listener). This concept is known as "Listener Isolation". Implementations that do not support Listener Isolation MUST clearly document this. + /// Implementations MAY merge separate Gateways onto a single set of Addresses if all Listeners across all Gateways are compatible. /// Support: Core pub listeners: Vec, } @@ -205,7 +217,7 @@ pub struct GatewayListenersTlsCertificateRefs { pub kind: Option, /// Name is the name of the referent. pub name: String, - /// Namespace is the namespace of the backend. When unspecified, the local namespace is inferred. + /// Namespace is the namespace of the referenced object. When unspecified, the local namespace is inferred. /// Note that when a namespace different than the local namespace is specified, a ReferenceGrant object is required in the referent namespace to allow that namespace's owner to accept the reference. See the ReferenceGrant documentation for details. /// Support: Core #[serde(default, skip_serializing_if = "Option::is_none")] @@ -225,7 +237,9 @@ pub enum GatewayListenersTlsMode { /// Status defines the current state of Gateway. #[derive(Serialize, Deserialize, Clone, Debug, JsonSchema)] pub struct GatewayStatus { - /// Addresses lists the IP addresses that have actually been bound to the Gateway. These addresses may differ from the addresses in the Spec, e.g. if the Gateway automatically assigns an address from a reserved pool. + /// Addresses lists the network addresses that have been bound to the Gateway. + /// This list may differ from the addresses provided in the spec under some conditions: + /// * no addresses are specified, all addresses are dynamically assigned * a combination of specified and dynamic addresses are assigned * a specified address was unusable (e.g. already in use) /// #[serde(default, skip_serializing_if = "Option::is_none")] pub addresses: Option>, @@ -240,7 +254,7 @@ pub struct GatewayStatus { pub listeners: Option>, } -/// GatewayStatusAddress describes an address that is bound to a Gateway. +/// GatewayStatusAddress describes a network address that is bound to a Gateway. #[derive(Serialize, Deserialize, Clone, Debug, JsonSchema)] pub struct GatewayStatusAddresses { /// Type of the address. @@ -286,7 +300,9 @@ pub enum GatewayStatusConditionsStatus { /// ListenerStatus is the status associated with a Listener. #[derive(Serialize, Deserialize, Clone, Debug, JsonSchema)] pub struct GatewayStatusListeners { - /// AttachedRoutes represents the total number of accepted Routes that have been successfully attached to this Listener. + /// AttachedRoutes represents the total number of Routes that have been successfully attached to this Listener. + /// Successful attachment of a Route to a Listener is based solely on the combination of the AllowedRoutes field on the corresponding Listener and the Route's ParentRefs field. A Route is successfully attached to a Listener when it is selected by the Listener's AllowedRoutes field AND the Route has a valid ParentRef selecting the whole Gateway resource or a specific Listener as a parent resource (more detail on attachment semantics can be found in the documentation on the various Route kinds ParentRefs fields). Listener or Route status does not impact successful attachment, i.e. the AttachedRoutes field count MUST be set for Listeners with condition Accepted: false and MUST count successfully attached Routes that may themselves have Accepted: false conditions. + /// Uses for this field include troubleshooting Route attachment and measuring blast radius/impact of changes to a Listener. #[serde(rename = "attachedRoutes")] pub attached_routes: i32, /// Conditions describe the current condition of this listener. diff --git a/src/apis/standard/httproutes.rs b/src/apis/standard/httproutes.rs index b464f3d..2dfa258 100644 --- a/src/apis/standard/httproutes.rs +++ b/src/apis/standard/httproutes.rs @@ -1,6 +1,6 @@ // WARNING: generated by kopium - manual changes will be overwritten // kopium command: kopium -Af - -// kopium version: 0.15.0 +// kopium version: 0.16.1 use kube::CustomResource; use schemars::JsonSchema; @@ -8,7 +8,7 @@ use serde::{Serialize, Deserialize}; /// Spec defines the desired state of HTTPRoute. #[derive(CustomResource, Serialize, Deserialize, Clone, Debug, JsonSchema)] -#[kube(group = "gateway.networking.k8s.io", version = "v1beta1", kind = "HTTPRoute", plural = "httproutes")] +#[kube(group = "gateway.networking.k8s.io", version = "v1", kind = "HTTPRoute", plural = "httproutes")] #[kube(namespaced)] #[kube(status = "HTTPRouteStatus")] pub struct HTTPRouteSpec { @@ -28,13 +28,14 @@ pub struct HTTPRouteSpec { pub hostnames: Option>, /// ParentRefs references the resources (usually Gateways) that a Route wants to be attached to. Note that the referenced parent resource needs to allow this for the attachment to be complete. For Gateways, that means the Gateway needs to allow attachment from Routes of this kind and namespace. For Services, that means the Service must either be in the same namespace for a "producer" route, or the mesh implementation must support and allow "consumer" routes for the referenced Service. ReferenceGrant is not applicable for governing ParentRefs to Services - it is not possible to create a "producer" route for a Service in a different namespace from the Route. /// There are two kinds of parent resources with "Core" support: - /// * Gateway (Gateway conformance profile) * Service (Mesh conformance profile, experimental, ClusterIP Services only) - /// This API may be extended in the future to support additional kinds of parent resources. - /// It is invalid to reference an identical parent more than once. It is valid to reference multiple distinct sections within the same parent resource, such as two separate Listeners on the same Gateway or two separate ports on the same Service. + /// * Gateway (Gateway conformance profile) This API may be extended in the future to support additional kinds of parent resources. + /// ParentRefs must be _distinct_. This means either that: + /// * They select different objects. If this is the case, then parentRef entries are distinct. In terms of fields, this means that the multi-part key defined by `group`, `kind`, `namespace`, and `name` must be unique across all parentRef entries in the Route. * They do not select different objects, but for each optional field used, each ParentRef that selects the same object must set the same set of optional fields to different values. If one ParentRef sets a combination of optional fields, all must set the same combination. + /// Some examples: + /// * If one ParentRef sets `sectionName`, all ParentRefs referencing the same object must also set `sectionName`. * If one ParentRef sets `port`, all ParentRefs referencing the same object must also set `port`. * If one ParentRef sets `sectionName` and `port`, all ParentRefs referencing the same object must also set `sectionName` and `port`. /// It is possible to separately reference multiple distinct objects that may be collapsed by an implementation. For example, some implementations may choose to merge compatible Gateway Listeners together. If that is the case, the list of routes attached to those resources should also be merged. /// Note that for ParentRefs that cross namespace boundaries, there are specific rules. Cross-namespace references are only valid if they are explicitly allowed by something in the namespace they are referring to. For example, Gateway has the AllowedRoutes field, and ReferenceGrant provides a generic way to enable other kinds of cross-namespace reference. - /// ParentRefs from a Route to a Service in the same namespace are "producer" routes, which apply default routing rules to inbound connections from any namespace to the Service. - /// ParentRefs from a Route to a Service in a different namespace are "consumer" routes, and these routing rules are only applied to outbound connections originating from the same namespace as the Route, for which the intended destination of the connections are a Service targeted as a ParentRef of the Route. + /// /// #[serde(default, skip_serializing_if = "Option::is_none", rename = "parentRefs")] pub parent_refs: Option>, @@ -64,8 +65,7 @@ pub struct HTTPRouteParentRefs { pub name: String, /// Namespace is the namespace of the referent. When unspecified, this refers to the local namespace of the Route. /// Note that there are specific rules for ParentRefs which cross namespace boundaries. Cross-namespace references are only valid if they are explicitly allowed by something in the namespace they are referring to. For example: Gateway has the AllowedRoutes field, and ReferenceGrant provides a generic way to enable any other kind of cross-namespace reference. - /// ParentRefs from a Route to a Service in the same namespace are "producer" routes, which apply default routing rules to inbound connections from any namespace to the Service. - /// ParentRefs from a Route to a Service in a different namespace are "consumer" routes, and these routing rules are only applied to outbound connections originating from the same namespace as the Route, for which the intended destination of the connections are a Service targeted as a ParentRef of the Route. + /// /// Support: Core #[serde(default, skip_serializing_if = "Option::is_none")] pub namespace: Option, @@ -120,7 +120,14 @@ pub struct HTTPRouteRules { pub matches: Option>, } -/// HTTPBackendRef defines how a HTTPRoute should forward an HTTP request. +/// HTTPBackendRef defines how a HTTPRoute forwards a HTTP request. +/// Note that when a namespace different than the local namespace is specified, a ReferenceGrant object is required in the referent namespace to allow that namespace's owner to accept the reference. See the ReferenceGrant documentation for details. +/// +/// When the BackendRef points to a Kubernetes Service, implementations SHOULD honor the appProtocol field if it is set for the target Service Port. +/// Implementations supporting appProtocol SHOULD recognize the Kubernetes Standard Application Protocols defined in KEP-3726. +/// If a Service appProtocol isn't specified, an implementation MAY infer the backend protocol through its own means. Implementations MAY infer the protocol from the Route type referring to the backend Service. +/// If a Route is not able to send traffic to the backend using the specified protocol then the backend is considered invalid. Implementations MUST set the "ResolvedRefs" condition to "False" with the "UnsupportedProtocol" reason. +/// #[derive(Serialize, Deserialize, Clone, Debug, JsonSchema)] pub struct HTTPRouteRulesBackendRefs { /// Filters defined at this level should be executed if and only if the request is being forwarded to the backend defined here. @@ -1006,8 +1013,7 @@ pub struct HTTPRouteStatusParentsParentRef { pub name: String, /// Namespace is the namespace of the referent. When unspecified, this refers to the local namespace of the Route. /// Note that there are specific rules for ParentRefs which cross namespace boundaries. Cross-namespace references are only valid if they are explicitly allowed by something in the namespace they are referring to. For example: Gateway has the AllowedRoutes field, and ReferenceGrant provides a generic way to enable any other kind of cross-namespace reference. - /// ParentRefs from a Route to a Service in the same namespace are "producer" routes, which apply default routing rules to inbound connections from any namespace to the Service. - /// ParentRefs from a Route to a Service in a different namespace are "consumer" routes, and these routing rules are only applied to outbound connections originating from the same namespace as the Route, for which the intended destination of the connections are a Service targeted as a ParentRef of the Route. + /// /// Support: Core #[serde(default, skip_serializing_if = "Option::is_none")] pub namespace: Option, diff --git a/src/apis/standard/referencegrants.rs b/src/apis/standard/referencegrants.rs index 0da8b00..421e6dc 100644 --- a/src/apis/standard/referencegrants.rs +++ b/src/apis/standard/referencegrants.rs @@ -1,6 +1,6 @@ // WARNING: generated by kopium - manual changes will be overwritten // kopium command: kopium -Af - -// kopium version: 0.15.0 +// kopium version: 0.16.1 use kube::CustomResource; use schemars::JsonSchema; diff --git a/update.sh b/update.sh index c64b1f7..ccfffa0 100755 --- a/update.sh +++ b/update.sh @@ -13,7 +13,7 @@ set -eoux pipefail -VERSION="v0.8.0" +VERSION="v1.0.0-rc1" STANDARD_APIS=( gatewayclasses