Assets
You can discover, download, and share assets using Bonsai, the Sensu asset index.
Read the guide to using assets to get started.
What is an asset?
Assets are shareable, reusable packages that make it easy to deploy Sensu plugins.
You can use assets to provide the plugins, libraries, and runtimes you need to automate your monitoring workflows.
Sensu supports runtime assets for checks, filters, mutators, and handlers.
NOTE: Assets are not required to use Sensu Go in production. Sensu plugins can still be installed using the sensu-install tool or a configuration management solution.
How do assets work?
Assets can be executed by the backend (for handler, filter, and mutator assets), or
by the agent (for check assets).
At runtime, the backend or agent sequentially fetches assets that appear in the runtime_assets
attribute of the handler, filter, mutator or check being executed, verifies the sha512 checksum, and unpacks them into the backend or agent’s local cache directory.
The directory path of each asset defined in runtime_assets
is then injected into the PATH
before the handler, filter, mutator or check command
is executed.
Subsequent handler, filter, mutator or check executions look for the asset in the local cache and ensure the contents match the configured checksum.
The backend or agent’s local cache path can be set using the --cache-dir
flag.
You can find a use case using a Sensu resource (a check) and an asset in this example asset with a check.
Sensu expects an asset to be a tar archive (optionally gzipped) containing one or more executables within a bin folder.
Any scripts or executables should be within a bin/
folder within in the archive.
See the Sensu Go Plugin template for an example asset and Bonsai configuration.
The following are injected into the execution context:
{PATH_TO_ASSET}/bin
is injected into the PATH
environment variable.
{PATH_TO_ASSET}/lib
is injected into the LD_LIBRARY_PATH
environment
variable.
{PATH_TO_ASSET}/include
is injected into the CPATH
environment variable.
NOTE: If you have used previous versions of Sensu and are familiar with plugins from the Sensu Plugins community, it is not possible to create an asset by creating an archive of an existing project. You must follow the steps outlined in this Sensu discourse guide. For further examples of Sensu users who have added the capability for a community plugin to be used as an asset, see this post.
Default cache directory
system |
sensu-backend |
sensu-agent |
Linux |
/var/cache/sensu/sensu-backend |
/var/cache/sensu/sensu-agent |
Windows |
N/A |
C:\ProgramData\sensu\cache\sensu-agent |
If the requested asset is not in the local cache, it is downloaded from the asset
URL. The Sensu backend does not currently provide any storage for assets; they
are expected to be retrieved over HTTP or HTTPS.
Example structure
sensu-example-handler_1.0.0_linux_amd64
├── CHANGELOG.md
├── LICENSE
├── README.md
└── bin
└── my-check.sh
└── lib
└── include
Asset specification
Top-level attributes
type |
|
description |
Top-level attribute specifying the sensuctl create resource type. Assets should always be of type Asset . |
required |
Required for asset definitions in wrapped-json or yaml format for use with sensuctl create . |
type |
String |
example |
|
api_version |
|
description |
Top-level attribute specifying the Sensu API group and version. For assets in Sensu backend version 5.8, this attribute should always be core/v2 . |
required |
Required for asset definitions in wrapped-json or yaml format for use with sensuctl create . |
type |
String |
example |
|
metadata |
|
description |
Top-level collection of metadata about the asset, including the name and namespace as well as custom labels and annotations . The metadata map is always at the top level of the asset definition. This means that in wrapped-json and yaml formats, the metadata scope occurs outside the spec scope. See the metadata attributes reference for details. |
required |
Required for asset definitions in wrapped-json or yaml format for use with sensuctl create . |
type |
Map of key-value pairs |
example |
"metadata": {
"name": "check_script",
"namespace": "default",
"labels": {
"region": "us-west-1"
},
"annotations": {
"slack-channel" : "#monitoring"
}
}
|
spec |
|
description |
Top-level map that includes the asset spec attributes. |
required |
Required for asset definitions in wrapped-json or yaml format for use with sensuctl create . |
type |
Map of key-value pairs |
example |
"spec": {
"url": "http://example.com/asset.tar.gz",
"sha512": "4f926bf4328fbad2b9cac873d117f771914f4b837c9c85584c38ccf55a3ef3c2e8d154812246e5dda4a87450576b2c58ad9ab40c9e2edc31b288d066b195b21b",
"filters": [
"entity.system.os == 'linux'",
"entity.system.arch == 'amd64'"
]
}
|
Spec attributes
url |
|
description |
The URL location of the asset. |
required |
true |
type |
String |
example |
"url": "http://example.com/asset.tar.gz"
|
sha512 |
|
description |
The checksum of the asset. |
required |
true |
type |
String |
example |
"sha512": "4f926bf4328..."
|
filters |
|
description |
A set of Sensu query expressions used to determine if the asset should be installed. If multiple expressions are included, each expression must return true in order for Sensu to install the asset.
Filters for check assets should match agent entity platforms, while filters for handler and filter assets should match your Sensu backend platform. You can create asset filter expressions using any supported entity system attributes, including os , arch , platform , and platform_family . PRO TIP: Asset filters let you reuse checks across platforms safely. Assign assets for multiple platforms to a single check, and rely on asset filters to ensure that only the appropriate asset is installed on each agent. |
required |
false |
type |
Array |
example |
"filters": ["entity.system.os=='linux'", "entity.system.arch=='amd64'"]
|
name |
|
description |
The unique name of the asset, validated with Go regex \A[\w\.\-]+\z . |
required |
true |
type |
String |
example |
|
namespace |
|
description |
The Sensu RBAC namespace that this asset belongs to. |
required |
false |
type |
String |
default |
default |
example |
"namespace": "production"
|
labels |
|
description |
Custom attributes you can use to create meaningful collections that can be selected with API filtering and sensuctl filtering. Overusing labels can impact Sensu’s internal performance, so we recommend moving complex, non-identifying metadata to annotations. |
required |
false |
type |
Map of key-value pairs. Keys can contain only letters, numbers, and underscores, but must start with a letter. Values can be any valid UTF-8 string. |
default |
null |
example |
"labels": {
"environment": "development",
"region": "us-west-2"
}
|
annotations |
|
description |
Non-identifying metadata that’s meaningful to people interacting with Sensu.
In contrast to labels, annotations cannot be used in API filtering or sensuctl filtering and do not impact Sensu’s internal performance. |
required |
false |
type |
Map of key-value pairs. Keys and values can be any valid UTF-8 string. |
default |
null |
example |
"annotations": {
"managed-by": "ops",
"playbook": "www.example.url"
}
|
Examples
Minimum required asset attributes
type: Asset
api_version: core/v2
metadata:
name: check_script
namespace: default
spec:
sha512: 4f926bf4328fbad2b9cac873d117f771914f4b837c9c85584c38ccf55a3ef3c2e8d154812246e5dda4a87450576b2c58ad9ab40c9e2edc31b288d066b195b21b
url: http://example.com/asset.tar.gz
{
"type": "Asset",
"api_version": "core/v2",
"metadata": {
"name": "check_script",
"namespace": "default"
},
"spec": {
"url": "http://example.com/asset.tar.gz",
"sha512": "4f926bf4328fbad2b9cac873d117f771914f4b837c9c85584c38ccf55a3ef3c2e8d154812246e5dda4a87450576b2c58ad9ab40c9e2edc31b288d066b195b21b"
}
}
Asset definition
type: Asset
api_version: core/v2
metadata:
annotations:
slack-channel: '#monitoring'
labels:
region: us-west-1
name: check_script
namespace: default
spec:
filters:
- entity.system.os == 'linux'
- entity.system.arch == 'amd64'
sha512: 4f926bf4328fbad2b9cac873d117f771914f4b837c9c85584c38ccf55a3ef3c2e8d154812246e5dda4a87450576b2c58ad9ab40c9e2edc31b288d066b195b21b
url: http://example.com/asset.tar.gz
{
"type": "Asset",
"api_version": "core/v2",
"metadata": {
"name": "check_script",
"namespace": "default",
"labels": {
"region": "us-west-1"
},
"annotations": {
"slack-channel" : "#monitoring"
}
},
"spec": {
"url": "http://example.com/asset.tar.gz",
"sha512": "4f926bf4328fbad2b9cac873d117f771914f4b837c9c85584c38ccf55a3ef3c2e8d154812246e5dda4a87450576b2c58ad9ab40c9e2edc31b288d066b195b21b",
"filters": [
"entity.system.os == 'linux'",
"entity.system.arch == 'amd64'"
]
}
}
Example asset with a check
---
type: Asset
api_version: core/v2
metadata:
name: sensu-prometheus-collector_linux_amd64
spec:
url: https://assets.bonsai.sensu.io/ef812286f59de36a40e51178024b81c69666e1b7/sensu-prometheus-collector_1.1.6_linux_amd64.tar.gz
sha512: a70056ca02662fbf2999460f6be93f174c7e09c5a8b12efc7cc42ce1ccb5570ee0f328a2dd8223f506df3b5972f7f521728f7bdd6abf9f6ca2234d690aeb3808
filters:
- entity.system.os == 'linux'
- entity.system.arch == 'amd64'
---
type: CheckConfig
api_version: core/v2
metadata:
name: prometheus_collector
namespace: default
spec:
command: "sensu-prometheus-collector -prom-url http://localhost:9090 -prom-query up"
interval: 10
publish: true
output_metric_handlers:
- influxdb
output_metric_format: influxdb_line
runtime_assets:
- sensu-prometheus-collector_linux_amd64
subscriptions:
- system
{
"type": "Asset",
"api_version": "core/v2",
"metadata": {
"name": "sensu-email-handler_linux_amd64"
},
"spec": {
"url": "https://assets.bonsai.sensu.io/45eaac0851501a19475a94016a4f8f9688a280f6/sensu-email-handler_0.2.0_linux_amd64.tar.gz",
"sha512": "d69df76612b74acd64aef8eed2ae10d985f6073f9b014c8115b7896ed86786128c20249fd370f30672bf9a11b041a99adb05e3a23342d3ad80d0c346ec23a946",
"filters": [
"entity.system.os == 'linux'",
"entity.system.arch == 'amd64'"
]
}
}
{
"type": "CheckConfig",
"api_version": "core/v2",
"metadata": {
"name": "prometheus_collector",
"namespace": "default"
},
"spec": {
"command": "sensu-prometheus-collector -prom-url http://localhost:9090 -prom-query up",
"handlers": [
"influxdb"
],
"interval": 10,
"publish": true,
"output_metric_format": "influxdb_line",
"runtime_assets": [
"sensu-prometheus-collector_linux_amd64"
],
"subscriptions": [
"system"
]
}
}
Sharing an asset on Bonsai
Share your open-source assets on Bonsai and connect with the Sensu Community.
Bonsai supports assets hosted on GitHub and released using GitHub releases.
For more information about creating Sensu Plugins, see the Sensu Plugin specification.
Bonsai requires a bonsai.yml
configuration file in the root directory of your repository that includes the project description, platforms, asset filenames, and SHA-512 checksums.
For a Bonsai-compatible asset template using Go and GoReleaser, see the Sensu Go plugin skeleton.
To share your asset on Bonsai, log in to Bonsai with your GitHub account and authorize Sensu.
Once logged in, you can register your asset on Bonsai by adding the GitHub repository, description, and tags.
Make sure to provide a helpful README for your asset with configuration examples.
bonsai.yml
example
---
description: "#{repo}"
builds:
- platform: "linux"
arch: "amd64"
asset_filename: "#{repo}_#{version}_linux_amd64.tar.gz"
sha_filename: "#{repo}_#{version}_sha512-checksums.txt"
filter:
- "entity.system.os == 'linux'"
- "entity.system.arch == 'amd64'"
- platform: "Windows"
arch: "amd64"
asset_filename: "#{repo}_#{version}_windows_amd64.tar.gz"
sha_filename: "#{repo}_#{version}_sha512-checksums.txt"
filter:
- "entity.system.os == 'windows'"
- "entity.system.arch == 'amd64'"
bonsai.yml
specification
description |
|
description |
The project description |
required |
true |
type |
String |
example |
|
builds |
|
description |
An array of asset details per platform |
required |
true |
type |
Array |
example |
builds:
- platform: "linux"
arch: "amd64"
asset_filename: "#{repo}_#{version}_linux_amd64.tar.gz"
sha_filename: "#{repo}_#{version}_sha512-checksums.txt"
filter:
- "entity.system.os == 'linux'"
- "entity.system.arch == 'amd64'"
|
Builds specification
platform |
|
description |
The platform supported by the asset |
required |
true |
type |
String |
example |
|
arch |
|
description |
The architecture supported by the asset |
required |
true |
type |
String |
example |
|
asset_filename |
|
description |
The filename of the archive containing the asset |
required |
true |
type |
String |
example |
asset_filename: "#{repo}_#{version}_linux_amd64.tar.gz"
|
sha_filename |
|
description |
The SHA-512 checksum for the asset archive |
required |
true |
type |
String |
example |
sha_filename: "#{repo}_#{version}_sha512-checksums.txt"
|
filter |
|
description |
Filter expressions describing the operating system and architecture supported by the asset |
required |
false |
type |
Array |
example |
filter:
- "entity.system.os == 'linux'"
- "entity.system.arch == 'amd64'"
|