In case you missed it, Sensu Go is here! And, as I wrote about previously, one of the hurdles with migrating workloads from the original version of Sensu to Sensu Go are the changes in the internal event data structure. The existing handlers and mutators in the community maintained Sensu Plugins collection might not work as expected in Sensu Go because of these event data model changes. But friends, I’m here to tell you that we’ve got this problem licked.
The new 3.0.0 release of the
sensu-plugin gem has opt-in logic to help you transition workloads using existing Ruby mutators and handlers from the Sensu Community Plugins collection. Once the community plugins you rely on are updated to require the 3.0
sensu-plugin gem, you’ll have a much easier time migrating your existing workflows without having to write your own mutator for event data. This post marks the first in a series in which I help folks migrate their workloads to Sensu Go.
Using updated handlers and mutators
Once a plugin has been updated to depend on the latest version of
sensu-plugin, all the provided handlers and mutators gain the option to enable mapping from Sensu Go to Sensu Ruby events. You can activate the logic using either an additional command line option or by setting an environment variable in your Sensu Go handler/mutator resource environment. If you want to see how it works in practice, grab the latest
sensu-plugin gem and ask mutator-sensu-go-into-ruby.rb for its help output:
mutator-sensu-go-into-ruby.rb --help Usage: /usr/local/bin/mutator-sensu-go-into-ruby.rb (options) --map-go-event-into-ruby Enable Sensu Go to Sensu Ruby event mapping. Alternatively set envvar SENSU_MAP_GO_EVENT_INTO_RUBY=1.
Using the mix-in magic in
sensu-plugin, the command line option and usage are added to every handler and mutator built from the base classes in
By default, the new mapping logic won’t be used in any handler or mutator command, so once your plugins are upgraded, (if you’re an existing Sensu 1.x user) you won’t have to do anything different for your configs. But when you’re ready to migrate to Sensu Go, you’ll be able to either use an environment variable to turn on the mapping for all handlers and mutators that support it or selectively enable the mapping using a command-line argument.
This event mapping logic is meant to be a transitional helper to keep existing handlers and mutators working until Sensu Go native implementations can be spun up. I say transitional because this approach uses a mutator operation to rewrite the event data, and is going to be suboptimal compared to a handler that can parse the Sensu Go event data directly because of the additional overhead to mutate the data object.
How you can help
Now with the new
sensu-plugin package released, the next step is to get the other Sensu Community Plugins updated to make use of the new version. This is a great opportunity for Sensu users — like you — to contribute and help make the Sensu Go experience better for everyone! If you haven’t done a pull request against any of the community maintained plugins before, these plugin updates should make for a great first-time technical contribution. You can use this search query to get a listing of open issues for plugins that are a candidate.
Feel free to take a look at the open issues list and see if there is a plugin you can help update. If you want to try to help out and contribute a fix, take a look at the Sensu Plugins pull request process. I’ll be watching the Sensu Go enablement issues and following up on relevant pull requests, but if you get stuck you can ping me in the Sensu Community Slack (@jspaleta) or raise an issue in our Community Forum and I’ll see if I can help.
For most plugins, this should be a very simple change to the gemspec to bump the
sensu-plugin runtime dependency, then running the local verification tests to ensure the plugin still builds as expected. Some plugins may need additional changes to update other runtime dependencies. I can help with that if needed — just ping me on Slack.
I am currently working on updating
sensu-plugins-logs, but there are several other community-maintained plugins that need to be updated. I have filed issues against all the Sensu Plugins I’m aware of with handlers or mutators in the Sensu Plugins GitHub organization. And please, if there are Sensu Plugins you’re using that are maintained outside of the Sensu Plugins organization, please file issues to encourage them to update their runtime dependency to
sensu-plugin 3.0 (and let me know you filed the issue so I can keep track).
Testing with the provided mutator
In the meantime, if you have event pipelines making use of Sensu Plugin handlers without need of a mutator, those can be tested for Sensu Go compatibility using the new
mutator-sensu-go-into-ruby.rb mutator provided in the latest
To manually test on the commandline, you can export a json representation of an event in Sensu Go using
sensuctl and feed that into the
mutator-sensu-go-into-ruby.rb command. The output should be a Sensu Core 1.x compatible event.
Here is a command line example using the Sensu Go keepalive event from the
sensu-go-sandbox entity to test the event mapping logic.
$ sensuctl event info sensu-go-sandbox keepalive --format json|jq .
The first command above shows the JSON representation of Sensu Go event nicely formatted. Notice there is no client defined .
$ sensuctl event info sensu-go-sandbox keepalive --format json| mutator-sensu-go-into-ruby.rb | jq .
The output of the mapping mutator should look more familiar to Sensu 1.x users, having a top-level client hash defined. The mapping logic does the minimal changes necessary to provide a Sensu 1.x compatible event.
But wait! There’s more!
One of our excellent Community Maintainers, Barry O’Rourke, has ported this work into the
sensu-plugins-python package! If you’re building Python-based handlers, you’ll soon be able to take advantage of a similar opt-in mechanism if you’ve based your handler on this Python package.
Thanks to everyone for contributing to Sensu! Once we have more of the Community Plugins updated to use the
sensu-plugin 3.0 release series, I plan to put together a blog post showing how to migrate workloads using community plugin handlers from Sensu 1.x to Sensu Go.