Add secret creation to docs for kubernetes backend #2374
Conversation
| @@ -121,7 +121,7 @@ Is possible to add additional authentication annotations in the Ingress rule. | |||
| The source of the authentication is a secret that contains usernames and passwords inside the the key auth. | |||
|
|
|||
| - `ingress.kubernetes.io/auth-type`: `basic` | |||
| - `ingress.kubernetes.io/auth-secret` | |||
| Enable backend sticky sessions (DEPRECATED) | ||
|
|
||
| You can find here an example [ingress](https://raw.githubusercontent.com/containous/traefik/master/examples/k8s/cheese-ingress.yaml) and [replication controller](https://raw.githubusercontent.com/containous/traefik/master/examples/k8s/traefik.yaml). | ||
|
|
||
| Additionally, an annotation can be used on Kubernetes services to set the [circuit breaker expression](/basics/#backends) for a backend. | ||
|
|
||
| - `traefik.backend.circuitbreaker: <expression>` |
| @@ -84,27 +84,27 @@ See [label-selectors](https://kubernetes.io/docs/concepts/overview/working-with- | |||
|
|
|||
| Annotations can be used on containers to override default behaviour for the whole Ingress resource: | |||
|
|
|||
| - `traefik.frontend.rule.type: PathPrefixStrip` | |||
| Override the default frontend rule type. Default: `PathPrefix`. | ||
| - `traefik.frontend.priority: "3"` | ||
| Override the default frontend rule priority. | ||
|
|
||
| Annotations can be used on the Kubernetes service to override default behaviour: | ||
|
|
||
| - `traefik.backend.loadbalancer.method=drr` |
| Override the default `wrr` load balancer algorithm | ||
| - `traefik.backend.loadbalancer.stickiness=true` |
There was a problem hiding this comment.
could you restore the spaces? (just keep 2 spaces)
| Manually set the cookie name for sticky sessions | ||
| - `traefik.backend.loadbalancer.sticky=true` |
There was a problem hiding this comment.
could you restore the spaces? (just keep 2 spaces)
docs/user-guide/kubernetes.md
Outdated
| @@ -75,9 +75,9 @@ For namespaced restrictions, one RoleBinding is required per watched namespace a | |||
|
|
|||
| 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. | |||
docs/user-guide/kubernetes.md
Outdated
| @@ -75,9 +75,9 @@ For namespaced restrictions, one RoleBinding is required per watched namespace a | |||
|
|
|||
| 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. | |||
docs/user-guide/kubernetes.md
Outdated
| @@ -321,7 +321,7 @@ 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. | |||
docs/user-guide/kubernetes.md
Outdated
| @@ -627,7 +680,7 @@ Note that priority values must be quoted to avoid them being interpreted as numb | |||
| ## 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. | |||
|
@ldez I have fixed my editor to stop doing that =) Spaces are back in place. |
docs/user-guide/kubernetes.md
Outdated
| @@ -330,6 +330,59 @@ echo "$(minikube ip) traefik-ui.minikube" | sudo tee -a /etc/hosts | |||
|
|
|||
| We should now be able to visit [traefik-ui.minikube](http://traefik-ui.minikube) in the browser and view the Træfik Web UI. | |||
|
|
|||
| ## Basic Authentication | |||
| Is possible to add additional authentication annotations in the Ingress rule. The source of the authentication is a secret that contains usernames and passwords inside the the key auth. | |||
There was a problem hiding this comment.
Could you please add a blank line after the heading?
docs/user-guide/kubernetes.md
Outdated
| * Basic authentication only | ||
| * Realm not configurable; only traefikdefault | ||
| * Secret is in same namespace as ingress rule | ||
| * Secret must contain only single file |
There was a problem hiding this comment.
The whole paragraph basically duplicates what can already be found in the Kubernetes configuration documentation. Instead of repeating, I suggest we only mention that a certain number of restrictions exist in general, and leave a pointer where to find them.
docs/user-guide/kubernetes.md
Outdated
|
|
||
| #### Creating the Secret | ||
|
|
||
| 1. `htpasswd -c ./auth myusername` |
There was a problem hiding this comment.
Can you prepend the actual htpasswd call by a sentence explaining what we're doing? Something like Use htpasswd to create a file containing the username and the base64-encoded password:
docs/user-guide/kubernetes.md
Outdated
| myusername:$apr1$78Jyn/1K$ERHKVRPPlzAX8eBtLuvRZ0 | ||
| ``` | ||
|
|
||
| 2. `kubectl --namespace=monitoring create secret generic mysecret --from-file auth` |
There was a problem hiding this comment.
A quick sentence here that we are creating a secret containing the htpasswd file in a namespace called monitoring?
docs/user-guide/kubernetes.md
Outdated
|
|
||
| **Note:** Secret must be in same namespace as the ingress rule. | ||
|
|
||
| 3. Now we will create our ingress using the following annotations to specify we want basic auth and that the username and password is stored in "mysecret". |
There was a problem hiding this comment.
Can you replace the we form by you / the imperative in order to be consistent with the rest of the guide? That is, rephrase the sentence like
Create the ingress using the following annotations to specify basic auth and that the username and password are stored in "mysecret".
docs/user-guide/kubernetes.md
Outdated
| - `ingress.kubernetes.io/auth-type: "basic"` | ||
| - `ingress.kubernetes.io/auth-secret: "mysecret"` | ||
|
|
||
| I saved the following in prometheus-ingress.yaml... |
There was a problem hiding this comment.
Let's use the passive form in the phrasing like
Following is a full ingress example based on Prometheus:
docs/user-guide/kubernetes.md
Outdated
| servicePort: 80 | ||
| ``` | ||
|
|
||
| `kubectl create -f prometheus-ingress.yaml -n monitoring` |
There was a problem hiding this comment.
Another short explanation like
You can apply the example as following:
|
@timoreimann I didn't know the docs in the repo were used to generate the site. Let me clean that up. |
docs/user-guide/kubernetes.md
Outdated
| @@ -330,6 +330,61 @@ echo "$(minikube ip) traefik-ui.minikube" | sudo tee -a /etc/hosts | |||
|
|
|||
| We should now be able to visit [traefik-ui.minikube](http://traefik-ui.minikube) in the browser and view the Træfik Web UI. | |||
|
|
|||
| ## Basic Authentication | |||
|
|
|||
| It's possible to add additional authentication annotations in the Ingress rule. The source of the authentication is a secret that contains usernames and passwords inside the the key auth. To read about basic auth limitations see the [Kubernetes Ingress](https://docs.traefik.io/configuration/backends/kubernetes/) configuration page. | |||
There was a problem hiding this comment.
It should be possible to use a relative URL like /configuration/backends/kubernetes. For an example, see here (3rd line from the top; note that it's the "reverse direction" but it's conceptually the same).
|
@timoreimann Link is working inside your neat little deploy preview =) |
|
@timoreimann something is wrong with code block now let me look into it. |
docs/user-guide/kubernetes.md
Outdated
| @@ -330,6 +330,61 @@ echo "$(minikube ip) traefik-ui.minikube" | sudo tee -a /etc/hosts | |||
|
|
|||
| We should now be able to visit [traefik-ui.minikube](http://traefik-ui.minikube) in the browser and view the Træfik Web UI. | |||
|
|
|||
| ## Basic Authentication | |||
|
|
|||
| It's possible to add additional authentication annotations in the Ingress rule. The source of the authentication is a secret that contains usernames and passwords inside the the key auth. To read about basic auth limitations see the [Kubernetes Ingress](/configuration/backends/kubernetes) configuration page. | |||
There was a problem hiding this comment.
Could put one sentence by line?
There was a problem hiding this comment.
Move the sentence up a line? @ldez
docs/user-guide/kubernetes.md
Outdated
|
|
||
| 1. Use `htpasswd` to create a file containing the username and the base64-encoded password: | ||
|
|
||
| `htpasswd -c ./auth myusername` |
There was a problem hiding this comment.
could you use this syntax:
```
htpasswd -c ./auth myusername
```
docs/user-guide/kubernetes.md
Outdated
| a file with the following: | ||
|
|
||
| ``` | ||
| ~$ cat auth |
docs/user-guide/kubernetes.md
Outdated
|
|
||
| 2. Now use `kubectl` to create a secret in the monitoring namespace using the file created by `htpasswd`. | ||
|
|
||
| `kubectl create secret generic mysecret --from-file auth --namespace=monitoring` |
There was a problem hiding this comment.
could you use this syntax:
```
kubectl create secret generic mysecret --from-file auth --namespace=monitoring
```
docs/user-guide/kubernetes.md
Outdated
|
|
||
| You can apply the example ingress as following: | ||
|
|
||
| `kubectl create -f prometheus-ingress.yaml -n monitoring` |
There was a problem hiding this comment.
could you use this syntax:
```
kubectl create -f prometheus-ingress.yaml -n monitoring
```
docs/user-guide/kubernetes.md
Outdated
|
|
||
| Following is a full ingress example based on Prometheus: | ||
|
|
||
| ```yaml |
There was a problem hiding this comment.
@ldez FWIW, except for one case, the guide uses yaml everywhere else.
There was a problem hiding this comment.
Could you remove all spaces at the start of each line of all code blocks?
https://github.com/containous/traefik/blob/master/CONTRIBUTING.md#documentation
docs/user-guide/kubernetes.md
Outdated
| 3. Create the ingress using the following annotations to specify basic auth and that the username and password is stored in "mysecret". | ||
|
|
||
| - ingress.kubernetes.io/auth-type: "basic" | ||
| - ingress.kubernetes.io/auth-secret: "mysecret" |
There was a problem hiding this comment.
Could you surround each annotation with backticks?
|
Looks better but the numbers are wrong for the steps |
|
@ldez Nice, It finally looks right =) |
docs/user-guide/kubernetes.md
Outdated
| ## Basic Authentication | ||
|
|
||
| It's possible to add additional authentication annotations in the Ingress rule. | ||
| The source of the authentication is a secret that contains usernames and passwords inside the the key auth. |
There was a problem hiding this comment.
Please remove one of the the in the the key auth.
There was a problem hiding this comment.
@nmengin that typo appears to have been in the code base... It's live on the docs site.
|
@shadycuz could you remove the 2 merge commits? I will rebase your PR on 1.4 branch when it will ready |
|
Sure
|
| ```shell | ||
| cat auth | ||
| ``` | ||
| ``` |
There was a problem hiding this comment.
Is the extra block intentional? It looks a bit strange on the rendered output.
I'd suggest to simply drop the cat auth part. It's clear from the paragraph right above that we're talking about the content of the auth file, no need to show the extra cat call IMHO.
There was a problem hiding this comment.
I have split the block: because it's more easy to copy-paste (with the end of block button)
|
waiting for me to undo the merges or not? |
|
Ah yeah, if you haven't done so yet and @ldez asked for it, you should do it. Should hopefully not affect my LGTM though. |
|
Cool I think it worked, I did a hard reset to before the merges, and then noticed the cat was mising, added it back and pushed. |
What does this PR do?
Adds additional documentation to help people setup basic auth with kubernetes ingress.
Motivation
I was unable to easily find the information I needed to create the secret. I had to resort to tracking down the original PR for that feature.
More
Additional Notes
I think the instructions to create the dashboard auth user and password (types of encryption) is the same for adding auth to an ingress but I could not confirm so I let it as is.
Note: Sublime must have removed some invisible trailing spaces, I see a bunch of lines that are modified but not changed.