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 create automated monitoring workflows with Sensu. Sensu supports runtime assets for checks, filters, mutators, and handlers.

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 entity sequentially fetches assets and stores them in its local cache. Asset dependencies are then injected into the PATH so they are available when the command is executed. Subsequent check, handler, filter, or mutator executions look for the asset in local cache and ensure the contents match the checksum. An entity’s local cache can be set using the --cache-dir flag.

Asset format specification

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.

Default cache directory

system sensu-backend sensu-agent
default /var/cache/sensu/sensu-backend /var/cache/sensu/sensu-agent
Windows C:\\ProgramData\sensu\cache\sensu-backend 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

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
description: "#{repo}"
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
- platform: "linux"
arch
description The architecture supported by the asset
required true
type String
example
  arch: "amd64"
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 Entity filters specifying the operating system and architecture supported by the asset
required false
type Array
example
  filter:
  -  "entity.system.os == 'linux'"
  -  "entity.system.arch == 'amd64'"

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
"type": "Asset"
api_version
description Top-level attribute specifying the Sensu API group and version. For assets in Sensu backend version 5.2, 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
"api_version": "core/v2"
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 by the agent to determine if the asset should be installed. If multiple expressions are included, each expression must return true in order for the agent to install the asset.
required false
type Array
example
"filters": ["entity.system.os=='linux'", "entity.system.arch=='amd64'"] 

Metadata attributes

name
description The unique name of the asset, validated with Go regex \A[\w\.\-]+\z.
required true
type String
example
"name": "check_script"
namespace
description The Sensu RBAC namespace that this asset belongs to.
required false
type String
default default
example
"namespace": "production"
labels
description Custom attributes to include with event data, which can be queried like regular attributes. You can use labels to organize assets into meaningful collections that can be selected using filters and tokens.
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 Arbitrary, non-identifying metadata to include with event data. In contrast to labels, annotations are not used internally by Sensu and cannot be used to identify assets. You can use annotations to add data that helps people or external tools interacting with Sensu.
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",
  "slack-channel": "#monitoring",
  "playbook": "www.example.url"
}

Examples

Minimum required asset attributes

{
  "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": {
    "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'"
    ]
  }
}