From f7771ef5e377f50725c1f546a856fd9a502aac99 Mon Sep 17 00:00:00 2001 From: mitchell amihod <4623+meeech@users.noreply.github.com> Date: Fri, 14 Apr 2023 08:49:59 -0400 Subject: [PATCH] Update docs to reflect new plugin naming pattern * update contributor plugin guide * update analysis/plugin overview * update trafic-management/plugin overview * automatic linting changes - whitespace, new line at end of file Signed-off-by: mitchell amihod <4623+meeech@users.noreply.github.com> #2720 --- docs/analysis/plugins.md | 18 +++++------ docs/features/traffic-management/plugins.md | 6 ++-- docs/plugins.md | 34 ++++++++++----------- 3 files changed, 29 insertions(+), 29 deletions(-) diff --git a/docs/analysis/plugins.md b/docs/analysis/plugins.md index 8b718bf136..89f8f7a782 100644 --- a/docs/analysis/plugins.md +++ b/docs/analysis/plugins.md @@ -2,10 +2,10 @@ !!! important Available since v1.5 - Status: Alpha -Argo Rollouts supports getting analysis metrics via 3rd party plugin system. This allows users to extend the capabilities of Rollouts +Argo Rollouts supports getting analysis metrics via 3rd party plugin system. This allows users to extend the capabilities of Rollouts to support metric providers that are not natively supported. Rollout's uses a plugin library called -[go-plugin](https://github.com/hashicorp/go-plugin) to do this. You can find a sample plugin -here: [rollouts-sample_prometheus-metric-plugin](https://github.com/argoproj-labs/rollouts-sample_prometheus-metric-plugin) +[go-plugin](https://github.com/hashicorp/go-plugin) to do this. You can find a sample plugin +here: [rollouts-plugin-metric-sample-prometheus](https://github.com/argoproj-labs/rollouts-plugin-metric-sample-prometheus) ## Using a Metric Plugin @@ -36,7 +36,7 @@ data: ### Using a HTTP(S) server to host the plugin executable -Argo Rollouts supports downloading the plugin executable from a HTTP(S) server. To use this method, you will need to +Argo Rollouts supports downloading the plugin executable from a HTTP(S) server. To use this method, you will need to configure the controller via the `argo-rollouts-config` configmap and set `pluginLocation` to a http(s) url. Example: ```yaml @@ -47,7 +47,7 @@ metadata: data: metricProviderPlugins: |- - name: "argoproj-labs/sample-prometheus" # name of the plugin, it must match the name required by the plugin so it can find it's configuration - location: "https://github.com/argoproj-labs/rollouts-sample_prometheus-metric-plugin/releases/download/v0.0.4/metric-plugin-linux-amd64" # supports http(s):// urls and file:// + location: "https://github.com/argoproj-labs/rollouts-plugin-metric-sample-prometheus/releases/download/v0.0.4/metric-plugin-linux-amd64" # supports http(s):// urls and file:// sha256: "dac10cbf57633c9832a17f8c27d2ca34aa97dd3d" #optional sha256 checksum of the plugin executable ``` @@ -56,18 +56,18 @@ data: Depending on which method you use to install and the plugin, there are some things to be aware of. The rollouts controller will not start if it can not download or find the plugin executable. This means that if you are using a method of installation that requires a download of the plugin and the server hosting the plugin for some reason is not available and the rollouts -controllers pod got deleted while the server was down or is coming up for the first time, it will not be able to start until +controllers pod got deleted while the server was down or is coming up for the first time, it will not be able to start until the server hosting the plugin is available again. Argo Rollouts will download the plugin at startup only once but if the pod is deleted it will need to download the plugin again on next startup. Running Argo Rollouts in HA mode can help a little with this situation because each pod will download the plugin at startup. So if a single pod gets -deleted during a server outage, the other pods will still be able to take over because there will already be a plugin executable available to it. It is the +deleted during a server outage, the other pods will still be able to take over because there will already be a plugin executable available to it. It is the responsibility of the Argo Rollouts administrator to define the plugin installation method considering the risks of each approach. ## List of Available Plugins (alphabetical order) #### Add Your Plugin Here * If you have created a plugin, please submit a PR to add it to this list. -#### [rollouts-sample_prometheus-metric-plugin](https://github.com/argoproj-labs/rollouts-sample_prometheus-metric-plugin) - * This is just a sample plugin that can be used as a starting point for creating your own plugin. +#### [rollouts-plugin-metric-sample-prometheus](https://github.com/argoproj-labs/rollouts-plugin-metric-sample-prometheus) + * This is just a sample plugin that can be used as a starting point for creating your own plugin. It is not meant to be used in production. It is based on the built-in prometheus provider. diff --git a/docs/features/traffic-management/plugins.md b/docs/features/traffic-management/plugins.md index b211ca75d0..f0d1634ee3 100644 --- a/docs/features/traffic-management/plugins.md +++ b/docs/features/traffic-management/plugins.md @@ -5,7 +5,7 @@ Argo Rollouts supports getting analysis metrics via 3rd party plugin system. This allows users to extend the capabilities of Rollouts to support metric providers that are not natively supported. Rollout's uses a plugin library called [go-plugin](https://github.com/hashicorp/go-plugin) to do this. You can find a sample plugin -here: [rollouts-sample_nginx-trafficrouter-plugin](https://github.com/argoproj-labs/rollouts-sample_nginx-trafficrouter-plugin) +here: [rollouts-plugin-trafficrouter-sample-nginx](https://github.com/argoproj-labs/rollouts-plugin-trafficrouter-sample-nginx) ## Using a Traffic Router Plugin @@ -47,7 +47,7 @@ metadata: data: trafficRouterPlugins: |- - name: "argoproj-labs/sample-nginx" # name of the plugin, it must match the name required by the plugin so it can find it's configuration - location: "https://github.com/argoproj-labs/rollouts-sample_nginx-trafficrouter-plugin/releases/download/v0.0.1/metric-plugin-linux-amd64" # supports http(s):// urls and file:// + location: "https://github.com/argoproj-labs/rollouts-plugin-trafficrouter-sample-nginx/releases/download/v0.0.1/metric-plugin-linux-amd64" # supports http(s):// urls and file:// sha256: "08f588b1c799a37bbe8d0fc74cc1b1492dd70b2c" #optional sha256 checksum of the plugin executable ``` @@ -68,6 +68,6 @@ responsibility of the Argo Rollouts administrator to define the plugin installat #### Add Your Plugin Here * If you have created a plugin, please submit a PR to add it to this list. -#### [rollouts-sample_nginx-trafficrouter-plugin](https://github.com/argoproj-labs/rollouts-sample_nginx-trafficrouter-plugin) +#### [rollouts-plugin-trafficrouter-sample-nginx](https://github.com/argoproj-labs/rollouts-plugin-trafficrouter-sample-nginx) * This is just a sample plugin that can be used as a starting point for creating your own plugin. It is not meant to be used in production. It is based on the built-in prometheus provider. diff --git a/docs/plugins.md b/docs/plugins.md index 794ec8157f..ce3a1770ee 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -2,7 +2,7 @@ ## High Level Overview -Argo Rollouts plugins depend on hashicorp's [go-plugin](https://github.com/hashicorp/go-plugin) library. This library +Argo Rollouts plugins depend on hashicorp's [go-plugin](https://github.com/hashicorp/go-plugin) library. This library provides a way for a plugin to be compiled as a standalone executable and then loaded by the rollouts controller at runtime. This works by having the plugin executable act as a rpc server and the rollouts controller act as a client. The plugin executable is started by the rollouts controller and is a long-lived process and that the rollouts controller connects to over a unix socket. @@ -11,22 +11,22 @@ The communication protocol uses golang built in net/rpc library so plugins have ## Plugin Repository In order to get plugins listed in the main argo rollouts documentation we ask that the plugin repository be created under -the [argoproj-labs](https://github.com/argoproj-labs) organization. Please open an issue under argo-rollouts requesting a -repo which you would be granted admin access on. +the [argoproj-labs](https://github.com/argoproj-labs) organization. Please open an issue under argo-rollouts requesting a +repo which you would be granted admin access on. -There is also a standard naming convention for plugin names used for configmap registration, as well as what the plugin -uses for locating its specific configuration on rollout or analysis resources. The name needs to be in the form of -`/` and both and have a regular expression check that matches Github's requirements -for `username/org` and `repository name`. This requirement is in place to help with allowing multiple creators of the same plugin -types to exist such as `/nginx` and `/nginx`. These names could be based of the repo name such -as `argoproj-labs/rollouts-sample_prometheus-metric-plugin` but it is not a requirement. +There is also a standard naming convention for plugin names used for configmap registration, as well as what the plugin +uses for locating its specific configuration on rollout or analysis resources. The name needs to be in the form of +`/` and both and have a regular expression check that matches Github's requirements +for `username/org` and `repository name`. This requirement is in place to help with allowing multiple creators of the same plugin +types to exist such as `/nginx` and `/nginx`. These names could be based of the repo name such +as `argoproj-labs/rollouts-plugin-metric-sample-prometheus` but it is not a requirement. -There will also be a standard for naming repositories under argoproj-labs in the form of `rollouts---plugin` +There will also be a standard for naming repositories under argoproj-labs in the form of `rollouts-plugin--` where `` is say `metric`, or `trafficrouter` and `` is the software the plugin is for say nginx. ## Plugin Name -So now that we have an idea on plugin naming and repository standards let's pick a name to use for the rest of this +So now that we have an idea on plugin naming and repository standards let's pick a name to use for the rest of this documentation and call our plugin `argoproj-labs/nginx`. This name will be used in a few different spots the first is the config map that your plugin users will need to configure. @@ -134,17 +134,17 @@ type TrafficRouterPlugin interface { ## Plugin Init Function -Each plugin interface has a `InitPlugin` function, this function is called when the plugin is first started up and is only called -once per startup. The `InitPlugin` function is used as a means to initialize the plugin it gives you the plugin author the ability -to either set up a client for a specific metrics provider or in the case of a traffic router construct a client or informer +Each plugin interface has a `InitPlugin` function, this function is called when the plugin is first started up and is only called +once per startup. The `InitPlugin` function is used as a means to initialize the plugin it gives you the plugin author the ability +to either set up a client for a specific metrics provider or in the case of a traffic router construct a client or informer for kubernetes api. The one thing to note about this though is because these calls happen over RPC the plugin author should not depend on state being stored in the plugin struct as it will not be persisted between calls. ## Kubernetes RBAC The plugin runs as a child process of the rollouts controller and as such it will inherit the same RBAC permissions as the -controller. This means that the service account for the rollouts controller will need the correct permissions for the plugin -to function. This might mean instructing users to create a role and role binding to the standard rollouts service account +controller. This means that the service account for the rollouts controller will need the correct permissions for the plugin +to function. This might mean instructing users to create a role and role binding to the standard rollouts service account for the plugin to use. This will probably affect traffic router plugins more than metrics plugins. ## Sample Plugins @@ -152,4 +152,4 @@ for the plugin to use. This will probably affect traffic router plugins more tha There are two sample plugins within the argo-rollouts repo that you can use as a reference for creating your own plugin. * [Sample Metrics Plugin](https://github.com/argoproj/argo-rollouts/tree/master/test/cmd/sample-metrics-plugin) -* [Sample Traffic Router Plugin](https://github.com/argoproj/argo-rollouts/tree/master/test/cmd/sample-trafficrouter-plugin) \ No newline at end of file +* [Sample Traffic Router Plugin](https://github.com/argoproj/argo-rollouts/tree/master/test/cmd/sample-trafficrouter-plugin)