Migrating to 2.0: the good, the bad & the ugly

Sensu 2.0 is coming!! Sensu 2.0 is coming?? Sensu 2.0 is coming!?!?!

The Sensu 2.0 release is dropping in October, and we’re already excited! As the version numbering implies, Sensu 2.0 includes significant changes from Sensu 1.x. Not only has the software been entirely re-engineered in Go — easing deployment significantly — the exposed APIs and internal data structures have changed to accommodate new features.

I know it sounds scary, but friends, I’m here to tell you that it’s not that bad and there are good reasons for all the changes. There is a lot of benefit in the re-engineered Sensu 2.0 — role based access, a more expressive API for resource management, RPC-based extensions, and more.

Unfortunately, to get to the brave new world of tomorrow, backwards compatibility with Sensu 1.x API and data structures had to be sacrificed. We changed the event data model for two reasons: “client” became “entity,” so we could describe more things (e.g., network gear, web server, cloud resource, etc.) and to add metrics for first-class support. APIs changed because the data model changed — Sensu is now configured via the API.

A goal for Sensu 2.0 is to provide feature parity with Sensu 1.4, so you can continue to use Sensu 2.0 for the same workflows. Yes, there is going to be some migration pain due to the API and data structure changes, but it can all be overcome. In the coming months, I’ll be putting together a series of articles on “Jef Practices for Sensu Migration” — they may not be the best practices, but are an account of my strategies for migrating Sensu 1.4 to Sensu 2.0.

But first, I want to start the conversation off by reviewing what works and what doesn’t — the good, the bad, and the ugly.

The good: what will keep working

Most check commands will continue to work. I say most here because there are some corner cases involving little-used check configuration features — in particular, if you’re using the stdin check config attribute, you might have some additional migration work to do. If you’re using that feature, I’d love to chat with you — drop me a line in the Sensu Community Slack.

Nagios check commands should continue to work.

The checks from the Sensu plugins gem collection will also continue to work as long as you have a Ruby environment to run them in (I hope to cover this in a future Jef Practices post).

There’s a tool to help you translate your existing configuration and prepare to import it into Sensu 2.0. Because Sensu 2.0 uses an RBAC model, configuration objects such as checks and handlers need to be associated with an org and an environment. The translator helps with the tedious work, but it doesn’t translate filters and extensions — the changes needed for these objects are too large to cleanly automate with a helper. I’ll get to that below.

The bad: what will need some slight adjustment

Any command that is configured to take in Sensu data object and process may need to be adjusted slightly. Which means for most workflows: handlers and filters and mutators! Oh, my!

The reason for this is the internal data model Sensu 2.0 uses for events is not backwards compatible with Sensu 1.4. For example, Sensu 2.0 introduces concepts that don’t fit within the data representation of Sensu 1.4. The result is that sensu-server handlers and mutators might not continue to work if they’re relying on attributes in the event JSON representation that no longer exist. This is not difficult to fix — the information has most likely moved to a different location inside the JSON representation. Watch for a future Jef Practice post covering this in more detail. The situation with filters is a little more complicated, so keep reading.

Client-side commands can also be impacted by this change, though not in most common workflows. Any checks or check hooks which rely on the stdin configuration attribute may need to be adjusted. These commands ingest a JSON representation of client and check configuration and may need to be adapted to ensure correct operation. As I said, this isn’t a common arrangement — none of the checks in the maintained Sensu plugins collection require the stdin attribute.

The ugly: significant refactoring required

Some workflow configurations in Sensu 1.x are tied directly to the choice of Ruby as an implementation decision and are deeply wedded to the Ruby internals. Unfortunately, these will most likely have to be rebuilt.

First up: filters.

….Filters? Really?

Yes.

Be prepared to rewrite your filters from scratch. In Sensu 1.x, filters gave you access to the full Ruby environment via the Ruby eval statement. As a result, seemingly simple filter logic can be intimately tied to having a Ruby environment running underneath. This is why the translator tool I mentioned before doesn’t even attempt to translate your filters. If you have a simple filter without complicated Ruby eval logic, this should be straightforward to convert by hand. If you have clever Ruby eval logic, you will need to refactor your filter as a gRPC service extension to Sensu 2.0.

Did I just mentation gRPC extensions? What a great segue!

Existing Sensu 1.x Ruby extensions will have to be rewritten or converted to gRPC services. Extensions aren’t going away, they’re just being decoupled from the main Sensu backend process and will now exist as gRPC processes running outside of the Sensu backend.

I love the move to gRPC; it gives us the ability to build extensions in many different languages. There’s a lot of long-term benefit here, such as being able to write your own in-house extensions using the language development tooling you have already spun up for testing. So if you’re a Python shop, Go shop, or a Ruby shop, you’ll be able to write your in-house Sensu extensions in the tooling you’re most proficient in. I’m keen on building my own gRPC extensions — in Python — so you’ll want to watch out for a follow-up post where I talk more about getting a gRPC extension up and running with Sensu 2.0.

Let’s talk more at Sensu Summit

I’m excited by what’s coming in Sensu 2.0, even though it means having to spend some effort migrating my Sensu 1.4 workloads. Thanks for sticking with us through the transition from Sensu 1.4 to Sensu 2.0 — the enhancements in Sensu 2.0 (like role-based access and deployable assets) are definitely worth the effort. None of what I’ve seen so far reviewing potential gotchas is unsurmountable. If you’re ready to give 2.0 a try, check out our installation and configuration guide. Bonus: if you’re joining us for Sensu Summit, we can talk face to face about moving over to Sensu 2.0. And, our community unconference (day two) will feature working sessions, with Sensu engineers on hand to help answer your migration questions.