|
| 1 | +# Metric Plugins |
| 2 | + |
| 3 | +!!! important Available since v1.5 |
| 4 | + |
| 5 | +Argo Rollouts supports getting analysis metrics via 3rd party plugin system. This allows users to extend the capabilities of Rollouts |
| 6 | +to support metric providers that are not natively supported. Rollout's uses a plugin library called |
| 7 | +[go-plugin](https://github.com/hashicorp/go-plugin) to do this. You can find a sample plugin |
| 8 | +here: [sample-rollouts-metric-plugin](https://github.com/argoproj-labs/sample-rollouts-metric-plugin) |
| 9 | + |
| 10 | +## Using a Metric Plugin |
| 11 | + |
| 12 | +There are two methods of installing and using an argo rollouts plugin. The first method is to mount up the plugin executable |
| 13 | +into the rollouts controller container. The second method is to use a HTTP(S) server to host the plugin executable. |
| 14 | + |
| 15 | +### Mounting the plugin executable into the rollouts controller container |
| 16 | + |
| 17 | +To use this method, you will need to build or download the plugin executable and then mount it into the rollouts controller container. |
| 18 | +The plugin executable must be mounted into the rollouts controller container at the path specified by the `--metric-plugin-location` flag. |
| 19 | + |
| 20 | +There are a few ways to mount the plugin executable into the rollouts controller container. Some of these will depend on your |
| 21 | +particular infrastructure. Here are a few methods: |
| 22 | + |
| 23 | +* Using an init container to download the plugin executable |
| 24 | +* Using a Kubernetes volume mount with a shared volume such as NFS, EBS, etc. |
| 25 | +* Building the plugin into the rollouts controller container |
| 26 | + |
| 27 | +Then you can use the configmap to point to the plugin executable. Example: |
| 28 | + |
| 29 | +```yaml |
| 30 | +apiVersion: v1 |
| 31 | +kind: ConfigMap |
| 32 | +metadata: |
| 33 | + name: argo-rollouts-config |
| 34 | +data: |
| 35 | + plugins: |- |
| 36 | + metrics: |
| 37 | + - name: "prometheus" # name the plugin uses to find this configuration, it must match the name required by the plugin |
| 38 | + pluginLocation: "file://./my-custom-plugin" # supports http(s):// urls and file:// |
| 39 | +``` |
| 40 | +
|
| 41 | +### Using a HTTP(S) server to host the plugin executable |
| 42 | +
|
| 43 | +Argo Rollouts supports downloading the plugin executable from a HTTP(S) server. To use this method, you will need to |
| 44 | +configure the controller via the `argo-rollouts-config` configmap and set `pluginLocation` to a http(s) url. Example: |
| 45 | + |
| 46 | +```yaml |
| 47 | +apiVersion: v1 |
| 48 | +kind: ConfigMap |
| 49 | +metadata: |
| 50 | + name: argo-rollouts-config |
| 51 | +data: |
| 52 | + plugins: |- |
| 53 | + metrics: |
| 54 | + - name: "prometheus" # name the plugin uses to find this configuration, it must match the name required by the plugin |
| 55 | + pluginLocation: "https://github.com/argoproj-labs/sample-rollouts-metric-plugin/releases/download/v0.0.3/metric-plugin-linux-amd64" # supports http(s):// urls and file:// |
| 56 | + pluginSha256: "08f588b1c799a37bbe8d0fc74cc1b1492dd70b2c" #optional sha256 checksum of the plugin executable |
| 57 | +``` |
| 58 | + |
| 59 | +## Some words of caution |
| 60 | + |
| 61 | +Depending on which method you use to install and the plugin, there are some things to be aware of. |
| 62 | +The rollouts controller will not start if it can not download or find the plugin executable. This means that if you are using |
| 63 | +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 |
| 64 | +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 |
| 65 | +the server hosting the plugin is available again. |
| 66 | + |
| 67 | +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 |
| 68 | +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 |
| 69 | +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. However, |
| 70 | +it is up to you to define your risk for and decide how you want to install the plugin executable. |
| 71 | + |
| 72 | +## List of Available Plugins (alphabetical order) |
| 73 | + |
| 74 | +#### Add Your Plugin Here |
| 75 | + * If you have created a plugin, please submit a PR to add it to this list. |
| 76 | +#### [sample-rollouts-metric-plugin](https://github.com/argoproj-labs/sample-rollouts-metric-plugin) |
| 77 | + * This is just a sample plugin that can be used as a starting point for creating your own plugin. |
| 78 | +It is not meant to be used in production. It is based on the built-in prometheus provider. |
0 commit comments