Kubernetes Service APIs (Service APIs) is an open source project managed by the SIG-NETWORK community at https://github.com/kubernetes-sigs/service-apis. The goal of the project is to develop Service APIs in the Kubernetes ecosystem. The goal of this project is to develop Service Network APIs in the Kubernetes ecosystem. Service APIs provide interfaces to expose Kubernetes applications - Services, Ingress, etc.

What is the goal of the Service API?

Service APIs are designed to improve service networks by providing expressible, extensible, role-oriented interfaces that are implemented by many vendors and supported by a wide range of industries.

The Service API is a collection of API resources-Service, GatewayClass, Gateway, HTTPRoute, TCPRoute, etc.-that work together to build models for various network use cases.

How can service APIs improve on current standards such as Ingress?

  • More expressive - Express more core functionality, such as they target features such as header-based matching, traffic weighting, and other features that are only possible in Ingress through customization.
  • More Extensible - They allow custom resources to be linked to various layers of the API, which allows for more fine-grained customization at the appropriate places in the API structure.
  • Role Oriented - They are broken into different API resources that map to common roles for running applications on Kubernetes.
  • Universal - Just as Ingress is a universal specification with many implementations, the service APIs are designed as a portable specification supported by many implementations to support a portable specification.

Some other notable features include…

  • Shared Gateways - **** enables shared load balancers and VIPs by allowing independent routing resources to be bound to the same gateway, which allows teams to securely share infrastructure without the need for direct coordination.
  • Typed Backend References - With typed backend references, Routes can reference Kubernetes Services, as well as any kind of Kubernetes resource that is designed to be a Gateway backend.
  • Cross Namespace References - Routes across different namespaces can be bound to a Gateway, allowing shared network infrastructure despite the namespace.
  • Classes - GatewayClasses formalize the types of load balancing implementations, and these classes make it easy and clear for users to understand what capabilities are available as a resource model itself.

There are 3 main roles in the Service API.

  • Infrastructure provider
  • Cluster Ops
  • Application Developer

In some use cases, there may be a fourth role application administrator.

The resources associated with the service API will initially be defined as CRDs in the networking.x-k8s.io API group. In our resource model, there are 3 main types of objects.

  • GatewayClass defines a set of gateways with common configuration and behavior.
  • Gateway A gateway requests a point where traffic can be converted to a service within the cluster.
  • Routes Routes describe how traffic coming through a gateway is mapped to a service.

GatewayClass

A GatewayClass defines a set of gateways that share common configuration and behavior, each GatewayClass will be handled by a single controller, although a controller can handle multiple GatewayClasses.

A GatewayClass is a cluster-wide resource, and at least one GatewayClass must be defined in order to provide Gateways functionality. Controllers that implement the Gateway API do so by providing an associated GatewayClass resource that users can reference from their Gateway.

This is similar to Ingress’s IngressClass and PersistentVolumes’s StorageClass. In Ingress v1beta1, the closest thing to GatewayClass is the ingress-class annotation, while in IngressV1, the closest thing is the IngressClass object.

Gateway

The Gateway gateway describes how traffic is routed to services within the cluster. That is, it defines method requests for routing traffic from places that do not know Kubernetes to places in Kubernetes. For example, traffic sent to a Kubernetes service from a cloud load balancer, an in-cluster proxy, or an external hardware load balancer is not mandatory, although client traffic for many use cases originates “outside” the cluster.

It defines a request for a specific load balancer configuration that implements the GatewayClass configuration and behavior agreement. This resource can be created directly by operations staff, or by the controller handling the GatewayClass.

Since the Gateway specification declares the user intent, it may not contain the full specification of all attributes in the specification. For example, users can omit fields such as address, port, TLS, etc. This allows the controller managing the GatewayClass to provide these settings to the user, making the specification more portable, and using the GatewayClass Status object will make this behavior clearer.

A Gateway can contain one or more *Route references that serve to route 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 a Kubernetes service.

HTTPRoute and TCPRoute are the only Route objects currently defined, and other protocol-specific Route objects may be added in the future.

BackendPolicy

BackendPolicy provides a way to configure the connection between the gateway and the backend. In this API, the backend is any resource to which the route can forward traffic. This level of configuration is currently limited to TLS, but will be extended in the future to support more advanced policies, such as health checks.

Some backend configurations may vary depending on the Route that is targeted to the backend. In these cases, the configuration fields will be placed on Routes rather than BackendPolicy; for more information on possible future configurations of this resource, please refer to the related GitHub Issue.

Combined types

The combination of GatewayClass, Gateway, xRoute, and Service will define an implementable load balancer, and the following diagram illustrates the relationship between these resources.

Request Process

A typical client/gateway API request flow for a gateway implemented using a reverse proxy is shown below.

  1. The client sends a request to http://foo.example.com
  2. DNS resolves the name to the gateway address.
  3. The reverse proxy receives the request on the Listener and uses the Host header to match the HTTPRoute.
  4. (Optional) The reverse proxy can perform request header and/orpath matching based on the HTTPRoute matching rules.
  5. (Optional) The reverse proxy can modify the request according to the HTTPRoute filtering rules, i.e. add/remove headers. Finally, the reverse proxy can forward the request to one or more objects in the cluster, i.e. Service, based on HTTPRoute’s forwardTo rule.

Extension Point

A number of extension points are provided in the API to provide flexibility in handling a large number of use cases that cannot be handled by the generic API.

The following is a summary of the extension points in the API.

  • XRouteMatch.ExtensionRef : This extension point should be used to extend the match semantics of a specific core Route. This is an experimental extension point and will be iterated in the future based on feedback.
  • XForwardTo.BackendRef : This extension point should be used to forward traffic to a network endpoint outside of the core Kubernetes service resources. Examples include S3 bucket, Lambda functions, file servers, etc.
  • HTTPRouteFilter : This API type in HTTPRoute provides a way to hook the request/response lifecycle of HTTP requests.
  • Custom Routes : If none of the above extension points meet the needs of the use case, implementers can choose to create custom routing resources for protocols not currently supported in the API.

Traefik

A Provider for Kubernetes Gateway, a Traefik implementation of the Service APIs specification for the Kubernetes SIGs, has been added in the latest traefikv2.4.0-rc1 release. This provider is proposed as an experimental feature that partially supports the Service APIs v0.1.0 specification.

Specific usage examples can be found in the documentation: https://doc.traefik.io/traefik/v2.4/providers/kubernetes-gateway/ for more information.