Service API's provide name-based virtual hosting of objects that reside in a Kubernetes cluster.
A Gateway
host's one or more names that clients connect to. A Gateway
exposes these names on one or more network endpoints called listeners. If applicable, the TLS configuration of the hosted name is used to perform a TLS handshake. The hosted name is used to match a VirtualHost
.
Persona: Cluster Ops
A VirtualHost
is an in-cluster object, i.e. Service
, exposed by a Gateway
. A VirtualHost
performs request manipulation (optional) and routing based on match, filter and action rules.
Persona: Dev
- A client makes a request: https://foo.example.com
- The client resolves "foo.example.com" to IP address 1.1.1.1
- The client requests a TLS handshake with 1.1.1.1 using "foo.example.com" as the SNI server_name.
- The request is received on listener "my-tls-listener" of a controller configured by
GatewayClass
"acme-tls-lb" andGateway
"my-tls-gateway". - The controller verifies that "foo.example.com" matches a name in
gateway.spec.hostedNames[]
. - A match is found, so the client's connection request is processed.
- The controller uses the TLS config associated to
gateway.spec.hostedName["foo.example.com"]
to perform the TLS handshake. - Since the client and "foo.example.com" TLS config match, the hanshake is successful and the controller continues to process the client's connection request.
- The controller performs a list/watch for all
VirtualHost
objects across allgateway.spec.allowedNamespaces
and stores the results in a cache. - The controller checks the cache for a
VirtualHost
with a hostname of "foo.example.com" and finds a hit, aVitualHost
named "foo". - The controller uses the
VitualHost
rules to perform manipulation of the request (optional) and forwards the request to an in-cluster object, i.e.Service
. - The in-cluster object receives the request.
TBD's:
- If the Gateway must terminate the client's TLS connection and establish a new TLS connection to the in-cluster object, i.e. "reencrypt", should the reencrypt config be a property of
Gateway
orVirtualHost
? We must first answer the question "Who is responsible for managing gateway<>in-cluster object security?". - Should
gateway.spec.hostedNames
be more specific, i.e.domainNames
,hostNames
, etc.?
Gateway
is no longer responsible for managingxRoute
, i.e.VirtualHost
association. AGateway
host's names that clients connect to. These names have optional TLS configs. AGateway
uses a hosted name to matchVirtualHosts
that exist within allowed namespaces.VirtualHost
replacesxRoute
. AVirtualHost
is now responsible for "requesting" a Gateway to be serviced by, i.e. binding. The Dev persona role will contain an RBAC rule allowing users to viewGateway
objects and choose aGateway
for theVirtualHost
. If theGateway
does not contain a hosted name that matches the hostname of theVirtualHost
, status is reflected accordingly.
Use Cases:
- Openshift Online *.example.com
TLS config have no ext refs
Think about how to support GRPC:
- ref Istio
http3?
hostedNames: # Specifies what names are hosted by this Gateway. # For http connection requests, a hosted name maps to the host header. # For tcp/tls sonnection requests, a hosted name maps to the SNI server_name: # See rfc 6066 for additional details: https://tools.ietf.org/html/rfc6066 # Use "" as a wildcard specifier. For example, "" will host any domain and ".example.com" # will host all subdomains for the "example.com" domain. # Use "." preceding the hosted domain to allow all hostnames of the specified domain. For exammple, # ".example.com" will host any hostname in domain "example.com", i.e. "foo.example.com". # TLS config can be associated to each hosted name (optional).
tls:
# https://github.com/kubernetes-sigs/service-apis/issues/51
insecureConnectionPolicy: redirect
# https://github.com/kubernetes-sigs/service-apis/issues/52
terminationPolicy: passthrough
certificates:
- group: core
resource: Secret
name: foo-cert
minimumVersion: TLS1_3
allowedNamespaces: Specifies the namespaces that are allowed to bind virtual hosts and TLS configs to this gateway. If unset, defaults to allowing virtual hosts from the same namespace as Gateway. Use "*" to allow binding of virtual hosts from all namespaces.
A listener exposes a Gateway on a specified protocol, port, address, etc..
Think of a listener as a network endpoint or socket.
listeners: