baalajimaestro/traefik
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

doc: kubernetes CRD provider

Browse source 
Co-authored-by: Jean-Baptiste Doumenjou <jb.doumenjou@gmail.com>
This commit is contained in:
mpl 2019-03-19 16:44:06 +01:00 committed by Traefiker Bot
parent f346251719
commit c4b7e8f288
9 changed files with 299 additions and 8 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
docs/content/middlewares/addprefix.md
View file

@ -26,6 +26,18 @@ The AddPrefix middleware updates the URL Path of the request before forwarding i
- "traefik.http.middlewares.add-bar.addprefix.prefix=/bar"
```
??? example "Kubernetes -- Prefixing with /bar"
```yaml
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
name: addprefix
spec:
addprefix:
prefix: /bar
```
## Configuration Options
### prefix

39
docs/content/middlewares/overview.md
View file

@ -48,6 +48,45 @@ Pieces of middleware can be combined in chains to fit every scenario.
- "traefik.http.middlewares.foo-add-prefix.addprefix.prefix=/foo",
```
??? example "As a Kubernetes Traefik IngressRoute"
```yaml
apiVersion: apiextensions.k8s.io/v1beta1
kind: CustomResourceDefinition
metadata:
name: middlewares.traefik.containo.us
spec:
group: traefik.containo.us
version: v1alpha1
names:
kind: Middleware
plural: middlewares
singular: middleware
scope: Namespaced
---
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
name: stripprefix
spec:
stripprefix:
prefixes:
- /stripit
---
apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
name: ingressroute.crd
spec:
# more fields...
routes:
# more fields...
middleware:
- name: stripprefix
```
## Advanced Configuration
When you declare a middleware, it lives in its `provider` namespace.

13
docs/content/providers/crd_ingress_route.yml Normal file
View file

@ -0,0 +1,13 @@
apiVersion: apiextensions.k8s.io/v1beta1
kind: CustomResourceDefinition
metadata:
name: ingressroutes.traefik.containo.us
spec:
group: traefik.containo.us
version: v1alpha1
names:
kind: IngressRoute
plural: ingressroutes
singular: ingressroute
scope: Namespaced

13
docs/content/providers/crd_middlewares.yml Normal file
View file

@ -0,0 +1,13 @@
apiVersion: apiextensions.k8s.io/v1beta1
kind: CustomResourceDefinition
metadata:
name: middlewares.traefik.containo.us
spec:
group: traefik.containo.us
version: v1alpha1
names:
kind: Middleware
plural: middlewares
singular: middleware
scope: Namespaced

122
docs/content/providers/kubernetes-crd.md Normal file
View file

@ -0,0 +1,122 @@
# Traefik & Kubernetes
The Kubernetes Ingress Controller, The Custom Resource Way.
{: .subtitle }
[comment]: # (Link "Kubernetes Ingress controller" to ./kubernetes-ingress.md)
The Traefik Kubernetes provider used to be a Kubernetes Ingress controller in the strict sense of the term; that is to say,
it would manage access to a cluster services by supporting the [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) specification.
However, as the community expressed the need to benefit from Traefik features without resorting to (lots of) annotations,
we ended up writing a [Custom Resource Definition](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) (alias CRD in the following) for an IngressRoute type, defined below, in order to provide a better way to configure access to a Kubernetes cluster.
## Traefik IngressRoute definition
```yaml
--8<-- "content/providers/crd_ingress_route.yml"
```
That `IngressRoute` kind can then be used to define an `IngressRoute` object, such as:
```yaml
apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
name: ingressroutefoo.crd
spec:
entrypoints:
- web
routes:
# Match is the rule corresponding to an underlying router.
# Later on, match could be the simple form of a path prefix, e.g. just "/bar",
# but for now we only support a traefik style matching rule.
- match: Host(`foo.com`) && PathPrefix(`/bar`)
# kind could eventually be one of "Rule", "Path", "Host", "Method", "Header",
# "Parameter", etc, to support simpler forms of rule matching, but for now we
# only support "Rule".
kind: Rule
# Priority disambiguates rules of the same length, for route matching.
priority: 12
services:
- name: whoami
port: 80
```
## Middleware
Additionally, to allow for the use of middlewares in an `IngressRoute`, we defined the CRD below for the `Middleware` kind.
```yaml
--8<-- "content/providers/crd_middlewares.yml"
```
Once the `Middleware` kind has been registered with the Kubernetes cluster, it can then be used in `IngressRoute` definitions, such as:
```yaml
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
name: stripprefix
spec:
stripprefix:
prefixes:
- /stripit
---
apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
name: ingressroutebar.crd
spec:
entrypoints:
- web
routes:
- match: Host(`bar.com`) && PathPrefix(`/stripit`)
kind: Rule
services:
- name: whoami
port: 80
middlewares:
- name: stripprefix
```
## TLS
To allow for TLS, we made use of the `Secret` kind, as it was already defined, and it can be directly used in an `IngressRoute`:
```yaml
apiVersion: v1
kind: Secret
metadata:
name: supersecret
data:
tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=
tls.key: LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCi0tLS0tRU5EIFBSSVZBVEUgS0VZLS0tLS0=
---
apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
name: ingressroutetls.crd
spec:
entryPoints:
- web
routes:
- match: Host(`foo.com`) && PathPrefix(`/bar`)
kind: Rule
services:
- name: whoami
port: 443
tls:
secretName: supersecret
```
## Full reference example
[Traefik IngressRoute Reference](../reference/providers/kubernetescrd.md).

6
docs/content/providers/kubernetes-ingress.md Normal file
View file

@ -0,0 +1,6 @@
# Traefik & Kubernetes
Kubernetes Ingress.
{: .subtitle }
TODO

18
docs/content/providers/overview.md
View file

@ -8,7 +8,8 @@ Traefik's Many Friends
Configuration discovery in Traefik is achieved through _Providers_.
The _providers_ are existing infrastructure components, whether orchestrators, container engines, cloud providers, or key-value stores.
The idea is that Traefik will query the providers' API in order to find relevant information about routing, and each time Traefik detects a change, it dynamically updates the routes.
The idea is that Traefik will query the providers' API in order to find relevant information about routing,
and each time Traefik detects a change, it dynamically updates the routes.
Deploy and forget is Traefik's credo.
@ -25,12 +26,12 @@ Even if each provider is different, we can categorize them in four groups:
Below is the list of the currently supported providers in Traefik.
| Provider | Type | Configuration Type |
|-----------------------------|--------------|--------------------|
| [Docker](./docker.md) | Orchestrator | Label |
| [File](./file.md) | Orchestrator | Custom Annotation |
| Kubernetes (not documented) | Orchestrator | Custom Annotation |
| Marathon (not documented) | Orchestrator | Label |
| Provider | Type | Configuration Type |
|---------------------------------|--------------|--------------------|
| [Docker](./docker.md) | Orchestrator | Label |
| [File](./file.md) | Orchestrator | Custom Annotation |
| [Kubernetes](kubernetes-crd.md) | Orchestrator | Custom Resource |
| Marathon (not yet documented) | Orchestrator | Label |
!!! note "More Providers"
@ -38,7 +39,8 @@ Below is the list of the currently supported providers in Traefik.
## Constraints Configuration
If you want to limit the scope of Traefik service discovery, you can set constraints. Doing so, Traefik will create routes for containers that match these constraints only.
If you want to limit the scope of Traefik service discovery, you can set constraints.
Doing so, Traefik will create routes for containers that match these constraints only.
??? example "Containers with the api Tag"

81
docs/content/reference/providers/kubernetescrd.md Normal file
View file

@ -0,0 +1,81 @@
# Kubernetes -- Reference
## Kubernetes
```yaml
################################################################
# Kubernetes Provider
################################################################
apiVersion: apiextensions.k8s.io/v1beta1
kind: CustomResourceDefinition
metadata:
name: ingressroutes.traefik.containo.us
spec:
group: traefik.containo.us
version: v1alpha1
names:
kind: IngressRoute
plural: ingressroutes
singular: ingressroute
scope: Namespaced
---
apiVersion: apiextensions.k8s.io/v1beta1
kind: CustomResourceDefinition
metadata:
name: middlewares.traefik.containo.us
spec:
group: traefik.containo.us
version: v1alpha1
names:
kind: Middleware
plural: middlewares
singular: middleware
scope: Namespaced
---
apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
name: ingressroute.crd
spec:
entrypoints:
- web
- web-secure
routes:
- match: Host(`foo.com`) && PathPrefix(`/bar`)
kind: Rule
priority: 12
# defining several services is possible and allowed, but for now the servers of
# all the services (for a given route) get merged altogether under the same
# load-balancing strategy.
services:
- name: s1
port: 80
healthcheck:
path: /health
host: baz.com
intervalseconds: 7
timeoutseconds: 60
# strategy defines the load balancing strategy between the servers. It defaults
# to Round Robin, and for now only Round Robin is supported anyway.
strategy: RoundRobin
- name: s2
port: 433
healthcheck:
path: /health
host: baz.com
intervalseconds: 7
timeoutseconds: 60
- match: PathPrefix(`/misc`)
services:
- name: s3
port: 80
middleware:
- name: stripprefix
- name: addprefix
tls:
secretName: supersecret
```

3
docs/mkdocs.yml
View file

@ -66,9 +66,11 @@ markdown_extensions:
# Page tree
nav:
- '': 'providers/kubernetes-ingress.md'
- '': 'reference/acme.md'
- '': 'reference/providers/docker.md'
- '': 'reference/providers/file.md'
- '': 'reference/providers/kubernetescrd.md'
- '': 'reference/entrypoints.md'
- 'Welcome': 'index.md'
- 'Getting Started':
@ -79,6 +81,7 @@ nav:
- 'Overview': 'providers/overview.md'
- 'Docker': 'providers/docker.md'
- 'File': 'providers/file.md'
- 'Kubernetes IngressRoute': 'providers/kubernetes-crd.md'
- 'Routing & Load Balancing':
- 'Overview': 'routing/overview.md'
- 'Entrypoints': 'routing/entrypoints.md'