Skip to content

Commit

Permalink
update contributor plugin guide to reflect new plugin naming convention
Browse files Browse the repository at this point in the history
* automatic linting changes - whitespace, new line at end of file

#2720
  • Loading branch information
meeech committed Apr 14, 2023
1 parent b9fbc9b commit 87121df
Showing 1 changed file with 17 additions and 17 deletions.
34 changes: 17 additions & 17 deletions docs/plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
`<namespace>/<name>` and both <namespace> and <name> 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 `<org1>/nginx` and `<org2>/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
`<namespace>/<name>` and both <namespace> and <name> 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 `<org1>/nginx` and `<org2>/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-<tool>-<type>-plugin`
There will also be a standard for naming repositories under argoproj-labs in the form of `rollouts-plugin-<type>-<tool>`
where `<type>` is say `metric`, or `trafficrouter` and `<tool>` 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.
Expand Down Expand Up @@ -134,22 +134,22 @@ 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

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)
* [Sample Traffic Router Plugin](https://github.com/argoproj/argo-rollouts/tree/master/test/cmd/sample-trafficrouter-plugin)

0 comments on commit 87121df

Please sign in to comment.