Automatically register and deregister entities

Sensu uses the publish/subscribe pattern of communication, which allows automated registration and deregistration of ephemeral systems. Sensu agents automatically discover and register infrastructure components and the services running on them. At the same time, when an agent process stops, the Sensu backend can automatically create and process a deregistration event.

Automatic registration and deregistration keeps your Sensu instance up-to-date and avoids unnecessary process load, especially in containerized environments where containers routinely come online and offline. You’ll see observability event data soon after an agent entity comes online, and you won’t receive stale events or alerts for entities that no longer exist.

You can also configure handlers that take specific actions based on agent registration and deregistration, such as updating external configuration management databases (CMDBs).

Discovery and registration

Sensu agents automatically discover and register infrastructure components and the services running on them.

Registration events

When an agent comes online, it sends its first keepalive event. When a Sensu backend processes a keepalive event for an agent whose name is not already listed in the Sensu agent registry, Sensu automatically registers the agent. The Sensu backend stores the entity registry, which you can view by running sensuctl entity list.

If you configure a handler named registration, the Sensu backend will create and process a registration event for that handler to process. The registration handler must reference the name of a handler or handler set that you want to execute for every registration event.

Registration handler example

You can use registration event handlers to execute one-time handlers for new Sensu agents based on registration events.

For example, suppose you want to update the ServiceNow CMDB table that contains your Sensu entity inventory upon every registration event. First, configure a handler that uses the sensu/sensu-servicenow-handler dynamic runtime asset and the --cmdb-registration argument:

---
type: Handler
api_version: core/v2
metadata:
  name: servicenow_cmdb
spec:
  type: pipe
  command: sensu-servicenow-handler --cmdb-registration
  runtime_assets:
  - sensu/sensu-servicenow-handler:3.0.0
  env_vars:
  - SERVICENOW_URL=https://example.servicenow.com
  secrets:
  - name: SERVICENOW_USERNAME
    secret: servicenow_username
  - name: SERVICENOW_PASSWORD
    secret: servicenow_password
  timeout: 10

{
  "type": "Handler",
  "api_version": "core/v2",
  "metadata": {
    "name": "servicenow_cmdb"
  },
  "spec": {
    "type": "pipe",
    "command": "sensu-servicenow-handler --cmdb-registration",
    "runtime_assets": [
      "sensu/sensu-servicenow-handler:3.0.0"
    ],
    "env_vars": [
      "SERVICENOW_URL=https://example.servicenow.com"
    ],
    "secrets": [
      {
        "name": "SERVICENOW_USERNAME",
        "secret": "servicenow_username"
      },
      {
        "name": "SERVICENOW_PASSWORD",
        "secret": "servicenow_password"
      }
    ],
    "timeout": 10
  }
}

Then, create a registration handler that references the servicenow_cmdb handler:

---
type: Handler
api_version: core/v2
metadata:
  name: registration
spec:
  handlers:
  - servicenow_cmdb
  type: pipe

{
  "type": "Handler",
  "api_version": "core/v2",
  "metadata": {
    "name": "registration"
  },
  "spec": {
    "handlers": [
      "servicenow_cmdb"
    ],
    "type": "pipe"
  }
}

Now the Sensu backend will execute the referenced servicenow-cmdb handler for every registration event. The referenced handler can send registration event alerts to any service, such as Sumo Logic or PagerDuty, as long as it is listed within a handler named registration.

Deregistration

Just like Sensu can automatically register new agent entities when they send their first keepalive, Sensu can automatically deregister agent entities when they shut down and the agent process stops.

To enable automatic deregistration, set the agent deregister attribute to true. When the Sensu agent process stops and the agent stops sending keepalive messages, the Sensu backend can deregister the corresponding entity without any further action.

Deregistration events

As with registration events, the Sensu backend can create and process a deregistration event when a Sensu agent process stops.

When an agent exceeds its keepalive timeout setting, the backends will generate a keepalive failure for that agent and create an event on its behalf. If you set the agent deregister attribute to true, when keepalive failure occurs, Sensu will delete the agent entity from the entity registry and send a deregistration event through the event pipeline.

To take action based on deregistration events, you must also specify a handler to use for deregistration events in the agent or backend configuration:

• To use a deregistration handler for a specific agent, set the agent deregistration-handler attribute.
• To use a deregistration handler to process all deregistration events for all agents, set the backend deregistration-handler attribute.

The agent deregistration-handler attribute overrides the backend deregistration-handler attribute. In other words, if you specify both an agent and backend deregistration handler, Sensu will use only the handler specified in the agent configuration.

Deregistration handler example

Just like registration events, deregistration events can trigger a one-time handler that performs an action like updating an external CMDB or ephemeral infrastructures. In fact, you can use the servicenow_cmdb handler to update the ServiceNow CMDB table that contains your Sensu entity inventory, this time based on every deregistration event.

To specify servicenow_cmdb as the agent deregistration handler:

sensu-agent start --deregistration-handler servicenow_cmdb

deregistration-handler: servicenow_cmdb

Next steps

The Sensu Catalog includes the Platform Discovery integration, which detects the agent operating system and platform information and updates the agent’s subscriptions accordingly. This integration allows you to deploy agents with a single subscription and use the auto-discovery check to add system-based subscriptions automatically.

Follow Create limited service accounts to automatically remove AWS EC2 instances that are not in a pending or running state.