Upgrading Sensu

Upgrading to the latest version of Sensu Go from 5.0.0 or later

To upgrade to the latest version of Sensu Go from version 5.0.0 or later, first install the latest packages.

Then restart the services.

NOTE: For systems using systemd, run sudo systemctl daemon-reload before restarting the services.

# Restart the Sensu agent
sudo service sensu-agent restart

# Restart the Sensu backend
sudo service sensu-backend restart

You can use the version command to determine the installed version using the sensu-agent, sensu-backend, and sensuctl tools. For example: sensu-backend version.

Upgrading to Sensu Go 5.15.0 from any earlier version

As of Sensu Go 5.15.0, Sensu’s free entity limit is 100 entities. All commercial features are available for free in the packaged Sensu Go distribution up to an entity limit of 100.

When you upgrade to 5.15.0, if your existing unlicensed instance has more than 100 entities, Sensu will continue to monitor those entities. However, if you try to create any new entities via the HTTP API or sensuctl, you will see the following message:

This functionality requires a valid Sensu Go license with a sufficient entity limit. To get a valid license file, arrange a trial, or increase your entity limit, contact Sales.

Connections from new agents will fail and result in a log message like this:

{"component":"agent","error":"handshake failed with status 402","level":"error","msg":"reconnection attempt failed","time":"2019-11-20T05:49:24-07:00"}

In the web UI, you will see the following message when you reach the 100-entity limit:

Sensu web UI warning when the entity limit is reached

If your Sensu instance includes more than 100 entities, contact Sales to learn how to upgrade your installation and increase your limit. See our blog announcement for more information about our usage policy.

Upgrading Sensu clusters from 5.7.0 or earlier to 5.8.0 or later

NOTE: This applies only to Sensu clusters with multiple backend nodes.

Due to updates to etcd serialization, Sensu clusters with multiple backend nodes must be shut down while upgrading from Sensu Go 5.7.0 or earlier to 5.8.0 or later. See the backend reference for more information about stopping and starting backends.

Upgrading Sensu backend binaries to 5.1.0

NOTE: This applies only to Sensu backend binaries downloaded from s3-us-west-2.amazonaws.com/sensu.io/sensu-go, not to Sensu RPM or DEB packages.

For Sensu backend binaries, the default state-dir in 5.1.0 is now /var/lib/sensu/sensu-backend instead of /var/lib/sensu. To upgrade your Sensu backend binary to 5.1.0, first download the latest version, then make sure the /etc/sensu/backend.yml configuration file specifies a state-dir. To continue using /var/lib/sensu as the state-dir, add the following configuration to /etc/sensu/backend.yml.

# /etc/sensu/backend.yml configuration to store backend data at /var/lib/sensu
state-dir: "/var/lib/sensu"

Then restart the backend.

Migrating to Sensu Go from Sensu Core 1.x

This guide provides general information for migrating your Sensu instance from Sensu Core 1.x to Sensu Go 5.0. For instructions and tools to help you translate your Sensu configuration from Sensu Core 1.x to Sensu Go, see the following resources.

Sensu Go includes important changes to all parts of Sensu: architecture, installation, resource definitions, event data model, check dependencies, filter evaluation, and more. Sensu Go also includes a lot of powerful features to make monitoring easier to build, scale, and offer as a self-service tool to your internal customers.


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; the client is now the agent. To learn more about new terminology in Sensu Go, see the glossary.


The external RabbitMQ transport and Redis datastore in Sensu Core 1.x have been replaced with an embedded transport and etcd datastore in Sensu Go. The Sensu backend and agent are configured using YAML files or using the sensu-backend or sensu-agent command-line tools, instead of using JSON files. Sensu checks and pipeline elements are now configured via the API or sensuctl tool instead of JSON files. See the backend, agent, and sensuctl reference docs for more information.


“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”. See the entity reference and the guide to monitoring external resources for more information.


Standalone checks are no longer supported in Sensu Go, although similar functionality can be achieved using role-based access control, assets, and entity subscriptions. There are also a few changes to check definitions to be aware of. The stdin check attribute is no longer supported in Sensu Go, and Sensu Go no longer tries to run a “default” handler when executing a check without a specified handler. Additionally, check subdues are not yet available in Sensu Go.

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.


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.


Transport handlers are no longer 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.


Ruby eval logic has been replaced with JavaScript expressions in Sensu Go, opening up powerful possibilities to filter events based on occurrences and other event attributes. As a result, the built-in occurrences filter in Sensu Core 1.x is not provided in Sensu Go, but you can replicate its functionality using this filter definition. Sensu Go includes three new built-in filters: only-incidents, only-metrics, and allow-silencing. Sensu Go does not yet include a built-in check dependencies filter or a filter-when feature.


The sensu-install tool has been replaced in Sensu Go by assets, shareable, reusable packages that make it easy to deploy Sensu plugins. Sensu Plugins in Ruby can still be installed via sensu-install by installing sensu-plugins-ruby; see the installing plugins guide for more information.

Role-based access control

Role-based access control (RBAC) is a built-in feature of the open-source version 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.


Silencing is now disabled by default in Sensu Go and must be enabled explicitly using the built-in not_silenced filter.

Token substitution

The syntax for using token substitution has changed from using triple colons to using double curly braces.


Check aggregates are supported through the commercial Sensu Go Aggregate Check Plugin.


In addition to the changes to resource definitions, Sensu Go includes a new, versioned API. See the API overview for more information.

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. See the metadata attributes section in the reference documentation for more information about using labels and annotations (for example: metadata attributes for entities).