+
Gateway represents an instantiation of a service-traffic handling infrastructure.
+ +| Field | +Description | +||||||
|---|---|---|---|---|---|---|---|
+apiVersion
+string |
+
+
+networking.x-k8s.io/v1alpha1
+
+ |
+||||||
+kind
+string
+ |
+Gateway |
+||||||
+metadata
+
+
+Kubernetes meta/v1.ObjectMeta
+
+
+ |
+
+Refer to the Kubernetes API documentation for the fields of the
+metadata field.
+ |
+||||||
+spec
+
+
+GatewaySpec
+
+
+ |
+
+ + +
|
+||||||
+status
+
+
+GatewayStatus
+
+
+ |
++ | +
@@ -180,6 +304,154 @@ GatewayClassStatus +
+
TcpRoute is the Schema for the tcproutes API
+ +| Field | +Description | +
|---|---|
+apiVersion
+string |
+
+
+networking.x-k8s.io/v1alpha1
+
+ |
+
+kind
+string
+ |
+TcpRoute |
+
+metadata
+
+
+Kubernetes meta/v1.ObjectMeta
+
+
+ |
+
+Refer to the Kubernetes API documentation for the fields of the
+metadata field.
+ |
+
+spec
+
+
+TcpRouteSpec
+
+
+ |
+
+ + + |
+
+status
+
+
+TcpRouteStatus
+
+
+ |
++ | +
+
TrafficSplit is the Schema for the trafficsplits API
+ +| Field | +Description | +
|---|---|
+apiVersion
+string |
+
+
+networking.x-k8s.io/v1alpha1
+
+ |
+
+kind
+string
+ |
+TrafficSplit |
+
+metadata
+
+
+Kubernetes meta/v1.ObjectMeta
+
+
+ |
+
+Refer to the Kubernetes API documentation for the fields of the
+metadata field.
+ |
+
+spec
+
+
+TrafficSplitSpec
+
+
+ |
+
+ + + |
+
+status
+
+
+TrafficSplitStatus
+
+
+ |
++ | +
string alias)@@ -321,107 +593,6 @@ surfaced in status.
--
Gateway represents an instantiation of a service-traffic handling infrastructure.
- -| Field | -Description | -||||||
|---|---|---|---|---|---|---|---|
-metadata
-
-
-Kubernetes meta/v1.ObjectMeta
-
-
- |
-
-Refer to the Kubernetes API documentation for the fields of the
-metadata field.
- |
-||||||
-spec
-
-
-GatewaySpec
-
-
- |
-
- - -
|
-||||||
-status
-
-
-GatewayStatus
-
-
- |
-- | -
@@ -2105,63 +2276,6 @@ construct.
TargetPort specifies the destination port number to use for a TargetRef.
--
TcpRoute is the Schema for the tcproutes API
- -| Field | -Description | -
|---|---|
-metadata
-
-
-Kubernetes meta/v1.ObjectMeta
-
-
- |
-
-Refer to the Kubernetes API documentation for the fields of the
-metadata field.
- |
-
-spec
-
-
-TcpRouteSpec
-
-
- |
-
- - - |
-
-status
-
-
-TcpRouteStatus
-
-
- |
-- | -
@@ -2180,63 +2294,6 @@ TcpRouteStatus
TcpRouteStatus defines the observed state of TcpRoute
--
TrafficSplit is the Schema for the trafficsplits API
- -| Field | -Description | -
|---|---|
-metadata
-
-
-Kubernetes meta/v1.ObjectMeta
-
-
- |
-
-Refer to the Kubernetes API documentation for the fields of the
-metadata field.
- |
-
-spec
-
-
-TrafficSplitSpec
-
-
- |
-
- - - |
-
-status
-
-
-TrafficSplitStatus
-
-
- |
-- | -
diff --git a/docs/search/search_index.json b/docs/search/search_index.json index bcbe07764d..17e5c8597b 100644 --- a/docs/search/search_index.json +++ b/docs/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Introduction This is the documentation for the evolution of service-related APIs for Kubernetes. This project is part of the Kubernetes project working under SIG-NETWORK . Gateway API Gateway is an API for a common portable declarative description of load-balancing infrastructure for Kubernetes. If you are a user: User guide (how to use the API) Cookbook for common tasks If you are a developer: How to build and test How to contribute, meetings, design docs For everyone: Concepts and detailed descriptions API specification Releases Security Model Enhancement requests Feedback and bug reports Contacts Slack: #sig-network-service-apis Project Owners","title":"Introduction"},{"location":"#introduction","text":"This is the documentation for the evolution of service-related APIs for Kubernetes. This project is part of the Kubernetes project working under SIG-NETWORK .","title":"Introduction"},{"location":"#gateway-api","text":"Gateway is an API for a common portable declarative description of load-balancing infrastructure for Kubernetes. If you are a user: User guide (how to use the API) Cookbook for common tasks If you are a developer: How to build and test How to contribute, meetings, design docs For everyone: Concepts and detailed descriptions API specification Releases Security Model Enhancement requests Feedback and bug reports","title":"Gateway API"},{"location":"#contacts","text":"Slack: #sig-network-service-apis Project Owners","title":"Contacts"},{"location":"community/","text":"How to contribute This page contains links to all of the meeting notes, design docs and related discussions around the APIs. Communications Major discussions and notifications will be sent on the SIG-NETWORK mailing list . We also have a Slack channel (sig-network-service-apis) on k8s.io for day-to-day questions, discussions. Meetings Meetings discussing the evolution of the service APIs will alternate times to accommodate participants from various time zones. This calendar includes all Service APIs meetings as well as any other SIG-Network meetings. Thursday 10:30 AM Pacific (EMEA Friendly Time) [Zoom Link] Thursday 4:30 (16:30) PM Pacific (APAC Friendly Time) Office Hours In addition to weekly meetings, we have informal weekly office hours meetings on Wednesdays. Wednesday 3:00 (15:00) PM Pacific Meeting notes Meeting schedule scratch pad Meeting recordings . Date Future meetings Check the calendar February 27, 2019 meeting notes , recording February 20, 2019 meeting notes , recording February 13, 2019 meeting notes , recording February 6, 2019 meeting notes , recording January 30, 2019 meeting notes , recording January 23, 2019 meeting notes , recording TODO January 16, 2019 meeting notes , recording January 9, 2019 meeting notes , recording January 2, 2020 meeting notes , recording didn't work :-( look at the notes December 19, 2019 meeting notes , recording November, 2019 Kubecon 2019 San Diego: API evolution design discussion November, 2019 SIG-NETWORK: Ingress Evolution Sync May, 2019 Kubecon 2019 Barcelona: SIG-NETWORK discussion (general topics, includes V2) Design docs Title Description API sketch Sketch of the proposed API Presentations, Talks Date Title November, 2019 Kubecon 2019 San Diego: Evolving the Kubernetes Ingress APIs to GA and Beyond slides , video November, 2019 Kubecon 2019 San Diego: SIG-NETWORK Service/Ingress Evolution Discussion slides May, 2019 Kubecon 2019 Barcelona: Ingress V2 and Multicluster Services slides , video March, 2018 SIG-NETWORK: Ingress user survey data , slides Code of conduct Participation in the Kubernetes community is governed by the Kubernetes Code of Conduct","title":"How to contribute"},{"location":"community/#how-to-contribute","text":"This page contains links to all of the meeting notes, design docs and related discussions around the APIs.","title":"How to contribute"},{"location":"community/#communications","text":"Major discussions and notifications will be sent on the SIG-NETWORK mailing list . We also have a Slack channel (sig-network-service-apis) on k8s.io for day-to-day questions, discussions.","title":"Communications"},{"location":"community/#meetings","text":"Meetings discussing the evolution of the service APIs will alternate times to accommodate participants from various time zones. This calendar includes all Service APIs meetings as well as any other SIG-Network meetings. Thursday 10:30 AM Pacific (EMEA Friendly Time) [Zoom Link] Thursday 4:30 (16:30) PM Pacific (APAC Friendly Time)","title":"Meetings"},{"location":"community/#office-hours","text":"In addition to weekly meetings, we have informal weekly office hours meetings on Wednesdays. Wednesday 3:00 (15:00) PM Pacific","title":"Office Hours"},{"location":"community/#meeting-notes","text":"Meeting schedule scratch pad Meeting recordings . Date Future meetings Check the calendar February 27, 2019 meeting notes , recording February 20, 2019 meeting notes , recording February 13, 2019 meeting notes , recording February 6, 2019 meeting notes , recording January 30, 2019 meeting notes , recording January 23, 2019 meeting notes , recording TODO January 16, 2019 meeting notes , recording January 9, 2019 meeting notes , recording January 2, 2020 meeting notes , recording didn't work :-( look at the notes December 19, 2019 meeting notes , recording November, 2019 Kubecon 2019 San Diego: API evolution design discussion November, 2019 SIG-NETWORK: Ingress Evolution Sync May, 2019 Kubecon 2019 Barcelona: SIG-NETWORK discussion (general topics, includes V2)","title":"Meeting notes"},{"location":"community/#design-docs","text":"Title Description API sketch Sketch of the proposed API","title":"Design docs"},{"location":"community/#presentations-talks","text":"Date Title November, 2019 Kubecon 2019 San Diego: Evolving the Kubernetes Ingress APIs to GA and Beyond slides , video November, 2019 Kubecon 2019 San Diego: SIG-NETWORK Service/Ingress Evolution Discussion slides May, 2019 Kubecon 2019 Barcelona: Ingress V2 and Multicluster Services slides , video March, 2018 SIG-NETWORK: Ingress user survey data , slides","title":"Presentations, Talks"},{"location":"community/#code-of-conduct","text":"Participation in the Kubernetes community is governed by the Kubernetes Code of Conduct","title":"Code of conduct"},{"location":"concepts/","text":"API Concepts This document is a deep dive into the reasoning and design for the API. The content of this document started from this API sketch . Roles and personas In the original design of Kubernetes, Ingress and Service resources were based on a self-service model of usage; developers who create Services and Ingresses control all aspects of defining and exposing their applications to their users. We have found that the self-service model does not fully capture some of the more complex deployment and team structures that our users are seeing. The Gateway/Routes API will target the following personas: Infrastructure provider : The infrastructure provider (infra) is responsible for the overall environment that the cluster(s) are operating in. Examples include public cloud providers (AWS, Azure, GCP, ...), or PaaS providers within an organization. Cluster operator : The cluster operator (ops) is responsible for administration of entire clusters. They manage policies, network access, and application permissions. Application developer : The application developer (dev) is responsible for defining their application configuration (e.g. timeouts, request matching/filter) and Service composition (e.g. path routing to backends). We expect that each persona will map approximately to a Role in the Kubernetes Role-Based Authentication (RBAC) system and will define resource model responsibility and separation. Depending on the environment, multiple roles can map to the same user. For example, giving the user all the above roles replicates the self-service model. For more information on the roles and personas considered in the Service API design, refer to the Security Model . Resource model Note: Resources will initially live in the networking.x-k8s.io API group as Custom Resource Definitions (CRDs). Unqualified resource names will implicitly be in this API group. There are three main types of objects in our resource model: GatewayClass defines a set of gateways with a common configuration and behavior. Gateway requests a point where traffic can be translated to Services within the cluster. Routes describe how traffic coming via the Gateway maps to the Services. GatewayClass GatewayClass defines a set of Gateways that share a common configuration and behaviour. Each GatewayClass will be handled by a single controller, although controllers MAY handle more than one. GatewayClass is a cluster-scoped resource. There MUST be at least one GatewayClass defined in order to be able to have functional Gateways. A controller that implements the Gateway API does so by providing an associated GatewayClass resource that the user can reference from their Gateway(s). This is similar to IngressClass for Ingress and StorageClass for PersistentVolumes. In Ingress v1beta1, the closest analog to GatewayClass is the ingress-class annotation, and in IngressV1, the closest analog is the IngressClass object. Gateway A Gateway describes how traffic can be translated to Services within the cluster. That is, it defines a request for a way to translate traffic from somewhere that does not know about Kubernetes to somewhere that does. For example, traffic sent to a Kubernetes Services by a cloud load balancer, an in-cluster proxy or external hardware load balancer. While many use cases have client traffic originating \u201coutside\u201d the cluster, this is not a requirement. It defines a request for a specific load balancer config that implements the GatewayClass\u2019 configuration and behaviour contract. The resource MAY be created by an operator directly, or MAY be created by a controller handling a GatewayClass. As the Gateway spec captures user intent, it may not contain a complete specification for all attributes in the spec. For example, the user may omit fields such as addresses, ports, TLS settings. This allows the controller managing the GatewayClass to provide these settings for the user, resulting in a more portable spec. This behaviour will be made clear using the GatewayClass Status object. A Gateway MAY contain one or more *Route references which serve to direct traffic for a subset of traffic to a specific service. {HTTP,TCP,Foo}Route Route objects define protocol-specific rules for mapping requests from a Gateway to Kubernetes Services. HTTPRoute and TCPRoute are currently the only defined Route objects. Additional protocol-specific Route objects may be added in the future. Combined types The combination of GatewayClass , Gateway , xRoute and Service (s) will define an implementable load-balancer. The diagram below illustrates the relationships between the different resources: Request flow A typical client/gateway API request flow for a gateway implemented using a reverse proxy is: A client makes a request to http://foo.example.com. DNS resolves the name to gateway.status.listeners[x].address . The reverse proxy receives the request on gateway.status.listeners[x].address : gateway.spec.listeners[x].port and uses the Host header to match an HTTPRoute . Optionally, the reverse proxy can perform request header and/or path matching based on match rules of the HTTPRoute . Optionally, the reverse proxy can manipulate the request, i.e. add/remove headers, etc. based on filter rules of the HTTPRoute . Lastly, the reverse proxy forwards the request to one or more objects in the cluster based on action rules of the HTTPRoute . When specifying multiple forwardTo objects, the request is split, i.e. forwarded to each object. TLS Configuration TLS configuration is tied to Gateway listeners. Although adding the option to configure TLS on other resources was considered, ultimately TLS configuration on Gateway listeners was deemed sufficient for the following reasons: In most cases, users that are configuring TLS will naturally also have access to Gateways. In other cases, TLS config could be implemented with a controller watching Routes and adding generated certs to corresponding Gateways. This does not solve the use case for users wanting to provide their own certs for Routes while not having access to a Gateway resource. This seems like it would be a rare edge case and is not worth supporting at this point. The security model outlined a potential approach to enable this in the future, but there does not seem to be a sufficient reason to work towards that now. Design considerations There are some general design guidelines used throughout this API. Single resource consistency The Kubernetes API guarantees consistency only on a single resource level. There are a couple of consequences for complex resource graphs as opposed to single resources: Error checking of properties spanning multiple resource will be asynchronous and eventually consistent. Simple syntax checks will be possible at the single resource level, but cross resource dependencies will need to be handled by the controller. Controllers will need to handle broken links between resources and/or mismatched configuration. Conflicts Separation and delegation of responsibility among independent actors (e.g between cluster ops and application developers) can result in conflicts in the configuration. For example, two application teams may inadvertently submit configuration for the same HTTP path. There are several different strategies for handling this: TODO Extensibility TODO GatewayClass GatewayClass ( source code ) is cluster-scoped resource defined by the infrastructure provider. This resource represents a class of Gateways that can be instantiated. Note: this serves the same function as the networking.IngressClass resource . kind: GatewayClass metadata: name: cluster-gateway spec: controller: \"acme.io/gateway-controller\" We expect that one or more GatewayClasses will be created by the infrastructure provider for the user. It allows decoupling of which mechanism (e.g. controller) implements the Gateways from the user. For instance, an infrastructure provider may create two GatewayClasses named internet and private to reflect Gateways that define Internet-facing vs private, internal applications. kind: GatewayClass metadata: name: internet ... --- kind: GatewayClass metadata: name: private ... The user of the classes will not need to know how internet and private are implemented. Instead, the user will only need to understand the resulting properties of the class that the Gateway was created with. GatewayClass parameters Providers of the Gateway API may need to pass parameters to their controller as part of the class definition. This is done using the GatewayClass.spec.parametersRef field: # GatewayClass for Gateways that define Internet-facing applications. kind: GatewayClass metadata: name: internet spec: controller: \"acme.io/gateway-controller\" parametersRef: name: internet-gateway --- kind: ConfigMap metadata: name: internet-gateway namespace: acme-system data: ip-address-pool: internet-vips ... Note: parametersRef will expect a ConfigMap as a referenced object if resource and group are omitted. The type of object referenced by GatewayClass.spec.parametersRef will depend on the provider itself. A core.ConfigMap is used in the example above, but controllers may opt to use a CustomResource for better schema validation. GatewayClass status GatewayClasses MUST be validated by the provider to ensure that the configured parameters are valid. The validity of the class will be signaled to the user via GatewayClass.status : kind: GatewayClass ... status: conditions: - type: InvalidParameters status: Unknown ... A new GatewayClass will start with the InvalidParameters condition set to Unknown . At this point the controller has not seen the configuration. Once the controller has processed the configuration, the condition will be set to False : kind: GatewayClass ... status: conditions: - type: InvalidParameters status: False ... If there is an error in the GatewayClass.spec , the conditions will be non-empty and contain information about the error. kind: GatewayClass ... status: conditions: - type: InvalidParameters status: True Reason: BadFooBar Message: \"foobar\" is an FooBar. Gateway A Gateway is 1:1 with the life cycle of the configuration of infrastructure. When a user creates a Gateway , some load balancing infrastructure is provisioned or configured (see below for details) by the GatewayClass controller. Gateway is the resource that triggers actions in this API. Other resources in this API are configuration snippets until a Gateway has been created to link the resources together. The Gateway spec defines the following: The GatewayClass used to instantiate this Gateway. The Listener bindings, which define addresses and ports, protocol termination, and TLS settings. The Listener configuration requested by a Gateway definition can be incompatible with a given GatewayClass (e.g. port/protocol combination is not supported). The Routes, which describe how traffic is processed and forwarded. If the Listener configuration requested by a Gateway definition is incompatible with a given GatewayClass, the Gateway will be in an error state, signaled by the status field. Deployment models Depending on the GatewayClass , the creation of the Gateway could do any of the following actions: Use cloud APIs to create an LB instance. Spawn a new instance of a software LB (in this or another cluster). Add a configuration stanza to an already instantiated LB to handle the new routes. Program the SDN to implement the configuration. Something else we haven\u2019t thought of yet... The API does not specify which one of these actions will be taken. Note that a GatewayClass controller that manages in-cluster proxy processes MAY restrict Gateway configuration scope, e.g. only be served in the same namespace. Gateway Status Gateways track status for the Gateway resource as a whole as well as each Listener it contains. The status for a specific Route is reported in the status of the Route resource. Within GatewayStatus , Listeners will have status entries corresponding to their name. Both GatewayStatus and ListenerStatus follow the conditions pattern used elsewhere in Kubernetes. This is a list that includes a type of condition, the status of that condition, and the last time this condition changed. Listeners TODO Routes TODO HTTPRoute TODO TCPRoute TODO Generic routing TODO Delegation/inclusion TODO Destinations TODO","title":"API concepts"},{"location":"concepts/#api-concepts","text":"This document is a deep dive into the reasoning and design for the API. The content of this document started from this API sketch .","title":"API Concepts"},{"location":"concepts/#roles-and-personas","text":"In the original design of Kubernetes, Ingress and Service resources were based on a self-service model of usage; developers who create Services and Ingresses control all aspects of defining and exposing their applications to their users. We have found that the self-service model does not fully capture some of the more complex deployment and team structures that our users are seeing. The Gateway/Routes API will target the following personas: Infrastructure provider : The infrastructure provider (infra) is responsible for the overall environment that the cluster(s) are operating in. Examples include public cloud providers (AWS, Azure, GCP, ...), or PaaS providers within an organization. Cluster operator : The cluster operator (ops) is responsible for administration of entire clusters. They manage policies, network access, and application permissions. Application developer : The application developer (dev) is responsible for defining their application configuration (e.g. timeouts, request matching/filter) and Service composition (e.g. path routing to backends). We expect that each persona will map approximately to a Role in the Kubernetes Role-Based Authentication (RBAC) system and will define resource model responsibility and separation. Depending on the environment, multiple roles can map to the same user. For example, giving the user all the above roles replicates the self-service model. For more information on the roles and personas considered in the Service API design, refer to the Security Model .","title":"Roles and personas"},{"location":"concepts/#resource-model","text":"Note: Resources will initially live in the networking.x-k8s.io API group as Custom Resource Definitions (CRDs). Unqualified resource names will implicitly be in this API group. There are three main types of objects in our resource model: GatewayClass defines a set of gateways with a common configuration and behavior. Gateway requests a point where traffic can be translated to Services within the cluster. Routes describe how traffic coming via the Gateway maps to the Services.","title":"Resource model"},{"location":"concepts/#gatewayclass","text":"GatewayClass defines a set of Gateways that share a common configuration and behaviour. Each GatewayClass will be handled by a single controller, although controllers MAY handle more than one. GatewayClass is a cluster-scoped resource. There MUST be at least one GatewayClass defined in order to be able to have functional Gateways. A controller that implements the Gateway API does so by providing an associated GatewayClass resource that the user can reference from their Gateway(s). This is similar to IngressClass for Ingress and StorageClass for PersistentVolumes. In Ingress v1beta1, the closest analog to GatewayClass is the ingress-class annotation, and in IngressV1, the closest analog is the IngressClass object.","title":"GatewayClass"},{"location":"concepts/#gateway","text":"A Gateway describes how traffic can be translated to Services within the cluster. That is, it defines a request for a way to translate traffic from somewhere that does not know about Kubernetes to somewhere that does. For example, traffic sent to a Kubernetes Services by a cloud load balancer, an in-cluster proxy or external hardware load balancer. While many use cases have client traffic originating \u201coutside\u201d the cluster, this is not a requirement. It defines a request for a specific load balancer config that implements the GatewayClass\u2019 configuration and behaviour contract. The resource MAY be created by an operator directly, or MAY be created by a controller handling a GatewayClass. As the Gateway spec captures user intent, it may not contain a complete specification for all attributes in the spec. For example, the user may omit fields such as addresses, ports, TLS settings. This allows the controller managing the GatewayClass to provide these settings for the user, resulting in a more portable spec. This behaviour will be made clear using the GatewayClass Status object. A Gateway MAY contain one or more *Route references which serve to direct traffic for a subset of traffic to a specific service.","title":"Gateway"},{"location":"concepts/#httptcpfooroute","text":"Route objects define protocol-specific rules for mapping requests from a Gateway to Kubernetes Services. HTTPRoute and TCPRoute are currently the only defined Route objects. Additional protocol-specific Route objects may be added in the future.","title":"{HTTP,TCP,Foo}Route"},{"location":"concepts/#combined-types","text":"The combination of GatewayClass , Gateway , xRoute and Service (s) will define an implementable load-balancer. The diagram below illustrates the relationships between the different resources:","title":"Combined types"},{"location":"concepts/#request-flow","text":"A typical client/gateway API request flow for a gateway implemented using a reverse proxy is: A client makes a request to http://foo.example.com. DNS resolves the name to gateway.status.listeners[x].address . The reverse proxy receives the request on gateway.status.listeners[x].address : gateway.spec.listeners[x].port and uses the Host header to match an HTTPRoute . Optionally, the reverse proxy can perform request header and/or path matching based on match rules of the HTTPRoute . Optionally, the reverse proxy can manipulate the request, i.e. add/remove headers, etc. based on filter rules of the HTTPRoute . Lastly, the reverse proxy forwards the request to one or more objects in the cluster based on action rules of the HTTPRoute . When specifying multiple forwardTo objects, the request is split, i.e. forwarded to each object.","title":"Request flow"},{"location":"concepts/#tls-configuration","text":"TLS configuration is tied to Gateway listeners. Although adding the option to configure TLS on other resources was considered, ultimately TLS configuration on Gateway listeners was deemed sufficient for the following reasons: In most cases, users that are configuring TLS will naturally also have access to Gateways. In other cases, TLS config could be implemented with a controller watching Routes and adding generated certs to corresponding Gateways. This does not solve the use case for users wanting to provide their own certs for Routes while not having access to a Gateway resource. This seems like it would be a rare edge case and is not worth supporting at this point. The security model outlined a potential approach to enable this in the future, but there does not seem to be a sufficient reason to work towards that now.","title":"TLS Configuration"},{"location":"concepts/#design-considerations","text":"There are some general design guidelines used throughout this API.","title":"Design considerations"},{"location":"concepts/#single-resource-consistency","text":"The Kubernetes API guarantees consistency only on a single resource level. There are a couple of consequences for complex resource graphs as opposed to single resources: Error checking of properties spanning multiple resource will be asynchronous and eventually consistent. Simple syntax checks will be possible at the single resource level, but cross resource dependencies will need to be handled by the controller. Controllers will need to handle broken links between resources and/or mismatched configuration.","title":"Single resource consistency"},{"location":"concepts/#conflicts","text":"Separation and delegation of responsibility among independent actors (e.g between cluster ops and application developers) can result in conflicts in the configuration. For example, two application teams may inadvertently submit configuration for the same HTTP path. There are several different strategies for handling this: TODO","title":"Conflicts"},{"location":"concepts/#extensibility","text":"TODO","title":"Extensibility"},{"location":"concepts/#gatewayclass_1","text":"GatewayClass ( source code ) is cluster-scoped resource defined by the infrastructure provider. This resource represents a class of Gateways that can be instantiated. Note: this serves the same function as the networking.IngressClass resource . kind: GatewayClass metadata: name: cluster-gateway spec: controller: \"acme.io/gateway-controller\" We expect that one or more GatewayClasses will be created by the infrastructure provider for the user. It allows decoupling of which mechanism (e.g. controller) implements the Gateways from the user. For instance, an infrastructure provider may create two GatewayClasses named internet and private to reflect Gateways that define Internet-facing vs private, internal applications. kind: GatewayClass metadata: name: internet ... --- kind: GatewayClass metadata: name: private ... The user of the classes will not need to know how internet and private are implemented. Instead, the user will only need to understand the resulting properties of the class that the Gateway was created with.","title":"GatewayClass"},{"location":"concepts/#gatewayclass-parameters","text":"Providers of the Gateway API may need to pass parameters to their controller as part of the class definition. This is done using the GatewayClass.spec.parametersRef field: # GatewayClass for Gateways that define Internet-facing applications. kind: GatewayClass metadata: name: internet spec: controller: \"acme.io/gateway-controller\" parametersRef: name: internet-gateway --- kind: ConfigMap metadata: name: internet-gateway namespace: acme-system data: ip-address-pool: internet-vips ... Note: parametersRef will expect a ConfigMap as a referenced object if resource and group are omitted. The type of object referenced by GatewayClass.spec.parametersRef will depend on the provider itself. A core.ConfigMap is used in the example above, but controllers may opt to use a CustomResource for better schema validation.","title":"GatewayClass parameters"},{"location":"concepts/#gatewayclass-status","text":"GatewayClasses MUST be validated by the provider to ensure that the configured parameters are valid. The validity of the class will be signaled to the user via GatewayClass.status : kind: GatewayClass ... status: conditions: - type: InvalidParameters status: Unknown ... A new GatewayClass will start with the InvalidParameters condition set to Unknown . At this point the controller has not seen the configuration. Once the controller has processed the configuration, the condition will be set to False : kind: GatewayClass ... status: conditions: - type: InvalidParameters status: False ... If there is an error in the GatewayClass.spec , the conditions will be non-empty and contain information about the error. kind: GatewayClass ... status: conditions: - type: InvalidParameters status: True Reason: BadFooBar Message: \"foobar\" is an FooBar.","title":"GatewayClass status"},{"location":"concepts/#gateway_1","text":"A Gateway is 1:1 with the life cycle of the configuration of infrastructure. When a user creates a Gateway , some load balancing infrastructure is provisioned or configured (see below for details) by the GatewayClass controller. Gateway is the resource that triggers actions in this API. Other resources in this API are configuration snippets until a Gateway has been created to link the resources together. The Gateway spec defines the following: The GatewayClass used to instantiate this Gateway. The Listener bindings, which define addresses and ports, protocol termination, and TLS settings. The Listener configuration requested by a Gateway definition can be incompatible with a given GatewayClass (e.g. port/protocol combination is not supported). The Routes, which describe how traffic is processed and forwarded. If the Listener configuration requested by a Gateway definition is incompatible with a given GatewayClass, the Gateway will be in an error state, signaled by the status field.","title":"Gateway"},{"location":"concepts/#deployment-models","text":"Depending on the GatewayClass , the creation of the Gateway could do any of the following actions: Use cloud APIs to create an LB instance. Spawn a new instance of a software LB (in this or another cluster). Add a configuration stanza to an already instantiated LB to handle the new routes. Program the SDN to implement the configuration. Something else we haven\u2019t thought of yet... The API does not specify which one of these actions will be taken. Note that a GatewayClass controller that manages in-cluster proxy processes MAY restrict Gateway configuration scope, e.g. only be served in the same namespace.","title":"Deployment models"},{"location":"concepts/#gateway-status","text":"Gateways track status for the Gateway resource as a whole as well as each Listener it contains. The status for a specific Route is reported in the status of the Route resource. Within GatewayStatus , Listeners will have status entries corresponding to their name. Both GatewayStatus and ListenerStatus follow the conditions pattern used elsewhere in Kubernetes. This is a list that includes a type of condition, the status of that condition, and the last time this condition changed.","title":"Gateway Status"},{"location":"concepts/#listeners","text":"TODO","title":"Listeners"},{"location":"concepts/#routes","text":"TODO","title":"Routes"},{"location":"concepts/#httproute","text":"TODO","title":"HTTPRoute"},{"location":"concepts/#tcproute","text":"TODO","title":"TCPRoute"},{"location":"concepts/#generic-routing","text":"TODO","title":"Generic routing"},{"location":"concepts/#delegationinclusion","text":"TODO","title":"Delegation/inclusion"},{"location":"concepts/#destinations","text":"TODO","title":"Destinations"},{"location":"cookbook/","text":"API Cookbook TODO: Cookbook will be a page w/ examples for common tasks (exposing an HTTP service, configuring TLS, etc).","title":"API cookbook"},{"location":"cookbook/#api-cookbook","text":"TODO: Cookbook will be a page w/ examples for common tasks (exposing an HTTP service, configuring TLS, etc).","title":"API Cookbook"},{"location":"devguide/","text":"Building, testing and deploying You will need to have Docker installed to perform the steps below. Project management We are using the Github issues and project dashboard to manage the list of TODOs for this project: Open issues Project dashboard Issues labeled good first issue and help wanted are especially good for a first contribution. Release cadence During the development phase, we expect to release on a monthly cadence. We are explicitly decoupling ourselves from the Kubernetes API versioning cycle to give us more flexibility to evolve the specification. As the specification solidifies, we will slow down our release cycle. General target timeline: 1H 2020: Monthly release cycle, with first release targeted for January 31 2H 2020: Slower release cycle Building the code The project uses make to drive the build. make will build the manager binary, run code generators, and run static analysis against the code. You can kick off an overall build from the top-level makefile: make Testing the code The easiest way to test the code is to use the kubebuilder created CRD with a kind cluster. Follow the installation instructions for kind in the README in the repo. kind create cluster ... # Install the CRDs make install # Remove the CRDs and associated CRs make uninstall Submitting a review TODO Verify Make sure you run the static analysis over the repo before submitting your changes. The Prow presubmit will not let your change merge if verification fails. make verify Documentation The site documentation is written in mkdocs format. The files are contained in docs-src/ . Generated files are in docs/ and published to Github Pages. Building the docs: make docs Live preview for editing (view on http://localhost:8000 , CTRL-C to quit): make serve Remove generated documentation files: make clean Publishing The docs are published automatically to Github pages . When making changes to the documentation, generate the new documentation and make the generated code a self-contained commit (e.g. the changes to docs/ ). This will keep the code reviews simple and clearly delineate user vs generated content.","title":"Developer guide"},{"location":"devguide/#building-testing-and-deploying","text":"You will need to have Docker installed to perform the steps below.","title":"Building, testing and deploying"},{"location":"devguide/#project-management","text":"We are using the Github issues and project dashboard to manage the list of TODOs for this project: Open issues Project dashboard Issues labeled good first issue and help wanted are especially good for a first contribution.","title":"Project management"},{"location":"devguide/#release-cadence","text":"During the development phase, we expect to release on a monthly cadence. We are explicitly decoupling ourselves from the Kubernetes API versioning cycle to give us more flexibility to evolve the specification. As the specification solidifies, we will slow down our release cycle. General target timeline: 1H 2020: Monthly release cycle, with first release targeted for January 31 2H 2020: Slower release cycle","title":"Release cadence"},{"location":"devguide/#building-the-code","text":"The project uses make to drive the build. make will build the manager binary, run code generators, and run static analysis against the code. You can kick off an overall build from the top-level makefile: make","title":"Building the code"},{"location":"devguide/#testing-the-code","text":"The easiest way to test the code is to use the kubebuilder created CRD with a kind cluster. Follow the installation instructions for kind in the README in the repo. kind create cluster ... # Install the CRDs make install # Remove the CRDs and associated CRs make uninstall","title":"Testing the code"},{"location":"devguide/#submitting-a-review","text":"TODO","title":"Submitting a review"},{"location":"devguide/#verify","text":"Make sure you run the static analysis over the repo before submitting your changes. The Prow presubmit will not let your change merge if verification fails. make verify","title":"Verify"},{"location":"devguide/#documentation","text":"The site documentation is written in mkdocs format. The files are contained in docs-src/ . Generated files are in docs/ and published to Github Pages. Building the docs: make docs Live preview for editing (view on http://localhost:8000 , CTRL-C to quit): make serve Remove generated documentation files: make clean","title":"Documentation"},{"location":"devguide/#publishing","text":"The docs are published automatically to Github pages . When making changes to the documentation, generate the new documentation and make the generated code a self-contained commit (e.g. the changes to docs/ ). This will keep the code reviews simple and clearly delineate user vs generated content.","title":"Publishing"},{"location":"enhancement-requests/","text":"Enhancement Tracking and Backlog Inspired by Kubernetes enhancements , service-api's provides a process for introducing new functionality or considerable changes to the project. The enhancement process will evolve over time as the project matures. Enhancements provides the basis of a community roadmap. Enhancements may be filed by anyone, but require approval from a maintainer to accept the enhancement into the project. Quick start Create an Issue and select \"Enhancement Request\". Follow the instructions in the enhancement request template and submit the Issue. What is Considered an Enhancement? An enhancement is generally anything that: impacts how a cluster is operated including addition or removal of significant capabilities introduces changes to an api needs significant effort to implement requires documentation to utilize It is unlikely to require an enhancement if it: fixes a bug adds more testing code refactors minimal impact to a release If you're unsure the proposed work requires an enhancement, file an issue and ask. When to Create a New Enhancement Create an enhancement once you have: circulated your idea to see if there is interest. identified community members who agree to work on and maintain the enhancement. enhancements may take several releases to complete. a prototype in your own fork (optional) Why are Enhancements Tracked As the project evolves, it's important that the service-api's community understands how the enhancement affects the project. Individually, it's hard to understand how all parts of the system interact, but as a community we can work together to build the right design and approach before getting too deep into an implementation. When to Comment on an Enhancement Issue Please comment on the enhancement issue to: - request a review or clarification on the process - update status of the enhancement effort - link to relevant issues in other repos","title":"Enhancement requests"},{"location":"enhancement-requests/#enhancement-tracking-and-backlog","text":"Inspired by Kubernetes enhancements , service-api's provides a process for introducing new functionality or considerable changes to the project. The enhancement process will evolve over time as the project matures. Enhancements provides the basis of a community roadmap. Enhancements may be filed by anyone, but require approval from a maintainer to accept the enhancement into the project.","title":"Enhancement Tracking and Backlog"},{"location":"enhancement-requests/#quick-start","text":"Create an Issue and select \"Enhancement Request\". Follow the instructions in the enhancement request template and submit the Issue.","title":"Quick start"},{"location":"enhancement-requests/#what-is-considered-an-enhancement","text":"An enhancement is generally anything that: impacts how a cluster is operated including addition or removal of significant capabilities introduces changes to an api needs significant effort to implement requires documentation to utilize It is unlikely to require an enhancement if it: fixes a bug adds more testing code refactors minimal impact to a release If you're unsure the proposed work requires an enhancement, file an issue and ask.","title":"What is Considered an Enhancement?"},{"location":"enhancement-requests/#when-to-create-a-new-enhancement","text":"Create an enhancement once you have: circulated your idea to see if there is interest. identified community members who agree to work on and maintain the enhancement. enhancements may take several releases to complete. a prototype in your own fork (optional)","title":"When to Create a New Enhancement"},{"location":"enhancement-requests/#why-are-enhancements-tracked","text":"As the project evolves, it's important that the service-api's community understands how the enhancement affects the project. Individually, it's hard to understand how all parts of the system interact, but as a community we can work together to build the right design and approach before getting too deep into an implementation.","title":"Why are Enhancements Tracked"},{"location":"enhancement-requests/#when-to-comment-on-an-enhancement-issue","text":"Please comment on the enhancement issue to: - request a review or clarification on the process - update status of the enhancement effort - link to relevant issues in other repos","title":"When to Comment on an Enhancement Issue"},{"location":"faq/","text":"Frequently Asked Questions (FAQ) Q: Will there be a default controller implementation (in this repo)? A: There is no current plan to have an \"official\" or \"default\" implementation. You will see the controller code in this repo be used for testing the support libraries.","title":"FAQ"},{"location":"faq/#frequently-asked-questions-faq","text":"Q: Will there be a default controller implementation (in this repo)? A: There is no current plan to have an \"official\" or \"default\" implementation. You will see the controller code in this repo be used for testing the support libraries.","title":"Frequently Asked Questions (FAQ)"},{"location":"feedback/","text":"Feedback and Bug Reports Feedback and bug reports should be filed as Github Issues on this repo. Be sure to use the following template: TODO","title":"Feedback"},{"location":"feedback/#feedback-and-bug-reports","text":"Feedback and bug reports should be filed as Github Issues on this repo. Be sure to use the following template: TODO","title":"Feedback and Bug Reports"},{"location":"releases/","text":"Releases Although Service APIs are an official Kubernetes project, and represent official APIs, these APIs will not be installed by default on Kubernetes clusters at this time. This project will use Custom Resource Definitions (CRDs) to represent the new API types that Service APIs include. Similar to other Kubernetes APIs, these will go through a formal Kubernetes Enhancement Proposal (KEP) review. Unlike other Kubernetes APIs, Service API releases will be independent from Kubernetes releases initially. Service API releases will include four components: * Custom Resource Definitions to define the API. * Go client libraries. * Validation webhooks to implement cross field validations. * Conversion webhooks to convert resources between API versions. Versioning Versioning will be completely separate from the Kubernetes release process, but similar methodology will be used. Service API versions will use the same version level requirements as other Kubernetes features . Service APIs are currently at the development stage of versioning described in the Kubernetes documentation above. An initial alpha release is currently planned for February 2020. A faster release cadence will be used for alpha versions, with new alpha releases monthly. Users and controller authors will be expected to use the latest version of the API. There will be little to no provisions for backwards compatibility for alpha versions. Generally we expect the alpha API to be for users and controller developers to test out the API but not in any production environment. Beta and stable releases will operate on a slower, more standard, release schedule. They will also provide all of the stability guarantees that other beta and stable Kubernetes features provide. Installation This project will be responsible for providing straightforward and reliable ways to install releases of Service APIs. Other Official Custom Resources This is a relatively new concept, and there is only one previous example of official custom resources being used: VolumeSnapshots . Although VolumeSnapshot CRDs can be installed directly by CSI drivers that support them, Service APIs must support multiple controllers per cluster, so the CRDs will live in and be installed from this repo.","title":"Releases"},{"location":"releases/#releases","text":"Although Service APIs are an official Kubernetes project, and represent official APIs, these APIs will not be installed by default on Kubernetes clusters at this time. This project will use Custom Resource Definitions (CRDs) to represent the new API types that Service APIs include. Similar to other Kubernetes APIs, these will go through a formal Kubernetes Enhancement Proposal (KEP) review. Unlike other Kubernetes APIs, Service API releases will be independent from Kubernetes releases initially. Service API releases will include four components: * Custom Resource Definitions to define the API. * Go client libraries. * Validation webhooks to implement cross field validations. * Conversion webhooks to convert resources between API versions.","title":"Releases"},{"location":"releases/#versioning","text":"Versioning will be completely separate from the Kubernetes release process, but similar methodology will be used. Service API versions will use the same version level requirements as other Kubernetes features . Service APIs are currently at the development stage of versioning described in the Kubernetes documentation above. An initial alpha release is currently planned for February 2020. A faster release cadence will be used for alpha versions, with new alpha releases monthly. Users and controller authors will be expected to use the latest version of the API. There will be little to no provisions for backwards compatibility for alpha versions. Generally we expect the alpha API to be for users and controller developers to test out the API but not in any production environment. Beta and stable releases will operate on a slower, more standard, release schedule. They will also provide all of the stability guarantees that other beta and stable Kubernetes features provide.","title":"Versioning"},{"location":"releases/#installation","text":"This project will be responsible for providing straightforward and reliable ways to install releases of Service APIs.","title":"Installation"},{"location":"releases/#other-official-custom-resources","text":"This is a relatively new concept, and there is only one previous example of official custom resources being used: VolumeSnapshots . Although VolumeSnapshot CRDs can be installed directly by CSI drivers that support them, Service APIs must support multiple controllers per cluster, so the CRDs will live in and be installed from this repo.","title":"Other Official Custom Resources"},{"location":"security-model/","text":"Security Model Introduction The Service APIs have been designed to enable granular authorization for each role in a typical organization. Resources The Service APIs have 4 primary API resources: GatewayClass defines a set of gateways with a common configuration and behavior. Gateway requests a point where traffic can be translated to Services within the cluster. Routes describe how traffic coming via the Gateway maps to the Services. TrafficSplits describe how traffic may be split from Routes. Additional Configuration There are two additional pieces of configuration that are important in this security model: Which namespaces can contain Gateways of the specified GatewayClass. Which namespaces Routes can be targeted in by Gateways of the specified GatewayClass. Roles For the purposes of this security model, 3 common roles have been identified: Infrastructure provider : The infrastructure provider (infra) is responsible for the overall environment that the cluster(s) are operating in. Examples include: the cloud provider (AWS, Azure, GCP, ...), the PaaS provider in a company. Cluster operator : The cluster operator (ops) is responsible for administration of entire clusters. They manage policies, network access, application permissions. Application developer : The application developer (dev) is responsible for defining their application configuration (e.g. timeouts, request matching/filter) and Service composition (e.g. path routing to backends). Although these roles can cover a wide variety of use cases, some organizations may be structured slightly differently. Many organizations may also have a fourth role that sits between \"cluster operator\" and \"application developer\": Application admin : The application admin has administrative access to some namespaces within a cluster, but not the cluster as a whole. The Security Model There are two primary components to the Service APIs security model: RBAC and namespace restrictions. RBAC RBAC (role-based access control) is the standard used for Kubernetes authorization. This allows users to configure who can perform actions on resources in specific scopes. RBAC can be used to enable each of the roles defined above. In most cases, it will be desirable to have all resources be readable by most roles, so instead we'll focus on write access for this model. Write Permissions for Simple 3 Tier Model GatewayClass Gateway Route TrafficSplit Infrastructure Provider Yes Yes Yes Yes Cluster Operators No Yes Yes Yes Application Developers No No Yes Yes Write Permissions for Advanced 4 Tier Model GatewayClass Gateway Route TrafficSplit Infrastructure Provider Yes Yes Yes Yes Cluster Operators Sometimes Yes Yes Yes Application Admins No In Specified Namespaces In Specified Namespaces In Specified Namespaces Application Developers No No In Specified Namespaces In Specified Namespaces Namespace Restrictions The extra configuration options are not possible to control with RBAC. Instead, they will be controlled with configuration fields on GatewayClasses: allowedGatewayNamespaces : This field is a selector of namespaces that Gateways can use this GatewayClass from. This is a standard Kubernetes LabelSelector, a label query over a set of resources. The result of matchLabels and matchExpressions are ANDed. Controllers must not support Gateways in namespaces outside this selector. An empty selector (default) indicates that Gateways can use this GatewayClass from any namespace. This field is intentionally not a pointer because the nil behavior (no namespaces) is undesirable here. allowedRouteNamespaces : This field is a selector of namespaces that Gateways of this class can reference Routes in. This is a standard Kubernetes LabelSelector, a label query over a set of resources. The result of matchLabels and matchExpressions are ANDed. Controllers must not support Routes in namespaces outside this selector. A nil selector (default) indicates that Gateways of this class can reference Routes within the same namespace. An empty selector indicates that Gateways can reference Routes in any namespace. This field is intentionally a pointer to support the nil behavior (only local Routes allowed). Controller Requirements To be considered conformant with the Service APIs spec, controllers need to: Populate status fields on Gateways and Resources to indicate if they are compatible with the corresponding GatewayClass configuration. Not implement invalid configuration. Fore example, if a route is referenced in an invalid namespace for the GatewayClass, it should be ignored. Respond to changes in GatewayClass configuration that may change which Gateways or Routes are valid. Alternative Approaches Considered New API Resources We considered introducing new API resources to cover these use cases. These resources might be look something like: ClusterGateway : A ClusterGateway could reference routes in any namespace. ClusterRoute : A ClusterRoute could be referenced by any Gateway or ClusterGateway. Benefits Easy to model with RBAC. API validation tied directly to each resource. Downsides New resources to deal with - more informers, clients, documentation, etc. Harder to expand with additional options in the future - may just end up with tons of API resources to cover all use cases. Boolean Multi Namespace Route Indicator on GatewayClass Instead of having the routeNamespaceSelector field on GatewayClass, we would use a boolean multiNamespaceRoutes field to indicate if Gateways of this class can target routes in multiple namespaces. This would default to false. A false value here would indicate that routes could only be targeted in the current namespace. Benefits Helpful for multi-tenant use cases with many isolated Gateways. Simple configuration with an easy to understand default value. Downsides GatewayClass admins are unable to partially limit namespaces that can be targeted by Gateways. Admins would have to choose between allowing access to Routes in all namespaces or only the local one. Validating Webhook A validating webhook could potentially handle some of the cross-resource validation necessary for this security model and provide more immediate feedback to end users. Benefits Immediate validation feedback. More validation logic stays in core Service APIs codebase. Downsides Imperfect solution for cross-resource validation. For example, a change to a GatewayClass could affect the validity of corresponding Gateway. Additional complexity involved in installing Service APIs in a cluster.","title":"Security Model"},{"location":"security-model/#security-model","text":"","title":"Security Model"},{"location":"security-model/#introduction","text":"The Service APIs have been designed to enable granular authorization for each role in a typical organization.","title":"Introduction"},{"location":"security-model/#resources","text":"The Service APIs have 4 primary API resources: GatewayClass defines a set of gateways with a common configuration and behavior. Gateway requests a point where traffic can be translated to Services within the cluster. Routes describe how traffic coming via the Gateway maps to the Services. TrafficSplits describe how traffic may be split from Routes.","title":"Resources"},{"location":"security-model/#additional-configuration","text":"There are two additional pieces of configuration that are important in this security model: Which namespaces can contain Gateways of the specified GatewayClass. Which namespaces Routes can be targeted in by Gateways of the specified GatewayClass.","title":"Additional Configuration"},{"location":"security-model/#roles","text":"For the purposes of this security model, 3 common roles have been identified: Infrastructure provider : The infrastructure provider (infra) is responsible for the overall environment that the cluster(s) are operating in. Examples include: the cloud provider (AWS, Azure, GCP, ...), the PaaS provider in a company. Cluster operator : The cluster operator (ops) is responsible for administration of entire clusters. They manage policies, network access, application permissions. Application developer : The application developer (dev) is responsible for defining their application configuration (e.g. timeouts, request matching/filter) and Service composition (e.g. path routing to backends). Although these roles can cover a wide variety of use cases, some organizations may be structured slightly differently. Many organizations may also have a fourth role that sits between \"cluster operator\" and \"application developer\": Application admin : The application admin has administrative access to some namespaces within a cluster, but not the cluster as a whole.","title":"Roles"},{"location":"security-model/#the-security-model","text":"There are two primary components to the Service APIs security model: RBAC and namespace restrictions.","title":"The Security Model"},{"location":"security-model/#rbac","text":"RBAC (role-based access control) is the standard used for Kubernetes authorization. This allows users to configure who can perform actions on resources in specific scopes. RBAC can be used to enable each of the roles defined above. In most cases, it will be desirable to have all resources be readable by most roles, so instead we'll focus on write access for this model.","title":"RBAC"},{"location":"security-model/#write-permissions-for-simple-3-tier-model","text":"GatewayClass Gateway Route TrafficSplit Infrastructure Provider Yes Yes Yes Yes Cluster Operators No Yes Yes Yes Application Developers No No Yes Yes","title":"Write Permissions for Simple 3 Tier Model"},{"location":"security-model/#write-permissions-for-advanced-4-tier-model","text":"GatewayClass Gateway Route TrafficSplit Infrastructure Provider Yes Yes Yes Yes Cluster Operators Sometimes Yes Yes Yes Application Admins No In Specified Namespaces In Specified Namespaces In Specified Namespaces Application Developers No No In Specified Namespaces In Specified Namespaces","title":"Write Permissions for Advanced 4 Tier Model"},{"location":"security-model/#namespace-restrictions","text":"The extra configuration options are not possible to control with RBAC. Instead, they will be controlled with configuration fields on GatewayClasses: allowedGatewayNamespaces : This field is a selector of namespaces that Gateways can use this GatewayClass from. This is a standard Kubernetes LabelSelector, a label query over a set of resources. The result of matchLabels and matchExpressions are ANDed. Controllers must not support Gateways in namespaces outside this selector. An empty selector (default) indicates that Gateways can use this GatewayClass from any namespace. This field is intentionally not a pointer because the nil behavior (no namespaces) is undesirable here. allowedRouteNamespaces : This field is a selector of namespaces that Gateways of this class can reference Routes in. This is a standard Kubernetes LabelSelector, a label query over a set of resources. The result of matchLabels and matchExpressions are ANDed. Controllers must not support Routes in namespaces outside this selector. A nil selector (default) indicates that Gateways of this class can reference Routes within the same namespace. An empty selector indicates that Gateways can reference Routes in any namespace. This field is intentionally a pointer to support the nil behavior (only local Routes allowed).","title":"Namespace Restrictions"},{"location":"security-model/#controller-requirements","text":"To be considered conformant with the Service APIs spec, controllers need to: Populate status fields on Gateways and Resources to indicate if they are compatible with the corresponding GatewayClass configuration. Not implement invalid configuration. Fore example, if a route is referenced in an invalid namespace for the GatewayClass, it should be ignored. Respond to changes in GatewayClass configuration that may change which Gateways or Routes are valid.","title":"Controller Requirements"},{"location":"security-model/#alternative-approaches-considered","text":"","title":"Alternative Approaches Considered"},{"location":"security-model/#new-api-resources","text":"We considered introducing new API resources to cover these use cases. These resources might be look something like: ClusterGateway : A ClusterGateway could reference routes in any namespace. ClusterRoute : A ClusterRoute could be referenced by any Gateway or ClusterGateway. Benefits Easy to model with RBAC. API validation tied directly to each resource. Downsides New resources to deal with - more informers, clients, documentation, etc. Harder to expand with additional options in the future - may just end up with tons of API resources to cover all use cases.","title":"New API Resources"},{"location":"security-model/#boolean-multi-namespace-route-indicator-on-gatewayclass","text":"Instead of having the routeNamespaceSelector field on GatewayClass, we would use a boolean multiNamespaceRoutes field to indicate if Gateways of this class can target routes in multiple namespaces. This would default to false. A false value here would indicate that routes could only be targeted in the current namespace. Benefits Helpful for multi-tenant use cases with many isolated Gateways. Simple configuration with an easy to understand default value. Downsides GatewayClass admins are unable to partially limit namespaces that can be targeted by Gateways. Admins would have to choose between allowing access to Routes in all namespaces or only the local one.","title":"Boolean Multi Namespace Route Indicator on GatewayClass"},{"location":"security-model/#validating-webhook","text":"A validating webhook could potentially handle some of the cross-resource validation necessary for this security model and provide more immediate feedback to end users. Benefits Immediate validation feedback. More validation logic stays in core Service APIs codebase. Downsides Imperfect solution for cross-resource validation. For example, a change to a GatewayClass could affect the validity of corresponding Gateway. Additional complexity involved in installing Service APIs in a cluster.","title":"Validating Webhook"},{"location":"spec/","text":"Packages: networking.x-k8s.io/v1alpha1 networking.x-k8s.io/v1alpha1 Package v1alpha1 contains API Schema definitions for the networking v1alpha1 API group Resource Types: GatewayClass GatewayClass GatewayClass describes a class of Gateways available to the user for creating Gateway resources. GatewayClass is a Cluster level resource. Support: Core. Field Description apiVersion string networking.x-k8s.io/v1alpha1 kind string GatewayClass metadata Kubernetes meta/v1.ObjectMeta Refer to the Kubernetes API documentation for the fields of the metadata field. spec GatewayClassSpec Spec for this GatewayClass. controller string Controller is a domain/path string that indicates the controller that managing Gateways of this class. Example: \u201cacme.io/gateway-controller\u201d. This field is not mutable and cannot be empty. The format of this field is DOMAIN \u201c/\u201d PATH, where DOMAIN and PATH are valid Kubernetes names ( https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names ). Support: Core allowedGatewayNamespaces Kubernetes meta/v1.LabelSelector (Optional) AllowedGatewayNamespaces is a selector of namespaces that Gateways can use this GatewayClass from. This is a standard Kubernetes LabelSelector, a label query over a set of resources. The result of matchLabels and matchExpressions are ANDed. Controllers must not support Gateways in namespaces outside this selector. An empty selector (default) indicates that Gateways can use this GatewayClass from any namespace. This field is intentionally not a pointer because the nil behavior (no namespaces) is undesirable here. Support: Core allowedRouteNamespaces Kubernetes meta/v1.LabelSelector (Optional) AllowedRouteNamespaces is a selector of namespaces that Gateways of this class can reference Routes in. This is a standard Kubernetes LabelSelector, a label query over a set of resources. The result of matchLabels and matchExpressions are ANDed. Controllers must not support Routes in namespaces outside this selector. A nil selector (default) indicates that Gateways of this class can reference Routes within the same namespace. An empty selector indicates that Gateways can reference Routes in any namespace. This field is intentionally a pointer to support the nil behavior (only local Routes allowed). Support: Core parametersRef ConfigMapsDefaultLocalObjectReference (Optional) ParametersRef is a controller specific resource containing the configuration parameters corresponding to this class. This is optional if the controller does not require any additional configuration. Valid resources for reference are up to the Controller. Examples include \u201cconfigmaps\u201d (omit or specify the empty string for the group to indicate the core API group) or a custom resource (CRD). Omitting or specifying the empty string for both the resource and group indicates that the resource is \u201cconfigmaps\u201d. If the referent cannot be found, the GatewayClass\u2019s \u201cInvalidParameters\u201d status condition will be true. Support: Custom status GatewayClassStatus Status of the GatewayClass. AddressType ( string alias) ( Appears on: ListenerAddress ) AddressType defines how a network address is represented as a text string. ConfigMapsDefaultLocalObjectReference ( Appears on: GatewayClassSpec , HTTPRouteAction , HTTPRouteFilter , HTTPRouteHost , HTTPRouteMatch , Listener ) RouteMatchExtensionObjectReference identifies a route-match extension object within a known namespace. Field Description group string Group is the group of the referent. Omitting the value or specifying the empty string indicates the core API group. For example, use the following to specify a configmaps: fooRef: resource: configmaps name: myconfigmap Otherwise, if the core API group is not desired, specify the desired group: fooRef: group: acme.io resource: foos name: myfoo resource string Resource is the API resource name of the referent. Omitting the value or specifying the empty string indicates the configmaps resource. For example, use the following to specify a configmaps resource: fooRef: name: myconfigmap Otherwise, if the configmaps resource is not desired, specify the desired group: fooRef: group: acme.io resource: foos name: myfoo name string Name is the name of the referent. ForwardToTarget ( Appears on: HTTPRouteAction ) ForwardToTarget identifies a target object within a known namespace. Field Description targetRef ServicesDefaultLocalObjectReference TargetRef is an object reference to forward matched requests to. Support: Core (Kubernetes Services) Support: Implementation-specific (Other resource types) targetPort TargetPort (Optional) TargetPort specifies the destination port number to use for the TargetRef. If unspecified and TargetRef is a Service object consisting of a single port definition, that port will be used. If unspecified and TargetRef is a Service object consisting of multiple port definitions, an error is surfaced in status. Support: Core Gateway Gateway represents an instantiation of a service-traffic handling infrastructure. Field Description metadata Kubernetes meta/v1.ObjectMeta Refer to the Kubernetes API documentation for the fields of the metadata field. spec GatewaySpec class string Class used for this Gateway. This is the name of a GatewayClass resource. listeners []Listener Listeners associated with this Gateway. Listeners define what addresses, ports, protocols are bound on this Gateway. routes RouteBindingSelector Routes specifies a schema for associating routes with the Gateway using selectors. A route is a resource capable of servicing a request and allows a cluster operator to expose a cluster resource (i.e. Service) by externally-reachable URL, load-balance traffic and terminate SSL/TLS. Typically, a route is a \u201chttproute\u201d or \u201ctcproute\u201d in group \u201cnetworking.x-k8s.io\u201d. However, an implementation may support other resources. Support: Core status GatewayStatus GatewayClassCondition ( Appears on: GatewayClassStatus ) GatewayClassCondition contains the details for the current condition of this GatewayClass. Support: Core, unless otherwise specified. Field Description type GatewayClassConditionType Type of this condition. status Kubernetes core/v1.ConditionStatus Status of this condition. reason string Reason is a machine consumable string for the last transition. It should be a one-word, CamelCase string. Reason will be defined by the controller. Support: Custom; values will be controller-specific. This field must not be empty. message string Message is a human readable reason for last transition. This field may be empty. lastTransitionTime Kubernetes meta/v1.Time LastTransitionTime is the time of the last change to this condition. GatewayClassConditionType ( string alias) ( Appears on: GatewayClassCondition ) GatewayClassConditionType is the type of status conditions. GatewayClassSpec ( Appears on: GatewayClass ) GatewayClassSpec reflects the configuration of a class of Gateways. Field Description controller string Controller is a domain/path string that indicates the controller that managing Gateways of this class. Example: \u201cacme.io/gateway-controller\u201d. This field is not mutable and cannot be empty. The format of this field is DOMAIN \u201c/\u201d PATH, where DOMAIN and PATH are valid Kubernetes names ( https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names ). Support: Core allowedGatewayNamespaces Kubernetes meta/v1.LabelSelector (Optional) AllowedGatewayNamespaces is a selector of namespaces that Gateways can use this GatewayClass from. This is a standard Kubernetes LabelSelector, a label query over a set of resources. The result of matchLabels and matchExpressions are ANDed. Controllers must not support Gateways in namespaces outside this selector. An empty selector (default) indicates that Gateways can use this GatewayClass from any namespace. This field is intentionally not a pointer because the nil behavior (no namespaces) is undesirable here. Support: Core allowedRouteNamespaces Kubernetes meta/v1.LabelSelector (Optional) AllowedRouteNamespaces is a selector of namespaces that Gateways of this class can reference Routes in. This is a standard Kubernetes LabelSelector, a label query over a set of resources. The result of matchLabels and matchExpressions are ANDed. Controllers must not support Routes in namespaces outside this selector. A nil selector (default) indicates that Gateways of this class can reference Routes within the same namespace. An empty selector indicates that Gateways can reference Routes in any namespace. This field is intentionally a pointer to support the nil behavior (only local Routes allowed). Support: Core parametersRef ConfigMapsDefaultLocalObjectReference (Optional) ParametersRef is a controller specific resource containing the configuration parameters corresponding to this class. This is optional if the controller does not require any additional configuration. Valid resources for reference are up to the Controller. Examples include \u201cconfigmaps\u201d (omit or specify the empty string for the group to indicate the core API group) or a custom resource (CRD). Omitting or specifying the empty string for both the resource and group indicates that the resource is \u201cconfigmaps\u201d. If the referent cannot be found, the GatewayClass\u2019s \u201cInvalidParameters\u201d status condition will be true. Support: Custom GatewayClassStatus ( Appears on: GatewayClass ) GatewayClassStatus is the current status for the GatewayClass. Field Description conditions []GatewayClassCondition (Optional) Conditions is the current status from the controller for this GatewayClass. GatewayCondition ( Appears on: GatewayStatus ) GatewayCondition is an error status for a given route. Field Description type GatewayConditionType Type indicates the type of condition. status Kubernetes core/v1.ConditionStatus Status describes the current state of this condition. Can be \u201cTrue\u201d, \u201cFalse\u201d, or \u201cUnknown\u201d. message string Message is a human-understandable message describing the condition. This field may be empty. reason string Reason indicates why the condition is in this state. This field must not be empty. lastTransitionTime Kubernetes meta/v1.Time LastTransitionTime indicates the last time this condition changed. GatewayConditionType ( string alias) ( Appears on: GatewayCondition ) GatewayConditionType is a type of condition associated with a Gateway. GatewayObjectReference ( Appears on: HTTPRouteStatus ) GatewayObjectReference identifies a Gateway object. Field Description namespace string (Optional) Namespace is the namespace of the referent. name string Name is the name of the referent. GatewaySpec ( Appears on: Gateway ) GatewaySpec defines the desired state of Gateway. The Spec is split into two major pieces: listeners describing client-facing properties and routes that describe application-level routing. Not all possible combinations of options specified in the Spec are valid. Some invalid configurations can be caught synchronously via a webhook, but there are many cases that will require asynchronous signaling via the GatewayStatus block. Field Description class string Class used for this Gateway. This is the name of a GatewayClass resource. listeners []Listener Listeners associated with this Gateway. Listeners define what addresses, ports, protocols are bound on this Gateway. routes RouteBindingSelector Routes specifies a schema for associating routes with the Gateway using selectors. A route is a resource capable of servicing a request and allows a cluster operator to expose a cluster resource (i.e. Service) by externally-reachable URL, load-balance traffic and terminate SSL/TLS. Typically, a route is a \u201chttproute\u201d or \u201ctcproute\u201d in group \u201cnetworking.x-k8s.io\u201d. However, an implementation may support other resources. Support: Core GatewayStatus ( Appears on: Gateway ) GatewayStatus defines the observed state of Gateway. Field Description conditions []GatewayCondition (Optional) Conditions describe the current conditions of the Gateway. listeners []ListenerStatus (Optional) Listeners provide status for each listener defined in the Spec. The name in ListenerStatus refers to the corresponding Listener of the same name. HTTPHeaderFilter ( Appears on: HTTPRouteFilter ) HTTPHeaderFilter defines the filter behavior for a request match. Field Description add map[string]string Add adds the given header (name, value) to the request before the action. Input: GET /foo HTTP/1.1 Config: add: {\u201cmy-header\u201d: \u201cfoo\u201d} Output: GET /foo HTTP/1.1 my-header: foo Support: extended? remove []string Remove the given header(s) on the HTTP request before the action. The value of RemoveHeader is a list of HTTP header names. Note that the header names are case-insensitive [RFC-2616 4.2]. Input: GET /foo HTTP/1.1 My-Header1: ABC My-Header2: DEF My-Header2: GHI Config: remove: [\u201cmy-header1\u201d, \u201cmy-header3\u201d] Output: GET /foo HTTP/1.1 My-Header2: DEF Support: extended? HTTPRoute HTTPRoute is the Schema for the httproutes API Field Description metadata Kubernetes meta/v1.ObjectMeta Refer to the Kubernetes API documentation for the fields of the metadata field. spec HTTPRouteSpec hosts []HTTPRouteHost Hosts is a list of Host definitions. default HTTPRouteHost (Optional) Default is the default host to use. Default.Hostnames must be an empty list. status HTTPRouteStatus HTTPRouteAction ( Appears on: HTTPRouteRule ) HTTPRouteAction is the action taken given a match. Field Description forwardTo ForwardToTarget ForwardTo sends requests to the referenced object. The resource may be \u201cservices\u201d (omit or use the empty string for the group), or an implementation may support other resources (for example, resource \u201cmyroutetargets\u201d in group \u201cnetworking.acme.io\u201d). Omitting or specifying the empty string for both the resource and group indicates that the resource is \u201cservices\u201d. If the referent cannot be found, the \u201cInvalidRoutes\u201d status condition on any Gateway that includes the HTTPRoute will be true. extensionRef ConfigMapsDefaultLocalObjectReference (Optional) ExtensionRef is an optional, implementation-specific extension to the \u201caction\u201d behavior. The resource may be \u201cconfigmaps\u201d (use the empty string for the group) or an implementation-defined resource (for example, resource \u201cmyrouteactions\u201d in group \u201cnetworking.acme.io\u201d). Omitting or specifying the empty string for both the resource and group indicates that the resource is \u201cconfigmaps\u201d. If the referent cannot be found, the \u201cInvalidRoutes\u201d status condition on any Gateway that includes the HTTPRoute will be true. Support: custom HTTPRouteFilter ( Appears on: HTTPRouteRule ) HTTPRouteFilter defines a filter-like action to be applied to requests. Field Description headers HTTPHeaderFilter (Optional) Headers related filters. Support: extended extensionRef ConfigMapsDefaultLocalObjectReference (Optional) ExtensionRef is an optional, implementation-specific extension to the \u201cfilter\u201d behavior. The resource may be \u201cconfigmap\u201d (use the empty string for the group) or an implementation-defined resource (for example, resource \u201cmyroutefilters\u201d in group \u201cnetworking.acme.io\u201d). Omitting or specifying the empty string for both the resource and group indicates that the resource is \u201cconfigmaps\u201d. If the referent cannot be found, the \u201cInvalidRoutes\u201d status condition on any Gateway that includes the HTTPRoute will be true. Support: custom HTTPRouteHost ( Appears on: HTTPRouteSpec ) HTTPRouteHost is the configuration for a given host. Field Description hostname string (Optional) Hostname is the fully qualified domain name of a network host, as defined by RFC 3986. Note the following deviations from the \u201chost\u201d part of the URI as defined in the RFC: IPs are not allowed. The : delimiter is not respected because ports are not allowed. Incoming requests are matched against Hostname before processing HTTPRoute rules. For example, if the request header contains host: foo.example.com, an HTTPRoute with hostname foo.example.com will match. However, an HTTPRoute with hostname example.com or bar.example.com will not match. If Hostname is unspecified, the Gateway routes all traffic based on the specified rules. Support: Core rules []HTTPRouteRule Rules are a list of HTTP matchers, filters and actions. extensionRef ConfigMapsDefaultLocalObjectReference (Optional) ExtensionRef is an optional, implementation-specific extension to the \u201chost\u201d block. The resource may be \u201cconfigmaps\u201d (omit or specify the empty string for the group) or an implementation-defined resource (for example, resource \u201cmyroutehosts\u201d in group \u201cnetworking.acme.io\u201d). Omitting or specifying the empty string for both the resource and group indicates that the resource is \u201cconfigmaps\u201d. If the referent cannot be found, the \u201cInvalidRoutes\u201d status condition on any Gateway that includes the HTTPRoute will be true. Support: custom HTTPRouteMatch ( Appears on: HTTPRouteRule ) HTTPRouteMatch defines the predicate used to match requests to a given action. Field Description pathType string (Optional) PathType is defines the semantics of the Path matcher. Support: core (Exact, Prefix) Support: extended (RegularExpression) Support: custom (ImplementationSpecific) Default: \u201cExact\u201d path string Path is the value of the HTTP path as interpreted via PathType. Default: \u201c/\u201d headerType string (Optional) HeaderType defines the semantics of the Header matcher. header map[string]string (Optional) Header are the Header matches as interpreted via HeaderType. extensionRef ConfigMapsDefaultLocalObjectReference (Optional) ExtensionRef is an optional, implementation-specific extension to the \u201cmatch\u201d behavior. The resource may be \u201cconfigmap\u201d (use the empty string for the group) or an implementation-defined resource (for example, resource \u201cmyroutematchers\u201d in group \u201cnetworking.acme.io\u201d). Omitting or specifying the empty string for both the resource and group indicates that the resource is \u201cconfigmaps\u201d. If the referent cannot be found, the \u201cInvalidRoutes\u201d status condition on any Gateway that includes the HTTPRoute will be true. Support: custom HTTPRouteRule ( Appears on: HTTPRouteHost ) HTTPRouteRule is the configuration for a given path. Field Description match HTTPRouteMatch (Optional) Match defines which requests match this path. filter HTTPRouteFilter (Optional) Filter defines what filters are applied to the request. action HTTPRouteAction (Optional) Action defines what happens to the request. HTTPRouteSpec ( Appears on: HTTPRoute ) HTTPRouteSpec defines the desired state of HTTPRoute Field Description hosts []HTTPRouteHost Hosts is a list of Host definitions. default HTTPRouteHost (Optional) Default is the default host to use. Default.Hostnames must be an empty list. HTTPRouteStatus ( Appears on: HTTPRoute ) HTTPRouteStatus defines the observed state of HTTPRoute. Field Description gatewayRefs []GatewayObjectReference Listener ( Appears on: GatewaySpec ) Listener defines a Field Description name string Name is the listener\u2019s name and should be specified as an RFC 1035 DNS_LABEL [1]: [1] https://tools.ietf.org/html/rfc1035 Each listener of a Gateway must have a unique name. Name is used for associating a listener in Gateway status. Support: Core address ListenerAddress (Optional) Address requested for this listener. This is optional and behavior can depend on GatewayClass. If a value is set in the spec and the request address is invalid, the GatewayClass MUST indicate this in the associated entry in GatewayStatus.Listeners. Support: port int32 (Optional) Port is a list of ports associated with the Address. Support: protocol string (Optional) Protocol to use. Support: tls TLSConfig (Optional) TLS is the TLS configuration for the Listener. If unspecified, the listener will not support TLS connections. Support: Core extensionRef ConfigMapsDefaultLocalObjectReference (Optional) ExtensionRef for this Listener. The resource may be \u201cconfigmaps\u201d or an implementation-defined resource (for example, resource \u201cmylisteners\u201d in group \u201cnetworking.acme.io\u201d). Omitting or specifying the empty string for both the resource and group indicates that the resource is \u201cconfigmaps\u201d. If the referent cannot be found, the listener\u2019s \u201cInvalidListener\u201d status condition will be true. Support: custom. ListenerAddress ( Appears on: Listener , ListenerStatus ) ListenerAddress describes an address for the Listener. Field Description type AddressType Type of the Address. This is one of the AddressType constants. Support: Extended value string Value. Examples: \u201c1.2.3.4\u201d, \u201c128::1\u201d, \u201cmy-ip-address\u201d. Validity of the values will depend on Type and support by the controller. ListenerCondition ( Appears on: ListenerStatus ) ListenerCondition is an error status for a given listener. Field Description type ListenerConditionType Type indicates the type of condition. status Kubernetes core/v1.ConditionStatus Status describes the current state of this condition. Can be \u201cTrue\u201d, \u201cFalse\u201d, or \u201cUnknown\u201d. message string Message is a human-understandable message describing the condition. This field may be empty. reason string Reason indicates why the condition is in this state. This field must not be empty. lastTransitionTime Kubernetes meta/v1.Time LastTransitionTime indicates the last time this condition changed. ListenerConditionType ( string alias) ( Appears on: ListenerCondition ) ListenerConditionType is a type of condition associated with the listener. ListenerStatus ( Appears on: GatewayStatus ) ListenerStatus is the status associated with each listener block. Field Description name string Name is the name of the listener this status refers to. address ListenerAddress Address bound on this listener. conditions []ListenerCondition Conditions describe the current condition of this listener. RouteBindingSelector ( Appears on: GatewaySpec ) RouteBindingSelector defines a schema for associating routes with the Gateway. If NamespaceSelector and RouteSelector are defined, only routes matching both selectors are associated with the Gateway. Field Description namespaceSelector Kubernetes meta/v1.LabelSelector NamespaceSelector specifies a set of namespace labels used for selecting routes to associate with the Gateway. If NamespaceSelector is defined, all routes in namespaces matching the NamespaceSelector are associated to the Gateway. An empty NamespaceSelector (default) indicates that routes from any namespace will be associated to this Gateway. This field is intentionally not a pointer because the nil behavior (no namespaces) is undesirable here. Support: Core routeSelector Kubernetes meta/v1.LabelSelector (Optional) RouteSelector specifies a set of route labels used for selecting routes to associate with the Gateway. If RouteSelector is defined, only routes matching the RouteSelector are associated with the Gateway. An empty RouteSelector matches all routes. If undefined, route labels are not used for associating routes to the gateway. Support: Core SecretsDefaultLocalObjectReference ( Appears on: TLSConfig ) SecretsDefaultLocalObjectReference identifies an API object within a known namespace that defaults group to core and resource to secrets if unspecified. Field Description group string Group is the group of the referent. Omitting the value or specifying the empty string indicates the core API group. For example, use the following to specify a secrets resource: fooRef: resource: secrets name: mysecret Otherwise, if the core API group is not desired, specify the desired group: fooRef: group: acme.io resource: foos name: myfoo resource string Resource is the API resource name of the referent. Omitting the value or specifying the empty string indicates the secrets resource. For example, use the following to specify a secrets resource: fooRef: name: mysecret Otherwise, if the secrets resource is not desired, specify the desired group: fooRef: group: acme.io resource: foos name: myfoo name string Name is the name of the referent. ServicesDefaultLocalObjectReference ( Appears on: ForwardToTarget ) ServicesDefaultLocalObjectReference identifies an API object within a known namespace that defaults group to core and resource to services if unspecified. Field Description group string Group is the group of the referent. Omitting the value or specifying the empty string indicates the core API group. For example, use the following to specify a service: fooRef: resource: services name: myservice Otherwise, if the core API group is not desired, specify the desired group: fooRef: group: acme.io resource: foos name: myfoo resource string Resource is the API resource name of the referent. Omitting the value or specifying the empty string indicates the services resource. For example, use the following to specify a services resource: fooRef: name: myservice Otherwise, if the services resource is not desired, specify the desired group: fooRef: group: acme.io resource: foos name: myfoo name string Name is the name of the referent. TLSConfig ( Appears on: Listener ) TLSConfig describes a TLS configuration. References - nginx: https://nginx.org/en/docs/http/configuring_https_servers.html - envoy: https://www.envoyproxy.io/docs/envoy/latest/api-v2/api/v2/auth/cert.proto - haproxy: https://www.haproxy.com/documentation/aloha/9-5/traffic-management/lb-layer7/tls/ - gcp: https://cloud.google.com/load-balancing/docs/use-ssl-policies#creating_an_ssl_policy_with_a_custom_profile - aws: https://docs.aws.amazon.com/elasticloadbalancing/latest/application/create-https-listener.html#describe-ssl-policies - azure: https://docs.microsoft.com/en-us/azure/app-service/configure-ssl-bindings#enforce-tls-1112 Field Description certificateRefs []SecretsDefaultLocalObjectReference CertificateRefs is a list of references to Kubernetes objects that each contain an identity certificate. The host name in a TLS SNI client hello message is used for certificate matching and route host name selection. The SNI server_name must match a route host name for the Gateway to route the TLS request. If an entry in this list omits or specifies the empty string for both the group and the resource, the resource defaults to \u201csecrets\u201d. An implementation may support other resources (for example, resource \u201cmycertificates\u201d in group \u201cnetworking.acme.io\u201d). Support: Core (Kubernetes Secrets) Support: Implementation-specific (Other resource types) minimumVersion string (Optional) MinimumVersion of TLS allowed. It is recommended to use one of the TLS constants above. Note: MinimumVersion is not strongly typed to allow implementation-specific versions to be used without requiring updates to the API types. String must be of the form \u201c \u201d. Support: Core for TLS1_{1,2,3}. Implementation-specific for all other values. options map[string]string Options are a list of key/value pairs to give extended options to the provider. There variation among providers as to how ciphersuites are expressed. If there is a common subset for expressing ciphers then it will make sense to loft that as a core API construct. Support: Implementation-specific. TargetPort ( int32 alias) ( Appears on: ForwardToTarget ) TargetPort specifies the destination port number to use for a TargetRef. TcpRoute TcpRoute is the Schema for the tcproutes API Field Description metadata Kubernetes meta/v1.ObjectMeta Refer to the Kubernetes API documentation for the fields of the metadata field. spec TcpRouteSpec status TcpRouteStatus TcpRouteSpec ( Appears on: TcpRoute ) TcpRouteSpec defines the desired state of TcpRoute TcpRouteStatus ( Appears on: TcpRoute ) TcpRouteStatus defines the observed state of TcpRoute TrafficSplit TrafficSplit is the Schema for the trafficsplits API Field Description metadata Kubernetes meta/v1.ObjectMeta Refer to the Kubernetes API documentation for the fields of the metadata field. spec TrafficSplitSpec status TrafficSplitStatus TrafficSplitSpec ( Appears on: TrafficSplit ) TrafficSplitSpec defines the desired state of TrafficSplit TrafficSplitStatus ( Appears on: TrafficSplit ) TrafficSplitStatus defines the observed state of TrafficSplit Generated with gen-crd-api-reference-docs .","title":"API specification"},{"location":"userguide/","text":"API user guide TODO","title":"User guide"},{"location":"userguide/#api-user-guide","text":"TODO","title":"API user guide"}]} \ No newline at end of file +{"config":{"lang":["en"],"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Introduction This is the documentation for the evolution of service-related APIs for Kubernetes. This project is part of the Kubernetes project working under SIG-NETWORK . Gateway API Gateway is an API for a common portable declarative description of load-balancing infrastructure for Kubernetes. If you are a user: User guide (how to use the API) Cookbook for common tasks If you are a developer: How to build and test How to contribute, meetings, design docs For everyone: Concepts and detailed descriptions API specification Releases Security Model Enhancement requests Feedback and bug reports Contacts Slack: #sig-network-service-apis Project Owners","title":"Introduction"},{"location":"#introduction","text":"This is the documentation for the evolution of service-related APIs for Kubernetes. This project is part of the Kubernetes project working under SIG-NETWORK .","title":"Introduction"},{"location":"#gateway-api","text":"Gateway is an API for a common portable declarative description of load-balancing infrastructure for Kubernetes. If you are a user: User guide (how to use the API) Cookbook for common tasks If you are a developer: How to build and test How to contribute, meetings, design docs For everyone: Concepts and detailed descriptions API specification Releases Security Model Enhancement requests Feedback and bug reports","title":"Gateway API"},{"location":"#contacts","text":"Slack: #sig-network-service-apis Project Owners","title":"Contacts"},{"location":"community/","text":"How to contribute This page contains links to all of the meeting notes, design docs and related discussions around the APIs. Communications Major discussions and notifications will be sent on the SIG-NETWORK mailing list . We also have a Slack channel (sig-network-service-apis) on k8s.io for day-to-day questions, discussions. Meetings Meetings discussing the evolution of the service APIs will alternate times to accommodate participants from various time zones. This calendar includes all Service APIs meetings as well as any other SIG-Network meetings. Thursday 10:30 AM Pacific (EMEA Friendly Time) [Zoom Link] Thursday 4:30 (16:30) PM Pacific (APAC Friendly Time) Office Hours In addition to weekly meetings, we have informal weekly office hours meetings on Wednesdays. Wednesday 3:00 (15:00) PM Pacific Meeting notes Meeting schedule scratch pad Meeting recordings . Date Future meetings Check the calendar February 27, 2019 meeting notes , recording February 20, 2019 meeting notes , recording February 13, 2019 meeting notes , recording February 6, 2019 meeting notes , recording January 30, 2019 meeting notes , recording January 23, 2019 meeting notes , recording TODO January 16, 2019 meeting notes , recording January 9, 2019 meeting notes , recording January 2, 2020 meeting notes , recording didn't work :-( look at the notes December 19, 2019 meeting notes , recording November, 2019 Kubecon 2019 San Diego: API evolution design discussion November, 2019 SIG-NETWORK: Ingress Evolution Sync May, 2019 Kubecon 2019 Barcelona: SIG-NETWORK discussion (general topics, includes V2) Design docs Title Description API sketch Sketch of the proposed API Presentations, Talks Date Title November, 2019 Kubecon 2019 San Diego: Evolving the Kubernetes Ingress APIs to GA and Beyond slides , video November, 2019 Kubecon 2019 San Diego: SIG-NETWORK Service/Ingress Evolution Discussion slides May, 2019 Kubecon 2019 Barcelona: Ingress V2 and Multicluster Services slides , video March, 2018 SIG-NETWORK: Ingress user survey data , slides Code of conduct Participation in the Kubernetes community is governed by the Kubernetes Code of Conduct","title":"How to contribute"},{"location":"community/#how-to-contribute","text":"This page contains links to all of the meeting notes, design docs and related discussions around the APIs.","title":"How to contribute"},{"location":"community/#communications","text":"Major discussions and notifications will be sent on the SIG-NETWORK mailing list . We also have a Slack channel (sig-network-service-apis) on k8s.io for day-to-day questions, discussions.","title":"Communications"},{"location":"community/#meetings","text":"Meetings discussing the evolution of the service APIs will alternate times to accommodate participants from various time zones. This calendar includes all Service APIs meetings as well as any other SIG-Network meetings. Thursday 10:30 AM Pacific (EMEA Friendly Time) [Zoom Link] Thursday 4:30 (16:30) PM Pacific (APAC Friendly Time)","title":"Meetings"},{"location":"community/#office-hours","text":"In addition to weekly meetings, we have informal weekly office hours meetings on Wednesdays. Wednesday 3:00 (15:00) PM Pacific","title":"Office Hours"},{"location":"community/#meeting-notes","text":"Meeting schedule scratch pad Meeting recordings . Date Future meetings Check the calendar February 27, 2019 meeting notes , recording February 20, 2019 meeting notes , recording February 13, 2019 meeting notes , recording February 6, 2019 meeting notes , recording January 30, 2019 meeting notes , recording January 23, 2019 meeting notes , recording TODO January 16, 2019 meeting notes , recording January 9, 2019 meeting notes , recording January 2, 2020 meeting notes , recording didn't work :-( look at the notes December 19, 2019 meeting notes , recording November, 2019 Kubecon 2019 San Diego: API evolution design discussion November, 2019 SIG-NETWORK: Ingress Evolution Sync May, 2019 Kubecon 2019 Barcelona: SIG-NETWORK discussion (general topics, includes V2)","title":"Meeting notes"},{"location":"community/#design-docs","text":"Title Description API sketch Sketch of the proposed API","title":"Design docs"},{"location":"community/#presentations-talks","text":"Date Title November, 2019 Kubecon 2019 San Diego: Evolving the Kubernetes Ingress APIs to GA and Beyond slides , video November, 2019 Kubecon 2019 San Diego: SIG-NETWORK Service/Ingress Evolution Discussion slides May, 2019 Kubecon 2019 Barcelona: Ingress V2 and Multicluster Services slides , video March, 2018 SIG-NETWORK: Ingress user survey data , slides","title":"Presentations, Talks"},{"location":"community/#code-of-conduct","text":"Participation in the Kubernetes community is governed by the Kubernetes Code of Conduct","title":"Code of conduct"},{"location":"concepts/","text":"API Concepts This document is a deep dive into the reasoning and design for the API. The content of this document started from this API sketch . Roles and personas In the original design of Kubernetes, Ingress and Service resources were based on a self-service model of usage; developers who create Services and Ingresses control all aspects of defining and exposing their applications to their users. We have found that the self-service model does not fully capture some of the more complex deployment and team structures that our users are seeing. The Gateway/Routes API will target the following personas: Infrastructure provider : The infrastructure provider (infra) is responsible for the overall environment that the cluster(s) are operating in. Examples include public cloud providers (AWS, Azure, GCP, ...), or PaaS providers within an organization. Cluster operator : The cluster operator (ops) is responsible for administration of entire clusters. They manage policies, network access, and application permissions. Application developer : The application developer (dev) is responsible for defining their application configuration (e.g. timeouts, request matching/filter) and Service composition (e.g. path routing to backends). We expect that each persona will map approximately to a Role in the Kubernetes Role-Based Authentication (RBAC) system and will define resource model responsibility and separation. Depending on the environment, multiple roles can map to the same user. For example, giving the user all the above roles replicates the self-service model. For more information on the roles and personas considered in the Service API design, refer to the Security Model . Resource model Note: Resources will initially live in the networking.x-k8s.io API group as Custom Resource Definitions (CRDs). Unqualified resource names will implicitly be in this API group. There are three main types of objects in our resource model: GatewayClass defines a set of gateways with a common configuration and behavior. Gateway requests a point where traffic can be translated to Services within the cluster. Routes describe how traffic coming via the Gateway maps to the Services. GatewayClass GatewayClass defines a set of Gateways that share a common configuration and behaviour. Each GatewayClass will be handled by a single controller, although controllers MAY handle more than one. GatewayClass is a cluster-scoped resource. There MUST be at least one GatewayClass defined in order to be able to have functional Gateways. A controller that implements the Gateway API does so by providing an associated GatewayClass resource that the user can reference from their Gateway(s). This is similar to IngressClass for Ingress and StorageClass for PersistentVolumes. In Ingress v1beta1, the closest analog to GatewayClass is the ingress-class annotation, and in IngressV1, the closest analog is the IngressClass object. Gateway A Gateway describes how traffic can be translated to Services within the cluster. That is, it defines a request for a way to translate traffic from somewhere that does not know about Kubernetes to somewhere that does. For example, traffic sent to a Kubernetes Services by a cloud load balancer, an in-cluster proxy or external hardware load balancer. While many use cases have client traffic originating \u201coutside\u201d the cluster, this is not a requirement. It defines a request for a specific load balancer config that implements the GatewayClass\u2019 configuration and behaviour contract. The resource MAY be created by an operator directly, or MAY be created by a controller handling a GatewayClass. As the Gateway spec captures user intent, it may not contain a complete specification for all attributes in the spec. For example, the user may omit fields such as addresses, ports, TLS settings. This allows the controller managing the GatewayClass to provide these settings for the user, resulting in a more portable spec. This behaviour will be made clear using the GatewayClass Status object. A Gateway MAY contain one or more *Route references which serve to direct traffic for a subset of traffic to a specific service. {HTTP,TCP,Foo}Route Route objects define protocol-specific rules for mapping requests from a Gateway to Kubernetes Services. HTTPRoute and TCPRoute are currently the only defined Route objects. Additional protocol-specific Route objects may be added in the future. Combined types The combination of GatewayClass , Gateway , xRoute and Service (s) will define an implementable load-balancer. The diagram below illustrates the relationships between the different resources: Request flow A typical client/gateway API request flow for a gateway implemented using a reverse proxy is: A client makes a request to http://foo.example.com. DNS resolves the name to gateway.status.listeners[x].address . The reverse proxy receives the request on gateway.status.listeners[x].address : gateway.spec.listeners[x].port and uses the Host header to match an HTTPRoute . Optionally, the reverse proxy can perform request header and/or path matching based on match rules of the HTTPRoute . Optionally, the reverse proxy can manipulate the request, i.e. add/remove headers, etc. based on filter rules of the HTTPRoute . Lastly, the reverse proxy forwards the request to one or more objects in the cluster based on action rules of the HTTPRoute . When specifying multiple forwardTo objects, the request is split, i.e. forwarded to each object. TLS Configuration TLS configuration is tied to Gateway listeners. Although adding the option to configure TLS on other resources was considered, ultimately TLS configuration on Gateway listeners was deemed sufficient for the following reasons: In most cases, users that are configuring TLS will naturally also have access to Gateways. In other cases, TLS config could be implemented with a controller watching Routes and adding generated certs to corresponding Gateways. This does not solve the use case for users wanting to provide their own certs for Routes while not having access to a Gateway resource. This seems like it would be a rare edge case and is not worth supporting at this point. The security model outlined a potential approach to enable this in the future, but there does not seem to be a sufficient reason to work towards that now. Design considerations There are some general design guidelines used throughout this API. Single resource consistency The Kubernetes API guarantees consistency only on a single resource level. There are a couple of consequences for complex resource graphs as opposed to single resources: Error checking of properties spanning multiple resource will be asynchronous and eventually consistent. Simple syntax checks will be possible at the single resource level, but cross resource dependencies will need to be handled by the controller. Controllers will need to handle broken links between resources and/or mismatched configuration. Conflicts Separation and delegation of responsibility among independent actors (e.g between cluster ops and application developers) can result in conflicts in the configuration. For example, two application teams may inadvertently submit configuration for the same HTTP path. There are several different strategies for handling this: TODO Extensibility TODO GatewayClass GatewayClass ( source code ) is cluster-scoped resource defined by the infrastructure provider. This resource represents a class of Gateways that can be instantiated. Note: this serves the same function as the networking.IngressClass resource . kind: GatewayClass metadata: name: cluster-gateway spec: controller: \"acme.io/gateway-controller\" We expect that one or more GatewayClasses will be created by the infrastructure provider for the user. It allows decoupling of which mechanism (e.g. controller) implements the Gateways from the user. For instance, an infrastructure provider may create two GatewayClasses named internet and private to reflect Gateways that define Internet-facing vs private, internal applications. kind: GatewayClass metadata: name: internet ... --- kind: GatewayClass metadata: name: private ... The user of the classes will not need to know how internet and private are implemented. Instead, the user will only need to understand the resulting properties of the class that the Gateway was created with. GatewayClass parameters Providers of the Gateway API may need to pass parameters to their controller as part of the class definition. This is done using the GatewayClass.spec.parametersRef field: # GatewayClass for Gateways that define Internet-facing applications. kind: GatewayClass metadata: name: internet spec: controller: \"acme.io/gateway-controller\" parametersRef: name: internet-gateway --- kind: ConfigMap metadata: name: internet-gateway namespace: acme-system data: ip-address-pool: internet-vips ... Note: parametersRef will expect a ConfigMap as a referenced object if resource and group are omitted. The type of object referenced by GatewayClass.spec.parametersRef will depend on the provider itself. A core.ConfigMap is used in the example above, but controllers may opt to use a CustomResource for better schema validation. GatewayClass status GatewayClasses MUST be validated by the provider to ensure that the configured parameters are valid. The validity of the class will be signaled to the user via GatewayClass.status : kind: GatewayClass ... status: conditions: - type: InvalidParameters status: Unknown ... A new GatewayClass will start with the InvalidParameters condition set to Unknown . At this point the controller has not seen the configuration. Once the controller has processed the configuration, the condition will be set to False : kind: GatewayClass ... status: conditions: - type: InvalidParameters status: False ... If there is an error in the GatewayClass.spec , the conditions will be non-empty and contain information about the error. kind: GatewayClass ... status: conditions: - type: InvalidParameters status: True Reason: BadFooBar Message: \"foobar\" is an FooBar. Gateway A Gateway is 1:1 with the life cycle of the configuration of infrastructure. When a user creates a Gateway , some load balancing infrastructure is provisioned or configured (see below for details) by the GatewayClass controller. Gateway is the resource that triggers actions in this API. Other resources in this API are configuration snippets until a Gateway has been created to link the resources together. The Gateway spec defines the following: The GatewayClass used to instantiate this Gateway. The Listener bindings, which define addresses and ports, protocol termination, and TLS settings. The Listener configuration requested by a Gateway definition can be incompatible with a given GatewayClass (e.g. port/protocol combination is not supported). The Routes, which describe how traffic is processed and forwarded. If the Listener configuration requested by a Gateway definition is incompatible with a given GatewayClass, the Gateway will be in an error state, signaled by the status field. Deployment models Depending on the GatewayClass , the creation of the Gateway could do any of the following actions: Use cloud APIs to create an LB instance. Spawn a new instance of a software LB (in this or another cluster). Add a configuration stanza to an already instantiated LB to handle the new routes. Program the SDN to implement the configuration. Something else we haven\u2019t thought of yet... The API does not specify which one of these actions will be taken. Note that a GatewayClass controller that manages in-cluster proxy processes MAY restrict Gateway configuration scope, e.g. only be served in the same namespace. Gateway Status Gateways track status for the Gateway resource as a whole as well as each Listener it contains. The status for a specific Route is reported in the status of the Route resource. Within GatewayStatus , Listeners will have status entries corresponding to their name. Both GatewayStatus and ListenerStatus follow the conditions pattern used elsewhere in Kubernetes. This is a list that includes a type of condition, the status of that condition, and the last time this condition changed. Listeners TODO Routes TODO HTTPRoute TODO TCPRoute TODO Generic routing TODO Delegation/inclusion TODO Destinations TODO","title":"API concepts"},{"location":"concepts/#api-concepts","text":"This document is a deep dive into the reasoning and design for the API. The content of this document started from this API sketch .","title":"API Concepts"},{"location":"concepts/#roles-and-personas","text":"In the original design of Kubernetes, Ingress and Service resources were based on a self-service model of usage; developers who create Services and Ingresses control all aspects of defining and exposing their applications to their users. We have found that the self-service model does not fully capture some of the more complex deployment and team structures that our users are seeing. The Gateway/Routes API will target the following personas: Infrastructure provider : The infrastructure provider (infra) is responsible for the overall environment that the cluster(s) are operating in. Examples include public cloud providers (AWS, Azure, GCP, ...), or PaaS providers within an organization. Cluster operator : The cluster operator (ops) is responsible for administration of entire clusters. They manage policies, network access, and application permissions. Application developer : The application developer (dev) is responsible for defining their application configuration (e.g. timeouts, request matching/filter) and Service composition (e.g. path routing to backends). We expect that each persona will map approximately to a Role in the Kubernetes Role-Based Authentication (RBAC) system and will define resource model responsibility and separation. Depending on the environment, multiple roles can map to the same user. For example, giving the user all the above roles replicates the self-service model. For more information on the roles and personas considered in the Service API design, refer to the Security Model .","title":"Roles and personas"},{"location":"concepts/#resource-model","text":"Note: Resources will initially live in the networking.x-k8s.io API group as Custom Resource Definitions (CRDs). Unqualified resource names will implicitly be in this API group. There are three main types of objects in our resource model: GatewayClass defines a set of gateways with a common configuration and behavior. Gateway requests a point where traffic can be translated to Services within the cluster. Routes describe how traffic coming via the Gateway maps to the Services.","title":"Resource model"},{"location":"concepts/#gatewayclass","text":"GatewayClass defines a set of Gateways that share a common configuration and behaviour. Each GatewayClass will be handled by a single controller, although controllers MAY handle more than one. GatewayClass is a cluster-scoped resource. There MUST be at least one GatewayClass defined in order to be able to have functional Gateways. A controller that implements the Gateway API does so by providing an associated GatewayClass resource that the user can reference from their Gateway(s). This is similar to IngressClass for Ingress and StorageClass for PersistentVolumes. In Ingress v1beta1, the closest analog to GatewayClass is the ingress-class annotation, and in IngressV1, the closest analog is the IngressClass object.","title":"GatewayClass"},{"location":"concepts/#gateway","text":"A Gateway describes how traffic can be translated to Services within the cluster. That is, it defines a request for a way to translate traffic from somewhere that does not know about Kubernetes to somewhere that does. For example, traffic sent to a Kubernetes Services by a cloud load balancer, an in-cluster proxy or external hardware load balancer. While many use cases have client traffic originating \u201coutside\u201d the cluster, this is not a requirement. It defines a request for a specific load balancer config that implements the GatewayClass\u2019 configuration and behaviour contract. The resource MAY be created by an operator directly, or MAY be created by a controller handling a GatewayClass. As the Gateway spec captures user intent, it may not contain a complete specification for all attributes in the spec. For example, the user may omit fields such as addresses, ports, TLS settings. This allows the controller managing the GatewayClass to provide these settings for the user, resulting in a more portable spec. This behaviour will be made clear using the GatewayClass Status object. A Gateway MAY contain one or more *Route references which serve to direct traffic for a subset of traffic to a specific service.","title":"Gateway"},{"location":"concepts/#httptcpfooroute","text":"Route objects define protocol-specific rules for mapping requests from a Gateway to Kubernetes Services. HTTPRoute and TCPRoute are currently the only defined Route objects. Additional protocol-specific Route objects may be added in the future.","title":"{HTTP,TCP,Foo}Route"},{"location":"concepts/#combined-types","text":"The combination of GatewayClass , Gateway , xRoute and Service (s) will define an implementable load-balancer. The diagram below illustrates the relationships between the different resources:","title":"Combined types"},{"location":"concepts/#request-flow","text":"A typical client/gateway API request flow for a gateway implemented using a reverse proxy is: A client makes a request to http://foo.example.com. DNS resolves the name to gateway.status.listeners[x].address . The reverse proxy receives the request on gateway.status.listeners[x].address : gateway.spec.listeners[x].port and uses the Host header to match an HTTPRoute . Optionally, the reverse proxy can perform request header and/or path matching based on match rules of the HTTPRoute . Optionally, the reverse proxy can manipulate the request, i.e. add/remove headers, etc. based on filter rules of the HTTPRoute . Lastly, the reverse proxy forwards the request to one or more objects in the cluster based on action rules of the HTTPRoute . When specifying multiple forwardTo objects, the request is split, i.e. forwarded to each object.","title":"Request flow"},{"location":"concepts/#tls-configuration","text":"TLS configuration is tied to Gateway listeners. Although adding the option to configure TLS on other resources was considered, ultimately TLS configuration on Gateway listeners was deemed sufficient for the following reasons: In most cases, users that are configuring TLS will naturally also have access to Gateways. In other cases, TLS config could be implemented with a controller watching Routes and adding generated certs to corresponding Gateways. This does not solve the use case for users wanting to provide their own certs for Routes while not having access to a Gateway resource. This seems like it would be a rare edge case and is not worth supporting at this point. The security model outlined a potential approach to enable this in the future, but there does not seem to be a sufficient reason to work towards that now.","title":"TLS Configuration"},{"location":"concepts/#design-considerations","text":"There are some general design guidelines used throughout this API.","title":"Design considerations"},{"location":"concepts/#single-resource-consistency","text":"The Kubernetes API guarantees consistency only on a single resource level. There are a couple of consequences for complex resource graphs as opposed to single resources: Error checking of properties spanning multiple resource will be asynchronous and eventually consistent. Simple syntax checks will be possible at the single resource level, but cross resource dependencies will need to be handled by the controller. Controllers will need to handle broken links between resources and/or mismatched configuration.","title":"Single resource consistency"},{"location":"concepts/#conflicts","text":"Separation and delegation of responsibility among independent actors (e.g between cluster ops and application developers) can result in conflicts in the configuration. For example, two application teams may inadvertently submit configuration for the same HTTP path. There are several different strategies for handling this: TODO","title":"Conflicts"},{"location":"concepts/#extensibility","text":"TODO","title":"Extensibility"},{"location":"concepts/#gatewayclass_1","text":"GatewayClass ( source code ) is cluster-scoped resource defined by the infrastructure provider. This resource represents a class of Gateways that can be instantiated. Note: this serves the same function as the networking.IngressClass resource . kind: GatewayClass metadata: name: cluster-gateway spec: controller: \"acme.io/gateway-controller\" We expect that one or more GatewayClasses will be created by the infrastructure provider for the user. It allows decoupling of which mechanism (e.g. controller) implements the Gateways from the user. For instance, an infrastructure provider may create two GatewayClasses named internet and private to reflect Gateways that define Internet-facing vs private, internal applications. kind: GatewayClass metadata: name: internet ... --- kind: GatewayClass metadata: name: private ... The user of the classes will not need to know how internet and private are implemented. Instead, the user will only need to understand the resulting properties of the class that the Gateway was created with.","title":"GatewayClass"},{"location":"concepts/#gatewayclass-parameters","text":"Providers of the Gateway API may need to pass parameters to their controller as part of the class definition. This is done using the GatewayClass.spec.parametersRef field: # GatewayClass for Gateways that define Internet-facing applications. kind: GatewayClass metadata: name: internet spec: controller: \"acme.io/gateway-controller\" parametersRef: name: internet-gateway --- kind: ConfigMap metadata: name: internet-gateway namespace: acme-system data: ip-address-pool: internet-vips ... Note: parametersRef will expect a ConfigMap as a referenced object if resource and group are omitted. The type of object referenced by GatewayClass.spec.parametersRef will depend on the provider itself. A core.ConfigMap is used in the example above, but controllers may opt to use a CustomResource for better schema validation.","title":"GatewayClass parameters"},{"location":"concepts/#gatewayclass-status","text":"GatewayClasses MUST be validated by the provider to ensure that the configured parameters are valid. The validity of the class will be signaled to the user via GatewayClass.status : kind: GatewayClass ... status: conditions: - type: InvalidParameters status: Unknown ... A new GatewayClass will start with the InvalidParameters condition set to Unknown . At this point the controller has not seen the configuration. Once the controller has processed the configuration, the condition will be set to False : kind: GatewayClass ... status: conditions: - type: InvalidParameters status: False ... If there is an error in the GatewayClass.spec , the conditions will be non-empty and contain information about the error. kind: GatewayClass ... status: conditions: - type: InvalidParameters status: True Reason: BadFooBar Message: \"foobar\" is an FooBar.","title":"GatewayClass status"},{"location":"concepts/#gateway_1","text":"A Gateway is 1:1 with the life cycle of the configuration of infrastructure. When a user creates a Gateway , some load balancing infrastructure is provisioned or configured (see below for details) by the GatewayClass controller. Gateway is the resource that triggers actions in this API. Other resources in this API are configuration snippets until a Gateway has been created to link the resources together. The Gateway spec defines the following: The GatewayClass used to instantiate this Gateway. The Listener bindings, which define addresses and ports, protocol termination, and TLS settings. The Listener configuration requested by a Gateway definition can be incompatible with a given GatewayClass (e.g. port/protocol combination is not supported). The Routes, which describe how traffic is processed and forwarded. If the Listener configuration requested by a Gateway definition is incompatible with a given GatewayClass, the Gateway will be in an error state, signaled by the status field.","title":"Gateway"},{"location":"concepts/#deployment-models","text":"Depending on the GatewayClass , the creation of the Gateway could do any of the following actions: Use cloud APIs to create an LB instance. Spawn a new instance of a software LB (in this or another cluster). Add a configuration stanza to an already instantiated LB to handle the new routes. Program the SDN to implement the configuration. Something else we haven\u2019t thought of yet... The API does not specify which one of these actions will be taken. Note that a GatewayClass controller that manages in-cluster proxy processes MAY restrict Gateway configuration scope, e.g. only be served in the same namespace.","title":"Deployment models"},{"location":"concepts/#gateway-status","text":"Gateways track status for the Gateway resource as a whole as well as each Listener it contains. The status for a specific Route is reported in the status of the Route resource. Within GatewayStatus , Listeners will have status entries corresponding to their name. Both GatewayStatus and ListenerStatus follow the conditions pattern used elsewhere in Kubernetes. This is a list that includes a type of condition, the status of that condition, and the last time this condition changed.","title":"Gateway Status"},{"location":"concepts/#listeners","text":"TODO","title":"Listeners"},{"location":"concepts/#routes","text":"TODO","title":"Routes"},{"location":"concepts/#httproute","text":"TODO","title":"HTTPRoute"},{"location":"concepts/#tcproute","text":"TODO","title":"TCPRoute"},{"location":"concepts/#generic-routing","text":"TODO","title":"Generic routing"},{"location":"concepts/#delegationinclusion","text":"TODO","title":"Delegation/inclusion"},{"location":"concepts/#destinations","text":"TODO","title":"Destinations"},{"location":"cookbook/","text":"API Cookbook TODO: Cookbook will be a page w/ examples for common tasks (exposing an HTTP service, configuring TLS, etc).","title":"API cookbook"},{"location":"cookbook/#api-cookbook","text":"TODO: Cookbook will be a page w/ examples for common tasks (exposing an HTTP service, configuring TLS, etc).","title":"API Cookbook"},{"location":"devguide/","text":"Building, testing and deploying You will need to have Docker installed to perform the steps below. Project management We are using the Github issues and project dashboard to manage the list of TODOs for this project: Open issues Project dashboard Issues labeled good first issue and help wanted are especially good for a first contribution. Release cadence During the development phase, we expect to release on a monthly cadence. We are explicitly decoupling ourselves from the Kubernetes API versioning cycle to give us more flexibility to evolve the specification. As the specification solidifies, we will slow down our release cycle. General target timeline: 1H 2020: Monthly release cycle, with first release targeted for January 31 2H 2020: Slower release cycle Building the code The project uses make to drive the build. make will build the manager binary, run code generators, and run static analysis against the code. You can kick off an overall build from the top-level makefile: make Testing the code The easiest way to test the code is to use the kubebuilder created CRD with a kind cluster. Follow the installation instructions for kind in the README in the repo. kind create cluster ... # Install the CRDs make install # Remove the CRDs and associated CRs make uninstall Submitting a review TODO Verify Make sure you run the static analysis over the repo before submitting your changes. The Prow presubmit will not let your change merge if verification fails. make verify Documentation The site documentation is written in mkdocs format. The files are contained in docs-src/ . Generated files are in docs/ and published to Github Pages. Building the docs: make docs Live preview for editing (view on http://localhost:8000 , CTRL-C to quit): make serve Remove generated documentation files: make clean Publishing The docs are published automatically to Github pages . When making changes to the documentation, generate the new documentation and make the generated code a self-contained commit (e.g. the changes to docs/ ). This will keep the code reviews simple and clearly delineate user vs generated content.","title":"Developer guide"},{"location":"devguide/#building-testing-and-deploying","text":"You will need to have Docker installed to perform the steps below.","title":"Building, testing and deploying"},{"location":"devguide/#project-management","text":"We are using the Github issues and project dashboard to manage the list of TODOs for this project: Open issues Project dashboard Issues labeled good first issue and help wanted are especially good for a first contribution.","title":"Project management"},{"location":"devguide/#release-cadence","text":"During the development phase, we expect to release on a monthly cadence. We are explicitly decoupling ourselves from the Kubernetes API versioning cycle to give us more flexibility to evolve the specification. As the specification solidifies, we will slow down our release cycle. General target timeline: 1H 2020: Monthly release cycle, with first release targeted for January 31 2H 2020: Slower release cycle","title":"Release cadence"},{"location":"devguide/#building-the-code","text":"The project uses make to drive the build. make will build the manager binary, run code generators, and run static analysis against the code. You can kick off an overall build from the top-level makefile: make","title":"Building the code"},{"location":"devguide/#testing-the-code","text":"The easiest way to test the code is to use the kubebuilder created CRD with a kind cluster. Follow the installation instructions for kind in the README in the repo. kind create cluster ... # Install the CRDs make install # Remove the CRDs and associated CRs make uninstall","title":"Testing the code"},{"location":"devguide/#submitting-a-review","text":"TODO","title":"Submitting a review"},{"location":"devguide/#verify","text":"Make sure you run the static analysis over the repo before submitting your changes. The Prow presubmit will not let your change merge if verification fails. make verify","title":"Verify"},{"location":"devguide/#documentation","text":"The site documentation is written in mkdocs format. The files are contained in docs-src/ . Generated files are in docs/ and published to Github Pages. Building the docs: make docs Live preview for editing (view on http://localhost:8000 , CTRL-C to quit): make serve Remove generated documentation files: make clean","title":"Documentation"},{"location":"devguide/#publishing","text":"The docs are published automatically to Github pages . When making changes to the documentation, generate the new documentation and make the generated code a self-contained commit (e.g. the changes to docs/ ). This will keep the code reviews simple and clearly delineate user vs generated content.","title":"Publishing"},{"location":"enhancement-requests/","text":"Enhancement Tracking and Backlog Inspired by Kubernetes enhancements , service-api's provides a process for introducing new functionality or considerable changes to the project. The enhancement process will evolve over time as the project matures. Enhancements provides the basis of a community roadmap. Enhancements may be filed by anyone, but require approval from a maintainer to accept the enhancement into the project. Quick start Create an Issue and select \"Enhancement Request\". Follow the instructions in the enhancement request template and submit the Issue. What is Considered an Enhancement? An enhancement is generally anything that: impacts how a cluster is operated including addition or removal of significant capabilities introduces changes to an api needs significant effort to implement requires documentation to utilize It is unlikely to require an enhancement if it: fixes a bug adds more testing code refactors minimal impact to a release If you're unsure the proposed work requires an enhancement, file an issue and ask. When to Create a New Enhancement Create an enhancement once you have: circulated your idea to see if there is interest. identified community members who agree to work on and maintain the enhancement. enhancements may take several releases to complete. a prototype in your own fork (optional) Why are Enhancements Tracked As the project evolves, it's important that the service-api's community understands how the enhancement affects the project. Individually, it's hard to understand how all parts of the system interact, but as a community we can work together to build the right design and approach before getting too deep into an implementation. When to Comment on an Enhancement Issue Please comment on the enhancement issue to: - request a review or clarification on the process - update status of the enhancement effort - link to relevant issues in other repos","title":"Enhancement requests"},{"location":"enhancement-requests/#enhancement-tracking-and-backlog","text":"Inspired by Kubernetes enhancements , service-api's provides a process for introducing new functionality or considerable changes to the project. The enhancement process will evolve over time as the project matures. Enhancements provides the basis of a community roadmap. Enhancements may be filed by anyone, but require approval from a maintainer to accept the enhancement into the project.","title":"Enhancement Tracking and Backlog"},{"location":"enhancement-requests/#quick-start","text":"Create an Issue and select \"Enhancement Request\". Follow the instructions in the enhancement request template and submit the Issue.","title":"Quick start"},{"location":"enhancement-requests/#what-is-considered-an-enhancement","text":"An enhancement is generally anything that: impacts how a cluster is operated including addition or removal of significant capabilities introduces changes to an api needs significant effort to implement requires documentation to utilize It is unlikely to require an enhancement if it: fixes a bug adds more testing code refactors minimal impact to a release If you're unsure the proposed work requires an enhancement, file an issue and ask.","title":"What is Considered an Enhancement?"},{"location":"enhancement-requests/#when-to-create-a-new-enhancement","text":"Create an enhancement once you have: circulated your idea to see if there is interest. identified community members who agree to work on and maintain the enhancement. enhancements may take several releases to complete. a prototype in your own fork (optional)","title":"When to Create a New Enhancement"},{"location":"enhancement-requests/#why-are-enhancements-tracked","text":"As the project evolves, it's important that the service-api's community understands how the enhancement affects the project. Individually, it's hard to understand how all parts of the system interact, but as a community we can work together to build the right design and approach before getting too deep into an implementation.","title":"Why are Enhancements Tracked"},{"location":"enhancement-requests/#when-to-comment-on-an-enhancement-issue","text":"Please comment on the enhancement issue to: - request a review or clarification on the process - update status of the enhancement effort - link to relevant issues in other repos","title":"When to Comment on an Enhancement Issue"},{"location":"faq/","text":"Frequently Asked Questions (FAQ) Q: Will there be a default controller implementation (in this repo)? A: There is no current plan to have an \"official\" or \"default\" implementation. You will see the controller code in this repo be used for testing the support libraries.","title":"FAQ"},{"location":"faq/#frequently-asked-questions-faq","text":"Q: Will there be a default controller implementation (in this repo)? A: There is no current plan to have an \"official\" or \"default\" implementation. You will see the controller code in this repo be used for testing the support libraries.","title":"Frequently Asked Questions (FAQ)"},{"location":"feedback/","text":"Feedback and Bug Reports Feedback and bug reports should be filed as Github Issues on this repo. Be sure to use the following template: TODO","title":"Feedback"},{"location":"feedback/#feedback-and-bug-reports","text":"Feedback and bug reports should be filed as Github Issues on this repo. Be sure to use the following template: TODO","title":"Feedback and Bug Reports"},{"location":"releases/","text":"Releases Although Service APIs are an official Kubernetes project, and represent official APIs, these APIs will not be installed by default on Kubernetes clusters at this time. This project will use Custom Resource Definitions (CRDs) to represent the new API types that Service APIs include. Similar to other Kubernetes APIs, these will go through a formal Kubernetes Enhancement Proposal (KEP) review. Unlike other Kubernetes APIs, Service API releases will be independent from Kubernetes releases initially. Service API releases will include four components: * Custom Resource Definitions to define the API. * Go client libraries. * Validation webhooks to implement cross field validations. * Conversion webhooks to convert resources between API versions. Versioning Versioning will be completely separate from the Kubernetes release process, but similar methodology will be used. Service API versions will use the same version level requirements as other Kubernetes features . Service APIs are currently at the development stage of versioning described in the Kubernetes documentation above. An initial alpha release is currently planned for February 2020. A faster release cadence will be used for alpha versions, with new alpha releases monthly. Users and controller authors will be expected to use the latest version of the API. There will be little to no provisions for backwards compatibility for alpha versions. Generally we expect the alpha API to be for users and controller developers to test out the API but not in any production environment. Beta and stable releases will operate on a slower, more standard, release schedule. They will also provide all of the stability guarantees that other beta and stable Kubernetes features provide. Installation This project will be responsible for providing straightforward and reliable ways to install releases of Service APIs. Other Official Custom Resources This is a relatively new concept, and there is only one previous example of official custom resources being used: VolumeSnapshots . Although VolumeSnapshot CRDs can be installed directly by CSI drivers that support them, Service APIs must support multiple controllers per cluster, so the CRDs will live in and be installed from this repo.","title":"Releases"},{"location":"releases/#releases","text":"Although Service APIs are an official Kubernetes project, and represent official APIs, these APIs will not be installed by default on Kubernetes clusters at this time. This project will use Custom Resource Definitions (CRDs) to represent the new API types that Service APIs include. Similar to other Kubernetes APIs, these will go through a formal Kubernetes Enhancement Proposal (KEP) review. Unlike other Kubernetes APIs, Service API releases will be independent from Kubernetes releases initially. Service API releases will include four components: * Custom Resource Definitions to define the API. * Go client libraries. * Validation webhooks to implement cross field validations. * Conversion webhooks to convert resources between API versions.","title":"Releases"},{"location":"releases/#versioning","text":"Versioning will be completely separate from the Kubernetes release process, but similar methodology will be used. Service API versions will use the same version level requirements as other Kubernetes features . Service APIs are currently at the development stage of versioning described in the Kubernetes documentation above. An initial alpha release is currently planned for February 2020. A faster release cadence will be used for alpha versions, with new alpha releases monthly. Users and controller authors will be expected to use the latest version of the API. There will be little to no provisions for backwards compatibility for alpha versions. Generally we expect the alpha API to be for users and controller developers to test out the API but not in any production environment. Beta and stable releases will operate on a slower, more standard, release schedule. They will also provide all of the stability guarantees that other beta and stable Kubernetes features provide.","title":"Versioning"},{"location":"releases/#installation","text":"This project will be responsible for providing straightforward and reliable ways to install releases of Service APIs.","title":"Installation"},{"location":"releases/#other-official-custom-resources","text":"This is a relatively new concept, and there is only one previous example of official custom resources being used: VolumeSnapshots . Although VolumeSnapshot CRDs can be installed directly by CSI drivers that support them, Service APIs must support multiple controllers per cluster, so the CRDs will live in and be installed from this repo.","title":"Other Official Custom Resources"},{"location":"security-model/","text":"Security Model Introduction The Service APIs have been designed to enable granular authorization for each role in a typical organization. Resources The Service APIs have 4 primary API resources: GatewayClass defines a set of gateways with a common configuration and behavior. Gateway requests a point where traffic can be translated to Services within the cluster. Routes describe how traffic coming via the Gateway maps to the Services. TrafficSplits describe how traffic may be split from Routes. Additional Configuration There are two additional pieces of configuration that are important in this security model: Which namespaces can contain Gateways of the specified GatewayClass. Which namespaces Routes can be targeted in by Gateways of the specified GatewayClass. Roles For the purposes of this security model, 3 common roles have been identified: Infrastructure provider : The infrastructure provider (infra) is responsible for the overall environment that the cluster(s) are operating in. Examples include: the cloud provider (AWS, Azure, GCP, ...), the PaaS provider in a company. Cluster operator : The cluster operator (ops) is responsible for administration of entire clusters. They manage policies, network access, application permissions. Application developer : The application developer (dev) is responsible for defining their application configuration (e.g. timeouts, request matching/filter) and Service composition (e.g. path routing to backends). Although these roles can cover a wide variety of use cases, some organizations may be structured slightly differently. Many organizations may also have a fourth role that sits between \"cluster operator\" and \"application developer\": Application admin : The application admin has administrative access to some namespaces within a cluster, but not the cluster as a whole. The Security Model There are two primary components to the Service APIs security model: RBAC and namespace restrictions. RBAC RBAC (role-based access control) is the standard used for Kubernetes authorization. This allows users to configure who can perform actions on resources in specific scopes. RBAC can be used to enable each of the roles defined above. In most cases, it will be desirable to have all resources be readable by most roles, so instead we'll focus on write access for this model. Write Permissions for Simple 3 Tier Model GatewayClass Gateway Route TrafficSplit Infrastructure Provider Yes Yes Yes Yes Cluster Operators No Yes Yes Yes Application Developers No No Yes Yes Write Permissions for Advanced 4 Tier Model GatewayClass Gateway Route TrafficSplit Infrastructure Provider Yes Yes Yes Yes Cluster Operators Sometimes Yes Yes Yes Application Admins No In Specified Namespaces In Specified Namespaces In Specified Namespaces Application Developers No No In Specified Namespaces In Specified Namespaces Namespace Restrictions The extra configuration options are not possible to control with RBAC. Instead, they will be controlled with configuration fields on GatewayClasses: allowedGatewayNamespaces : This field is a selector of namespaces that Gateways can use this GatewayClass from. This is a standard Kubernetes LabelSelector, a label query over a set of resources. The result of matchLabels and matchExpressions are ANDed. Controllers must not support Gateways in namespaces outside this selector. An empty selector (default) indicates that Gateways can use this GatewayClass from any namespace. This field is intentionally not a pointer because the nil behavior (no namespaces) is undesirable here. allowedRouteNamespaces : This field is a selector of namespaces that Gateways of this class can reference Routes in. This is a standard Kubernetes LabelSelector, a label query over a set of resources. The result of matchLabels and matchExpressions are ANDed. Controllers must not support Routes in namespaces outside this selector. A nil selector (default) indicates that Gateways of this class can reference Routes within the same namespace. An empty selector indicates that Gateways can reference Routes in any namespace. This field is intentionally a pointer to support the nil behavior (only local Routes allowed). Controller Requirements To be considered conformant with the Service APIs spec, controllers need to: Populate status fields on Gateways and Resources to indicate if they are compatible with the corresponding GatewayClass configuration. Not implement invalid configuration. Fore example, if a route is referenced in an invalid namespace for the GatewayClass, it should be ignored. Respond to changes in GatewayClass configuration that may change which Gateways or Routes are valid. Alternative Approaches Considered New API Resources We considered introducing new API resources to cover these use cases. These resources might be look something like: ClusterGateway : A ClusterGateway could reference routes in any namespace. ClusterRoute : A ClusterRoute could be referenced by any Gateway or ClusterGateway. Benefits Easy to model with RBAC. API validation tied directly to each resource. Downsides New resources to deal with - more informers, clients, documentation, etc. Harder to expand with additional options in the future - may just end up with tons of API resources to cover all use cases. Boolean Multi Namespace Route Indicator on GatewayClass Instead of having the routeNamespaceSelector field on GatewayClass, we would use a boolean multiNamespaceRoutes field to indicate if Gateways of this class can target routes in multiple namespaces. This would default to false. A false value here would indicate that routes could only be targeted in the current namespace. Benefits Helpful for multi-tenant use cases with many isolated Gateways. Simple configuration with an easy to understand default value. Downsides GatewayClass admins are unable to partially limit namespaces that can be targeted by Gateways. Admins would have to choose between allowing access to Routes in all namespaces or only the local one. Validating Webhook A validating webhook could potentially handle some of the cross-resource validation necessary for this security model and provide more immediate feedback to end users. Benefits Immediate validation feedback. More validation logic stays in core Service APIs codebase. Downsides Imperfect solution for cross-resource validation. For example, a change to a GatewayClass could affect the validity of corresponding Gateway. Additional complexity involved in installing Service APIs in a cluster.","title":"Security Model"},{"location":"security-model/#security-model","text":"","title":"Security Model"},{"location":"security-model/#introduction","text":"The Service APIs have been designed to enable granular authorization for each role in a typical organization.","title":"Introduction"},{"location":"security-model/#resources","text":"The Service APIs have 4 primary API resources: GatewayClass defines a set of gateways with a common configuration and behavior. Gateway requests a point where traffic can be translated to Services within the cluster. Routes describe how traffic coming via the Gateway maps to the Services. TrafficSplits describe how traffic may be split from Routes.","title":"Resources"},{"location":"security-model/#additional-configuration","text":"There are two additional pieces of configuration that are important in this security model: Which namespaces can contain Gateways of the specified GatewayClass. Which namespaces Routes can be targeted in by Gateways of the specified GatewayClass.","title":"Additional Configuration"},{"location":"security-model/#roles","text":"For the purposes of this security model, 3 common roles have been identified: Infrastructure provider : The infrastructure provider (infra) is responsible for the overall environment that the cluster(s) are operating in. Examples include: the cloud provider (AWS, Azure, GCP, ...), the PaaS provider in a company. Cluster operator : The cluster operator (ops) is responsible for administration of entire clusters. They manage policies, network access, application permissions. Application developer : The application developer (dev) is responsible for defining their application configuration (e.g. timeouts, request matching/filter) and Service composition (e.g. path routing to backends). Although these roles can cover a wide variety of use cases, some organizations may be structured slightly differently. Many organizations may also have a fourth role that sits between \"cluster operator\" and \"application developer\": Application admin : The application admin has administrative access to some namespaces within a cluster, but not the cluster as a whole.","title":"Roles"},{"location":"security-model/#the-security-model","text":"There are two primary components to the Service APIs security model: RBAC and namespace restrictions.","title":"The Security Model"},{"location":"security-model/#rbac","text":"RBAC (role-based access control) is the standard used for Kubernetes authorization. This allows users to configure who can perform actions on resources in specific scopes. RBAC can be used to enable each of the roles defined above. In most cases, it will be desirable to have all resources be readable by most roles, so instead we'll focus on write access for this model.","title":"RBAC"},{"location":"security-model/#write-permissions-for-simple-3-tier-model","text":"GatewayClass Gateway Route TrafficSplit Infrastructure Provider Yes Yes Yes Yes Cluster Operators No Yes Yes Yes Application Developers No No Yes Yes","title":"Write Permissions for Simple 3 Tier Model"},{"location":"security-model/#write-permissions-for-advanced-4-tier-model","text":"GatewayClass Gateway Route TrafficSplit Infrastructure Provider Yes Yes Yes Yes Cluster Operators Sometimes Yes Yes Yes Application Admins No In Specified Namespaces In Specified Namespaces In Specified Namespaces Application Developers No No In Specified Namespaces In Specified Namespaces","title":"Write Permissions for Advanced 4 Tier Model"},{"location":"security-model/#namespace-restrictions","text":"The extra configuration options are not possible to control with RBAC. Instead, they will be controlled with configuration fields on GatewayClasses: allowedGatewayNamespaces : This field is a selector of namespaces that Gateways can use this GatewayClass from. This is a standard Kubernetes LabelSelector, a label query over a set of resources. The result of matchLabels and matchExpressions are ANDed. Controllers must not support Gateways in namespaces outside this selector. An empty selector (default) indicates that Gateways can use this GatewayClass from any namespace. This field is intentionally not a pointer because the nil behavior (no namespaces) is undesirable here. allowedRouteNamespaces : This field is a selector of namespaces that Gateways of this class can reference Routes in. This is a standard Kubernetes LabelSelector, a label query over a set of resources. The result of matchLabels and matchExpressions are ANDed. Controllers must not support Routes in namespaces outside this selector. A nil selector (default) indicates that Gateways of this class can reference Routes within the same namespace. An empty selector indicates that Gateways can reference Routes in any namespace. This field is intentionally a pointer to support the nil behavior (only local Routes allowed).","title":"Namespace Restrictions"},{"location":"security-model/#controller-requirements","text":"To be considered conformant with the Service APIs spec, controllers need to: Populate status fields on Gateways and Resources to indicate if they are compatible with the corresponding GatewayClass configuration. Not implement invalid configuration. Fore example, if a route is referenced in an invalid namespace for the GatewayClass, it should be ignored. Respond to changes in GatewayClass configuration that may change which Gateways or Routes are valid.","title":"Controller Requirements"},{"location":"security-model/#alternative-approaches-considered","text":"","title":"Alternative Approaches Considered"},{"location":"security-model/#new-api-resources","text":"We considered introducing new API resources to cover these use cases. These resources might be look something like: ClusterGateway : A ClusterGateway could reference routes in any namespace. ClusterRoute : A ClusterRoute could be referenced by any Gateway or ClusterGateway. Benefits Easy to model with RBAC. API validation tied directly to each resource. Downsides New resources to deal with - more informers, clients, documentation, etc. Harder to expand with additional options in the future - may just end up with tons of API resources to cover all use cases.","title":"New API Resources"},{"location":"security-model/#boolean-multi-namespace-route-indicator-on-gatewayclass","text":"Instead of having the routeNamespaceSelector field on GatewayClass, we would use a boolean multiNamespaceRoutes field to indicate if Gateways of this class can target routes in multiple namespaces. This would default to false. A false value here would indicate that routes could only be targeted in the current namespace. Benefits Helpful for multi-tenant use cases with many isolated Gateways. Simple configuration with an easy to understand default value. Downsides GatewayClass admins are unable to partially limit namespaces that can be targeted by Gateways. Admins would have to choose between allowing access to Routes in all namespaces or only the local one.","title":"Boolean Multi Namespace Route Indicator on GatewayClass"},{"location":"security-model/#validating-webhook","text":"A validating webhook could potentially handle some of the cross-resource validation necessary for this security model and provide more immediate feedback to end users. Benefits Immediate validation feedback. More validation logic stays in core Service APIs codebase. Downsides Imperfect solution for cross-resource validation. For example, a change to a GatewayClass could affect the validity of corresponding Gateway. Additional complexity involved in installing Service APIs in a cluster.","title":"Validating Webhook"},{"location":"spec/","text":"Packages: networking.x-k8s.io/v1alpha1 networking.x-k8s.io/v1alpha1 Package v1alpha1 contains API Schema definitions for the networking v1alpha1 API group Resource Types: Gateway GatewayClass TcpRoute TrafficSplit Gateway Gateway represents an instantiation of a service-traffic handling infrastructure. Field Description apiVersion string networking.x-k8s.io/v1alpha1 kind string Gateway metadata Kubernetes meta/v1.ObjectMeta Refer to the Kubernetes API documentation for the fields of the metadata field. spec GatewaySpec class string Class used for this Gateway. This is the name of a GatewayClass resource. listeners []Listener Listeners associated with this Gateway. Listeners define what addresses, ports, protocols are bound on this Gateway. routes RouteBindingSelector Routes specifies a schema for associating routes with the Gateway using selectors. A route is a resource capable of servicing a request and allows a cluster operator to expose a cluster resource (i.e. Service) by externally-reachable URL, load-balance traffic and terminate SSL/TLS. Typically, a route is a \u201chttproute\u201d or \u201ctcproute\u201d in group \u201cnetworking.x-k8s.io\u201d. However, an implementation may support other resources. Support: Core status GatewayStatus GatewayClass GatewayClass describes a class of Gateways available to the user for creating Gateway resources. GatewayClass is a Cluster level resource. Support: Core. Field Description apiVersion string networking.x-k8s.io/v1alpha1 kind string GatewayClass metadata Kubernetes meta/v1.ObjectMeta Refer to the Kubernetes API documentation for the fields of the metadata field. spec GatewayClassSpec Spec for this GatewayClass. controller string Controller is a domain/path string that indicates the controller that managing Gateways of this class. Example: \u201cacme.io/gateway-controller\u201d. This field is not mutable and cannot be empty. The format of this field is DOMAIN \u201c/\u201d PATH, where DOMAIN and PATH are valid Kubernetes names ( https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names ). Support: Core allowedGatewayNamespaces Kubernetes meta/v1.LabelSelector (Optional) AllowedGatewayNamespaces is a selector of namespaces that Gateways can use this GatewayClass from. This is a standard Kubernetes LabelSelector, a label query over a set of resources. The result of matchLabels and matchExpressions are ANDed. Controllers must not support Gateways in namespaces outside this selector. An empty selector (default) indicates that Gateways can use this GatewayClass from any namespace. This field is intentionally not a pointer because the nil behavior (no namespaces) is undesirable here. Support: Core allowedRouteNamespaces Kubernetes meta/v1.LabelSelector (Optional) AllowedRouteNamespaces is a selector of namespaces that Gateways of this class can reference Routes in. This is a standard Kubernetes LabelSelector, a label query over a set of resources. The result of matchLabels and matchExpressions are ANDed. Controllers must not support Routes in namespaces outside this selector. A nil selector (default) indicates that Gateways of this class can reference Routes within the same namespace. An empty selector indicates that Gateways can reference Routes in any namespace. This field is intentionally a pointer to support the nil behavior (only local Routes allowed). Support: Core parametersRef ConfigMapsDefaultLocalObjectReference (Optional) ParametersRef is a controller specific resource containing the configuration parameters corresponding to this class. This is optional if the controller does not require any additional configuration. Valid resources for reference are up to the Controller. Examples include \u201cconfigmaps\u201d (omit or specify the empty string for the group to indicate the core API group) or a custom resource (CRD). Omitting or specifying the empty string for both the resource and group indicates that the resource is \u201cconfigmaps\u201d. If the referent cannot be found, the GatewayClass\u2019s \u201cInvalidParameters\u201d status condition will be true. Support: Custom status GatewayClassStatus Status of the GatewayClass. TcpRoute TcpRoute is the Schema for the tcproutes API Field Description apiVersion string networking.x-k8s.io/v1alpha1 kind string TcpRoute metadata Kubernetes meta/v1.ObjectMeta Refer to the Kubernetes API documentation for the fields of the metadata field. spec TcpRouteSpec status TcpRouteStatus TrafficSplit TrafficSplit is the Schema for the trafficsplits API Field Description apiVersion string networking.x-k8s.io/v1alpha1 kind string TrafficSplit metadata Kubernetes meta/v1.ObjectMeta Refer to the Kubernetes API documentation for the fields of the metadata field. spec TrafficSplitSpec status TrafficSplitStatus AddressType ( string alias) ( Appears on: ListenerAddress ) AddressType defines how a network address is represented as a text string. ConfigMapsDefaultLocalObjectReference ( Appears on: GatewayClassSpec , HTTPRouteAction , HTTPRouteFilter , HTTPRouteHost , HTTPRouteMatch , Listener ) RouteMatchExtensionObjectReference identifies a route-match extension object within a known namespace. Field Description group string Group is the group of the referent. Omitting the value or specifying the empty string indicates the core API group. For example, use the following to specify a configmaps: fooRef: resource: configmaps name: myconfigmap Otherwise, if the core API group is not desired, specify the desired group: fooRef: group: acme.io resource: foos name: myfoo resource string Resource is the API resource name of the referent. Omitting the value or specifying the empty string indicates the configmaps resource. For example, use the following to specify a configmaps resource: fooRef: name: myconfigmap Otherwise, if the configmaps resource is not desired, specify the desired group: fooRef: group: acme.io resource: foos name: myfoo name string Name is the name of the referent. ForwardToTarget ( Appears on: HTTPRouteAction ) ForwardToTarget identifies a target object within a known namespace. Field Description targetRef ServicesDefaultLocalObjectReference TargetRef is an object reference to forward matched requests to. Support: Core (Kubernetes Services) Support: Implementation-specific (Other resource types) targetPort TargetPort (Optional) TargetPort specifies the destination port number to use for the TargetRef. If unspecified and TargetRef is a Service object consisting of a single port definition, that port will be used. If unspecified and TargetRef is a Service object consisting of multiple port definitions, an error is surfaced in status. Support: Core GatewayClassCondition ( Appears on: GatewayClassStatus ) GatewayClassCondition contains the details for the current condition of this GatewayClass. Support: Core, unless otherwise specified. Field Description type GatewayClassConditionType Type of this condition. status Kubernetes core/v1.ConditionStatus Status of this condition. reason string Reason is a machine consumable string for the last transition. It should be a one-word, CamelCase string. Reason will be defined by the controller. Support: Custom; values will be controller-specific. This field must not be empty. message string Message is a human readable reason for last transition. This field may be empty. lastTransitionTime Kubernetes meta/v1.Time LastTransitionTime is the time of the last change to this condition. GatewayClassConditionType ( string alias) ( Appears on: GatewayClassCondition ) GatewayClassConditionType is the type of status conditions. GatewayClassSpec ( Appears on: GatewayClass ) GatewayClassSpec reflects the configuration of a class of Gateways. Field Description controller string Controller is a domain/path string that indicates the controller that managing Gateways of this class. Example: \u201cacme.io/gateway-controller\u201d. This field is not mutable and cannot be empty. The format of this field is DOMAIN \u201c/\u201d PATH, where DOMAIN and PATH are valid Kubernetes names ( https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names ). Support: Core allowedGatewayNamespaces Kubernetes meta/v1.LabelSelector (Optional) AllowedGatewayNamespaces is a selector of namespaces that Gateways can use this GatewayClass from. This is a standard Kubernetes LabelSelector, a label query over a set of resources. The result of matchLabels and matchExpressions are ANDed. Controllers must not support Gateways in namespaces outside this selector. An empty selector (default) indicates that Gateways can use this GatewayClass from any namespace. This field is intentionally not a pointer because the nil behavior (no namespaces) is undesirable here. Support: Core allowedRouteNamespaces Kubernetes meta/v1.LabelSelector (Optional) AllowedRouteNamespaces is a selector of namespaces that Gateways of this class can reference Routes in. This is a standard Kubernetes LabelSelector, a label query over a set of resources. The result of matchLabels and matchExpressions are ANDed. Controllers must not support Routes in namespaces outside this selector. A nil selector (default) indicates that Gateways of this class can reference Routes within the same namespace. An empty selector indicates that Gateways can reference Routes in any namespace. This field is intentionally a pointer to support the nil behavior (only local Routes allowed). Support: Core parametersRef ConfigMapsDefaultLocalObjectReference (Optional) ParametersRef is a controller specific resource containing the configuration parameters corresponding to this class. This is optional if the controller does not require any additional configuration. Valid resources for reference are up to the Controller. Examples include \u201cconfigmaps\u201d (omit or specify the empty string for the group to indicate the core API group) or a custom resource (CRD). Omitting or specifying the empty string for both the resource and group indicates that the resource is \u201cconfigmaps\u201d. If the referent cannot be found, the GatewayClass\u2019s \u201cInvalidParameters\u201d status condition will be true. Support: Custom GatewayClassStatus ( Appears on: GatewayClass ) GatewayClassStatus is the current status for the GatewayClass. Field Description conditions []GatewayClassCondition (Optional) Conditions is the current status from the controller for this GatewayClass. GatewayCondition ( Appears on: GatewayStatus ) GatewayCondition is an error status for a given route. Field Description type GatewayConditionType Type indicates the type of condition. status Kubernetes core/v1.ConditionStatus Status describes the current state of this condition. Can be \u201cTrue\u201d, \u201cFalse\u201d, or \u201cUnknown\u201d. message string Message is a human-understandable message describing the condition. This field may be empty. reason string Reason indicates why the condition is in this state. This field must not be empty. lastTransitionTime Kubernetes meta/v1.Time LastTransitionTime indicates the last time this condition changed. GatewayConditionType ( string alias) ( Appears on: GatewayCondition ) GatewayConditionType is a type of condition associated with a Gateway. GatewayObjectReference ( Appears on: HTTPRouteStatus ) GatewayObjectReference identifies a Gateway object. Field Description namespace string (Optional) Namespace is the namespace of the referent. name string Name is the name of the referent. GatewaySpec ( Appears on: Gateway ) GatewaySpec defines the desired state of Gateway. The Spec is split into two major pieces: listeners describing client-facing properties and routes that describe application-level routing. Not all possible combinations of options specified in the Spec are valid. Some invalid configurations can be caught synchronously via a webhook, but there are many cases that will require asynchronous signaling via the GatewayStatus block. Field Description class string Class used for this Gateway. This is the name of a GatewayClass resource. listeners []Listener Listeners associated with this Gateway. Listeners define what addresses, ports, protocols are bound on this Gateway. routes RouteBindingSelector Routes specifies a schema for associating routes with the Gateway using selectors. A route is a resource capable of servicing a request and allows a cluster operator to expose a cluster resource (i.e. Service) by externally-reachable URL, load-balance traffic and terminate SSL/TLS. Typically, a route is a \u201chttproute\u201d or \u201ctcproute\u201d in group \u201cnetworking.x-k8s.io\u201d. However, an implementation may support other resources. Support: Core GatewayStatus ( Appears on: Gateway ) GatewayStatus defines the observed state of Gateway. Field Description conditions []GatewayCondition (Optional) Conditions describe the current conditions of the Gateway. listeners []ListenerStatus (Optional) Listeners provide status for each listener defined in the Spec. The name in ListenerStatus refers to the corresponding Listener of the same name. HTTPHeaderFilter ( Appears on: HTTPRouteFilter ) HTTPHeaderFilter defines the filter behavior for a request match. Field Description add map[string]string Add adds the given header (name, value) to the request before the action. Input: GET /foo HTTP/1.1 Config: add: {\u201cmy-header\u201d: \u201cfoo\u201d} Output: GET /foo HTTP/1.1 my-header: foo Support: extended? remove []string Remove the given header(s) on the HTTP request before the action. The value of RemoveHeader is a list of HTTP header names. Note that the header names are case-insensitive [RFC-2616 4.2]. Input: GET /foo HTTP/1.1 My-Header1: ABC My-Header2: DEF My-Header2: GHI Config: remove: [\u201cmy-header1\u201d, \u201cmy-header3\u201d] Output: GET /foo HTTP/1.1 My-Header2: DEF Support: extended? HTTPRoute HTTPRoute is the Schema for the httproutes API Field Description metadata Kubernetes meta/v1.ObjectMeta Refer to the Kubernetes API documentation for the fields of the metadata field. spec HTTPRouteSpec hosts []HTTPRouteHost Hosts is a list of Host definitions. default HTTPRouteHost (Optional) Default is the default host to use. Default.Hostnames must be an empty list. status HTTPRouteStatus HTTPRouteAction ( Appears on: HTTPRouteRule ) HTTPRouteAction is the action taken given a match. Field Description forwardTo ForwardToTarget ForwardTo sends requests to the referenced object. The resource may be \u201cservices\u201d (omit or use the empty string for the group), or an implementation may support other resources (for example, resource \u201cmyroutetargets\u201d in group \u201cnetworking.acme.io\u201d). Omitting or specifying the empty string for both the resource and group indicates that the resource is \u201cservices\u201d. If the referent cannot be found, the \u201cInvalidRoutes\u201d status condition on any Gateway that includes the HTTPRoute will be true. extensionRef ConfigMapsDefaultLocalObjectReference (Optional) ExtensionRef is an optional, implementation-specific extension to the \u201caction\u201d behavior. The resource may be \u201cconfigmaps\u201d (use the empty string for the group) or an implementation-defined resource (for example, resource \u201cmyrouteactions\u201d in group \u201cnetworking.acme.io\u201d). Omitting or specifying the empty string for both the resource and group indicates that the resource is \u201cconfigmaps\u201d. If the referent cannot be found, the \u201cInvalidRoutes\u201d status condition on any Gateway that includes the HTTPRoute will be true. Support: custom HTTPRouteFilter ( Appears on: HTTPRouteRule ) HTTPRouteFilter defines a filter-like action to be applied to requests. Field Description headers HTTPHeaderFilter (Optional) Headers related filters. Support: extended extensionRef ConfigMapsDefaultLocalObjectReference (Optional) ExtensionRef is an optional, implementation-specific extension to the \u201cfilter\u201d behavior. The resource may be \u201cconfigmap\u201d (use the empty string for the group) or an implementation-defined resource (for example, resource \u201cmyroutefilters\u201d in group \u201cnetworking.acme.io\u201d). Omitting or specifying the empty string for both the resource and group indicates that the resource is \u201cconfigmaps\u201d. If the referent cannot be found, the \u201cInvalidRoutes\u201d status condition on any Gateway that includes the HTTPRoute will be true. Support: custom HTTPRouteHost ( Appears on: HTTPRouteSpec ) HTTPRouteHost is the configuration for a given host. Field Description hostname string (Optional) Hostname is the fully qualified domain name of a network host, as defined by RFC 3986. Note the following deviations from the \u201chost\u201d part of the URI as defined in the RFC: IPs are not allowed. The : delimiter is not respected because ports are not allowed. Incoming requests are matched against Hostname before processing HTTPRoute rules. For example, if the request header contains host: foo.example.com, an HTTPRoute with hostname foo.example.com will match. However, an HTTPRoute with hostname example.com or bar.example.com will not match. If Hostname is unspecified, the Gateway routes all traffic based on the specified rules. Support: Core rules []HTTPRouteRule Rules are a list of HTTP matchers, filters and actions. extensionRef ConfigMapsDefaultLocalObjectReference (Optional) ExtensionRef is an optional, implementation-specific extension to the \u201chost\u201d block. The resource may be \u201cconfigmaps\u201d (omit or specify the empty string for the group) or an implementation-defined resource (for example, resource \u201cmyroutehosts\u201d in group \u201cnetworking.acme.io\u201d). Omitting or specifying the empty string for both the resource and group indicates that the resource is \u201cconfigmaps\u201d. If the referent cannot be found, the \u201cInvalidRoutes\u201d status condition on any Gateway that includes the HTTPRoute will be true. Support: custom HTTPRouteMatch ( Appears on: HTTPRouteRule ) HTTPRouteMatch defines the predicate used to match requests to a given action. Field Description pathType string (Optional) PathType is defines the semantics of the Path matcher. Support: core (Exact, Prefix) Support: extended (RegularExpression) Support: custom (ImplementationSpecific) Default: \u201cExact\u201d path string Path is the value of the HTTP path as interpreted via PathType. Default: \u201c/\u201d headerType string (Optional) HeaderType defines the semantics of the Header matcher. header map[string]string (Optional) Header are the Header matches as interpreted via HeaderType. extensionRef ConfigMapsDefaultLocalObjectReference (Optional) ExtensionRef is an optional, implementation-specific extension to the \u201cmatch\u201d behavior. The resource may be \u201cconfigmap\u201d (use the empty string for the group) or an implementation-defined resource (for example, resource \u201cmyroutematchers\u201d in group \u201cnetworking.acme.io\u201d). Omitting or specifying the empty string for both the resource and group indicates that the resource is \u201cconfigmaps\u201d. If the referent cannot be found, the \u201cInvalidRoutes\u201d status condition on any Gateway that includes the HTTPRoute will be true. Support: custom HTTPRouteRule ( Appears on: HTTPRouteHost ) HTTPRouteRule is the configuration for a given path. Field Description match HTTPRouteMatch (Optional) Match defines which requests match this path. filter HTTPRouteFilter (Optional) Filter defines what filters are applied to the request. action HTTPRouteAction (Optional) Action defines what happens to the request. HTTPRouteSpec ( Appears on: HTTPRoute ) HTTPRouteSpec defines the desired state of HTTPRoute Field Description hosts []HTTPRouteHost Hosts is a list of Host definitions. default HTTPRouteHost (Optional) Default is the default host to use. Default.Hostnames must be an empty list. HTTPRouteStatus ( Appears on: HTTPRoute ) HTTPRouteStatus defines the observed state of HTTPRoute. Field Description gatewayRefs []GatewayObjectReference Listener ( Appears on: GatewaySpec ) Listener defines a Field Description name string Name is the listener\u2019s name and should be specified as an RFC 1035 DNS_LABEL [1]: [1] https://tools.ietf.org/html/rfc1035 Each listener of a Gateway must have a unique name. Name is used for associating a listener in Gateway status. Support: Core address ListenerAddress (Optional) Address requested for this listener. This is optional and behavior can depend on GatewayClass. If a value is set in the spec and the request address is invalid, the GatewayClass MUST indicate this in the associated entry in GatewayStatus.Listeners. Support: port int32 (Optional) Port is a list of ports associated with the Address. Support: protocol string (Optional) Protocol to use. Support: tls TLSConfig (Optional) TLS is the TLS configuration for the Listener. If unspecified, the listener will not support TLS connections. Support: Core extensionRef ConfigMapsDefaultLocalObjectReference (Optional) ExtensionRef for this Listener. The resource may be \u201cconfigmaps\u201d or an implementation-defined resource (for example, resource \u201cmylisteners\u201d in group \u201cnetworking.acme.io\u201d). Omitting or specifying the empty string for both the resource and group indicates that the resource is \u201cconfigmaps\u201d. If the referent cannot be found, the listener\u2019s \u201cInvalidListener\u201d status condition will be true. Support: custom. ListenerAddress ( Appears on: Listener , ListenerStatus ) ListenerAddress describes an address for the Listener. Field Description type AddressType Type of the Address. This is one of the AddressType constants. Support: Extended value string Value. Examples: \u201c1.2.3.4\u201d, \u201c128::1\u201d, \u201cmy-ip-address\u201d. Validity of the values will depend on Type and support by the controller. ListenerCondition ( Appears on: ListenerStatus ) ListenerCondition is an error status for a given listener. Field Description type ListenerConditionType Type indicates the type of condition. status Kubernetes core/v1.ConditionStatus Status describes the current state of this condition. Can be \u201cTrue\u201d, \u201cFalse\u201d, or \u201cUnknown\u201d. message string Message is a human-understandable message describing the condition. This field may be empty. reason string Reason indicates why the condition is in this state. This field must not be empty. lastTransitionTime Kubernetes meta/v1.Time LastTransitionTime indicates the last time this condition changed. ListenerConditionType ( string alias) ( Appears on: ListenerCondition ) ListenerConditionType is a type of condition associated with the listener. ListenerStatus ( Appears on: GatewayStatus ) ListenerStatus is the status associated with each listener block. Field Description name string Name is the name of the listener this status refers to. address ListenerAddress Address bound on this listener. conditions []ListenerCondition Conditions describe the current condition of this listener. RouteBindingSelector ( Appears on: GatewaySpec ) RouteBindingSelector defines a schema for associating routes with the Gateway. If NamespaceSelector and RouteSelector are defined, only routes matching both selectors are associated with the Gateway. Field Description namespaceSelector Kubernetes meta/v1.LabelSelector NamespaceSelector specifies a set of namespace labels used for selecting routes to associate with the Gateway. If NamespaceSelector is defined, all routes in namespaces matching the NamespaceSelector are associated to the Gateway. An empty NamespaceSelector (default) indicates that routes from any namespace will be associated to this Gateway. This field is intentionally not a pointer because the nil behavior (no namespaces) is undesirable here. Support: Core routeSelector Kubernetes meta/v1.LabelSelector (Optional) RouteSelector specifies a set of route labels used for selecting routes to associate with the Gateway. If RouteSelector is defined, only routes matching the RouteSelector are associated with the Gateway. An empty RouteSelector matches all routes. If undefined, route labels are not used for associating routes to the gateway. Support: Core SecretsDefaultLocalObjectReference ( Appears on: TLSConfig ) SecretsDefaultLocalObjectReference identifies an API object within a known namespace that defaults group to core and resource to secrets if unspecified. Field Description group string Group is the group of the referent. Omitting the value or specifying the empty string indicates the core API group. For example, use the following to specify a secrets resource: fooRef: resource: secrets name: mysecret Otherwise, if the core API group is not desired, specify the desired group: fooRef: group: acme.io resource: foos name: myfoo resource string Resource is the API resource name of the referent. Omitting the value or specifying the empty string indicates the secrets resource. For example, use the following to specify a secrets resource: fooRef: name: mysecret Otherwise, if the secrets resource is not desired, specify the desired group: fooRef: group: acme.io resource: foos name: myfoo name string Name is the name of the referent. ServicesDefaultLocalObjectReference ( Appears on: ForwardToTarget ) ServicesDefaultLocalObjectReference identifies an API object within a known namespace that defaults group to core and resource to services if unspecified. Field Description group string Group is the group of the referent. Omitting the value or specifying the empty string indicates the core API group. For example, use the following to specify a service: fooRef: resource: services name: myservice Otherwise, if the core API group is not desired, specify the desired group: fooRef: group: acme.io resource: foos name: myfoo resource string Resource is the API resource name of the referent. Omitting the value or specifying the empty string indicates the services resource. For example, use the following to specify a services resource: fooRef: name: myservice Otherwise, if the services resource is not desired, specify the desired group: fooRef: group: acme.io resource: foos name: myfoo name string Name is the name of the referent. TLSConfig ( Appears on: Listener ) TLSConfig describes a TLS configuration. References - nginx: https://nginx.org/en/docs/http/configuring_https_servers.html - envoy: https://www.envoyproxy.io/docs/envoy/latest/api-v2/api/v2/auth/cert.proto - haproxy: https://www.haproxy.com/documentation/aloha/9-5/traffic-management/lb-layer7/tls/ - gcp: https://cloud.google.com/load-balancing/docs/use-ssl-policies#creating_an_ssl_policy_with_a_custom_profile - aws: https://docs.aws.amazon.com/elasticloadbalancing/latest/application/create-https-listener.html#describe-ssl-policies - azure: https://docs.microsoft.com/en-us/azure/app-service/configure-ssl-bindings#enforce-tls-1112 Field Description certificateRefs []SecretsDefaultLocalObjectReference CertificateRefs is a list of references to Kubernetes objects that each contain an identity certificate. The host name in a TLS SNI client hello message is used for certificate matching and route host name selection. The SNI server_name must match a route host name for the Gateway to route the TLS request. If an entry in this list omits or specifies the empty string for both the group and the resource, the resource defaults to \u201csecrets\u201d. An implementation may support other resources (for example, resource \u201cmycertificates\u201d in group \u201cnetworking.acme.io\u201d). Support: Core (Kubernetes Secrets) Support: Implementation-specific (Other resource types) minimumVersion string (Optional) MinimumVersion of TLS allowed. It is recommended to use one of the TLS constants above. Note: MinimumVersion is not strongly typed to allow implementation-specific versions to be used without requiring updates to the API types. String must be of the form \u201c \u201d. Support: Core for TLS1_{1,2,3}. Implementation-specific for all other values. options map[string]string Options are a list of key/value pairs to give extended options to the provider. There variation among providers as to how ciphersuites are expressed. If there is a common subset for expressing ciphers then it will make sense to loft that as a core API construct. Support: Implementation-specific. TargetPort ( int32 alias) ( Appears on: ForwardToTarget ) TargetPort specifies the destination port number to use for a TargetRef. TcpRouteSpec ( Appears on: TcpRoute ) TcpRouteSpec defines the desired state of TcpRoute TcpRouteStatus ( Appears on: TcpRoute ) TcpRouteStatus defines the observed state of TcpRoute TrafficSplitSpec ( Appears on: TrafficSplit ) TrafficSplitSpec defines the desired state of TrafficSplit TrafficSplitStatus ( Appears on: TrafficSplit ) TrafficSplitStatus defines the observed state of TrafficSplit Generated with gen-crd-api-reference-docs .","title":"API specification"},{"location":"userguide/","text":"API user guide TODO","title":"User guide"},{"location":"userguide/#api-user-guide","text":"TODO","title":"API user guide"}]} \ No newline at end of file diff --git a/docs/spec/index.html b/docs/spec/index.html index 14b78a1afe..35244a809c 100644 --- a/docs/spec/index.html +++ b/docs/spec/index.html @@ -360,8 +360,132 @@
Resource Types:
+
Gateway represents an instantiation of a service-traffic handling infrastructure.
+ +| Field | +Description | +||||||
|---|---|---|---|---|---|---|---|
+apiVersion
+string |
+
+
+networking.x-k8s.io/v1alpha1
+
+ |
+||||||
+kind
+string
+ |
+Gateway |
+||||||
+metadata
+
+
+Kubernetes meta/v1.ObjectMeta
+
+
+ |
+
+Refer to the Kubernetes API documentation for the fields of the
+metadata field.
+ |
+||||||
+spec
+
+
+GatewaySpec
+
+
+ |
+
+ + +
|
+||||||
+status
+
+
+GatewayStatus
+
+
+ |
++ | +
@@ -530,6 +654,154 @@
+
TcpRoute is the Schema for the tcproutes API
+ +| Field | +Description | +
|---|---|
+apiVersion
+string |
+
+
+networking.x-k8s.io/v1alpha1
+
+ |
+
+kind
+string
+ |
+TcpRoute |
+
+metadata
+
+
+Kubernetes meta/v1.ObjectMeta
+
+
+ |
+
+Refer to the Kubernetes API documentation for the fields of the
+metadata field.
+ |
+
+spec
+
+
+TcpRouteSpec
+
+
+ |
+
+ + + |
+
+status
+
+
+TcpRouteStatus
+
+
+ |
++ | +
+
TrafficSplit is the Schema for the trafficsplits API
+ +| Field | +Description | +
|---|---|
+apiVersion
+string |
+
+
+networking.x-k8s.io/v1alpha1
+
+ |
+
+kind
+string
+ |
+TrafficSplit |
+
+metadata
+
+
+Kubernetes meta/v1.ObjectMeta
+
+
+ |
+
+Refer to the Kubernetes API documentation for the fields of the
+metadata field.
+ |
+
+spec
+
+
+TrafficSplitSpec
+
+
+ |
+
+ + + |
+
+status
+
+
+TrafficSplitStatus
+
+
+ |
++ | +
string alias)@@ -671,107 +943,6 @@
-
Gateway represents an instantiation of a service-traffic handling infrastructure.
- -| Field | -Description | -||||||
|---|---|---|---|---|---|---|---|
-metadata
-
-
-Kubernetes meta/v1.ObjectMeta
-
-
- |
-
-Refer to the Kubernetes API documentation for the fields of the
-metadata field.
- |
-||||||
-spec
-
-
-GatewaySpec
-
-
- |
-
- - -
|
-||||||
-status
-
-
-GatewayStatus
-
-
- |
-- | -
@@ -2455,63 +2626,6 @@
TargetPort specifies the destination port number to use for a TargetRef.
--
TcpRoute is the Schema for the tcproutes API
- -| Field | -Description | -
|---|---|
-metadata
-
-
-Kubernetes meta/v1.ObjectMeta
-
-
- |
-
-Refer to the Kubernetes API documentation for the fields of the
-metadata field.
- |
-
-spec
-
-
-TcpRouteSpec
-
-
- |
-
- - - |
-
-status
-
-
-TcpRouteStatus
-
-
- |
-- | -
@@ -2530,63 +2644,6 @@
TcpRouteStatus defines the observed state of TcpRoute
--
TrafficSplit is the Schema for the trafficsplits API
- -| Field | -Description | -
|---|---|
-metadata
-
-
-Kubernetes meta/v1.ObjectMeta
-
-
- |
-
-Refer to the Kubernetes API documentation for the fields of the
-metadata field.
- |
-
-spec
-
-
-TrafficSplitSpec
-
-
- |
-
- - - |
-
-status
-
-
-TrafficSplitStatus
-
-
- |
-- | -