Hub documentation
Co-authored-by: jbdoumenjou <jb.doumenjou@gmail.com> Co-authored-by: Baptiste Mayelle <baptiste.mayelle@traefik.io>
This commit is contained in:
Ludovic Fernandez
GitHub
parent
b3eb629785
commit
73306a1533
2 changed files with 348 additions and 0 deletions
347
docs/content/traefik-hub/index.md
Normal file
347
docs/content/traefik-hub/index.md
Normal file
|
|
@ -0,0 +1,347 @@
|
||||||
|
# Traefik Hub (Experimental)
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Once the Traefik Hub Experimental feature is enabled in Traefik,
|
||||||
|
Traefik and its local agent communicate together.
|
||||||
|
|
||||||
|
This agent can:
|
||||||
|
|
||||||
|
* get the Traefik metrics to display them in the Traefik Hub UI
|
||||||
|
* secure the Traefik routers
|
||||||
|
* provide ACME certificates to Traefik
|
||||||
|
* transfer requests from the SaaS Platform to Traefik (and then avoid the users to expose directly their infrastructure on the internet)
|
||||||
|
|
||||||
|
!!! warning "Traefik Hub Entrypoints"
|
||||||
|
|
||||||
|
When the Traefik Hub feature is enabled, Traefik exposes some services meant for the Traefik Hub Agent on dedicated entrypoints (on ports `9900` and `9901` by default).
|
||||||
|
Given their sensitive nature, those services should not be publicly exposed.
|
||||||
|
Also those dedicated entrypoints, regardless of how they are created (default, or user-defined), should not be used by anything other than the Hub Agent.
|
||||||
|
|
||||||
|
!!! important "Learn More About Traefik Hub"
|
||||||
|
|
||||||
|
This section is intended only as a brief overview for Traefik users who are not familiar with Traefik Hub.
|
||||||
|
To explore all that Traefik Hub has to offer, please consult the [Traefik Hub Documentation](https://doc.traefik.io/traefik-hub).
|
||||||
|
|
||||||
|
!!! Note "Prerequisites"
|
||||||
|
|
||||||
|
* Traefik Hub is compatible with Traefik Proxy 2.7 or later.
|
||||||
|
* The Traefik Hub Agent must be installed to connect to the Traefik Hub platform.
|
||||||
|
* Activate this feature in the experimental section of the static configuration.
|
||||||
|
|
||||||
|
!!! example "Minimal Static Configuration to Activate Traefik Hub for Docker"
|
||||||
|
|
||||||
|
```yaml tab="File (YAML)"
|
||||||
|
experimental:
|
||||||
|
hub: true
|
||||||
|
|
||||||
|
hub:
|
||||||
|
tls:
|
||||||
|
insecure: true
|
||||||
|
|
||||||
|
metrics:
|
||||||
|
prometheus:
|
||||||
|
addRoutersLabels: true
|
||||||
|
```
|
||||||
|
|
||||||
|
```toml tab="File (TOML)"
|
||||||
|
[experimental]
|
||||||
|
hub = true
|
||||||
|
|
||||||
|
[hub]
|
||||||
|
[hub.tls]
|
||||||
|
insecure = true
|
||||||
|
|
||||||
|
[metrics]
|
||||||
|
[metrics.prometheus]
|
||||||
|
addRoutersLabels = true
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash tab="CLI"
|
||||||
|
--experimental.hub
|
||||||
|
--hub.tls.insecure
|
||||||
|
--metrics.prometheus.addrouterslabels
|
||||||
|
```
|
||||||
|
|
||||||
|
!!! example "Minimal Static Configuration to Activate Traefik Hub for Kubernetes"
|
||||||
|
|
||||||
|
```yaml tab="File (YAML)"
|
||||||
|
experimental:
|
||||||
|
hub: true
|
||||||
|
|
||||||
|
hub: {}
|
||||||
|
|
||||||
|
metrics:
|
||||||
|
prometheus:
|
||||||
|
addRoutersLabels: true
|
||||||
|
```
|
||||||
|
|
||||||
|
```toml tab="File (TOML)"
|
||||||
|
[experimental]
|
||||||
|
hub = true
|
||||||
|
|
||||||
|
[hub]
|
||||||
|
|
||||||
|
[metrics]
|
||||||
|
[metrics.prometheus]
|
||||||
|
addRoutersLabels = true
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash tab="CLI"
|
||||||
|
--experimental.hub
|
||||||
|
--hub
|
||||||
|
--metrics.prometheus.addrouterslabels
|
||||||
|
```
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
### Entrypoints
|
||||||
|
|
||||||
|
#### `traefikhub-api`
|
||||||
|
|
||||||
|
This entrypoint is used to communicate between the Hub agent and Traefik.
|
||||||
|
It allows the Hub agent to create routing.
|
||||||
|
|
||||||
|
This dedicated Traefik Hub entryPoint should not be used by anything other than Traefik Hub.
|
||||||
|
|
||||||
|
The default port is `9900`.
|
||||||
|
To change the port, you have to define an entrypoint named `traefikhub-api`.
|
||||||
|
|
||||||
|
```yaml tab="File (YAML)"
|
||||||
|
entryPoints:
|
||||||
|
traefikhub-api: ":8000"
|
||||||
|
```
|
||||||
|
|
||||||
|
```toml tab="File (TOML)"
|
||||||
|
[entryPoints.traefikhub-api]
|
||||||
|
address = ":8000"
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash tab="CLI"
|
||||||
|
--entrypoints.traefikhub-api.address=:8000
|
||||||
|
```
|
||||||
|
|
||||||
|
#### `traefikhub-tunl`
|
||||||
|
|
||||||
|
This entrypoint is used to communicate between Traefik Hub and Traefik.
|
||||||
|
It allows to create secured tunnels.
|
||||||
|
|
||||||
|
This dedicated Traefik Hub entryPoint should not be used by anything other than Traefik Hub.
|
||||||
|
|
||||||
|
The default port is `9901`.
|
||||||
|
To change the port, you have to define an entrypoint named `traefikhub-tunl`.
|
||||||
|
|
||||||
|
```yaml tab="File (YAML)"
|
||||||
|
entryPoints:
|
||||||
|
traefikhub-tunl: ":8000"
|
||||||
|
```
|
||||||
|
|
||||||
|
```toml tab="File (TOML)"
|
||||||
|
[entryPoints.traefikhub-tunl]
|
||||||
|
address = ":8000"
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash tab="CLI"
|
||||||
|
--entrypoints.traefikhub-tunl.address=:8000
|
||||||
|
```
|
||||||
|
|
||||||
|
### `tls`
|
||||||
|
|
||||||
|
_Optional, Default=None_
|
||||||
|
|
||||||
|
This section is required when using the Hub agent for Docker.
|
||||||
|
|
||||||
|
This section allows configuring mutual TLS connection between Traefik Proxy and the Traefik Hub Agent.
|
||||||
|
The key and the certificate are the credentials for Traefik Proxy as a TLS client.
|
||||||
|
The certificate authority authenticates the Traefik Hub Agent certificate.
|
||||||
|
|
||||||
|
!!! note "Certificate Domain"
|
||||||
|
|
||||||
|
The certificate must be valid for the `proxy.traefik` domain.
|
||||||
|
|
||||||
|
!!! note "Certificates Definition"
|
||||||
|
|
||||||
|
Certificates can be defined either by their content or their path.
|
||||||
|
|
||||||
|
!!! note "Insecure Mode"
|
||||||
|
|
||||||
|
The `insecure` option is mutually exclusive with any other option.
|
||||||
|
|
||||||
|
```yaml tab="File (YAML)"
|
||||||
|
hub:
|
||||||
|
tls:
|
||||||
|
ca: /path/to/ca.pem
|
||||||
|
cert: /path/to/cert.pem
|
||||||
|
key: /path/to/key.pem
|
||||||
|
```
|
||||||
|
|
||||||
|
```toml tab="File (TOML)"
|
||||||
|
[hub.tls]
|
||||||
|
ca= "/path/to/ca.pem"
|
||||||
|
cert= "/path/to/cert.pem"
|
||||||
|
key= "/path/to/key.pem"
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash tab="CLI"
|
||||||
|
--hub.tls.ca=/path/to/ca.pem
|
||||||
|
--hub.tls.cert=/path/to/cert.pem
|
||||||
|
--hub.tls.key=/path/to/key.pem
|
||||||
|
```
|
||||||
|
|
||||||
|
### `tls.ca`
|
||||||
|
|
||||||
|
The certificate authority authenticates the Traefik Hub Agent certificate.
|
||||||
|
|
||||||
|
```yaml tab="File (YAML)"
|
||||||
|
hub:
|
||||||
|
tls:
|
||||||
|
ca: |-
|
||||||
|
-----BEGIN CERTIFICATE-----
|
||||||
|
MIIBcjCCARegAwIBAgIQaewCzGdRz5iNnjAiEoO5AzAKBggqhkjOPQQDAjASMRAw
|
||||||
|
DgYDVQQKEwdBY21lIENvMCAXDTIyMDMyMTE2MTY0NFoYDzIxMjIwMjI1MTYxNjQ0
|
||||||
|
WjASMRAwDgYDVQQKEwdBY21lIENvMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE
|
||||||
|
ZaKYPj2G8Hnmju6jbHt+vODwKqNDVQMH5nxhtAgSUZS61mLWwZvvUhIYLNPwHz8a
|
||||||
|
x8C7+cuihEC6Tzvn8DeGeKNNMEswDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoG
|
||||||
|
CCsGAQUFBwMBMAwGA1UdEwEB/wQCMAAwFgYDVR0RBA8wDYILZXhhbXBsZS5jb20w
|
||||||
|
CgYIKoZIzj0EAwIDSQAwRgIhAO8sucDGY+JOrNgQg1a9ZqqYvbxPFnYsSZr7F/vz
|
||||||
|
aUX2AiEAilZ+M5eX4RiMFc3nlm9qVs1LZhV3dZW/u80/mPQ/oaY=
|
||||||
|
-----END CERTIFICATE-----
|
||||||
|
```
|
||||||
|
|
||||||
|
```toml tab="File (TOML)"
|
||||||
|
[hub.tls]
|
||||||
|
ca = """-----BEGIN CERTIFICATE-----
|
||||||
|
MIIBcjCCARegAwIBAgIQaewCzGdRz5iNnjAiEoO5AzAKBggqhkjOPQQDAjASMRAw
|
||||||
|
DgYDVQQKEwdBY21lIENvMCAXDTIyMDMyMTE2MTY0NFoYDzIxMjIwMjI1MTYxNjQ0
|
||||||
|
WjASMRAwDgYDVQQKEwdBY21lIENvMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE
|
||||||
|
ZaKYPj2G8Hnmju6jbHt+vODwKqNDVQMH5nxhtAgSUZS61mLWwZvvUhIYLNPwHz8a
|
||||||
|
x8C7+cuihEC6Tzvn8DeGeKNNMEswDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoG
|
||||||
|
CCsGAQUFBwMBMAwGA1UdEwEB/wQCMAAwFgYDVR0RBA8wDYILZXhhbXBsZS5jb20w
|
||||||
|
CgYIKoZIzj0EAwIDSQAwRgIhAO8sucDGY+JOrNgQg1a9ZqqYvbxPFnYsSZr7F/vz
|
||||||
|
aUX2AiEAilZ+M5eX4RiMFc3nlm9qVs1LZhV3dZW/u80/mPQ/oaY=
|
||||||
|
-----END CERTIFICATE-----"""
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash tab="CLI"
|
||||||
|
--hub.tls.ca=-----BEGIN CERTIFICATE-----
|
||||||
|
MIIBcjCCARegAwIBAgIQaewCzGdRz5iNnjAiEoO5AzAKBggqhkjOPQQDAjASMRAw
|
||||||
|
DgYDVQQKEwdBY21lIENvMCAXDTIyMDMyMTE2MTY0NFoYDzIxMjIwMjI1MTYxNjQ0
|
||||||
|
WjASMRAwDgYDVQQKEwdBY21lIENvMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE
|
||||||
|
ZaKYPj2G8Hnmju6jbHt+vODwKqNDVQMH5nxhtAgSUZS61mLWwZvvUhIYLNPwHz8a
|
||||||
|
x8C7+cuihEC6Tzvn8DeGeKNNMEswDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoG
|
||||||
|
CCsGAQUFBwMBMAwGA1UdEwEB/wQCMAAwFgYDVR0RBA8wDYILZXhhbXBsZS5jb20w
|
||||||
|
CgYIKoZIzj0EAwIDSQAwRgIhAO8sucDGY+JOrNgQg1a9ZqqYvbxPFnYsSZr7F/vz
|
||||||
|
aUX2AiEAilZ+M5eX4RiMFc3nlm9qVs1LZhV3dZW/u80/mPQ/oaY=
|
||||||
|
-----END CERTIFICATE-----
|
||||||
|
```
|
||||||
|
|
||||||
|
### `tls.cert`
|
||||||
|
|
||||||
|
The TLS certificate for Traefik Proxy as a TLS client.
|
||||||
|
|
||||||
|
!!! note "Certificate Domain"
|
||||||
|
|
||||||
|
The certificate must be valid for the `proxy.traefik` domain.
|
||||||
|
|
||||||
|
```yaml tab="File (YAML)"
|
||||||
|
hub:
|
||||||
|
tls:
|
||||||
|
cert: |-
|
||||||
|
-----BEGIN CERTIFICATE-----
|
||||||
|
MIIBcjCCARegAwIBAgIQaewCzGdRz5iNnjAiEoO5AzAKBggqhkjOPQQDAjASMRAw
|
||||||
|
DgYDVQQKEwdBY21lIENvMCAXDTIyMDMyMTE2MTY0NFoYDzIxMjIwMjI1MTYxNjQ0
|
||||||
|
WjASMRAwDgYDVQQKEwdBY21lIENvMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE
|
||||||
|
ZaKYPj2G8Hnmju6jbHt+vODwKqNDVQMH5nxhtAgSUZS61mLWwZvvUhIYLNPwHz8a
|
||||||
|
x8C7+cuihEC6Tzvn8DeGeKNNMEswDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoG
|
||||||
|
CCsGAQUFBwMBMAwGA1UdEwEB/wQCMAAwFgYDVR0RBA8wDYILZXhhbXBsZS5jb20w
|
||||||
|
CgYIKoZIzj0EAwIDSQAwRgIhAO8sucDGY+JOrNgQg1a9ZqqYvbxPFnYsSZr7F/vz
|
||||||
|
aUX2AiEAilZ+M5eX4RiMFc3nlm9qVs1LZhV3dZW/u80/mPQ/oaY=
|
||||||
|
-----END CERTIFICATE-----
|
||||||
|
```
|
||||||
|
|
||||||
|
```toml tab="File (TOML)"
|
||||||
|
[hub.tls]
|
||||||
|
cert = """-----BEGIN CERTIFICATE-----
|
||||||
|
MIIBcjCCARegAwIBAgIQaewCzGdRz5iNnjAiEoO5AzAKBggqhkjOPQQDAjASMRAw
|
||||||
|
DgYDVQQKEwdBY21lIENvMCAXDTIyMDMyMTE2MTY0NFoYDzIxMjIwMjI1MTYxNjQ0
|
||||||
|
WjASMRAwDgYDVQQKEwdBY21lIENvMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE
|
||||||
|
ZaKYPj2G8Hnmju6jbHt+vODwKqNDVQMH5nxhtAgSUZS61mLWwZvvUhIYLNPwHz8a
|
||||||
|
x8C7+cuihEC6Tzvn8DeGeKNNMEswDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoG
|
||||||
|
CCsGAQUFBwMBMAwGA1UdEwEB/wQCMAAwFgYDVR0RBA8wDYILZXhhbXBsZS5jb20w
|
||||||
|
CgYIKoZIzj0EAwIDSQAwRgIhAO8sucDGY+JOrNgQg1a9ZqqYvbxPFnYsSZr7F/vz
|
||||||
|
aUX2AiEAilZ+M5eX4RiMFc3nlm9qVs1LZhV3dZW/u80/mPQ/oaY=
|
||||||
|
-----END CERTIFICATE-----"""
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash tab="CLI"
|
||||||
|
--hub.tls.cert=-----BEGIN CERTIFICATE-----
|
||||||
|
MIIBcjCCARegAwIBAgIQaewCzGdRz5iNnjAiEoO5AzAKBggqhkjOPQQDAjASMRAw
|
||||||
|
DgYDVQQKEwdBY21lIENvMCAXDTIyMDMyMTE2MTY0NFoYDzIxMjIwMjI1MTYxNjQ0
|
||||||
|
WjASMRAwDgYDVQQKEwdBY21lIENvMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE
|
||||||
|
ZaKYPj2G8Hnmju6jbHt+vODwKqNDVQMH5nxhtAgSUZS61mLWwZvvUhIYLNPwHz8a
|
||||||
|
x8C7+cuihEC6Tzvn8DeGeKNNMEswDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoG
|
||||||
|
CCsGAQUFBwMBMAwGA1UdEwEB/wQCMAAwFgYDVR0RBA8wDYILZXhhbXBsZS5jb20w
|
||||||
|
CgYIKoZIzj0EAwIDSQAwRgIhAO8sucDGY+JOrNgQg1a9ZqqYvbxPFnYsSZr7F/vz
|
||||||
|
aUX2AiEAilZ+M5eX4RiMFc3nlm9qVs1LZhV3dZW/u80/mPQ/oaY=
|
||||||
|
-----END CERTIFICATE-----
|
||||||
|
```
|
||||||
|
|
||||||
|
### `tls.key`
|
||||||
|
|
||||||
|
The TLS key for Traefik Proxy as a TLS client.
|
||||||
|
|
||||||
|
```yaml tab="File (YAML)"
|
||||||
|
hub:
|
||||||
|
tls:
|
||||||
|
key: |-
|
||||||
|
-----BEGIN PRIVATE KEY-----
|
||||||
|
MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgm+XJ3LVrTbbirJea
|
||||||
|
O+Crj2ADVsVHjMuiyd72VE3lgxihRANCAARlopg+PYbweeaO7qNse3684PAqo0NV
|
||||||
|
AwfmfGG0CBJRlLrWYtbBm+9SEhgs0/AfPxrHwLv5y6KEQLpPO+fwN4Z4
|
||||||
|
-----END PRIVATE KEY-----
|
||||||
|
```
|
||||||
|
|
||||||
|
```toml tab="File (TOML)"
|
||||||
|
[hub.tls]
|
||||||
|
key = """-----BEGIN PRIVATE KEY-----
|
||||||
|
MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgm+XJ3LVrTbbirJea
|
||||||
|
O+Crj2ADVsVHjMuiyd72VE3lgxihRANCAARlopg+PYbweeaO7qNse3684PAqo0NV
|
||||||
|
AwfmfGG0CBJRlLrWYtbBm+9SEhgs0/AfPxrHwLv5y6KEQLpPO+fwN4Z4
|
||||||
|
-----END PRIVATE KEY-----"""
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash tab="CLI"
|
||||||
|
--hub.tls.key=-----BEGIN PRIVATE KEY-----
|
||||||
|
MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgm+XJ3LVrTbbirJea
|
||||||
|
O+Crj2ADVsVHjMuiyd72VE3lgxihRANCAARlopg+PYbweeaO7qNse3684PAqo0NV
|
||||||
|
AwfmfGG0CBJRlLrWYtbBm+9SEhgs0/AfPxrHwLv5y6KEQLpPO+fwN4Z4
|
||||||
|
-----END PRIVATE KEY-----
|
||||||
|
```
|
||||||
|
|
||||||
|
### `tls.insecure`
|
||||||
|
|
||||||
|
_Optional, Default=false_
|
||||||
|
|
||||||
|
Enables an insecure TLS connection that uses default credentials,
|
||||||
|
and which has no peer authentication between Traefik Proxy and the Traefik Hub Agent.
|
||||||
|
The `insecure` option is mutually exclusive with any other option.
|
||||||
|
|
||||||
|
!!! warning "Security Consideration"
|
||||||
|
|
||||||
|
Do not use this setup in production.
|
||||||
|
This option implies sensitive data can be exposed to potential malicious third-party programs.
|
||||||
|
|
||||||
|
```yaml tab="File (YAML)"
|
||||||
|
hub:
|
||||||
|
tls:
|
||||||
|
insecure: true
|
||||||
|
```
|
||||||
|
|
||||||
|
```toml tab="File (TOML)"
|
||||||
|
[hub.tls]
|
||||||
|
insecure = true
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash tab="CLI"
|
||||||
|
--hub.tls.insecure=true
|
||||||
|
```
|
||||||
|
|
@ -135,6 +135,7 @@ nav:
|
||||||
- 'Overview': 'middlewares/tcp/overview.md'
|
- 'Overview': 'middlewares/tcp/overview.md'
|
||||||
- 'InFlightConn': 'middlewares/tcp/inflightconn.md'
|
- 'InFlightConn': 'middlewares/tcp/inflightconn.md'
|
||||||
- 'IpWhitelist': 'middlewares/tcp/ipwhitelist.md'
|
- 'IpWhitelist': 'middlewares/tcp/ipwhitelist.md'
|
||||||
|
- 'Traefik Hub': 'traefik-hub/index.md'
|
||||||
- 'Plugins & Traefik Pilot': 'plugins/index.md'
|
- 'Plugins & Traefik Pilot': 'plugins/index.md'
|
||||||
- 'Operations':
|
- 'Operations':
|
||||||
- 'CLI': 'operations/cli.md'
|
- 'CLI': 'operations/cli.md'
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue