Use sensuctl with Bonsai

Sensuctl supports installing dynamic runtime asset definitions directly from Bonsai, the Sensu asset hub, and checking your Sensu backend for outdated dynamic runtime assets. You can also use sensuctl command to install, execute, list, and delete commands from Bonsai or a URL.

Install dynamic runtime asset definitions

To install a dynamic runtime asset definition directly from Bonsai, use sensuctl asset add [NAMESPACE/NAME][:VERSION]. [:VERSION] is only required if you require a specific version or are pinning to a specific version.

Replace [NAMESPACE/NAME] with the namespace and name of the dynamic runtime asset from Bonsai:

Bonsai page for InfluxDB handler showing namespace and name

sensuctl asset add sensu/sensu-influxdb-handler:3.1.1
fetching bonsai asset: sensu/sensu-influxdb-handler:3.1.1
added asset: sensu/sensu-influxdb-handler:3.1.1

You have successfully added the Sensu asset resource, but the asset will not get downloaded until
it's invoked by another Sensu resource (ex. check). To add this runtime asset to the appropriate
resource, populate the "runtime_assets" field with ["sensu/sensu-influxdb-handler"].

You can also use the --rename flag to rename the dynamic runtime asset on install:

sensuctl asset add sensu/sensu-influxdb-handler:3.1.1 --rename influxdb-handler
fetching bonsai asset: sensu/sensu-influxdb-handler:3.1.1
added asset: sensu/sensu-influxdb-handler:3.1.1

You have successfully added the Sensu asset resource, but the asset will not get downloaded until
it's invoked by another Sensu resource (ex. check). To add this runtime asset to the appropriate
resource, populate the "runtime_assets" field with ["influxdb-handler"].

NOTE: Sensu does not download and install dynamic runtime asset builds onto the system until they are needed for command execution. Read the asset reference for more information about dynamic runtime asset builds.

Check your Sensu backend for outdated dynamic runtime assets

To check your Sensu backend for dynamic runtime assets that have newer versions available on Bonsai, use sensuctl asset outdated. This will print a list of dynamic runtime assets installed in the backend whose version is older than the newest version available on Bonsai:

sensuctl asset outdated
          Asset Name                  Bonsai Asset          Current Version  Latest Version
----------------------------  ----------------------------  ---------------  --------------
sensu/sensu-influxdb-handler  sensu/sensu-influxdb-handler       3.1.1            3.1.2

Extend sensuctl with commands

Use sensuctl command to install, execute, list, and delete commands from Bonsai or a URL.

Install commands

To install a sensuctl command from Bonsai or a URL:

sensuctl command install [ALIAS] ([NAMESPACE/NAME]:[VERSION] | --url [ARCHIVE_URL] --checksum [ARCHIVE_CHECKSUM]) [flags]

To install a command plugin, use the Bonsai asset name or specify a URL and SHA512 checksum.

To install a command using the Bonsai asset name, replace [NAMESPACE/NAME] with the name of the asset from Bonsai. [:VERSION] is only required if you require a specific version or are pinning to a specific version. If you do not specify a version, sensuctl will fetch the latest version from Bonsai.

Replace [ALIAS] with a unique name for the command. For example, for the Sensu EC2 Discovery Plugin, you might use the alias sensu-ec2-discovery. [ALIAS] is required.

Replace [flags] with the flags you want to use. Run sensuctl command install -h to view flags. Flags are optional and apply only to the install command — they are not saved as part of the command you are installing.

To install a command from the Sensu EC2 Discovery Plugin with no flags:

sensuctl command install sensu-ec2-discovery portertech/sensu-ec2-discovery:0.3.0

To install a command from a URL, replace [ARCHIVE_URL] with a command URL that points to a tarball (e.g. https://path/to/asset.tar.gz). Replace [ARCHIVE_CHECKSUM] with the checksum you want to use. Replace [ALIAS] with a unique name for the command.

Replace [flags] with the flags you want to use. Run sensuctl command install -h to view flags. Flags are optional and apply only to the install command — they are not saved as part of the command you are installing.

For example, to install a command-test dynamic runtime asset via URL with no flags:

sensuctl command install command-test --url https://github.com/amdprophet/command-test/releases/download/v0.0.4/command-test_0.0.4_darwin_amd64.tar.gz --checksum 8b15a170e091dab42256fe64ca7c4a050ed49a9dbfd6c8129c95506a8a9a91f2762ac1a6d24f4fc545430613fd45abc91d3e5d3605fcfffb270dcf01996caa7f

NOTE: Dynamic runtime asset definitions with multiple asset builds are only supported via Bonsai.

Execute commands

To execute a sensuctl command plugin via its dynamic runtime asset’s bin/entrypoint executable:

sensuctl command exec [ALIAS] [args] [flags]

Replace [ALIAS] with a unique name for the command. For example, for the Sensu EC2 Discovery Plugin, you might use the alias sensu-ec2-discovery. [ALIAS] is required.

Replace [flags] with the flags you want to use. Run sensuctl command exec -h to view flags. Flags are optional and apply only to the exec command — they are not saved as part of the command you are executing.

Replace [args] with the globlal flags you want to use. Run sensuctl command exec -h to view global flags. To pass [args] flags to the bin/entrypoint executable, make sure to specify them after a double dash surrounded by spaces.

NOTE: When you use sensuctl command exec, the environment variables are passed to the command.

For example:

sensuctl command exec mycommand arg1 arg2 --cache-dir /tmp -- --flag1 --flag2=value

Sensuctl will parse the –cache-dir flag, but bin/entrypoint will parse all flags after the --.

In this example, the full command run by sensuctl exec would be:

bin/entrypoint arg1 arg2 --flag1 --flag2=value

List commands

To list installed sensuctl commands:

sensuctl command list [flags]

Replace [flags] with the flags you want to use. Run sensuctl command list -h to view flags. Flags are optional and apply only to the list command.

Delete commands

To delete sensuctl commands:

sensuctl command delete [ALIAS] [flags]

Replace [ALIAS] with a unique name for the command. For example, for the Sensu EC2 Discovery Plugin, you might use the alias sensu-ec2-discovery. [ALIAS] is required.

Replace [flags] with the flags you want to use. Run sensuctl command delete -h to view flags. Flags are optional and apply only to the delete command.