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

Documentation enhancements

Browse source
This commit is contained in:
sven 2024-01-02 17:30:06 +01:00 • committed by GitHub
parent 0e92b02474
commit cd7d324295
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
8 changed files with 48 additions and 47 deletions
Download patch file Download diff file Expand all files Collapse all files

4
docs/content/getting-started/configuration-overview.md
View file

@ -82,11 +82,11 @@ docker run traefik[:version] --help
# ex: docker run traefik:v2.10 --help
```
All available arguments can also be found [here](../reference/static-configuration/cli.md).
Check the [CLI reference](../reference/static-configuration/cli.md "Link to CLI reference overview") for an overview about all available arguments.
### Environment Variables
All available environment variables can be found [here](../reference/static-configuration/env.md)
All available environment variables can be found in the [static configuration environment overview](../reference/static-configuration/env.md).
## Available Configuration Options

16
docs/content/getting-started/faq.md
View file

@ -29,7 +29,7 @@ Not to mention that dynamic configuration changes potentially make that kind of
Therefore, in this dynamic context,
the static configuration of an `entryPoint` does not give any hint whatsoever about how the traffic going through that `entryPoint` is going to be routed.
Or whether it's even going to be routed at all,
i.e. whether there is a Router matching the kind of traffic going through it.
that is whether there is a Router matching the kind of traffic going through it.
### `404 Not found`
@ -71,7 +71,7 @@ Traefik returns a `502` response code when an error happens while contacting the
### `503 Service Unavailable`
Traefik returns a `503` response code when a Router has been matched
Traefik returns a `503` response code when a Router has been matched,
but there are no servers ready to handle the request.
This situation is encountered when a service has been explicitly configured without servers,
@ -84,7 +84,7 @@ Sometimes, the `404` response code doesn't play well with other parties or servi
In these situations, you may want Traefik to always reply with a `503` response code,
instead of a `404` response code.
To achieve this behavior, a simple catchall router,
To achieve this behavior, a catchall router,
with the lowest possible priority and routing to a service without servers,
can handle all the requests when no other router has been matched.
@ -130,7 +130,7 @@ http:
the principle of the above example above (a catchall router) still stands,
but the `unavailable` service should be adapted to fit such a need.
## Why Is My TLS Certificate Not Reloaded When Its Contents Change?
## Why Is My TLS Certificate Not Reloaded When Its Contents Change?
With the file provider,
a configuration update is only triggered when one of the [watched](../providers/file.md#provider-configuration) configuration files is modified.
@ -216,7 +216,7 @@ error: field not found, node: -badField-
The "field not found" error occurs, when an unknown property is encountered in the dynamic or static configuration.
One easy way to check whether a configuration file is well-formed, is to validate it with:
One way to check whether a configuration file is well-formed, is to validate it with:
- [JSON Schema of the static configuration](https://json.schemastore.org/traefik-v2.json)
- [JSON Schema of the dynamic configuration](https://json.schemastore.org/traefik-v2-file-provider.json)
@ -226,11 +226,11 @@ One easy way to check whether a configuration file is well-formed, is to validat
As a common tip, if a resource is dropped/not created by Traefik after the dynamic configuration was evaluated,
one should look for an error in the logs.
If found, the error obviously confirms that something went wrong while creating the resource,
If found, the error confirms that something went wrong while creating the resource,
and the message should help in figuring out the mistake(s) in the configuration, and how to fix it.
When using the file provider,
one easy way to check if the dynamic configuration is well-formed is to validate it with the [JSON Schema of the dynamic configuration](https://json.schemastore.org/traefik-v2-file-provider.json).
one way to check if the dynamic configuration is well-formed is to validate it with the [JSON Schema of the dynamic configuration](https://json.schemastore.org/traefik-v2-file-provider.json).
## Why does Let's Encrypt wildcard certificate renewal/generation with DNS challenge fail?
@ -248,6 +248,6 @@ then it could be due to `CNAME` support.
In which case, you should make sure your infrastructure is properly set up for a
`DNS` challenge that does not rely on `CNAME`, and you should try disabling `CNAME` support with:
```bash
```shell
LEGO_DISABLE_CNAME_SUPPORT=true
```

8
docs/content/getting-started/install-traefik.md
View file

@ -19,7 +19,7 @@ Choose one of the [official Docker images](https://hub.docker.com/_/traefik) and
* [YAML](https://raw.githubusercontent.com/traefik/traefik/v2.10/traefik.sample.yml)
* [TOML](https://raw.githubusercontent.com/traefik/traefik/v2.10/traefik.sample.toml)
```bash
```shell
docker run -d -p 8080:8080 -p 80:80 \
-v $PWD/traefik.yml:/etc/traefik/traefik.yml traefik:v2.10
```
@ -59,7 +59,7 @@ You can update the chart repository by running:
helm repo update
```
And install it with the `helm` command line:
And install it with the Helm command line:
```bash
helm install traefik traefik/traefik
@ -69,7 +69,7 @@ helm install traefik traefik/traefik
All [Helm features](https://helm.sh/docs/intro/using_helm/) are supported.
Examples are provided [here](https://github.com/traefik/traefik-helm-chart/blob/master/EXAMPLES.md).
Examples are provided [here](https://github.com/traefik/traefik-helm-chart/blob/master/EXAMPLES.md).
For instance, installing the chart in a dedicated namespace:
@ -106,7 +106,7 @@ helm install traefik traefik/traefik
### Exposing the Traefik dashboard
This HelmChart does not expose the Traefik dashboard by default, for security concerns.
This Helm chart does not expose the Traefik dashboard by default, for security concerns.
Thus, there are multiple ways to expose the dashboard.
For instance, the dashboard access could be achieved through a port-forward:

36
docs/content/getting-started/quick-start-with-kubernetes.md
View file

@ -1,23 +1,23 @@
---
title: "Traefik Getting Started With Kubernetes"
description: "Looking to get started with Traefik Proxy? Read the technical documentation to learn a simple use case that leverages Kubernetes."
description: "Get started with Traefik Proxy and Kubernetes."
---
# Quick Start
A Simple Use Case of Traefik Proxy and Kubernetes
A Use Case of Traefik Proxy and Kubernetes
{: .subtitle }
This guide is an introduction to using Traefik Proxy in a Kubernetes environment.
The objective is to learn how to run an application behind a Traefik reverse proxy in Kubernetes.
This guide is an introduction to using Traefik Proxy in a Kubernetes environment.
The objective is to learn how to run an application behind a Traefik reverse proxy in Kubernetes.
It presents and explains the basic blocks required to start with Traefik such as Ingress Controller, Ingresses, Deployments, static, and dynamic configuration.
## Permissions and Accesses
Traefik uses the Kubernetes API to discover running services.
In order to use the Kubernetes API, Traefik needs some permissions.
This [permission mechanism](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) is based on roles defined by the cluster administrator.
To use the Kubernetes API, Traefik needs some permissions.
This [permission mechanism](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) is based on roles defined by the cluster administrator.
The role is then bound to an account used by an application, in this case, Traefik Proxy.
The first step is to create the role.
@ -88,7 +88,7 @@ roleRef:
subjects:
- kind: ServiceAccount
name: traefik-account
namespace: default # Using "default" because we did not specify a namespace when creating the ClusterAccount.
namespace: default # This tutorial uses the "default" K8s namespace.
```
!!! info "`roleRef` is the Kubernetes reference to the role created in `00-role.yml`."
@ -102,7 +102,7 @@ subjects:
!!! info "This section can be managed with the help of the [Traefik Helm chart](../install-traefik/#use-the-helm-chart)."
The [ingress controller](https://traefik.io/glossary/kubernetes-ingress-and-ingress-controller-101/#what-is-a-kubernetes-ingress-controller)
is a software that runs in the same way as any other application on a cluster.
is a software that runs in the same way as any other application on a cluster.
To start Traefik on the Kubernetes cluster,
a [`Deployment`](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/deployment-v1/) resource must exist to describe how to configure
and scale containers horizontally to support larger workloads.
@ -141,12 +141,12 @@ spec:
containerPort: 8080
```
The deployment contains an important attribute for customizing Traefik: `args`.
These arguments are the static configuration for Traefik.
The deployment contains an important attribute for customizing Traefik: `args`.
These arguments are the static configuration for Traefik.
From here, it is possible to enable the dashboard,
configure entry points,
select dynamic configuration providers,
and [more](../reference/static-configuration/cli.md)...
and [more](../reference/static-configuration/cli.md).
In this deployment,
the static configuration enables the Traefik dashboard,
@ -159,10 +159,10 @@ and uses Kubernetes native Ingress resources as router definitions to route inco
!!! info "When enabling the [`api.insecure`](../../operations/api/#insecure) mode, Traefik exposes the dashboard on the port `8080`."
A deployment manages scaling and then can create lots of containers, called [Pods](https://kubernetes.io/docs/concepts/workloads/pods/).
Each Pod is configured following the `spec` field in the deployment.
Each Pod is configured following the `spec` field in the deployment.
Given that, a Deployment can run multiple Traefik Proxy Pods,
a piece is required to forward the traffic to any of the instance:
namely a [`Service`](https://kubernetes.io/docs/reference/kubernetes-api/service-resources/service-v1/#Service).
namely a [`Service`](https://kubernetes.io/docs/reference/kubernetes-api/service-resources/service-v1/#Service).
Create a file called `02-traefik-services.yml` and insert the two `Service` resources:
```yaml tab="02-traefik-services.yml"
@ -195,7 +195,7 @@ spec:
!!! warning "It is possible to expose a service in different ways."
Depending on your working environment and use case, the `spec.type` might change.
Depending on your working environment and use case, the `spec.type` might change.
It is strongly recommended to understand the available [service types](https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types) before proceeding to the next step.
It is now time to apply those files on your cluster to start Traefik.
@ -210,11 +210,11 @@ kubectl apply -f 00-role.yml \
## Proxying applications
The only part still missing is the business application behind the reverse proxy.
The only part still missing is the business application behind the reverse proxy.
For this guide, we use the example application [traefik/whoami](https://github.com/traefik/whoami),
but the principles are applicable to any other application.
The `whoami` application is a simple HTTP server running on port 80 which answers host-related information to the incoming requests.
The `whoami` application is an HTTP server running on port 80 which answers host-related information to the incoming requests.
As usual, start by creating a file called `03-whoami.yml` and paste the following `Deployment` resource:
```yaml tab="03-whoami.yml"
@ -262,8 +262,8 @@ spec:
```
Thanks to the Kubernetes API,
Traefik is notified when an Ingress resource is created, updated, or deleted.
This makes the process dynamic.
Traefik is notified when an Ingress resource is created, updated, or deleted.
This makes the process dynamic.
The ingresses are, in a way, the [dynamic configuration](../../providers/kubernetes-ingress/) for Traefik.
!!! tip

14
docs/content/getting-started/quick-start.md
View file

@ -1,11 +1,11 @@
---
title: "Traefik Getting Started Quickly"
description: "Looking to get started with Traefik Proxy quickly? Read the technical documentation to learn a simple use case that leverages Docker."
description: "Get started with Traefik Proxy and Docker."
---
# Quick Start
A Simple Use Case Using Docker
A Use Case Using Docker
{: .subtitle }
![quickstart-diagram](../assets/img/quickstart-diagram.png)
@ -41,11 +41,11 @@ Start your `reverse-proxy` with the following command:
docker-compose up -d reverse-proxy
```
You can open a browser and go to `http://localhost:8080/api/rawdata` to see Traefik's API rawdata (we'll go back there once we have launched a service in step 2).
You can open a browser and go to `http://localhost:8080/api/rawdata` to see Traefik's API rawdata (you'll go back there once you have launched a service in step 2).
## Traefik Detects New Services and Creates the Route for You
Now that we have a Traefik instance up and running, we will deploy new services.
Now that you have a Traefik instance up and running, you will deploy new services.
Edit your `docker-compose.yml` file and add the following at the end of your file.
@ -63,7 +63,7 @@ services:
- "traefik.http.routers.whoami.rule=Host(`whoami.docker.localhost`)"
```
The above defines `whoami`: a simple web service that outputs information about the machine it is deployed on (its IP address, host, and so on).
The above defines `whoami`: a web service that outputs information about the machine it is deployed on (its IP address, host, and others).
Start the `whoami` service with the following command:
@ -73,7 +73,7 @@ docker-compose up -d whoami
Go back to your browser (`http://localhost:8080/api/rawdata`) and see that Traefik has automatically detected the new container and updated its own configuration.
When Traefik detects new services, it creates the corresponding routes so you can call them ... _let's see!_ (Here, we're using curl)
When Traefik detects new services, it creates the corresponding routes so you can call them ... _let's see!_ (Here, you're using curl)
```shell
curl -H Host:whoami.docker.localhost http://127.0.0.1
@ -103,7 +103,7 @@ Finally, see that Traefik load-balances between the two instances of your servic
curl -H Host:whoami.docker.localhost http://127.0.0.1
```
The output will show alternatively one of the followings:
The output will show alternatively one of the following:
```yaml
Hostname: a656c8ddca6c