Assets

• What is an asset?
• How do assets work?
• Asset format specification
• Asset specification
• Examples
• Sharing an asset on Bonsai

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.

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 the local cache and ensure the contents match the checksum. The backend or agent’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

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

Spec attributes

"url": "http://example.com/asset.tar.gz"

"sha512": "4f926bf4328..."

"filters": ["entity.system.os=='linux'", "entity.system.arch=='amd64'"] 

Metadata attributes

"name": "check_script"

"namespace": "production"

"labels": {
  "environment": "development",
  "region": "us-west-2"
}

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

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

Builds specification

- 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'"