Install plugins with assets

Assets are shareable, reusable packages that make it easier to deploy Sensu plugins. You can use assets to provide the plugins, libraries, and runtimes you need to automate your monitoring workflows. See the asset reference for more information about assets.

1. Download an asset definition from Bonsai

You can discover, download, and share assets with Bonsai, the Sensu asset index. To use an asset, click the Download button on the asset page in Bonsai to download the asset definition for your Sensu backend platform and architecture. Asset definitions tell Sensu how to download and verify the asset when required by a check, filter, mutator, or handler.

For example, here’s the asset definition for version 1.1.0 of the Sensu PagerDuty Handler asset for Linux AMD64:

---
type: Asset
api_version: core/v2
metadata:
  name: sensu-pagerduty-handler
  namespace: default
  labels: {}
  annotations: {}
spec:
  url: https://assets.bonsai.sensu.io/698710262d59c72ace3e31524960630dc1e4f190/sensu-pagerduty-handler_1.1.0_linux_amd64.tar.gz
  sha512: e93ec4465af5a2057664e8c3cd68e9352457b81315b97578eaae5e21f0cf7419d4fc36feb0155eeb0dd5a227e267307a58ee58a9f3e85bf3d44da3738bf691ca
  filters:
  - entity.system.os == 'linux'
  - entity.system.arch == 'amd64'

After you download an asset definition, open the file and adjust the namespace and filters for your Sensu instance. Filters for check assets should match entity platforms. Filters for handler and filter assets should match your Sensu backend platform. If the provided filters are too restrictive for your platform, replace os and arch with any supported entity system attributes (for example, entity.system.platform_family == 'rhel'). You may also want to customize the asset name to reflect the supported platform (for example, sensu-pagerduty-handler-linux) and add custom attributes with labels and annotations.

Enterprise-tier assets (like the ServiceNow and Jira event handlers) require a Sensu commercial license. For more information about commercial features and to activate your license, see Get started with commercial features.

2. Register the asset with Sensu

After you download the asset definition, you can register the asset with Sensu using sensuctl:

sensuctl create --file sensu-sensu-pagerduty-handler-1.1.0-linux-amd64.yml

You can also use sensuctl to verify that the asset is registered and ready to use:

sensuctl asset list

3. Create a workflow

With the asset downloaded and registered, you can use it in a monitoring workflow. Assets may provide executable plugins intended for use with a Sensu check, handler, mutator, or hook, or JavaScript libraries intended to provide functionality for use in event filters. The details in Bonsai are the best resource for information about each asset’s capabilities and configuration.

For example, to use the Sensu PagerDuty Handler asset, you would create a pagerduty handler that includes your PagerDuty service API key in place of SECRET and sensu-pagerduty-handler as a runtime asset:

type: Handler
api_version: core/v2
metadata:
  name: pagerduty
  namespace: default
spec:
  command: sensu-pagerduty-handler
  env_vars:
  - PAGERDUTY_TOKEN=SECRET
  filters:
  - is_incident
  runtime_assets:
  - sensu-pagerduty-handler
  timeout: 10
  type: pipe
{
    "api_version": "core/v2",
    "type": "Handler",
    "metadata": {
        "namespace": "default",
        "name": "pagerduty"
    },
    "spec": {
        "type": "pipe",
        "command": "sensu-pagerduty-handler",
        "env_vars": [
          "PAGERDUTY_TOKEN=SECRET"
        ],
        "runtime_assets": ["sensu-pagerduty-handler"],
        "timeout": 10,
        "filters": [
            "is_incident"
        ]
    }
}

Save the definition to a file (for example, pagerduty-handler.json), and add it to Sensu with sensuctl:

sensuctl create --file pagerduty-handler.json

Now that Sensu can create incidents in PagerDuty, you can automate this workflow by adding the pagerduty handler to your Sensu service check definitions. See Monitor server resources to learn more.

Next steps

Read these resources for more information about using assets in Sensu: