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 evaluates assets that appear in the runtime_assets attribute of the handler, filter, mutator or check being executed.

What are asset builds?

An asset build is the combination of an artifact URL, SHA512 checksum and optional Sensu query expression filters. Each asset definition may describe one or more builds.

NOTE: Assets which provide url and sha512 attributes at the top-level of the spec scope are single build assets – this form of asset defintion is deprecated. We recommend using multiple build asset defintions, which specify one or more builds under the spec scope.

How are asset builds evaluated?

For each build provided in an asset, Sensu will evaluate any defined filters to determine whether any build matches the agent or backend service’s environment. If all filters specified on a build evaluate to true, that build is considered a match. For assets with multiple builds, only the first build which matches will be downloaded and installed.

How are asset builds installed?

After finding a matching build, the build artifact will be downloaded from the provided URL. If the asset definition includes headers, these will be passed along as part of the HTTP request. If the downloaded artifact’s SHA512 checksum matches the checksum provided by the build, it is unpacked into the Sensu service’s local cache directory.

The backend or agent’s local cache path can be set using the --cache-dir flag. You can disable assets for an agent using the agent --disable-assets configuration flag.

How are asset builds executed?

The directory path of each asset defined in runtime_assets is appended to 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.

You can find a use case using a Sensu resource (a check) and an asset in this example asset with a check.

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.

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 hello world example

In this example, we’ll run a script that outputs Hello World:

hello-world.sh

#!/bin/sh

STRING="Hello World"

echo $STRING

if [ $? -eq 0 ]; then
    exit 0
else
    exit 2
fi

The first step is to ensure that our directory structure is in place. As noted in Example structure, our script could live in three potential directories in the project: /bin, /lib, or /include. For this case, we will put our script in the /bin directory. We’ll create the directories sensu-go-hello-world and /bin:

$ mkdir sensu-go-hello-world

$ cd sensu-go-hello-world

$ mkdir bin

$ cp hello-world.sh bin/

$ tree
.
└── bin
    └── hello-world.sh

Next, we’ll ensure that the script is marked as executable:

$ chmod +x bin/hello-world.sh 
mode of 'hello-world.sh' changed from 0644 (rw-r--r--) to 0755 (rwxr-xr-x)

Now that the script is in the directory, let’s move on to the next step: packaging the sensu-go-hello-world directory as an asset tarball.

Packaging the asset

Assets are archives, so the first step in packaging the asset is to create a tar.gz archive of our project. This assumes we’re in the directory we want to tar up:

$ cd ..
$ tar -C sensu-go-hello-world -cvzf sensu-go-hello-world-0.0.1.tar.gz .
...

Excellent. Now that we’ve created an archive, we’ll need to generate a SHA512 sum for it (this is required–otherwise, the asset won’t work):

sha512sum sensu-go-hello-world-0.0.1.tar.gz | tee sha512sum.txt
dbfd4a714c0c51c57f77daeb62f4a21141665ae71440951399be2d899bf44b3634dad2e6f2516fff1ef4b154c198b9c7cdfe1e8867788c820db7bb5bcad83827 sensu-go-hello-world-0.0.1.tar.gz

Now that we have our sha512sum, we’ll need to host the release (archive and sha512sum) somewhere. You can do this with S3, a GitHub release, or even just serving the files out of a directory using Nginx/Apache.

In this case, we’ll use GitHub to serve our release. Click Create a new release:

Create a new github release

We will see the following screen:

Release details screen

On this screen, we’ll enter a tag version, release title, and release description details and drag and drop our asset and checksum so they will be uploaded as part of the release. When we’ve done that, the screen will look something like this:

Release details filled in

Click Publish release. The latest release page will load:

Completed release

Next, we need to create definitions for the asset and the check.

Generating the definitions

So far, we’ve created a directory for our asset with our script present in /bin, packaged up the asset and generated a checksum for it, and hosted our release on GitHub. Now, let’s generate some definitions for our asset to make it work.

First, let’s generate our asset definition:

---
type: Asset
api_version: core/v2
metadata:
  name: sensu-go-hello-world-asset
  namespace: default
spec:
  url: https://github.com/yourusername/sensu-go-hello-world/releases/download/0.0.1/sensu-go-hello-world-0.0.1.tar.gz
  sha512: dbfd4a714c0c51c57f77daeb62f4a21141665ae71440951399be2d899bf44b3634dad2e6f2516fff1ef4b154c198b9c7cdfe1e8867788c820db7bb5bcad83827
{
  "type": "Asset",
  "api_version": "core/v2",
  "metadata": {
    "name": "sensu-go-hello-world-asset",
    "namespace": "default"
  },
  "spec": {
    "url": "https://github.com/yourusername/sensu-go-hello-world/releases/download/0.0.1/sensu-go-hello-world-0.0.1.tar.gz",
    "sha512": "dbfd4a714c0c51c57f77daeb62f4a21141665ae71440951399be2d899bf44b3634dad2e6f2516fff1ef4b154c198b9c7cdfe1e8867788c820db7bb5bcad83827"
  }
}

Second, we’ll create a basic check that uses the asset:

type: CheckConfig
api_version: core/v2
metadata:
  name: sensu-go-hello-world
  namespace: default
spec:
  command: hello-world.sh
  runtime_assets:
  - sensu-go-hello-world-asset
  interval: 10
  publish: true
  handlers:
    - debug
  subscriptions:
  - linux
{
  "type": "CheckConfig",
  "api_version": "core/v2",
  "metadata": {
    "name": "sensu-go-hello-world",
    "namespace": "default"
  },
  "spec": {
    "command": "hello-world.sh",
    "runtime_assets": [
      "sensu-go-hello-world-asset"
    ],
    "interval": 10,
    "publish": true,
    "handlers": [
      "debug"
    ],
    "subscriptions": [
      "linux"
    ]
  }
}

Third, we’ll apply both definitions to our Sensu Go deployment:

sensuctl create -f sensu-go-hello-world-asset.yml
sensuctl create -f sensu-go-hello-world-check.yml

Finally, let’s take a look in the dashboard to see our check using our asset. In this case, we have an entity named sensu-agent-01, and we can see that the check successfully executes:

Sensu go agent successfully executes check with hello world asset

Congratulations! You created an asset from a script, uploaded the asset to GitHub as a release, and created your own definitions to use the asset.

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 this version of Sensu, 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": {
    "playbook" : "www.example.url"
  }
}
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 (multiple builds)
"spec": {
  "builds": [
    {
      "url": "http://example.com/asset-linux-amd64.tar.gz",
      "sha512": "487ab34b37da8ce76d2657b62d37b35fbbb240c3546dd463fa0c37dc58a72b786ef0ca396a0a12c8d006ac7fa21923e0e9ae63419a4d56aec41fccb574c1a5d3",
      "filters": [
        "entity.system.os == 'linux'",
        "entity.system.arch == 'amd64'"
      ]
    },
    {
        "url": "http://example.com/asset-linux-armv7.tar.gz",
        "sha512": "70df8b7e9aa36cf942b972e1781af04815fa560441fcdea1d1538374066a4603fc5566737bfd6c7ffa18314edb858a9f93330a57d430deeb7fd6f75670a8c68b",
        "filters": [
          "entity.system.os == 'linux'",
          "entity.system.arch == 'arm'",
          "entity.system.arm_version == 7"
        ]
      }
  ],
  "headers": {
    "Authorization": "Bearer $TOKEN",
    "X-Forwarded-For": "client1, proxy1, proxy2"
  }
}
example (single build, deprecated)
"spec": {
  "url": "http://example.com/asset.tar.gz",
  "sha512": "4f926bf4328fbad2b9cac873d117f771914f4b837c9c85584c38ccf55a3ef3c2e8d154812246e5dda4a87450576b2c58ad9ab40c9e2edc31b288d066b195b21b",
  "filters": [
    "entity.system.os == 'linux'",
    "entity.system.arch == 'amd64'"
  ],
  "headers": {
    "Authorization": "Bearer $TOKEN",
    "X-Forwarded-For": "client1, proxy1, proxy2"
  }
}

Spec attributes

builds
description A list of asset builds used to define multiple artifacts which provide the named asset.
required true, if url, sha512 and filters are not provided
type Array
example
"builds": [
    {
      "url": "http://example.com/asset-linux-amd64.tar.gz",
      "sha512": "487ab34b37da8ce76d2657b62d37b35fbbb240c3546dd463fa0c37dc58a72b786ef0ca396a0a12c8d006ac7fa21923e0e9ae63419a4d56aec41fccb574c1a5d3",
      "filters": [
        "entity.system.os == 'linux'",
        "entity.system.arch == 'amd64'"
      ]
    },
    {
        "url": "http://example.com/asset-linux-armv7.tar.gz",
        "sha512": "70df8b7e9aa36cf942b972e1781af04815fa560441fcdea1d1538374066a4603fc5566737bfd6c7ffa18314edb858a9f93330a57d430deeb7fd6f75670a8c68b",
        "filters": [
          "entity.system.os == 'linux'",
          "entity.system.arch == 'arm'",
          "entity.system.arm_version == 7"
        ]
      }
  ]
url
description The URL location of the asset.
required true, unless builds are provided.
type String
example
"url": "http://example.com/asset.tar.gz"
sha512
description The checksum of the asset.
required true, unless builds are provided.
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'"] 
headers
description HTTP headers to apply to asset retrieval requests. You can use headers to access secured assets. For headers requiring multiple values, separate values with a comma.
required false
type Map of key-value string pairs
example
"headers": {
  "Authorization": "Bearer $TOKEN",
  "X-Forwarded-For": "client1, proxy1, proxy2"
}

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 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:
  builds:
  - sha512: 4f926bf4328fbad2b9cac873d117f771914f4b837c9c85584c38ccf55a3ef3c2e8d154812246e5dda4a87450576b2c58ad9ab40c9e2edc31b288d066b195b21b
    url: http://example.com/asset.tar.gz
{
  "type": "Asset",
  "api_version": "core/v2",
  "metadata": {
    "name": "check_script",
    "namespace": "default"
  },
  "spec": {
    "builds": [
      {
        "url": "http://example.com/asset.tar.gz",
        "sha512": "4f926bf4328fbad2b9cac873d117f771914f4b837c9c85584c38ccf55a3ef3c2e8d154812246e5dda4a87450576b2c58ad9ab40c9e2edc31b288d066b195b21b"
      }
    ]
  }
}

Asset definition (single build, deprecated)

type: Asset
api_version: core/v2
metadata:
  name: check_cpu_linux_amd64
  namespace: default
  labels:
    origin: bonsai
  annotations:
    project_url: https://bonsai.sensu.io/assets/asachs01/sensu-go-cpu-check
    version: 0.0.3
spec:
  url: https://assets.bonsai.sensu.io/981307deb10ebf1f1433a80da5504c3c53d5c44f/sensu-go-cpu-check_0.0.3_linux_amd64.tar.gz
  sha512: 487ab34b37da8ce76d2657b62d37b35fbbb240c3546dd463fa0c37dc58a72b786ef0ca396a0a12c8d006ac7fa21923e0e9ae63419a4d56aec41fccb574c1a5d3
  filters:
  - entity.system.os == 'linux'
  - entity.system.arch == 'amd64'
  headers:
    Authorization: Bearer $TOKEN
    X-Forwarded-For: client1, proxy1, proxy2
{
  "type": "Asset",
  "api_version": "core/v2",
  "metadata": {
    "name": "check_cpu_linux_amd64",
    "namespace": "default",
    "labels": {
      "origin": "bonsai"
    },
    "annotations": {
      "project_url": "https://bonsai.sensu.io/assets/asachs01/sensu-go-cpu-check",
      "version": "0.0.3"
    }
  },
  "spec": {
    "url": "https://assets.bonsai.sensu.io/981307deb10ebf1f1433a80da5504c3c53d5c44f/sensu-go-cpu-check_0.0.3_linux_amd64.tar.gz",
    "sha512": "487ab34b37da8ce76d2657b62d37b35fbbb240c3546dd463fa0c37dc58a72b786ef0ca396a0a12c8d006ac7fa21923e0e9ae63419a4d56aec41fccb574c1a5d3",
    "filters": [
      "entity.system.os == 'linux'",
      "entity.system.arch == 'amd64'"
    ],
    "headers": {
      "Authorization": "Bearer $TOKEN",
      "X-Forwarded-For": "client1, proxy1, proxy2"
    }
  }
}

Asset definition (multiple builds)

type: Asset
api_version: core/v2
metadata:
  name: check_cpu
  namespace: default
  labels:
    origin: bonsai
  annotations:
    project_url: https://bonsai.sensu.io/assets/asachs01/sensu-go-cpu-check
    version: 0.0.3
spec:
  builds:
  - url: https://assets.bonsai.sensu.io/981307deb10ebf1f1433a80da5504c3c53d5c44f/sensu-go-cpu-check_0.0.3_linux_amd64.tar.gz
    sha512: 487ab34b37da8ce76d2657b62d37b35fbbb240c3546dd463fa0c37dc58a72b786ef0ca396a0a12c8d006ac7fa21923e0e9ae63419a4d56aec41fccb574c1a5d3
    filters:
    - entity.system.os == 'linux'
    - entity.system.arch == 'amd64'
    headers:
      Authorization: Bearer $TOKEN
      X-Forwarded-For: client1, proxy1, proxy2
  - url: https://assets.bonsai.sensu.io/981307deb10ebf1f1433a80da5504c3c53d5c44f/sensu-go-cpu-check_0.0.3_linux_armv7.tar.gz
    sha512: 70df8b7e9aa36cf942b972e1781af04815fa560441fcdea1d1538374066a4603fc5566737bfd6c7ffa18314edb858a9f93330a57d430deeb7fd6f75670a8c68b
    filters:
    - entity.system.os == 'linux'
    - entity.system.arch == 'arm'
    - entity.system.arm_version == 7
    headers:
      Authorization: Bearer $TOKEN
      X-Forwarded-For: client1, proxy1, proxy2
  - url: https://assets.bonsai.sensu.io/981307deb10ebf1f1433a80da5504c3c53d5c44f/sensu-go-cpu-check_0.0.3_windows_amd64.tar.gz
    sha512: 10d6411e5c8bd61349897cf8868087189e9ba59c3c206257e1ebc1300706539cf37524ac976d0ed9c8099bdddc50efadacf4f3c89b04a1a8bf5db581f19c157f
    filters:
    - entity.system.os == 'windows'
    - entity.system.arch == 'amd64'
    headers:
      Authorization: Bearer $TOKEN
      X-Forwarded-For: client1, proxy1, proxy2
{
  "type": "Asset",
  "api_version": "core/v2",
  "metadata": {
    "name": "check_cpu",
    "namespace": "default",
    "labels": {
      "origin": "bonsai"
    },
    "annotations": {
      "project_url": "https://bonsai.sensu.io/assets/asachs01/sensu-go-cpu-check",
      "version": "0.0.3"
    }
  },
  "spec": {
    "builds": [
      {
        "url": "https://assets.bonsai.sensu.io/981307deb10ebf1f1433a80da5504c3c53d5c44f/sensu-go-cpu-check_0.0.3_linux_amd64.tar.gz",
        "sha512": "487ab34b37da8ce76d2657b62d37b35fbbb240c3546dd463fa0c37dc58a72b786ef0ca396a0a12c8d006ac7fa21923e0e9ae63419a4d56aec41fccb574c1a5d3",
        "filters": [
          "entity.system.os == 'linux'",
          "entity.system.arch == 'amd64'"
        ],
        "headers": {
          "Authorization": "Bearer $TOKEN",
          "X-Forwarded-For": "client1, proxy1, proxy2"
        }
      },
      {
        "url": "https://assets.bonsai.sensu.io/981307deb10ebf1f1433a80da5504c3c53d5c44f/sensu-go-cpu-check_0.0.3_linux_armv7.tar.gz",
        "sha512": "70df8b7e9aa36cf942b972e1781af04815fa560441fcdea1d1538374066a4603fc5566737bfd6c7ffa18314edb858a9f93330a57d430deeb7fd6f75670a8c68b",
        "filters": [
          "entity.system.os == 'linux'",
          "entity.system.arch == 'arm'",
          "entity.system.arm_version == 7"
        ],
        "headers": {
          "Authorization": "Bearer $TOKEN",
          "X-Forwarded-For": "client1, proxy1, proxy2"
        }
      },
      {
        "url": "https://assets.bonsai.sensu.io/981307deb10ebf1f1433a80da5504c3c53d5c44f/sensu-go-cpu-check_0.0.3_windows_amd64.tar.gz",
        "sha512": "10d6411e5c8bd61349897cf8868087189e9ba59c3c206257e1ebc1300706539cf37524ac976d0ed9c8099bdddc50efadacf4f3c89b04a1a8bf5db581f19c157f",
        "filters": [
          "entity.system.os == 'windows'",
          "entity.system.arch == 'amd64'"
        ],
        "headers": {
          "Authorization": "Bearer $TOKEN",
          "X-Forwarded-For": "client1, proxy1, proxy2"
        }
      }
    ]
  }
}

Example asset with a check

---
type: Asset
api_version: core/v2
metadata:
  name: sensu-prometheus-collector
spec:
  builds:
  - 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
  subscriptions:
  - system
{
  "type": "Asset",
  "api_version": "core/v2",
  "metadata": {
    "name": "sensu-email-handler"
  },
  "spec": {
    "builds": [
      {
        "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"
    ],
    "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
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 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'"

Deleting Assets

As of Sensu Go 5.12, assets can be deleted using the /assets (DELETE) endpoint, or via sensuctl (sensuctl asset delete). Note that when an asset is removed from Sensu, this does not remove references to the deleted asset in any other resource (checks, filters, mutators, handlers, hooks). You must also update resources and remove any reference to the deleted asset. Failure to do so will result in errors like: sh: asset.sh: command not found.

Errors as a result of failing to remove the asset from checks and hooks will be surfaced in the event data, whereas failing to remove the asset reference on a mutator, handler and filter will only be surfaced in the backend logs.

It is also worth noting that deleting an asset does not delete the archive or downloaded files on disk. These must be removed from the asset cache manually.