baalajimaestro/traefik
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity
traefik/docs/content/routing/providers/kubernetes-gateway.md

329 lines
25 KiB
Markdown
Raw Normal View History

Add Kubernetes Gateway Provider Co-authored-by: Jean-Baptiste Doumenjou <925513+jbdoumenjou@users.noreply.github.com>
2020-12-15 15:40:05 +00:00
# Traefik & Kubernetes
The Kubernetes Gateway API, The Experimental Way.
{: .subtitle }
## Configuration Examples
??? example "Configuring Kubernetes Gateway provider and Deploying/Exposing Services"
```yaml tab="Gateway API"
--8<-- "content/reference/dynamic-configuration/kubernetes-gateway-simple-https.yml"
```
```yaml tab="Whoami Service"
--8<-- "content/reference/dynamic-configuration/kubernetes-whoami-svc.yml"
```
```yaml tab="Traefik Service"
--8<-- "content/reference/dynamic-configuration/kubernetes-gateway-traefik-lb-svc.yml"
```
```yaml tab="RBAC"
--8<-- "content/reference/dynamic-configuration/kubernetes-gateway-rbac.yml"
```
## Routing Configuration
### Custom Resource Definition (CRD)
* You can find an exhaustive list, of the custom resources and their attributes in
Update to gateway-api v0.2.0 Co-authored-by: Romain <rtribotte@users.noreply.github.com>
2021-03-15 08:44:03 +00:00
[the reference page](../../reference/dynamic-configuration/kubernetes-gateway.md) or in the Kubernetes Sigs `Gateway API` [repository](https://github.com/kubernetes-sigs/gateway-api).
Add Kubernetes Gateway Provider Co-authored-by: Jean-Baptiste Doumenjou <925513+jbdoumenjou@users.noreply.github.com>
2020-12-15 15:40:05 +00:00
* Validate that [the prerequisites](../../providers/kubernetes-gateway.md#configuration-requirements) are fulfilled before using the Traefik Kubernetes Gateway Provider.
You can find an excerpt of the supported Kubernetes Gateway API resources in the table below:
gatewayapi: adding support for TCPRoute and TLSRoute Co-authored-by: Jean-Baptiste Doumenjou <925513+jbdoumenjou@users.noreply.github.com>
2021-05-20 09:50:12 +00:00
| Kind | Purpose | Concept Behind |
|------------------------------------|---------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
| [GatewayClass](#kind-gatewayclass) | Defines a set of Gateways that share a common configuration and behaviour | [GatewayClass](https://gateway-api.sigs.k8s.io/api-types/gatewayclass) |
| [Gateway](#kind-gateway) | Describes how traffic can be translated to Services within the cluster | [Gateway](https://gateway-api.sigs.k8s.io/api-types/gateway) |
| [HTTPRoute](#kind-httproute) | HTTP rules for mapping requests from a Gateway to Kubernetes Services | [Route](https://gateway-api.sigs.k8s.io/api-types/httproute) |
| [TCPRoute](#kind-tcproute) | Allows mapping TCP requests from a Gateway to Kubernetes Services | [Route](https://gateway-api.sigs.k8s.io/concepts/api-overview/#httptcpfooroute) |
| [TLSRoute](#kind-tlsroute) | Allows mapping TLS requests from a Gateway to Kubernetes Services | [Route](https://gateway-api.sigs.k8s.io/concepts/api-overview/#httptcpfooroute) |
Add Kubernetes Gateway Provider Co-authored-by: Jean-Baptiste Doumenjou <925513+jbdoumenjou@users.noreply.github.com>
2020-12-15 15:40:05 +00:00
### Kind: `GatewayClass`
`GatewayClass` is cluster-scoped resource defined by the infrastructure provider. This resource represents a class of Gateways that can be instantiated.
Fix Kubernetes Gateway API documentation links
2021-04-13 16:26:03 +00:00
More details on the GatewayClass [official documentation](https://gateway-api.sigs.k8s.io/api-types/gatewayclass/).
Add Kubernetes Gateway Provider Co-authored-by: Jean-Baptiste Doumenjou <925513+jbdoumenjou@users.noreply.github.com>
2020-12-15 15:40:05 +00:00
The `GatewayClass` should be declared by the infrastructure provider, otherwise please register the `GatewayClass`
[definition](../../reference/dynamic-configuration/kubernetes-gateway.md#definitions) in the Kubernetes cluster before
creating `GatewayClass` objects.
!!! info "Declaring GatewayClass"
```yaml
kind: GatewayClass
apiVersion: networking.x-k8s.io/v1alpha1
metadata:
name: my-gateway-class
spec:
# Controller is a domain/path string that indicates
# the controller that is managing Gateways of this class.
controller: traefik.io/gateway-controller
```
### Kind: `Gateway`
A `Gateway` is 1:1 with the life cycle of the configuration of infrastructure. When a user creates a Gateway,
some load balancing infrastructure is provisioned or configured by the GatewayClass controller.
Fix Kubernetes Gateway API documentation links
2021-04-13 16:26:03 +00:00
More details on the Gateway [official documentation](https://gateway-api.sigs.k8s.io/api-types/gateway/).
Add Kubernetes Gateway Provider Co-authored-by: Jean-Baptiste Doumenjou <925513+jbdoumenjou@users.noreply.github.com>
2020-12-15 15:40:05 +00:00
Register the `Gateway` [definition](../../reference/dynamic-configuration/kubernetes-gateway.md#definitions) in the
Kubernetes cluster before creating `Gateway` objects.
gatewayapi: adding support for TCPRoute and TLSRoute Co-authored-by: Jean-Baptiste Doumenjou <925513+jbdoumenjou@users.noreply.github.com>
2021-05-20 09:50:12 +00:00
Depending on the Listener Protocol, different modes and Route types are supported.
| Listener Protocol | TLS Mode | Route Type Supported |
|-------------------|----------------|------------------------------|
| TCP | Not applicable | [TCPRoute](#kind-tcproute) |
| TLS | Passthrough | [TLSRoute](#kind-tlsroute) |
| TLS | Terminate | [TCPRoute](#kind-tcproute) |
| HTTP | Not applicable | [HTTPRoute](#kind-httproute) |
| HTTPS | Terminate | [HTTPRoute](#kind-httproute) |
Add Kubernetes Gateway Provider Co-authored-by: Jean-Baptiste Doumenjou <925513+jbdoumenjou@users.noreply.github.com>
2020-12-15 15:40:05 +00:00
!!! info "Declaring Gateway"
gatewayapi: adding support for TCPRoute and TLSRoute Co-authored-by: Jean-Baptiste Doumenjou <925513+jbdoumenjou@users.noreply.github.com>
2021-05-20 09:50:12 +00:00
```yaml tab="HTTP Listener"
kind: Gateway
apiVersion: networking.x-k8s.io/v1alpha1
metadata:
name: my-http-gateway
namespace: default
spec:
gatewayClassName: my-gateway-class # [1]
listeners: # [2]
- protocol: HTTP # [3]
port: 80 # [4]
routes: # [8]
kind: HTTPRoute # [9]
selector: # [10]
matchLabels: # [11]
app: foo
Add Kubernetes Gateway Provider Co-authored-by: Jean-Baptiste Doumenjou <925513+jbdoumenjou@users.noreply.github.com>
2020-12-15 15:40:05 +00:00
```
gatewayapi: adding support for TCPRoute and TLSRoute Co-authored-by: Jean-Baptiste Doumenjou <925513+jbdoumenjou@users.noreply.github.com>
2021-05-20 09:50:12 +00:00
```yaml tab="HTTPS Listener"
Add Kubernetes Gateway Provider Co-authored-by: Jean-Baptiste Doumenjou <925513+jbdoumenjou@users.noreply.github.com>
2020-12-15 15:40:05 +00:00
kind: Gateway
apiVersion: networking.x-k8s.io/v1alpha1
metadata:
gatewayapi: adding support for TCPRoute and TLSRoute Co-authored-by: Jean-Baptiste Doumenjou <925513+jbdoumenjou@users.noreply.github.com>
2021-05-20 09:50:12 +00:00
name: my-https-gateway
Add Kubernetes Gateway Provider Co-authored-by: Jean-Baptiste Doumenjou <925513+jbdoumenjou@users.noreply.github.com>
2020-12-15 15:40:05 +00:00
namespace: default
spec:
gatewayClassName: my-gateway-class # [1]
listeners: # [2]
- protocol: HTTPS # [3]
port: 443 # [4]
gatewayapi: adding support for TCPRoute and TLSRoute Co-authored-by: Jean-Baptiste Doumenjou <925513+jbdoumenjou@users.noreply.github.com>
2021-05-20 09:50:12 +00:00
tls: # [6]
certificateRef: # [7]
Add Kubernetes Gateway Provider Co-authored-by: Jean-Baptiste Doumenjou <925513+jbdoumenjou@users.noreply.github.com>
2020-12-15 15:40:05 +00:00
group: "core"
kind: "Secret"
name: "mysecret"
gatewayapi: adding support for TCPRoute and TLSRoute Co-authored-by: Jean-Baptiste Doumenjou <925513+jbdoumenjou@users.noreply.github.com>
2021-05-20 09:50:12 +00:00
routes: # [8]
kind: HTTPRoute # [9]
selector: # [10]
matchLabels: # [11]
Add Kubernetes Gateway Provider Co-authored-by: Jean-Baptiste Doumenjou <925513+jbdoumenjou@users.noreply.github.com>
2020-12-15 15:40:05 +00:00
app: foo
```
gatewayapi: adding support for TCPRoute and TLSRoute Co-authored-by: Jean-Baptiste Doumenjou <925513+jbdoumenjou@users.noreply.github.com>
2021-05-20 09:50:12 +00:00
```yaml tab="TCP Listener"
kind: Gateway
apiVersion: networking.x-k8s.io/v1alpha1
metadata:
name: my-tcp-gateway
namespace: default
spec:
gatewayClassName: my-gateway-class # [1]
listeners: # [2]
- protocol: TCP # [3]
port: 8000 # [4]
routes: # [8]
kind: TCPRoute # [9]
selector: # [10]
matchLabels: # [11]
app: footcp
```
```yaml tab="TLS Listener"
kind: Gateway
apiVersion: networking.x-k8s.io/v1alpha1
metadata:
name: my-tls-gateway
namespace: default
spec:
gatewayClassName: my-gateway-class # [1]
listeners: # [2]
- protocol: TLS # [3]
port: 443 # [4]
hostname: foo.com # [5]
tls: # [6]
certificateRef: # [7]
group: "core"
kind: "Secret"
name: "mysecret"
routes: # [8]
kind: TLSRoute # [9]
selector: # [10]
matchLabels: # [11]
app: footcp
```
| Ref | Attribute | Description |
|------|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
| [1] | `gatewayClassName` | GatewayClassName used for this Gateway. This is the name of a GatewayClass resource. |
| [2] | `listeners` | Logical endpoints that are bound on this Gateway's addresses. At least one Listener MUST be specified. |
| [3] | `protocol` | The network protocol this listener expects to receive (only HTTP and HTTPS are implemented). |
| [4] | `port` | The network port. |
| [5] | `hostname` | Hostname specifies the virtual hostname to match for protocol types that define this concept. When unspecified, “”, or *, all hostnames are matched. |
| [6] | `tls` | TLS configuration for the Listener. This field is required if the Protocol field is "HTTPS" or "TLS" and ignored otherwise. |
| [7] | `certificateRef` | The reference to Kubernetes object that contains a TLS certificate and private key. |
| [8] | `routes` | A schema for associating routes with the Listener using selectors. |
| [9] | `kind` | The kind of the referent. |
| [10] | `selector` | Routes in namespaces selected by the selector may be used by this Gateway routes to associate with the Gateway. |
| [11] | `matchLabels` | A set of route labels used for selecting routes to associate with the Gateway. |
Add Kubernetes Gateway Provider Co-authored-by: Jean-Baptiste Doumenjou <925513+jbdoumenjou@users.noreply.github.com>
2020-12-15 15:40:05 +00:00
### Kind: `HTTPRoute`
`HTTPRoute` defines HTTP rules for mapping requests from a `Gateway` to Kubernetes Services.
Register the `HTTPRoute` [definition](../../reference/dynamic-configuration/kubernetes-gateway.md#definitions) in the
Kubernetes cluster before creating `HTTPRoute` objects.
!!! info "Declaring HTTPRoute"
```yaml
kind: HTTPRoute
apiVersion: networking.x-k8s.io/v1alpha1
metadata:
name: http-app-1
namespace: default
Allow crossprovider service reference Co-authored-by: Harold Ozouf <harold.ozouf@gmail.com>
2021-02-02 18:36:04 +00:00
labels: # [1]
Add Kubernetes Gateway Provider Co-authored-by: Jean-Baptiste Doumenjou <925513+jbdoumenjou@users.noreply.github.com>
2020-12-15 15:40:05 +00:00
app: foo
spec:
Allow crossprovider service reference Co-authored-by: Harold Ozouf <harold.ozouf@gmail.com>
2021-02-02 18:36:04 +00:00
hostnames: # [2]
Add Kubernetes Gateway Provider Co-authored-by: Jean-Baptiste Doumenjou <925513+jbdoumenjou@users.noreply.github.com>
2020-12-15 15:40:05 +00:00
- "whoami"
Allow crossprovider service reference Co-authored-by: Harold Ozouf <harold.ozouf@gmail.com>
2021-02-02 18:36:04 +00:00
rules: # [3]
- matches: # [4]
- path: # [5]
type: Exact # [6]
value: /bar # [7]
- headers: # [8]
type: Exact # [9]
values: # [10]
Add Kubernetes Gateway Provider Co-authored-by: Jean-Baptiste Doumenjou <925513+jbdoumenjou@users.noreply.github.com>
2020-12-15 15:40:05 +00:00
- foo: bar
Allow crossprovider service reference Co-authored-by: Harold Ozouf <harold.ozouf@gmail.com>
2021-02-02 18:36:04 +00:00
forwardTo: # [11]
- serviceName: whoami # [12]
weight: 1 # [13]
port: 80 # [14]
- backendRef: # [15]
group: traefik.containo.us # [16]
kind: TraefikService # [17]
name: api@internal # [18]
port: 80
weight: 1
Add Kubernetes Gateway Provider Co-authored-by: Jean-Baptiste Doumenjou <925513+jbdoumenjou@users.noreply.github.com>
2020-12-15 15:40:05 +00:00
```
gatewayapi: adding support for TCPRoute and TLSRoute Co-authored-by: Jean-Baptiste Doumenjou <925513+jbdoumenjou@users.noreply.github.com>
2021-05-20 09:50:12 +00:00
| Ref | Attribute | Description |
|------|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [1] | `labels` | Labels to match with the `Gateway` labelselector. |
| [2] | `hostnames` | A set of hostname that should match against the HTTP Host header to select a HTTPRoute to process the request. |
| [3] | `rules` | A list of HTTP matchers, filters and actions. |
| [4] | `matches` | Conditions used for matching the rule against incoming HTTP requests. Each match is independent, i.e. this rule will be matched if **any** one of the matches is satisfied. |
| [5] | `path` | An HTTP request path matcher. If this field is not specified, a default prefix match on the "/" path is provided. |
| [6] | `type` | Type of match against the path Value (supported types: `Exact`, `Prefix`). |
| [7] | `value` | The value of the HTTP path to match against. |
| [8] | `headers` | Conditions to select a HTTP route by matching HTTP request headers. |
| [9] | `type` | Type of match for the HTTP request header match against the `values` (supported types: `Exact`). |
| [10] | `values` | A map of HTTP Headers to be matched. It MUST contain at least one entry. |
| [11] | `forwardTo` | The upstream target(s) where the request should be sent. |
| [12] | `serviceName` | The name of the referent service. |
| [13] | `weight` | The proportion of traffic forwarded to a targetRef, computed as weight/(sum of all weights in targetRefs). |
| [14] | `port` | The port of the referent service. |
Allow crossprovider service reference Co-authored-by: Harold Ozouf <harold.ozouf@gmail.com>
2021-02-02 18:36:04 +00:00
| [15] | `backendRef` | The BackendRef is a reference to a backend (API object within a known namespace) to forward matched requests to. If both BackendRef and ServiceName are specified, ServiceName will be given precedence. Only `TraefikService` is supported. |
gatewayapi: adding support for TCPRoute and TLSRoute Co-authored-by: Jean-Baptiste Doumenjou <925513+jbdoumenjou@users.noreply.github.com>
2021-05-20 09:50:12 +00:00
| [16] | `group` | Group is the group of the referent. Only `traefik.containo.us` value is supported. |
| [17] | `kind` | Kind is kind of the referent. Only `TraefikService` value is supported. |
| [18] | `name` | Name is the name of the referent. |
### Kind: `TCPRoute`
`TCPRoute` allows mapping TCP requests from a `Gateway` to Kubernetes Services
Register the `TCPRoute` [definition](../../reference/dynamic-configuration/kubernetes-gateway.md#definitions) in the
Kubernetes cluster before creating `TCPRoute` objects.
!!! info "Declaring TCPRoute"
```yaml
kind: TCPRoute
apiVersion: networking.x-k8s.io/v1alpha1
metadata:
name: tcp-app-1
namespace: default
labels: # [1]
app: tcp-app-1
spec:
rules: # [2]
- forwardTo: # [3]
- serviceName: whoamitcp # [4]
weight: 1 # [5]
port: 8080 # [6]
- backendRef: # [7]
group: traefik.containo.us # [8]
kind: TraefikService # [9]
name: api@internal # [10]
```
| Ref | Attribute | Description |
|------|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [1] | `labels` | Labels to match with the `Gateway` labelselector. |
| [2] | `rules` | Rules are a list of TCP matchers and actions. |
| [3] | `forwardTo` | The upstream target(s) where the request should be sent. |
| [4] | `serviceName` | The name of the referent service. |
| [5] | `weight` | The proportion of traffic forwarded to a targetRef, computed as weight/(sum of all weights in targetRefs). |
| [6] | `port` | The port of the referent service. |
| [7] | `backendRef` | The BackendRef is a reference to a backend (API object within a known namespace) to forward matched requests to. If both BackendRef and ServiceName are specified, ServiceName will be given precedence. Only `TraefikService` is supported. |
| [8] | `group` | Group is the group of the referent. Only `traefik.containo.us` value is supported. |
| [9] | `kind` | Kind is kind of the referent. Only `TraefikService` value is supported. |
| [10] | `name` | Name is the name of the referent. |
### Kind: `TLSRoute`
`TLSRoute` allows mapping TLS requests from a `Gateway` to Kubernetes Services
Register the `TLSRoute` [definition](../../reference/dynamic-configuration/kubernetes-gateway.md#definitions) in the
Kubernetes cluster before creating `TLSRoute` objects.
!!! info "Declaring TCPRoute"
```yaml
kind: TLSRoute
apiVersion: networking.x-k8s.io/v1alpha1
metadata:
name: tls-app-1
namespace: default
labels: # [1]
app: tls-app-1
spec:
rules: # [2]
- forwardTo: # [3]
- serviceName: whoamitcp # [4]
weight: 1 # [5]
port: 8080 # [6]
- backendRef: # [7]
group: traefik.containo.us # [8]
kind: TraefikService # [9]
name: api@internal # [10]
```
| Ref | Attribute | Description |
|------|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [1] | `labels` | Labels to match with the `Gateway` labelselector. |
| [2] | `rules` | Rules are a list of TCP matchers and actions. |
| [3] | `forwardTo` | The upstream target(s) where the request should be sent. |
| [4] | `serviceName` | The name of the referent service. |
| [5] | `weight` | The proportion of traffic forwarded to a targetRef, computed as weight/(sum of all weights in targetRefs). |
| [6] | `port` | The port of the referent service. |
| [7] | `backendRef` | The BackendRef is a reference to a backend (API object within a known namespace) to forward matched requests to. If both BackendRef and ServiceName are specified, ServiceName will be given precedence. Only `TraefikService` is supported. |
| [8] | `group` | Group is the group of the referent. Only `traefik.containo.us` value is supported. |
| [9] | `kind` | Kind is kind of the referent. Only `TraefikService` value is supported. |
| [10] | `name` | Name is the name of the referent. |
Reference in a new issue Copy permalink