diff --git a/api/v1alpha1/gateway_types.go b/api/v1alpha1/gateway_types.go index 2e00e05b82..4f66beb1fc 100644 --- a/api/v1alpha1/gateway_types.go +++ b/api/v1alpha1/gateway_types.go @@ -70,7 +70,11 @@ const ( // Listener defines a type Listener struct { - // Address bound on the listener. This is optional and behavior + // Name can be used to tie this Listener to a ListenerStatus entry with the + // same name. Each listener must have a unique name within a Gateway. This + // must be a valid DNS_LABEL. + Name string `json:"string"` + // 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. @@ -113,8 +117,7 @@ const ( NamedAddress = "NamedAddress" ) -// ListenerAddress describes an address bound by the -// Listener. +// ListenerAddress describes an address bound by the Listener. type ListenerAddress struct { // Type of the Address. This is one of the *AddressType constants. // @@ -179,56 +182,95 @@ type ListenerTLS struct { // GatewayStatus defines the observed state of Gateway type GatewayStatus struct { - // TODO overall status - - // Listeners is the status for each listener block in the - // Spec. The status for a given block will match the order as - // declared in the Spec, e.g. the status for Spec.Listeners[3] - // will be in Status.Listeners[3]. + // Conditions describe the current conditions of the Gateway. + Conditions []GatewayCondition `json:"conditions"` + // Listeners provide status for each listener defined in the Spec. The name + // in ListenerStatus refers to the corresponding Listener of the same name. Listeners []ListenerStatus `json:"listeners"` - // Routes is the status for each attached route to the - // Gateway. The status for a given route will match the orer as - // declared in the Spec, e.g. the status for Spec.Routes[3] will - // be in Status.Routes[3]. - Routes []GatewayRouteStatus `json:"routes"` +} + +// GatewayConditionType is a type of condition associated with a Gateway. +type GatewayConditionType string + +const ( + // ConditionNoSuchGatewayClass indicates that the specified GatewayClass + // does not exist. + ConditionNoSuchGatewayClass GatewayConditionType = "NoSuchGatewayClass" + // ConditionGatewayNotScheduled indicates that the Gateway has not been + // scheduled. + ConditionGatewayNotScheduled GatewayConditionType = "GatewayNotScheduled" + // ConditionListenersNotReady indicates that at least one of the specified + // listeners os not ready. + ConditionListenersNotReady GatewayConditionType = "ListenersNotReady" + // ConditionInvalidListeners indicates that at least one of the specified + // routes is invalid. + ConditionInvalidListeners GatewayConditionType = "InvalidListeners" + // ConditionRoutesNotReady indicates that at least one of the specified + // routes is not ready. + ConditionRoutesNotReady GatewayConditionType = "RoutesNotReady" + // ConditionInvalidRoutes indicates that at least one of the specified + // routes is invalid. + ConditionInvalidRoutes GatewayConditionType = "InvalidRoutes" +) + +// GatewayCondition is an error status for a given route. +type GatewayCondition struct { + // Type indicates the type of condition. + Type GatewayConditionType `json:"type"` + // Status describes the current state of this condition. Can be "True", + // "False", or "Unknown". + Status core.ConditionStatus `json:"status"` + // Message is a human-understandable message describing the condition. + Message string `json:"message"` + // Reason indicates why the condition is in this state. + // +optional + Reason string `json:"reason"` + // LastTransitionTime indicates the last time this condition changed. + // +optional + LastTransitionTime metav1.Time `json:"lastTransitionTime"` } // ListenerStatus is the status associated with each listener block. type ListenerStatus struct { - // Errors is a list of reasons why a given Listener Spec is - // not valid. Errors will be empty if the Spec is valid. - Errors []ListenerError `json:"errors"` - - // - Address string `json:"address"` + // Name is the name of the listener this status refers to. + Name string `json:"name"` + // Address bound on this listener. + Address *ListenerAddress `json:"address"` + // Conditions describe the current condition of this listener. + Conditions []ListenerCondition `json:"conditions"` } -// ListenerErrorReason is the type for errors associated with the -// listener. -type ListenerErrorReason string +// ListenerConditionType is a type of condition associated with the listener. +type ListenerConditionType string const ( - // ErrListenerInvalidSpec is a generic error that is a - // catch all for unsupported configurations that do not match a - // more specific error. Implementors should try to use more - // specific errors instead of this one to give users and - // automation a more information. - ErrListenerInvalidSpec ListenerErrorReason = "InvalidSpec" - // ErrListenerBadAddress indicates the Address - ErrListenerBadAddress ListenerErrorReason = "InvalidAddress" + // ConditionInvalidListener is a generic condition that is a catch all for + // unsupported configurations that do not match a more specific condition. + // Implementors should try to use more specific condition instead of this + // one to give users and automation a more information. + ConditionInvalidListener ListenerConditionType = "InvalidListener" + // ConditionInvalidAddress indicates the Address is invalid. + ConditionInvalidAddress ListenerConditionType = "InvalidAddress" + // ConditionNoSuchListener indicates the listener does not exist. + ConditionNoSuchListener ListenerConditionType = "NoSuchListener" ) -// ListenerError is an error status for a given ListenerSpec. -type ListenerError struct { - // Reason is a automation friendly reason code for the error. - Reason ListenerErrorReason `json:"reason"` - // Message is a human-understandable error message. +// ListenerCondition is an error status for a given listener. +type ListenerCondition struct { + // Type indicates the type of condition. Can be "InvalidListener", + // "InvalidAddress", or "NoSuchListener". + Type ListenerConditionType `json:"type"` + // Status describes the current state of this condition. Can be "True", + // "False", or "Unknown". + Status core.ConditionStatus `json:"status"` + // Message is a human-understandable message describing the condition. Message string `json:"message"` -} - -// GatewayRouteStatus is the status associated with a given (Gateway, -// Route) pair. -type GatewayRouteStatus struct { + // Reason indicates why the condition is in this state. + // +optional + Reason string `json:"reason"` + // LastTransitionTime indicates the last time this condition changed. + // +optional + LastTransitionTime metav1.Time `json:"lastTransitionTime"` } func init() { diff --git a/api/v1alpha1/zz_generated.deepcopy.go b/api/v1alpha1/zz_generated.deepcopy.go index 3d620640b0..fd9733c611 100644 --- a/api/v1alpha1/zz_generated.deepcopy.go +++ b/api/v1alpha1/zz_generated.deepcopy.go @@ -113,6 +113,22 @@ func (in *GatewayClassList) DeepCopyObject() runtime.Object { return nil } +// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil. +func (in *GatewayCondition) DeepCopyInto(out *GatewayCondition) { + *out = *in + in.LastTransitionTime.DeepCopyInto(&out.LastTransitionTime) +} + +// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new GatewayCondition. +func (in *GatewayCondition) DeepCopy() *GatewayCondition { + if in == nil { + return nil + } + out := new(GatewayCondition) + in.DeepCopyInto(out) + return out +} + // DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil. func (in *GatewayList) DeepCopyInto(out *GatewayList) { *out = *in @@ -145,21 +161,6 @@ func (in *GatewayList) DeepCopyObject() runtime.Object { return nil } -// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil. -func (in *GatewayRouteStatus) DeepCopyInto(out *GatewayRouteStatus) { - *out = *in -} - -// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new GatewayRouteStatus. -func (in *GatewayRouteStatus) DeepCopy() *GatewayRouteStatus { - if in == nil { - return nil - } - out := new(GatewayRouteStatus) - in.DeepCopyInto(out) - return out -} - // DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil. func (in *GatewaySpec) DeepCopyInto(out *GatewaySpec) { *out = *in @@ -192,6 +193,13 @@ func (in *GatewaySpec) DeepCopy() *GatewaySpec { // DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil. func (in *GatewayStatus) DeepCopyInto(out *GatewayStatus) { *out = *in + if in.Conditions != nil { + in, out := &in.Conditions, &out.Conditions + *out = make([]GatewayCondition, len(*in)) + for i := range *in { + (*in)[i].DeepCopyInto(&(*out)[i]) + } + } if in.Listeners != nil { in, out := &in.Listeners, &out.Listeners *out = make([]ListenerStatus, len(*in)) @@ -199,11 +207,6 @@ func (in *GatewayStatus) DeepCopyInto(out *GatewayStatus) { (*in)[i].DeepCopyInto(&(*out)[i]) } } - if in.Routes != nil { - in, out := &in.Routes, &out.Routes - *out = make([]GatewayRouteStatus, len(*in)) - copy(*out, *in) - } } // DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new GatewayStatus. @@ -554,16 +557,17 @@ func (in *ListenerAddress) DeepCopy() *ListenerAddress { } // DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil. -func (in *ListenerError) DeepCopyInto(out *ListenerError) { +func (in *ListenerCondition) DeepCopyInto(out *ListenerCondition) { *out = *in + in.LastTransitionTime.DeepCopyInto(&out.LastTransitionTime) } -// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ListenerError. -func (in *ListenerError) DeepCopy() *ListenerError { +// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ListenerCondition. +func (in *ListenerCondition) DeepCopy() *ListenerCondition { if in == nil { return nil } - out := new(ListenerError) + out := new(ListenerCondition) in.DeepCopyInto(out) return out } @@ -571,10 +575,17 @@ func (in *ListenerError) DeepCopy() *ListenerError { // DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil. func (in *ListenerStatus) DeepCopyInto(out *ListenerStatus) { *out = *in - if in.Errors != nil { - in, out := &in.Errors, &out.Errors - *out = make([]ListenerError, len(*in)) - copy(*out, *in) + if in.Address != nil { + in, out := &in.Address, &out.Address + *out = new(ListenerAddress) + **out = **in + } + if in.Conditions != nil { + in, out := &in.Conditions, &out.Conditions + *out = make([]ListenerCondition, len(*in)) + for i := range *in { + (*in)[i].DeepCopyInto(&(*out)[i]) + } } } diff --git a/docs-src/concepts.md b/docs-src/concepts.md index 7ebaedcb3e..bf4afd9ab6 100644 --- a/docs-src/concepts.md +++ b/docs-src/concepts.md @@ -17,7 +17,7 @@ limitations under the License. # API Concepts This document is a deep dive into the reasoning and design for the API. The -content of this document is taken from the [API sketch][api-sketch]. +content of this document is taken from the [API sketch][api-sketch]. > We will try to keep the two documents in sync as the sketch document has to > lowest bar to contribution, but this document is easier to format well and @@ -30,7 +30,7 @@ content of this document is taken from the [API sketch][api-sketch]. In the original design of Kubernetes, the 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. +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 @@ -121,7 +121,7 @@ kind: GatewayClass metadata: name: from-internet controller: # links to a custom resource - apiGroup: networking.acme.io # that implements this class. + apiGroup: networking.acme.io # that implements this class. kind: cloud-lb name: from-internet ``` @@ -161,13 +161,14 @@ The Gateway spec defines the following: * GatewayClass used to instantiate this Gateway. * Listener bindings, which define addresses and ports, protocol termination, - TLS-settings. Listener configuration requested by a Gateway definition can be - incompatible with a given GatewayClass (e.g. port/protocol combination is not - supported) + TLS-settings. -. In this case, the Gateway will be in an error state, signalled by the status field. +Listener configuration requested by a Gateway definition can be incompatible +with a given GatewayClass (e.g. port/protocol combination is not supported). In +this case, the Gateway will be in an error state, signalled by the status field. Routes, which point to a set of protocol-specific routing served by the Gateway. -OPTIONAL: A Gateway can point directly to Kubernetes Service if no advanced routing is required. +A Gateway can point directly to Kubernetes Service if no advanced routing is +required. #### Deployment models @@ -185,6 +186,15 @@ 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. Status can be tracked indepently on each 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 diff --git a/docs/concepts/index.html b/docs/concepts/index.html index 1aee565753..5ffde5294d 100644 --- a/docs/concepts/index.html +++ b/docs/concepts/index.html @@ -331,6 +331,13 @@ Deployment models + + +
  • + + Gateway Status + +
  • @@ -558,6 +565,13 @@ Deployment models +
    • + +
  • + + Gateway Status + +
  • @@ -660,7 +674,7 @@

    API Concepts

    This document is a deep dive into the reasoning and design for the API. The -content of this document is taken from the API sketch.

    +content of this document is taken from the API sketch.

    We will try to keep the two documents in sync as the sketch document has to lowest bar to contribution, but this document is easier to format well and @@ -670,7 +684,7 @@

    Roles and personas

    In the original design of Kubernetes, the 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.

    +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:

    @@ -748,7 +762,7 @@

    GatewayClass

    metadata: name: from-internet controller: # links to a custom resource - apiGroup: networking.acme.io # that implements this class. + apiGroup: networking.acme.io # that implements this class. kind: cloud-lb name: from-internet @@ -784,13 +798,14 @@

    Gateway

    -

    . In this case, the Gateway will be in an error state, signalled by the status field. +

    Listener configuration requested by a Gateway definition can be incompatible +with a given GatewayClass (e.g. port/protocol combination is not supported). In +this case, the Gateway will be in an error state, signalled by the status field. Routes, which point to a set of protocol-specific routing served by the Gateway. -OPTIONAL: A Gateway can point directly to Kubernetes Service if no advanced routing is required.

    +A Gateway can point directly to Kubernetes Service if no advanced routing is +required.

    Deployment models

    Depending on the GatewayClass, the creation of the Gateway could do any of the following actions:

    @@ -805,6 +820,13 @@

    Deployment models

    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. Status can be tracked indepently on each 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

    diff --git a/docs/search/search_index.json b/docs/search/search_index.json index 8b774570be..361da3f1b3 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 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 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: Thursday 10:30 AM Pacific (EMEA Friendly Time) [Zoom Link] Thursday 4:30 (16:30) PM Pacific (APAC Friendly Time) [Zoom Link] Meeting notes Meeting schedule scratch pad Date February 6, 2019 10:30 PT (Planned) Conformance, what is going to be in the MVP? January 30, 2019 16:30 PT (Planned) First pass: Status, Extensibility January 23, 2019 10:30 PT (Planned) First pass: Routes (HTTPRoutes), Inclusion/delegation January 16, 2019 16:30 PT (Planned) First pass: Gateway: Listener (HTTPS, SNI, lifecycle); Gateway <=> Route binding January 9, 2019 10:30 PT First pass: Personas and resource model: RBAC, resource scope, GatewayClass meeting notes January 2, 2020 4:30 PM PT meeting notes (recording didn't work :-( look at the notes) December 19, 2019 10:30 AM PT 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: Thursday 10:30 AM Pacific (EMEA Friendly Time) [Zoom Link] Thursday 4:30 (16:30) PM Pacific (APAC Friendly Time) [Zoom Link]","title":"Meetings"},{"location":"community/#meeting-notes","text":"Meeting schedule scratch pad Date February 6, 2019 10:30 PT (Planned) Conformance, what is going to be in the MVP? January 30, 2019 16:30 PT (Planned) First pass: Status, Extensibility January 23, 2019 10:30 PT (Planned) First pass: Routes (HTTPRoutes), Inclusion/delegation January 16, 2019 16:30 PT (Planned) First pass: Gateway: Listener (HTTPS, SNI, lifecycle); Gateway <=> Route binding January 9, 2019 10:30 PT First pass: Personas and resource model: RBAC, resource scope, GatewayClass meeting notes January 2, 2020 4:30 PM PT meeting notes (recording didn't work :-( look at the notes) December 19, 2019 10:30 AM PT 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 is taken from the API sketch . We will try to keep the two documents in sync as the sketch document has to lowest bar to contribution, but this document is easier to format well and review. Roles and personas In the original design of Kubernetes, the 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: 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). 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 of the above role replicates the self-service model. Resource model Note: Resource will initially live in the networking.x-k8s.io API group as Custom Resource Definitions (CRDs). Unqualified resource names will implicitly be assumed to be part of this API group. Our resource model is based around a separation of concerns for a service producer. Each resource is intended to be (mostly) independently-evolvable and self-consistent: A way to group pods (backends) into a set via label selection: Kubernetes core.Service , independent of application-level routing. A way to describe application-level routing: xxxxRoute , e.g. HTTPRoute , TCPRoute independent of traffic access and consumption (e.g. A way to describe traffic access and consumption: Gateway independent of implementation. A way to describe which implementations of traffic access are available: GatewayClass . The combination of GatewayClass , Gateway , xxxxRoute and Service (s) will define an implementable load-balancer. The diagram below illustrates the relationships between the different resources: 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. 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 is cluster-scoped resource defined by the infrastructure ops. This resource represents a category of Gateways that can be instantiated. apiVersion: networking.x-k8s.io/v1alpha1 kind: GatewayClass metadata: name: from-internet controller: # links to a custom resource apiGroup: networking.acme.io # that implements this class. kind: cloud-lb name: from-internet A sample controller file: apiVersion: networking.acme.io/v1alpha1 kind: CloudLB metadata: name: from-internet networkTier: auto ipAllocation: auto We expect that one or more GatewayClasses will be created by the infrastructure provider for the user as part of their cloud infrastructure. If the cluster operator wishes to customize their GatewayClasses , they are free to do so, interacting with the custom resource parameters. Example parameters GatewayClass.controller resource will include cluster-level defaults and constraints. The community may converge around a common set of GatewayClass names with well-known meanings (e.g. internet , private ) to ease interoperability between platforms. Gateway A Gateway is 1:1 with the life cycle of the configuration of LB infrastructure. When a user creates a Gateway , a load balancer is provisioned (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: GatewayClass used to instantiate this Gateway. Listener bindings, which define addresses and ports, protocol termination, TLS-settings. Listener configuration requested by a Gateway definition can be incompatible with a given GatewayClass (e.g. port/protocol combination is not supported) . In this case, the Gateway will be in an error state, signalled by the status field. Routes, which point to a set of protocol-specific routing served by the Gateway. OPTIONAL: A Gateway can point directly to Kubernetes Service if no advanced routing is required. 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. 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 is taken from the API sketch . We will try to keep the two documents in sync as the sketch document has to lowest bar to contribution, but this document is easier to format well and review.","title":"API Concepts"},{"location":"concepts/#roles-and-personas","text":"In the original design of Kubernetes, the 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: 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). 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 of the above role replicates the self-service model.","title":"Roles and personas"},{"location":"concepts/#resource-model","text":"Note: Resource will initially live in the networking.x-k8s.io API group as Custom Resource Definitions (CRDs). Unqualified resource names will implicitly be assumed to be part of this API group. Our resource model is based around a separation of concerns for a service producer. Each resource is intended to be (mostly) independently-evolvable and self-consistent: A way to group pods (backends) into a set via label selection: Kubernetes core.Service , independent of application-level routing. A way to describe application-level routing: xxxxRoute , e.g. HTTPRoute , TCPRoute independent of traffic access and consumption (e.g. A way to describe traffic access and consumption: Gateway independent of implementation. A way to describe which implementations of traffic access are available: GatewayClass . The combination of GatewayClass , Gateway , xxxxRoute and Service (s) will define an implementable load-balancer. The diagram below illustrates the relationships between the different resources:","title":"Resource model"},{"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. 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","text":"GatewayClass is cluster-scoped resource defined by the infrastructure ops. This resource represents a category of Gateways that can be instantiated. apiVersion: networking.x-k8s.io/v1alpha1 kind: GatewayClass metadata: name: from-internet controller: # links to a custom resource apiGroup: networking.acme.io # that implements this class. kind: cloud-lb name: from-internet A sample controller file: apiVersion: networking.acme.io/v1alpha1 kind: CloudLB metadata: name: from-internet networkTier: auto ipAllocation: auto We expect that one or more GatewayClasses will be created by the infrastructure provider for the user as part of their cloud infrastructure. If the cluster operator wishes to customize their GatewayClasses , they are free to do so, interacting with the custom resource parameters. Example parameters GatewayClass.controller resource will include cluster-level defaults and constraints. The community may converge around a common set of GatewayClass names with well-known meanings (e.g. internet , private ) to ease interoperability between platforms.","title":"GatewayClass"},{"location":"concepts/#gateway","text":"A Gateway is 1:1 with the life cycle of the configuration of LB infrastructure. When a user creates a Gateway , a load balancer is provisioned (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: GatewayClass used to instantiate this Gateway. Listener bindings, which define addresses and ports, protocol termination, TLS-settings. Listener configuration requested by a Gateway definition can be incompatible with a given GatewayClass (e.g. port/protocol combination is not supported) . In this case, the Gateway will be in an error state, signalled by the status field. Routes, which point to a set of protocol-specific routing served by the Gateway. OPTIONAL: A Gateway can point directly to Kubernetes Service if no advanced routing is required.","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/#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. 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 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. 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","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":"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":"spec/","text":"API specification TODO","title":"API specification"},{"location":"spec/#api-specification","text":"TODO","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 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 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: Thursday 10:30 AM Pacific (EMEA Friendly Time) [Zoom Link] Thursday 4:30 (16:30) PM Pacific (APAC Friendly Time) [Zoom Link] Meeting notes Meeting schedule scratch pad Date February 6, 2019 10:30 PT (Planned) Conformance, what is going to be in the MVP? January 30, 2019 16:30 PT (Planned) First pass: Status, Extensibility January 23, 2019 10:30 PT (Planned) First pass: Routes (HTTPRoutes), Inclusion/delegation January 16, 2019 16:30 PT (Planned) First pass: Gateway: Listener (HTTPS, SNI, lifecycle); Gateway <=> Route binding January 9, 2019 10:30 PT First pass: Personas and resource model: RBAC, resource scope, GatewayClass meeting notes January 2, 2020 4:30 PM PT meeting notes (recording didn't work :-( look at the notes) December 19, 2019 10:30 AM PT 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: Thursday 10:30 AM Pacific (EMEA Friendly Time) [Zoom Link] Thursday 4:30 (16:30) PM Pacific (APAC Friendly Time) [Zoom Link]","title":"Meetings"},{"location":"community/#meeting-notes","text":"Meeting schedule scratch pad Date February 6, 2019 10:30 PT (Planned) Conformance, what is going to be in the MVP? January 30, 2019 16:30 PT (Planned) First pass: Status, Extensibility January 23, 2019 10:30 PT (Planned) First pass: Routes (HTTPRoutes), Inclusion/delegation January 16, 2019 16:30 PT (Planned) First pass: Gateway: Listener (HTTPS, SNI, lifecycle); Gateway <=> Route binding January 9, 2019 10:30 PT First pass: Personas and resource model: RBAC, resource scope, GatewayClass meeting notes January 2, 2020 4:30 PM PT meeting notes (recording didn't work :-( look at the notes) December 19, 2019 10:30 AM PT 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 is taken from the API sketch . We will try to keep the two documents in sync as the sketch document has to lowest bar to contribution, but this document is easier to format well and review. Roles and personas In the original design of Kubernetes, the 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: 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). 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 of the above role replicates the self-service model. Resource model Note: Resource will initially live in the networking.x-k8s.io API group as Custom Resource Definitions (CRDs). Unqualified resource names will implicitly be assumed to be part of this API group. Our resource model is based around a separation of concerns for a service producer. Each resource is intended to be (mostly) independently-evolvable and self-consistent: A way to group pods (backends) into a set via label selection: Kubernetes core.Service , independent of application-level routing. A way to describe application-level routing: xxxxRoute , e.g. HTTPRoute , TCPRoute independent of traffic access and consumption (e.g. A way to describe traffic access and consumption: Gateway independent of implementation. A way to describe which implementations of traffic access are available: GatewayClass . The combination of GatewayClass , Gateway , xxxxRoute and Service (s) will define an implementable load-balancer. The diagram below illustrates the relationships between the different resources: 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. 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 is cluster-scoped resource defined by the infrastructure ops. This resource represents a category of Gateways that can be instantiated. apiVersion: networking.x-k8s.io/v1alpha1 kind: GatewayClass metadata: name: from-internet controller: # links to a custom resource apiGroup: networking.acme.io # that implements this class. kind: cloud-lb name: from-internet A sample controller file: apiVersion: networking.acme.io/v1alpha1 kind: CloudLB metadata: name: from-internet networkTier: auto ipAllocation: auto We expect that one or more GatewayClasses will be created by the infrastructure provider for the user as part of their cloud infrastructure. If the cluster operator wishes to customize their GatewayClasses , they are free to do so, interacting with the custom resource parameters. Example parameters GatewayClass.controller resource will include cluster-level defaults and constraints. The community may converge around a common set of GatewayClass names with well-known meanings (e.g. internet , private ) to ease interoperability between platforms. Gateway A Gateway is 1:1 with the life cycle of the configuration of LB infrastructure. When a user creates a Gateway , a load balancer is provisioned (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: GatewayClass used to instantiate this Gateway. Listener bindings, which define addresses and ports, protocol termination, TLS-settings. Listener configuration requested by a Gateway definition can be incompatible with a given GatewayClass (e.g. port/protocol combination is not supported). In this case, the Gateway will be in an error state, signalled by the status field. Routes, which point to a set of protocol-specific routing served by the Gateway. A Gateway can point directly to Kubernetes Service if no advanced routing is required. 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. Status can be tracked indepently on each 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 is taken from the API sketch . We will try to keep the two documents in sync as the sketch document has to lowest bar to contribution, but this document is easier to format well and review.","title":"API Concepts"},{"location":"concepts/#roles-and-personas","text":"In the original design of Kubernetes, the 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: 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). 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 of the above role replicates the self-service model.","title":"Roles and personas"},{"location":"concepts/#resource-model","text":"Note: Resource will initially live in the networking.x-k8s.io API group as Custom Resource Definitions (CRDs). Unqualified resource names will implicitly be assumed to be part of this API group. Our resource model is based around a separation of concerns for a service producer. Each resource is intended to be (mostly) independently-evolvable and self-consistent: A way to group pods (backends) into a set via label selection: Kubernetes core.Service , independent of application-level routing. A way to describe application-level routing: xxxxRoute , e.g. HTTPRoute , TCPRoute independent of traffic access and consumption (e.g. A way to describe traffic access and consumption: Gateway independent of implementation. A way to describe which implementations of traffic access are available: GatewayClass . The combination of GatewayClass , Gateway , xxxxRoute and Service (s) will define an implementable load-balancer. The diagram below illustrates the relationships between the different resources:","title":"Resource model"},{"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. 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","text":"GatewayClass is cluster-scoped resource defined by the infrastructure ops. This resource represents a category of Gateways that can be instantiated. apiVersion: networking.x-k8s.io/v1alpha1 kind: GatewayClass metadata: name: from-internet controller: # links to a custom resource apiGroup: networking.acme.io # that implements this class. kind: cloud-lb name: from-internet A sample controller file: apiVersion: networking.acme.io/v1alpha1 kind: CloudLB metadata: name: from-internet networkTier: auto ipAllocation: auto We expect that one or more GatewayClasses will be created by the infrastructure provider for the user as part of their cloud infrastructure. If the cluster operator wishes to customize their GatewayClasses , they are free to do so, interacting with the custom resource parameters. Example parameters GatewayClass.controller resource will include cluster-level defaults and constraints. The community may converge around a common set of GatewayClass names with well-known meanings (e.g. internet , private ) to ease interoperability between platforms.","title":"GatewayClass"},{"location":"concepts/#gateway","text":"A Gateway is 1:1 with the life cycle of the configuration of LB infrastructure. When a user creates a Gateway , a load balancer is provisioned (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: GatewayClass used to instantiate this Gateway. Listener bindings, which define addresses and ports, protocol termination, TLS-settings. Listener configuration requested by a Gateway definition can be incompatible with a given GatewayClass (e.g. port/protocol combination is not supported). In this case, the Gateway will be in an error state, signalled by the status field. Routes, which point to a set of protocol-specific routing served by the Gateway. A Gateway can point directly to Kubernetes Service if no advanced routing is required.","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. Status can be tracked indepently on each 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. 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 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. 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","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":"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":"spec/","text":"API specification TODO","title":"API specification"},{"location":"spec/#api-specification","text":"TODO","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/sitemap.xml b/docs/sitemap.xml index ead820daba..303621eb73 100644 --- a/docs/sitemap.xml +++ b/docs/sitemap.xml @@ -2,47 +2,47 @@ None - 2020-01-24 + 2020-01-30 daily None - 2020-01-24 + 2020-01-30 daily None - 2020-01-24 + 2020-01-30 daily None - 2020-01-24 + 2020-01-30 daily None - 2020-01-24 + 2020-01-30 daily None - 2020-01-24 + 2020-01-30 daily None - 2020-01-24 + 2020-01-30 daily None - 2020-01-24 + 2020-01-30 daily None - 2020-01-24 + 2020-01-30 daily \ No newline at end of file diff --git a/docs/sitemap.xml.gz b/docs/sitemap.xml.gz index 976d7c4f84..9096b67e11 100644 Binary files a/docs/sitemap.xml.gz and b/docs/sitemap.xml.gz differ