Enhance documentation readability.
This commit is contained in:
Ludovic Fernandez
Traefiker
parent
6d28c52f59
commit
c7c9349b00
35 changed files with 1044 additions and 577 deletions
|
|
@ -1,6 +1,7 @@
|
|||
# Kubernetes Ingress Controller
|
||||
|
||||
This guide explains how to use Træfik as an Ingress controller in a Kubernetes cluster.
|
||||
|
||||
If you are not familiar with Ingresses in Kubernetes you might want to read the [Kubernetes user guide](https://kubernetes.io/docs/concepts/services-networking/ingress/)
|
||||
|
||||
The config files used in this guide can be found in the [examples directory](https://github.com/containous/traefik/tree/master/examples/k8s)
|
||||
|
|
@ -72,9 +73,10 @@ kubectl apply -f https://raw.githubusercontent.com/containous/traefik/master/exa
|
|||
|
||||
It is possible to use Træfik with a [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) or a [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) object,
|
||||
whereas both options have their own pros and cons:
|
||||
The scalability is much better when using a Deployment, because you will have a Single-Pod-per-Node model when using the DeaemonSet.
|
||||
It is possible to exclusively run a Service on a dedicated set of machines using taints and tolerations with a DaemonSet.
|
||||
On the other hand the DaemonSet allows you to access any Node directly on Port 80 and 443, where you have to setup a [Service](https://kubernetes.io/docs/concepts/services-networking/service/) object with a Deployment.
|
||||
|
||||
- The scalability is much better when using a Deployment, because you will have a Single-Pod-per-Node model when using the DeaemonSet.
|
||||
- It is possible to exclusively run a Service on a dedicated set of machines using taints and tolerations with a DaemonSet.
|
||||
- On the other hand the DaemonSet allows you to access any Node directly on Port 80 and 443, where you have to setup a [Service](https://kubernetes.io/docs/concepts/services-networking/service/) object with a Deployment.
|
||||
|
||||
The Deployment objects looks like this:
|
||||
|
||||
|
|
@ -131,7 +133,8 @@ spec:
|
|||
```
|
||||
[examples/k8s/traefik-deployment.yaml](https://github.com/containous/traefik/tree/master/examples/k8s/traefik-deployment.yaml)
|
||||
|
||||
> The Service will expose two NodePorts which allow access to the ingress and the web interface.
|
||||
!!! note
|
||||
The Service will expose two NodePorts which allow access to the ingress and the web interface.
|
||||
|
||||
The DaemonSet objects looks not much different:
|
||||
|
||||
|
|
@ -198,20 +201,20 @@ spec:
|
|||
To deploy Træfik to your cluster start by submitting one of the YAML files to the cluster with `kubectl`:
|
||||
|
||||
```shell
|
||||
$ kubectl apply -f https://raw.githubusercontent.com/containous/traefik/master/examples/k8s/traefik-deployment.yaml
|
||||
kubectl apply -f https://raw.githubusercontent.com/containous/traefik/master/examples/k8s/traefik-deployment.yaml
|
||||
```
|
||||
|
||||
```shell
|
||||
$ kubectl apply -f https://raw.githubusercontent.com/containous/traefik/master/examples/k8s/traefik-ds.yaml
|
||||
kubectl apply -f https://raw.githubusercontent.com/containous/traefik/master/examples/k8s/traefik-ds.yaml
|
||||
```
|
||||
|
||||
There are some significant differences between using Deployments and DaemonSets.
|
||||
The Deployment has easier up and down scaling possibilities. It can implement full pod lifecycle and supports rolling updates from Kubernetes 1.2.
|
||||
At least one Pod is needed to run the Deployment.
|
||||
The DaemonSet automatically scales to all nodes that meets a specific selector and guarantees to fill nodes one at a time.
|
||||
Rolling updates are fully supported from Kubernetes 1.7 for DaemonSets as well.
|
||||
|
||||
There are some significant differences between using Deployments and DaemonSets:
|
||||
|
||||
- The Deployment has easier up and down scaling possibilities.
|
||||
It can implement full pod lifecycle and supports rolling updates from Kubernetes 1.2.
|
||||
At least one Pod is needed to run the Deployment.
|
||||
- The DaemonSet automatically scales to all nodes that meets a specific selector and guarantees to fill nodes one at a time.
|
||||
Rolling updates are fully supported from Kubernetes 1.7 for DaemonSets as well.
|
||||
|
||||
### Check the Pods
|
||||
|
||||
|
|
@ -220,8 +223,10 @@ Now lets check if our command was successful.
|
|||
Start by listing the pods in the `kube-system` namespace:
|
||||
|
||||
```shell
|
||||
$ kubectl --namespace=kube-system get pods
|
||||
kubectl --namespace=kube-system get pods
|
||||
```
|
||||
|
||||
```
|
||||
NAME READY STATUS RESTARTS AGE
|
||||
kube-addon-manager-minikubevm 1/1 Running 0 4h
|
||||
kubernetes-dashboard-s8krj 1/1 Running 0 4h
|
||||
|
|
@ -231,14 +236,17 @@ traefik-ingress-controller-678226159-eqseo 1/1 Running 0 7m
|
|||
You should see that after submitting the Deployment or DaemonSet to Kubernetes it has launched a Pod, and it is now running.
|
||||
_It might take a few moments for kubernetes to pull the Træfik image and start the container._
|
||||
|
||||
> You could also check the deployment with the Kubernetes dashboard, run
|
||||
> `minikube dashboard` to open it in your browser, then choose the `kube-system`
|
||||
> namespace from the menu at the top right of the screen.
|
||||
!!! note
|
||||
You could also check the deployment with the Kubernetes dashboard, run
|
||||
`minikube dashboard` to open it in your browser, then choose the `kube-system`
|
||||
namespace from the menu at the top right of the screen.
|
||||
|
||||
You should now be able to access Træfik on port 80 of your Minikube instance when using the DaemonSet:
|
||||
|
||||
```sh
|
||||
curl $(minikube ip)
|
||||
```
|
||||
```
|
||||
404 page not found
|
||||
```
|
||||
|
||||
|
|
@ -246,20 +254,24 @@ If you decided to use the deployment, then you need to target the correct NodePo
|
|||
|
||||
```sh
|
||||
curl $(minikube ip):<NODEPORT>
|
||||
```
|
||||
```
|
||||
404 page not found
|
||||
```
|
||||
|
||||
> We expect to see a 404 response here as we haven't yet given Træfik any configuration.
|
||||
!!! note
|
||||
We expect to see a 404 response here as we haven't yet given Træfik any configuration.
|
||||
|
||||
## Deploy Træfik using Helm Chart
|
||||
|
||||
Instead of installing Træfik via an own object, you can also use the Træfik Helm chart.
|
||||
|
||||
This allows more complex configuration via Kubernetes [ConfigMap](https://kubernetes.io/docs/tasks/configure-pod-container/configmap/) and enabled TLS certificates.
|
||||
|
||||
Install Træfik chart by:
|
||||
|
||||
```shell
|
||||
$ helm install stable/traefik
|
||||
helm install stable/traefik
|
||||
```
|
||||
|
||||
For more information, check out [the doc](https://github.com/kubernetes/charts/tree/master/stable/traefik).
|
||||
|
|
@ -305,9 +317,8 @@ kubectl apply -f https://raw.githubusercontent.com/containous/traefik/master/exa
|
|||
|
||||
Now lets setup an entry in our /etc/hosts file to route `traefik-ui.minikube` to our cluster.
|
||||
|
||||
> In production you would want to set up real dns entries.
|
||||
|
||||
> You can get the ip address of your minikube instance by running `minikube ip`
|
||||
In production you would want to set up real dns entries.
|
||||
You can get the ip address of your minikube instance by running `minikube ip`
|
||||
|
||||
```shell
|
||||
echo "$(minikube ip) traefik-ui.minikube" | sudo tee -a /etc/hosts
|
||||
|
|
@ -474,8 +485,8 @@ spec:
|
|||
task: wensleydale
|
||||
```
|
||||
|
||||
> Notice that we also set a [circuit breaker expression](https://docs.traefik.io/basics/#backends) for one of the backends
|
||||
> by setting the `traefik.backend.circuitbreaker` annotation on the service.
|
||||
!!! note
|
||||
We also set a [circuit breaker expression](/basics/#backends) for one of the backends by setting the `traefik.backend.circuitbreaker` annotation on the service.
|
||||
|
||||
|
||||
[examples/k8s/cheese-services.yaml](https://github.com/containous/traefik/tree/master/examples/k8s/cheese-services.yaml)
|
||||
|
|
@ -519,13 +530,15 @@ spec:
|
|||
```
|
||||
[examples/k8s/cheese-ingress.yaml](https://github.com/containous/traefik/tree/master/examples/k8s/cheese-ingress.yaml)
|
||||
|
||||
> Notice that we list each hostname, and add a backend service.
|
||||
!!! note
|
||||
we list each hostname, and add a backend service.
|
||||
|
||||
```shell
|
||||
kubectl apply -f https://raw.githubusercontent.com/containous/traefik/master/examples/k8s/cheese-ingress.yaml
|
||||
```
|
||||
|
||||
Now visit the [Træfik dashboard](http://traefik-ui.minikube/) and you should see a frontend for each host. Along with a backend listing for each service with a Server set up for each pod.
|
||||
Now visit the [Træfik dashboard](http://traefik-ui.minikube/) and you should see a frontend for each host.
|
||||
Along with a backend listing for each service with a Server set up for each pod.
|
||||
|
||||
If you edit your `/etc/hosts` again you should be able to access the cheese websites in your browser.
|
||||
|
||||
|
|
@ -543,7 +556,6 @@ Now lets suppose that our fictional client has decided that while they are super
|
|||
|
||||
No problem, we say, why don't we reconfigure the sites to host all 3 under one domain.
|
||||
|
||||
|
||||
```yaml
|
||||
apiVersion: extensions/v1beta1
|
||||
kind: Ingress
|
||||
|
|
@ -572,9 +584,8 @@ spec:
|
|||
```
|
||||
[examples/k8s/cheeses-ingress.yaml](https://github.com/containous/traefik/tree/master/examples/k8s/cheeses-ingress.yaml)
|
||||
|
||||
> Notice that we are configuring Træfik to strip the prefix from the url path
|
||||
> with the `traefik.frontend.rule.type` annotation so that we can use
|
||||
> the containers from the previous example without modification.
|
||||
!!! note
|
||||
we are configuring Træfik to strip the prefix from the url path with the `traefik.frontend.rule.type` annotation so that we can use the containers from the previous example without modification.
|
||||
|
||||
```shell
|
||||
kubectl apply -f https://raw.githubusercontent.com/containous/traefik/master/examples/k8s/cheeses-ingress.yaml
|
||||
|
|
@ -632,18 +643,20 @@ spec:
|
|||
## Forwarding to ExternalNames
|
||||
|
||||
When specifying an [ExternalName](https://kubernetes.io/docs/concepts/services-networking/service/#services-without-selectors),
|
||||
Træfik will forward requests to the given host accordingly and use HTTPS when the Service port matches 443.
|
||||
Træfik will forward requests to the given host accordingly and use HTTPS when the Service port matches 443.
|
||||
This still requires setting up a proper port mapping on the Service from the Ingress port to the (external) Service port.
|
||||
|
||||
## Disable passing the Host header
|
||||
|
||||
By default Træfik will pass the incoming Host header on to the upstream resource.
|
||||
|
||||
There are times however where you may not want this to be the case.
|
||||
For example if your service is of the ExternalName type.
|
||||
|
||||
### Disable entirely
|
||||
|
||||
Add the following to your toml config:
|
||||
|
||||
```toml
|
||||
disablePassHostHeaders = true
|
||||
```
|
||||
|
|
@ -653,6 +666,7 @@ disablePassHostHeaders = true
|
|||
To disable passing the Host header per ingress resource set the `traefik.frontend.passHostHeader` annotation on your ingress to `false`.
|
||||
|
||||
Here is an example ingress definition:
|
||||
|
||||
```yaml
|
||||
apiVersion: extensions/v1beta1
|
||||
kind: Ingress
|
||||
|
|
@ -673,6 +687,7 @@ spec:
|
|||
```
|
||||
|
||||
And an example service definition:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
|
|
@ -696,6 +711,7 @@ If you were to visit `example.com/static` the request would then be passed onto
|
|||
## Excluding an ingress from Træfik
|
||||
|
||||
You can control which ingress Træfik cares about by using the `kubernetes.io/ingress.class` annotation.
|
||||
|
||||
By default if the annotation is not set at all Træfik will include the ingress.
|
||||
If the annotation is set to anything other than traefik or a blank string Træfik will ignore it.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue