From 2e8d99c5b8e51451e5001b80c6025a128ed398a8 Mon Sep 17 00:00:00 2001 From: Neil McAllister Date: Fri, 16 Oct 2020 02:20:05 -0700 Subject: [PATCH] Revise Traefik Pilot documentation section --- .../assets/styles/product-switcher.css | 2 +- docs/content/plugins/index.md | 49 +++++++ docs/content/plugins/overview.md | 38 ------ docs/content/plugins/using-plugins.md | 122 ------------------ docs/mkdocs.yml | 4 +- docs/theme/partials/product-switcher.html | 12 ++ 6 files changed, 63 insertions(+), 164 deletions(-) create mode 100644 docs/content/plugins/index.md delete mode 100644 docs/content/plugins/overview.md delete mode 100644 docs/content/plugins/using-plugins.md diff --git a/docs/content/assets/styles/product-switcher.css b/docs/content/assets/styles/product-switcher.css index fa6c6c472..abd5de885 100644 --- a/docs/content/assets/styles/product-switcher.css +++ b/docs/content/assets/styles/product-switcher.css @@ -20,5 +20,5 @@ .product-switcher .nav-dropdown-menu--products .nav-dropdown-menu-wrapper { width: auto; - height: auto; + height: 335px; } diff --git a/docs/content/plugins/index.md b/docs/content/plugins/index.md new file mode 100644 index 000000000..ac3330dbe --- /dev/null +++ b/docs/content/plugins/index.md @@ -0,0 +1,49 @@ +# Plugins and Traefik Pilot + +Traefik Pilot is a software-as-a-service (SaaS) platform that connects to Traefik to extend its capabilities. +It offers a number of features to enhance observability and control of Traefik through a global control plane and dashboard, including: + +* Metrics for network activity of Traefik proxies and groups of proxies +* Alerts for service health issues and security vulnerabilities +* Plugins that extend the functionality of Traefik + +!!! important "Learn More About Traefik Pilot" + This section is intended only as a brief overview for Traefik users who are not familiar with Traefik Pilot. + To explore all that Traefik Pilot has to offer, please consult the [Traefik Pilot Documentation](https://doc.traefik.io/traefik-pilot/) + +!!! Note "Prerequisites" + Traefik Pilot is compatible with Traefik Proxy 2.3 or later. + +## Connecting to Traefik Pilot + +To connect your Traefik proxies to Traefik Pilot, login or create an account at the [Traefik Pilot homepage](https://pilot.traefik.io) and choose **Register New Traefik Instance**. + +To complete the connection, Traefik Pilot will issue a token that must be added to your Traefik static configuration, according to the instructions provided by the Traefik Pilot dashboard. +For more information, consult the [Quick Start Guide](https://doc.traefik.io/traefik-pilot/connecting/) + +Health and security alerts for registered Traefik instances can be enabled from the Preferences in your [Traefik Pilot Profile](https://pilot.traefik.io/profile). + +## Plugins + +Plugins are available to any Traefik proxies that are connected to Traefik Pilot. +They are a powerful feature for extending Traefik with custom features and behaviors. + +You can browse community-contributed plugins from the catalog in the [Traefik Pilot Dashboard](https://pilot.traefik.io/plugins). + +To add a new plugin to a Traefik instance, you must modify that instance's static configuration. +The code to be added is provided for you when you choose **Install the Plugin** from the Traefik Pilot dashboard. +To learn more about Traefik plugins, consult the [documentation](https://doc.traefik.io/traefik-pilot/plugins/overview/). + +!!! danger "Experimental Features" + Plugins can potentially modify the behavior of Traefik in unforeseen ways. + Exercise caution when adding new plugins to production Traefik instances. + +## Build Your Own Plugins + +Traefik users can create their own plugins and contribute them to the Traefik Pilot catalog to share them with the community. + +Traefik plugins are loaded dynamically. +They need not be compiled, and no complex toolchain is necessary to build them. +The experience of implementing a Traefik plugin is comparable to writing a web browser extension. + +To learn more and see code for example Traefik plugins, please see the [developer documentation](https://doc.traefik.io/traefik-pilot/plugins/plugin-dev/). diff --git a/docs/content/plugins/overview.md b/docs/content/plugins/overview.md deleted file mode 100644 index 2ebd9977b..000000000 --- a/docs/content/plugins/overview.md +++ /dev/null @@ -1,38 +0,0 @@ -# Plugins and Traefik Pilot - -Overview -{: .subtitle} - -Traefik Pilot is a software-as-a-service (SaaS) platform that connects to Traefik to extend its capabilities. -It does this through *plugins*, which are dynamically loaded components that enable new features. - -For example, Traefik plugins can add features to modify requests or headers, issue redirects, add authentication, and so on, providing similar functionality to Traefik [middlewares](https://doc.traefik.io/traefik/middlewares/overview/). - -Traefik Pilot can also monitor connected Traefik instances and issue alerts when one is not responding, or when it is subject to security vulnerabilities. - -!!! note "Availability" - Plugins are available for Traefik v2.3.0-rc1 and later. - -!!! danger "Experimental Features" - Plugins can potentially modify the behavior of Traefik in unforeseen ways. - Exercise caution when adding new plugins to production Traefik instances. - -## Connecting to Traefik Pilot - -Plugins are available when a Traefik instance is connected to Traefik Pilot. - -To register a new instance and begin working with plugins, login or create an account at the [Traefik Pilot homepage](https://pilot.traefik.io) and choose **Register New Instance**. - -To complete the connection, Traefik Pilot will issue a token that must be added to your Traefik static configuration by following the instructions provided. - -!!! note "Enabling Alerts" - Health and security alerts for registered Traefik instances can be enabled from the Preferences in your [Traefik Pilot Profile](https://pilot.traefik.io/profile). - -## Creating Plugins - -Traefik users can create their own plugins and contribute them to the Traefik Pilot catalog to share them with the community. - -Plugins are written in [Go](https://golang.org/) and their code is executed by an [embedded Go interpreter](https://github.com/traefik/yaegi). -There is no need to compile binaries and all plugins are 100% cross-platform. - -To learn more and see code for example Traefik plugins, please see the [developer documentation](https://github.com/traefik/plugindemo). diff --git a/docs/content/plugins/using-plugins.md b/docs/content/plugins/using-plugins.md deleted file mode 100644 index 592262166..000000000 --- a/docs/content/plugins/using-plugins.md +++ /dev/null @@ -1,122 +0,0 @@ -# Using Plugins - -Plugins are available to any instance of Traefik v2.3 or later that is [registered](overview.md#connecting-to-traefik-pilot) with Traefik Pilot. -Plugins are hosted on GitHub, but you can browse plugins to add to your registered Traefik instances from the Traefik Pilot UI. - -!!! danger "Experimental Features" - Plugins can potentially modify the behavior of Traefik in unforeseen ways. - Exercise caution when adding new plugins to production Traefik instances. - -## Add a Plugin - -To add a new plugin to a Traefik instance, you must modify that instance's static configuration. -The code to be added is provided by the Traefik Pilot UI when you choose **Install the Plugin**. - -In the example below, we add the [`blockpath`](http://github.com/traefik/plugin-blockpath) and [`rewritebody`](https://github.com/traefik/plugin-rewritebody) plugins: - -```toml tab="File (TOML)" -[entryPoints] - [entryPoints.web] - address = ":80" - -[pilot] - token = "xxxxxxxxx" - -[experimental.plugins] - [experimental.plugins.block] - modulename = "github.com/traefik/plugin-blockpath" - version = "v0.2.0" - - [experimental.plugins.rewrite] - modulename = "github.com/traefik/plugin-rewritebody" - version = "v0.3.0" -``` - -```yaml tab="File (YAML)" -entryPoints: - web: - address: :80 - -pilot: - token: xxxxxxxxx - -experimental: - plugins: - block: - modulename: github.com/traefik/plugin-blockpath - version: v0.2.0 - rewrite: - modulename: github.com/traefik/plugin-rewritebody - version: v0.3.0 -``` - -```bash tab="CLI" ---entryPoints.web.address=:80 ---pilot.token=xxxxxxxxx ---experimental.plugins.block.modulename=github.com/traefik/plugin-blockpath ---experimental.plugins.block.version=v0.2.0 ---experimental.plugins.rewrite.modulename=github.com/traefik/plugin-rewritebody ---experimental.plugins.rewrite.version=v0.3.0 -``` - -## Configuring Plugins - -Some plugins will need to be configured by adding a dynamic configuration. -For the `bodyrewrite` plugin, for example: - -```yaml tab="Docker" -labels: - - "traefik.http.middlewares.my-rewritebody.plugin.rewrite.rewrites[0].regex=example" - - "traefik.http.middlewares.my-rewritebody.plugin.rewrite.rewrites[0].replacement=test" -``` - -```yaml tab="Kubernetes" -apiVersion: traefik.containo.us/v1alpha1 -kind: Middleware -metadata: - name: my-rewritebody -spec: - plugin: - rewrite: - rewrites: - - regex: example - replacement: test -``` - -```yaml tab="Consul Catalog" -- "traefik.http.middlewares.my-rewritebody.plugin.rewrite.rewrites[0].regex=example" -- "traefik.http.middlewares.my-rewritebody.plugin.rewrite.rewrites[0].replacement=test" -``` - -```json tab="Marathon" -"labels": { - "traefik.http.middlewares.my-rewritebody.plugin.rewrite.rewrites[0].regex": "example", - "traefik.http.middlewares.my-rewritebody.plugin.rewrite.rewrites[0].replacement": "test" -} -``` - -```yaml tab="Rancher" -labels: - - "traefik.http.middlewares.my-rewritebody.plugin.rewrite.rewrites[0].regex=example" - - "traefik.http.middlewares.my-rewritebody.plugin.rewrite.rewrites[0].replacement=test" -``` - -```toml tab="File (TOML)" -[http.middlewares] -  [http.middlewares.my-rewritebody.plugin.rewrite] - lastModified = true - [[http.middlewares.my-rewritebody.plugin.rewrite.rewrites]] -    regex = "example" - replacement = "test" -``` - -```yaml tab="File (YAML)" -http: - middlewares: - my-rewritebody: - plugin: - rewrite: - rewrites: - - regex: example - replacement: test -``` diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 6613bfc93..e869b5583 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -133,9 +133,7 @@ nav: - 'Retry': 'middlewares/retry.md' - 'StripPrefix': 'middlewares/stripprefix.md' - 'StripPrefixRegex': 'middlewares/stripprefixregex.md' - - 'Plugins & Traefik Pilot': - - 'Overview': 'plugins/overview.md' - - 'Using Plugins': 'plugins/using-plugins.md' + - 'Plugins & Traefik Pilot': 'plugins/index.md' - 'Operations': - 'CLI': 'operations/cli.md' - 'Dashboard' : 'operations/dashboard.md' diff --git a/docs/theme/partials/product-switcher.html b/docs/theme/partials/product-switcher.html index 83293a90a..4c7f2401e 100644 --- a/docs/theme/partials/product-switcher.html +++ b/docs/theme/partials/product-switcher.html @@ -43,6 +43,18 @@ +
+
+ Traefik Pilot Documentation +
+ +
Traefik Pilot
+
+ Monitor and Manage your Traefik Instances +
+ +
+