baalajimaestro/traefik
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 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
Show stats 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 # 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 ### 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 ## 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, 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. 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, 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` ### `404 Not found`
@ -71,7 +71,7 @@ Traefik returns a `502` response code when an error happens while contacting the
### `503 Service Unavailable` ### `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. but there are no servers ready to handle the request.
This situation is encountered when a service has been explicitly configured without servers, 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, In these situations, you may want Traefik to always reply with a `503` response code,
instead of a `404` 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, with the lowest possible priority and routing to a service without servers,
can handle all the requests when no other router has been matched. 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, the principle of the above example above (a catchall router) still stands,
but the `unavailable` service should be adapted to fit such a need. 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, With the file provider,
a configuration update is only triggered when one of the [watched](../providers/file.md#provider-configuration) configuration files is modified. 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. 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 static configuration](https://json.schemastore.org/traefik-v2.json)
- [JSON Schema of the dynamic configuration](https://json.schemastore.org/traefik-v2-file-provider.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, 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. 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. and the message should help in figuring out the mistake(s) in the configuration, and how to fix it.
When using the file provider, 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? ## 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 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: `DNS` challenge that does not rely on `CNAME`, and you should try disabling `CNAME` support with:
```bash ```shell
LEGO_DISABLE_CNAME_SUPPORT=true 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) * [YAML](https://raw.githubusercontent.com/traefik/traefik/v2.10/traefik.sample.yml)
* [TOML](https://raw.githubusercontent.com/traefik/traefik/v2.10/traefik.sample.toml) * [TOML](https://raw.githubusercontent.com/traefik/traefik/v2.10/traefik.sample.toml)
```bash ```shell
docker run -d -p 8080:8080 -p 80:80 \ docker run -d -p 8080:8080 -p 80:80 \
-v $PWD/traefik.yml:/etc/traefik/traefik.yml traefik:v2.10 -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 helm repo update
``` ```
And install it with the `helm` command line: And install it with the Helm command line:
```bash ```bash
helm install traefik traefik/traefik 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. 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: For instance, installing the chart in a dedicated namespace:
@ -106,7 +106,7 @@ helm install traefik traefik/traefik
### Exposing the Traefik dashboard ### 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. Thus, there are multiple ways to expose the dashboard.
For instance, the dashboard access could be achieved through a port-forward: 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" 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 # Quick Start
A Simple Use Case of Traefik Proxy and Kubernetes A Use Case of Traefik Proxy and Kubernetes
{: .subtitle } {: .subtitle }
This guide is an introduction to using Traefik Proxy in a Kubernetes environment. 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. 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. 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 ## Permissions and Accesses
Traefik uses the Kubernetes API to discover running services. Traefik uses the Kubernetes API to discover running services.
In order to use the Kubernetes API, Traefik needs some permissions. 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. 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 role is then bound to an account used by an application, in this case, Traefik Proxy.
The first step is to create the role. The first step is to create the role.
@ -88,7 +88,7 @@ roleRef:
subjects: subjects:
- kind: ServiceAccount - kind: ServiceAccount
name: traefik-account 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`." !!! 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)." !!! 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) 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, 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 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. and scale containers horizontally to support larger workloads.
@ -141,12 +141,12 @@ spec:
containerPort: 8080 containerPort: 8080
``` ```
The deployment contains an important attribute for customizing Traefik: `args`. The deployment contains an important attribute for customizing Traefik: `args`.
These arguments are the static configuration for Traefik. These arguments are the static configuration for Traefik.
From here, it is possible to enable the dashboard, From here, it is possible to enable the dashboard,
configure entry points, configure entry points,
select dynamic configuration providers, select dynamic configuration providers,
and [more](../reference/static-configuration/cli.md)... and [more](../reference/static-configuration/cli.md).
In this deployment, In this deployment,
the static configuration enables the Traefik dashboard, 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`." !!! 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/). 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, Given that, a Deployment can run multiple Traefik Proxy Pods,
a piece is required to forward the traffic to any of the instance: 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: Create a file called `02-traefik-services.yml` and insert the two `Service` resources:
```yaml tab="02-traefik-services.yml" ```yaml tab="02-traefik-services.yml"
@ -195,7 +195,7 @@ spec:
!!! warning "It is possible to expose a service in different ways." !!! 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 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. 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 ## 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), For this guide, we use the example application [traefik/whoami](https://github.com/traefik/whoami),
but the principles are applicable to any other application. 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: As usual, start by creating a file called `03-whoami.yml` and paste the following `Deployment` resource:
```yaml tab="03-whoami.yml" ```yaml tab="03-whoami.yml"
@ -262,8 +262,8 @@ spec:
``` ```
Thanks to the Kubernetes API, Thanks to the Kubernetes API,
Traefik is notified when an Ingress resource is created, updated, or deleted. Traefik is notified when an Ingress resource is created, updated, or deleted.
This makes the process dynamic. This makes the process dynamic.
The ingresses are, in a way, the [dynamic configuration](../../providers/kubernetes-ingress/) for Traefik. The ingresses are, in a way, the [dynamic configuration](../../providers/kubernetes-ingress/) for Traefik.
!!! tip !!! tip

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

@ -1,11 +1,11 @@
--- ---
title: "Traefik Getting Started Quickly" 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 # Quick Start
A Simple Use Case Using Docker A Use Case Using Docker
{: .subtitle } {: .subtitle }
![quickstart-diagram](../assets/img/quickstart-diagram.png) ![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 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 ## 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. 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`)" - "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: 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. 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 ```shell
curl -H Host:whoami.docker.localhost http://127.0.0.1 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 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 ```yaml
Hostname: a656c8ddca6c Hostname: a656c8ddca6c

2
docs/content/index.md
View file

@ -18,7 +18,7 @@ Traefik is natively compliant with every major cluster technology, such as Kuber
With Traefik, there is no need to maintain and synchronize a separate configuration file: everything happens automatically, in real time (no restarts, no connection interruptions). With Traefik, there is no need to maintain and synchronize a separate configuration file: everything happens automatically, in real time (no restarts, no connection interruptions).
With Traefik, you spend time developing and deploying new features to your system, not on configuring and maintaining its working state. With Traefik, you spend time developing and deploying new features to your system, not on configuring and maintaining its working state.
Developing Traefik, our main goal is to make it simple to use, and we're sure you'll enjoy it. Developing Traefik, our main goal is to make it effortless to use, and we're sure you'll enjoy it.
-- The Traefik Maintainer Team -- The Traefik Maintainer Team

6
docs/content/operations/dashboard.md
View file

@ -71,11 +71,11 @@ with a router attached to the service `api@internal` in the
to allow defining: to allow defining:
- One or more security features through [middlewares](../middlewares/overview.md) - One or more security features through [middlewares](../middlewares/overview.md)
like authentication ([basicAuth](../middlewares/http/basicauth.md) , [digestAuth](../middlewares/http/digestauth.md), like authentication ([basicAuth](../middlewares/http/basicauth.md), [digestAuth](../middlewares/http/digestauth.md),
[forwardAuth](../middlewares/http/forwardauth.md)) or [whitelisting](../middlewares/http/ipwhitelist.md). [forwardAuth](../middlewares/http/forwardauth.md)) or [whitelisting](../middlewares/http/ipwhitelist.md).
- A [router rule](#dashboard-router-rule) for accessing the dashboard, - A [router rule](#dashboard-router-rule) for accessing the dashboard,
through Traefik itself (sometimes referred as "Traefik-ception"). through Traefik itself (sometimes referred to as "Traefik-ception").
### Dashboard Router Rule ### Dashboard Router Rule
@ -83,7 +83,7 @@ As underlined in the [documentation for the `api.dashboard` option](./api.md#das
the [router rule](../routing/routers/index.md#rule) defined for Traefik must match the [router rule](../routing/routers/index.md#rule) defined for Traefik must match
the path prefixes `/api` and `/dashboard`. the path prefixes `/api` and `/dashboard`.
We recommend to use a "Host Based rule" as ```Host(`traefik.example.com`)``` to match everything on the host domain, We recommend using a "Host Based rule" as ```Host(`traefik.example.com`)``` to match everything on the host domain,
or to make sure that the defined rule captures both prefixes: or to make sure that the defined rule captures both prefixes:
```bash tab="Host Rule" ```bash tab="Host Rule"

9
docs/content/operations/ping.md
View file

@ -33,7 +33,7 @@ whose default value is `traefik` (port `8080`).
| Path | Method | Description | | Path | Method | Description |
|---------|---------------|-----------------------------------------------------------------------------------------------------| |---------|---------------|-----------------------------------------------------------------------------------------------------|
| `/ping` | `GET`, `HEAD` | A simple endpoint to check for Traefik process liveness. Return a code `200` with the content: `OK` | | `/ping` | `GET`, `HEAD` | An endpoint to check for Traefik process liveness. Return a code `200` with the content: `OK` |
!!! note !!! note
The `cli` comes with a [`healthcheck`](./cli.md#healthcheck) command which can be used for calling this endpoint. The `cli` comes with a [`healthcheck`](./cli.md#healthcheck) command which can be used for calling this endpoint.
@ -92,10 +92,11 @@ ping:
_Optional, Default=503_ _Optional, Default=503_
During the period in which Traefik is gracefully shutting down, the ping handler During the period in which Traefik is gracefully shutting down, the ping handler
returns a 503 status code by default. If Traefik is behind e.g. a load-balancer returns a `503` status code by default.
If Traefik is behind, for example a load-balancer
doing health checks (such as the Kubernetes LivenessProbe), another code might doing health checks (such as the Kubernetes LivenessProbe), another code might
be expected as the signal for graceful termination. In which case, the be expected as the signal for graceful termination.
terminatingStatusCode can be used to set the code returned by the ping In that case, the terminatingStatusCode can be used to set the code returned by the ping
handler during termination. handler during termination.
```yaml tab="File (YAML)" ```yaml tab="File (YAML)"