diff --git a/docs/content/traefik-hub/index.md b/docs/content/traefik-hub/index.md new file mode 100644 index 000000000..c618da77a --- /dev/null +++ b/docs/content/traefik-hub/index.md @@ -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 +``` diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 08c78cae2..b615a85b7 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -135,6 +135,7 @@ nav: - 'Overview': 'middlewares/tcp/overview.md' - 'InFlightConn': 'middlewares/tcp/inflightconn.md' - 'IpWhitelist': 'middlewares/tcp/ipwhitelist.md' + - 'Traefik Hub': 'traefik-hub/index.md' - 'Plugins & Traefik Pilot': 'plugins/index.md' - 'Operations': - 'CLI': 'operations/cli.md'