Migrating to Sensu Go

This guide provides information for migrating your Sensu instance from Sensu 1.x to Sensu Go. Read the blog post to learn more about end-of-life for Sensu 1.x. To migrate from Sensu Enterprise, see the Sensu Enterprise migration guide.

Learn about Sensu Go

Sensu Go includes powerful features to make monitoring easier to build, scale, and offer as a self-service tool to your internal customers. Read the blog post for more information about the features of Sensu Go.

To set up a local Sensu Go playground, download and start the Sensu sandbox using Vagrant and Virtual box. Get started with Sensu by running through the sandbox tutorial.

Install Sensu Go

Sensu is now provided as three packages: sensu-go-backend, sensu-go-agent, and sensu-go-cli (sensuctl). This results in a fundamental change in Sensu terminology from Sensu Core 1.x: the server is now the backend.

“Clients” are now represented within Sensu Go as abstract “entities” that can describe a wider range of system components (network gear, web server, cloud resource, etc.) Entities include “agent entities” (entities running a Sensu agent) and familiar “proxy entities”.

To install Sensu Go alongside your current Sensu instance, first upgrade to at least Sensu Core 1.7.0.

Sensu Go architecture

Sensu architecture diagram

Powered by an embedded transport and etcd datastore, the Sensu backend gives you flexible, automated workflows to route metrics and alerts. Sensu backends require persistent storage for their embedded database, disk space for local asset caching, and three exposed ports:

  • 3000 - Sensu web UI
  • 8080 - Sensu API used by sensuctl, some plugins, and any of your custom tooling
  • 8081 - WebSocket API used by Sensu agents

Sensu backends running in a clustered configuration require additional ports. See the deployment guide for architecture recommendations.

Sensu agents are lightweight clients that run on the infrastructure components you want to monitor. Agents register automatically with Sensu as entities and are responsible for creating check and metric events to send to the backend event pipeline. Agents using Sensu assets require some disk space for a local cache. Optionally, agents can expose three ports:

Supported platforms

Sensu Go is available for RHEL/CentOS, Debian, Ubuntu, and Docker. The Sensu Go agent is also available for Windows. Configuration management integrations for Sensu Go are available for Puppet, Chef, and Ansible. See the list of supported platforms for more information.

Deployment recommendations

See the deployment and hardware requirements guides for deployment recommendations.

1. Install the Sensu Go backend

The Sensu backend is available for Ubuntu/Debian, RHEL/CentOS, and Docker. See the installation guide to install, configure, and start the Sensu backend according to your deployment strategy.

2. Log in to the Sensu web UI

The Sensu Go web UI provides a unified view of your monitoring events with user-friendly tools to reduce alert fatigue and manage your Sensu instance. After starting the Sensu backend, open the web UI by visiting http://localhost:3000. You may need to replace localhost with the hostname or IP address where the Sensu backend is running.

To log in, enter your Sensu user credentials, or use Sensu’s default admin credentials (username: admin and password: P@ssw0rd!). Select the ☰ icon to explore the web UI.

3. Install sensuctl on your workstation

Sensuctl is a command line tool for managing resources within Sensu. It works by calling Sensu’s HTTP API to create, read, update, and delete resources, events, and entities. Sensuctl is available for Linux, Windows, and macOS. See the installation guide to install and configure sensuctl.

4. Set up Sensu users

Role-based access control (RBAC) is a built-in feature of Sensu Go. RBAC allows management and access of users and resources based on namespaces, groups, roles, and bindings. To learn more about setting up RBAC in Sensu Go, see the RBAC reference and the guide to creating a read-only user.

In Sensu Go, namespaces partition resources within a Sensu instance; Sensu Go entities, checks, handlers, and other namespaced resources belong to a single namespace. The Sensu translator that we’ll use later places all translated resources into the default namespace.

In addition to built-in RBAC, Sensu includes license-activated support for authentication using Microsoft Active Directory and standards-compliant Lightweight Directory Access Protocol tools like OpenLDAP.

5. Install agents

The Sensu agent is available for Ubuntu/Debian, RHEL/CentOS, Windows, and Docker. See the installation guide to install, configure, and start Sensu agents.

If you’re doing a side-by-side migration, add api-port (default: 3031) and socket-port (default: 3030) to your agent configuration; this prevents the Sensu Go agent API and socket from conflicting with the Sensu 1.x client API and socket. You can also disable these features in the agent configuration using the disable-socket and disable-api flags.

# agent configuration: /etc/sensu.agent.yml

...
api-port: 4041
socket-port: 4030
...

Now you should have Sensu installed and functional. The next step is to translate your Sensu 1.x configs to Sensu Go.

Translate your configuration

The Sensu translator is a command-line tool to help you transfer your Sensu Core 1.x checks, handlers, and mutators to Sensu Go.

1. Run the translator

Install and run the translator.

# Install dependencies
yum install -q -y rubygems ruby-devel

# Install sensu-translator
gem install sensu-translator

# Translate all config in /etc/sensu/conf.d to Sensu Go, output to /sensu_config_translated
# Optionally, you can translate your config in sections according to resource type
sensu-translator -d /etc/sensu/conf.d -o /sensu_config_translated

If translation is successful, you should see a few callouts followed by DONE!.

Sensu 1.x filter translation is not yet supported
Unable to translate Sensu 1.x filter: only_production {:attributes=>{:check=>{:environment=>"production"}}}
DONE!

Combine your config into a sensuctl-readable format. Note that, for use with sensuctl create, Sensu Go resource definitions in JSON format should not have a comma between resource objects.

find sensu_config_translated/ -name '*.json' -exec cat {} \; > sensu_config_translated_singlefile.json

While most attributes are ready to use as-is, you’ll need to adjust your Sensu Go configuration manually to migrate some of Sensu’s features.

NOTE: To make it easy to compare your Sensu 1.x configuration with your Sensu Go configuration, output your current Sensu 1.x configuration using the API: curl -s http://127.0.0.1:4567/settings | jq . > sensu_config_original.json

2. Translate checks

Review your Sensu 1.x check configuration for the following attributes, and make the corresponding updates to your Sensu Go configuration.

1.x attribute Manual updates required in Sensu Go config
::: foo ::: Update the syntax for token substitution from triple colons to curly braces. For example: {{{ foo }}}
stdin: true No updates required. Sensu Go checks accept data on stdin by default.
handlers: default Sensu Go no longer has the concept of a default handler, so you’ll need to create a handler named default to continue using this pattern.
subdues Check subdues are not available in Sensu Go.
standalone: true Standalone checks are not supported in Sensu Go, although similar functionality can be achieved using role-based access control, assets, and entity subscriptions. The translator assigns all 1.x standalone checks to a standalone subscription in Sensu Go. Configure one or more Sensu Go agents with the standalone subscription to execute formerly-standalone checks.
metrics: true See the section on translating metric checks.
proxy_requests See the section on translating proxy requests.
subscribers: roundrobin... Remove roundrobin from the subscription name, and add the round_robin check attribute set to true.
aggregate Check aggregates are supported through the license-activated Sensu Go Aggregate Check Plugin.
hooks See the section on translating hooks.
dependencies Check dependencies are not available in Sensu Go.

PRO TIP: When using token substitution in Sensu Go and accessing labels or annotations that include . (for example: sensu.io.json_attributes), use the index function. For example, {{index .annotations "web_url"}} substitutes the value of the web_url annotation; {{index .annotations "production.ID"}} substitutes the value of the production.ID annotation.

Translating metric checks

The Sensu 1.x type: metric attribute is no longer part of the Sensu Go check spec, so we’ll need to adjust it by hand. Sensu 1.x checks could be configured as type: metric which told Sensu to always handle the check regardless of the check status output. This allowed Sensu 1.x to process output metrics via a handler even when the check status was not in an alerting state.

Sensu Go treats output metrics as first-class objects, allowing you to process check status as well as output metrics via different event pipelines. See the guide to metric output to update your metric checks with the output_metric_handlers and output_metric_format attributes.

Translating proxy requests and proxy entities

See the guide to monitoring external resources to re-configure proxy_requests attributes and update your proxy check configuration, and see the entity reference to re-create your proxy client configurations as Sensu Go proxy entities.

Translating hooks

Check hooks are now a resource type in Sensu Go, meaning that hooks can be created, managed, and reused independently of check definitions. You can also execute multiple hooks for any given response code. See the guide and hooks reference docs to re-create your Sensu 1.x hooks as Sensu Go hook resources.

Custom attributes

Custom check attributes are no longer supported in Sensu Go. Instead, Sensu Go provides the ability to add custom labels and annotations to entities, checks, assets, hooks, filters, mutators, handlers, and silences. The translator stores all check extended attributes in the check metadata annotation named sensu.io.json_attributes. See the check reference for more information about using labels and annotations in check definitions.

3. Translate filters

Ruby eval logic used in Sensu 1.x filters has been replaced with JavaScript expressions in Sensu Go, opening up powerful possibilities to combine filters with filter assets. As a result, you’ll need to rewrite your Sensu 1.x filters in Sensu Go format.

First, review your 1.x handlers to see which filters are being used. Then, using the filter reference and guide to using filters, re-write your filters using Sensu Go expressions and event data. Also check out the blog post for a deep dive into Sensu Go filter capabilities.

# Sensu 1.x hourly filter
{
  "filters": {
    "recurrences": {
      "attributes": {
        "occurrences": "eval: value == 1 || value % 60 == 0"
      }
    }
  }
}

# Sensu Go hourly filter
  {
    "metadata": {
      "name": "hourly",
      "namespace": "default"
    },
    "action": "allow",
    "expressions": [
      "event.check.occurrences == 1 || event.check.occurrences % (3600 / event.check.interval) == 0"
    ],
    "runtime_assets": null
  }

4. Translate handlers

All check results are now considered events and are processed by event handlers. You can use the built-in incidents filter to recreate the Sensu Core 1.x behavior in which only check results with a non-zero status are considered events.

IMPORTANT: Silencing is now disabled by default in Sensu Go and must be enabled explicitly using the built-in not_silenced filter. Add the not_silenced filter to any handlers for which you want to enable Sensu’s silencing feature.

Review your Sensu 1.x check configuration for the following attributes, and make the corresponding updates to your Sensu Go configuration.

1.x attribute Manual updates required in Sensu Go config
filters: occurrences The built-in occurrences filter in Sensu Core 1.x is not available in Sensu Go, but you can replicate its functionality using the sensu-go-fatigue-check-filter asset.
type: transport Transport handlers are not supported by Sensu Go, but you can create similar functionality using a pipe handler that connects to a message bus and injects event data into a queue.
filters: check_dependencies Sensu Go does not include a built-in check dependencies filter.
severities Severities are not available in Sensu Go.
handle_silenced Silencing is now disabled by default in Sensu Go and must be enabled explicitly using the built-in not_silenced filter.
handle_flapping All check results are now considered events and are processed by event handlers.

5. Upload your config to your Sensu Go instance

Once you’ve reviewed your translated configuration, made any necessary updates, and added resource definitions for any filters and entities you want to migrate, upload your Sensu Go config using sensuctl.

sensuctl create --file /path/to/config.json

PRO TIP: sensuctl create (and sensuctl delete) are powerful tools to help you manage your Sensu configs across namespaces. See the sensuctl reference for more information.

You can now access your Sensu Go config using the Sensu API.

# Set up a local API testing environment by saving your Sensu credentials
# and token as environment variables. Requires curl and jq.
export SENSU_USER=admin && SENSU_PASS=P@ssw0rd!

export SENSU_TOKEN=`curl -XGET -u "$SENSU_USER:$SENSU_PASS" -s http://localhost:8080/auth | jq -r ".access_token"`

# Return list of all configured checks
curl -H "Authorization: Bearer $SENSU_TOKEN" http://127.0.0.1:8080/api/core/v2/namespaces/default/checks

# Return list of all configured handlers
curl -H "Authorization: Bearer $SENSU_TOKEN" http://127.0.0.1:8080/api/core/v2/namespaces/default/handlers

You can also access your Sensu Go configuration in JSON or YAML using sensuctl; for example: sensuctl check list --format json. Run sensuctl help to see available commands. For more information about sensuctl’s output formats (json, wrapped-json, and yaml), see the sensuctl reference.

Translate plugins and register assets

Sensu Plugins

Within the Sensu Plugins org, see individual plugin READMEs for compatibility status with Sensu Go. For handler and mutators plugins, see the Sensu Plugins README to map event data to the Sensu Go format. This allows you to use Sensu Plugins for handlers and mutators with Sensu Go without re-writing them.

To re-install Sensu Plugins onto your Sensu Go agent nodes (check plugins) and backend nodes (mutator and handler plugins), see the guide to installing the sensu-install tool for use with Sensu Go.

Sensu Go assets

Assets are shareable, reusable packages that make it easy to deploy Sensu plugins. Although not required to run Sensu Go, we recommend using assets to install plugins where possible. Sensu supports runtime assets for checks, filters, mutators, and handlers. You can discover, download, and share assets using Bonsai, the Sensu asset index.

To create your own assets, see the asset reference and guide to sharing an asset on Bonsai. To contribute to converting a Sensu Plugin to an asset, see the discourse post.

Sunset your Sensu 1.x instance

When you’re ready to sunset your Sensu 1.x instance, see the platform docs to stop the Sensu 1.x services. You may also want to re-install the sensu-install tool using the sensu-plugins-ruby package.

Resources