Role-based access control

Sensu role-based access control (RBAC) helps different teams and projects share a Sensu instance. RBAC allows management and access of users and resources based on namespaces, groups, roles, and bindings.

  • Namespaces partition resources within Sensu. Sensu checks, handlers, and other namespaced resources belong to a single namespace.
  • Roles create sets of permissions (get, delete, etc.) tied to resource types. Cluster roles apply permissions across namespaces and include access to cluster-wide resources like users and namespaces.
  • Users represent a person or agent that interacts with Sensu. Users can belong to one or more groups.
  • Role bindings assign a role to a set of users and groups within a namespace; cluster role bindings assign a cluster role to a set of users and groups cluster-wide.

Sensu access controls apply to sensuctl, the Sensu API, and the Sensu dashboard.

Namespaces

Namespaces help teams use different resources (checks, handlers, etc.) within Sensu and impose their own controls on those resources. A Sensu instance can have multiple namespaces, each with their own set of managed resources. Resource names need to be unique within a namespace, but not across namespaces.

To create and manage namespaces, configure sensuctl as the default admin user or create a cluster role with namespaces permissions.

Default namespace

Every Sensu backend includes a default namespace. All resources created without a specified namespace are created within the default namespace.

Viewing namespaces

You can use sensuctl to view all namespaces within Sensu:

sensuctl namespace list

Creating a namespace

You can use sensuctl to create a namespace. For example, the following command creates a namespace called production:

sensuctl namespace create production

Namespace names can contain alphanumeric characters and hyphens, but must begin and end with an alphanumeric character.

Managing namespaces

You can use sensuctl to view, create, and delete namespaces.

To delete a namespace:

sensuctl namespace delete [NAMESPACE-NAME]

WARNING: This deletes every resource definition associated with the namespace.

To get help managing namespaces with sensuctl:

sensuctl namespace help

Assigning a resource to a namespace

You can assign a resource to a namespace in the resource definition. Only resources belonging to a namespaced resource type (like checks, filters, and handlers) can be assigned to a namespace.

For example, to assign a check called check-cpu to the production namespace, include the namespace attribute in the check definition:

{
  "type": "CheckConfig",
  "api_version": "core/v2",
  "metadata": {
    "name": "check-cpu",
    "namespace": "default"
  },
  "spec": {
    "check_hooks": null,
    "command": "check-cpu.sh -w 75 -c 90",
    "handlers": [
      "slack"
    ],
    "interval": 30,
    "subscriptions": [
      "system"
    ],
    "timeout": 0,
    "ttl": 0
  }
}

See the reference docs for the corresponding resource type to create resource definitions.

Namespace specification

Attributes

name
description The name of the namespace. Names can contain alphanumeric characters and hyphens, but must begin and end with an alphanumeric character.
required true
type String
example
"name": "production"

Namespace examples

The following examples are in wrapped-json format for use with sensuctl create.

{
  "type": "Namespace",
  "api_version": "core/v2",
  "metadata": {},
  "spec": {
    "name": "default"
  }
}

Resources

Permissions within Sensu are scoped to resource types, like checks, handlers, and users. You can use resource types to configure permissions in Sensu roles and cluster roles.

Namespaced resource types

Namespaced resources must belong to a single namespace and can be accessed by roles and cluster roles.

Type Description
assets Asset resources within a namespace
checks Check resources within a namespace
entities Entity resources within a namespace
events Event resources within a namespace
filters Filter resources within a namespace
handlers Handler resources within a namespace
hooks Hook resources within a namespace
mutators Mutator resources within a namespace
rolebindings Namespace-specific role assigners
roles Namespace-specific permission sets
silenced Silencing resources within a namespace

Cluster-wide resource types

Cluster-wide resources cannot be assigned to a namespace and can only be accessed by cluster roles.

Type Description
cluster Sensu clusters running multiple Sensu backends
clusterrolebindings Cluster-wide role assigners
clusterroles Cluster-wide permission sets
namespaces Resource partitions within a Sensu instance
users People or agents interacting with Sensu

Special resource types

Special resources types can be accessed by both roles and cluster roles.

Type Description
* All resources within Sensu. The * type takes precedence over other rules within the same role. If you wish to deny a certain type, you can’t use the * type and must explicitly allow every type required. When applied to a role, the * type applies only to namespaced resource types. When applied to a cluster role, the * type applies to both namespaced resource types and cluster-wide resource types.

Users

A user represents a person or an agent which interacts with Sensu. Users and groups can be assigned one or more roles and inherit all permissions from each role assigned to them.

You can use your Sensu username and password to configure sensuctl or log in to the dashboard.

Default user

By default, Sensu includes a global admin user that you can use to manage Sensu and create new users.

attribute value
username admin
password P@ssw0rd!
groups cluster-admins
cluster role cluster-admin
cluster role binding cluster-admin

We strongly recommended changing the default password for the admin user immediately. Once authenticated, you can change the password using the change-password command.

sensuctl user change-password

Sensu also includes an agent user that is used internally by the Sensu agent and should not be modified.

WARNING: Modification of the agent user can result in non-functional Sensu agents.

Viewing users

You can use sensuctl to see a list of all users within Sensu:

sensuctl user list

Creating a user

You can use sensuctl to create a user. For example, the following command creates a user with the username alice and the password password.

sensuctl user create alice --password 'password'

Assigning user permissions

To assign permissions to a user:

  1. Create the user.
  2. Create a role or (for cluster-wide access) a cluster role.
  3. Create a role binding (or cluster role binding) to assign the role to the user.

Managing users

You can use sensuctl to view, create, and manage users.

To change the password for a user:

sensuctl user change-password [USERNAME]

To disable a user:

sensuctl user disable [USERNAME]

To re-enable a disabled user:

sensuctl user reinstate [USERNAME]

User specification

Attributes

username
description The name of the user. Cannot contain special characters.
required true
type String
example
"username": "alice"
password
description The user’s password. Cannot be empty.
required true
type String
example
"password": "P@ssw0rd!"
groups
description Groups to which the user belongs.
required false
type Array
example
"groups": ["dev", "ops"]
disabled
description The state of the user’s account.
required false
type Boolean
default false
example
"disabled": false

Groups

A group is a set of users within Sensu. Groups can be assigned one or more roles and inherit all permissions from each role assigned to them. Users can be assigned to one or more groups.

Default group

Sensu includes a default cluster-admins group that contains the default admin user. Additionally, Sensu includes a system:agents group used internally by Sensu agents.

WARNING: Modification of the system:agents group can result in non-functional Sensu agents.

Assigning a user to a group

Groups are created and managed within user definitions. You can use sensuctl to add users to groups.

To add a user to a group:

sensuctl user add-group [USERNAME] [GROUP]

To set the groups for a user:

sensuctl user set-groups USERNAME GROUP1[,GROUP2, ...[,GROUPN]]

Removing a user from a group

You can use sensuctl to remove users from groups.

To remove a user from a group:

sensuctl user remove-group [USERNAME] [GROUP]

To remove a user from all groups:

sensuctl user remove-groups [USERNAME]

Roles and cluster roles

A role is a set of permissions controlling access to Sensu resources. Roles specify permissions for resources within a namespace while cluster roles can include permissions for cluster-wide resources. You can use roles bindings to assign roles to user and groups. To avoid re-creating commonly used roles in each namespace, create a cluster role and use a role binding (not a cluster role binding) to restrict permissions within a specific namespace.

To create and manage roles cluster-wide, configure sensuctl as the default admin user or create a cluster role with roles permissions. To create and manage roles within a namespace, create a role with roles permissions within that namespace.

Cluster roles

Cluster roles can specify access permissions for cluster-wide resources like users and namespaces as well as namespaced resources like checks and handlers. They can also be used to grant access to namespaced resources across all namespaces (needed to run sensuctl check list --all-namespaces, for example) when used in conjunction with cluster role bindings. Cluster roles use the same specification as roles and can be managed using the same sensuctl commands with cluster-role substituted for role.

To create and manage cluster roles, configure sensuctl as the default admin user or create a cluster role with permissions for clusterroles.

Default roles

Every Sensu backend includes:

Role name Type Description
cluster-admin ClusterRole Full access to all resource types across namespaces, including access to cluster-wide resource types.
admin ClusterRole Full access to all resource types. You can apply this cluster role within a namespace by using a role binding (not a cluster role binding).
edit ClusterRole Read and write access to most resources with the exception of roles and role bindings. You can apply this cluster role within a namespace by using a role binding (not a cluster role binding).
view ClusterRole Read-only permission to most resource types with the exception of roles and role bindings. You can apply this cluster role within a namespace by using a role binding (not a cluster role binding).
system:agent ClusterRole Used internally by Sensu agents. WARNING: Modification of this cluster role can result in non-functional Sensu agents.

Viewing roles

You can use sensuctl to see a list of roles within Sensu:

sensuctl role list

To see the permissions and scope for a specific role:

sensuctl role info admin

To view cluster roles, use the cluster-role command:

sensuctl cluster-role list

Creating a role

You can use sensuctl to create a role. For example, the following command creates an admin role restricted to the production namespace.

sensuctl role create prod-admin --verb get,list,create,update,delete --resource * --namespace production

Creating a cluster-wide role

You can use sensuctl to create a cluster role. For example, the following command creates a global event reader role that can read only events across all namespaces within Sensu.

sensuctl cluster-role create global-event-reader --verb get,list --resource events

Managing roles

You can use sensuctl to view, create, edit, and delete roles. To use any of these commands with cluster roles, substitute the cluster-role command for the role command.

To edit a role:

sensuctl edit roles [ROLE-NAME] [flags]

To delete a role:

sensuctl role delete [ROLE-NAME]

To get help managing roles with sensuctl:

sensuctl role help

Role and cluster role specification

Role attributes

name
description Name of the role
required true
type String
example
"name": "admin"
namespace
description Namespace the role is restricted to. This attribute is not available for cluster roles.
required false
type String
example
"namespace": "production"
rules
description The rulesets that a role applies.
required true
type Array
example
"rules": [
  {
    "verbs": ["get", "list"],
    "resources": ["checks"],
    "resourceNames": [""]
  }
]

Rule attributes

A rule is an explicit statement which grants a particular permission to a resource.

verbs
description The permissions to be applied by the rule: get, list, create, update, or delete.
required true
type Array
example
"verbs": ["get", "list"]
resources
description The type of resource that the rule has permission to access. Roles can only access namespaced resource types while cluster roles can access namespaced and cluster-wide resource types. See resource types for available types.
required true
type Array
example
"resources": ["checks"]
resourceNames
description Specific resource names that the rule has permission to access. Resource name permissions are only available for get, delete, and update verbs.
required false
type Array
example
"resourceNames": ["check-cpu"]

Role examples

The following examples are in wrapped-json format for use with sensuctl create.

{
  "type": "Role",
  "api_version": "core/v2",
  "metadata": {
    "name": "event-reader",
    "namespace": "default"
  },
  "spec": {
    "rules": [
      {
        "resource_names": [],
        "resources": [
          "events"
        ],
        "verbs": [
          "get",
          "list"
        ]
      }
    ]
  }
}

Cluster role examples

The following examples are in wrapped-json format for use with sensuctl create.

{
  "type": "ClusterRole",
  "api_version": "core/v2",
  "metadata": {
    "name": "global-event-reader"
  },
  "spec": {
    "rules": [
      {
        "resource_names": [],
        "resources": [
          "events"
        ],
        "verbs": [
          "get",
          "list"
        ]
      }
    ]
  }
}

Role bindings and cluster role bindings

A role binding assigns a role or cluster role to a user or set of users. A cluster role binding assigns a cluster role to a user or set of users. Roles bindings apply roles within a namespace while cluster role bindings apply across namespaces and resource types.

To create and manage role bindings within a namespace, create a role with rolebindings permissions within that namespace, and log in by configuring sensuctl.

Cluster role bindings

Cluster roles bindings can assign a cluster role to users and groups. Cluster role bindings use the same specification as role bindings and can be managed using the same sensuctl commands with cluster-role-binding substituted for role-binding.

To create and manage cluster role bindings, configure sensuctl as the default admin user or create a cluster role with permissions for clusterrolebindings.

Viewing role bindings

You can use sensuctl to see a list of role bindings within Sensu:

sensuctl role-binding list

To see the details for a specific role binding:

sensuctl role-binding info [BINDING-NAME]

To see a list of cluster role bindings:

sensuctl cluster-role-binding list

Creating a role binding

You can use sensuctl to see a create a role binding that assigns a role:

sensuctl role-binding create [NAME] --role=NAME [--user=username] [--group=groupname]

Or a role binding that assigns a cluster role:

sensuctl role-binding create [NAME] --cluster-role=NAME [--user=username] [--group=groupname]

To create a cluster role binding:

sensuctl cluster-role-binding create [NAME] --cluster-role=NAME [--user=username] [--group=groupname]

Assigning user permissions

To assign permissions to a user:

  1. Create the user.
  2. Create a role or (for cluster-wide access) a cluster role.
  3. Create a role binding (or cluster role binding) to assign the role to the user.

Managing role bindings

You can use sensuctl to see a list, create, and delete role bindings and cluster role bindings. To use any of these commands with cluster roles, substitute the cluster-role-binding command for the role-binding command.

To delete a role binding:

sensuctl role-binding delete [ROLE-NAME]

To get help managing role bindings with sensuctl:

sensuctl role-binding help

Role binding and cluster role binding specification

roleRef
description References a role in the current namespace or a cluster role.
required true
type Hash
example
"roleRef": {
  "type": "Role",
  "name": "event-reader"
}
subjects
description The users or groups being assigned.
required true
type Array
example
"subjects": [
  {
    "type": "User",
    "name": "alice"
  }
]

roleRef specification

type
description Role for a role binding or ClusterRole for a cluster role binding.
required true
type String
example
"type": "Role"
name
description The name of the role or cluster role being assigned.
required true
type String
example
"name": "event-reader"

subjects specification

type
description User for assigning a user or Group for assigning a group.
required true
type String
example
"type": "User"
name
description Username or group name.
required true
type String
example
"name": "alice"

Role binding examples

The following examples are in wrapped-json format for use with sensuctl create.

{
  "type": "RoleBinding",
  "api_version": "core/v2",
  "metadata": {
    "name": "event-reader-binding",
    "namespace": "default"
  },
  "spec": {
    "role_ref": {
      "name": "event-reader",
      "type": "Role"
    },
    "subjects": [
      {
        "name": "bob",
        "type": "User"
      }
    ]
  }
}

Cluster role binding examples

The following examples are in wrapped-json format for use with sensuctl create.

{
  "type": "ClusterRoleBinding",
  "api_version": "core/v2",
  "metadata": {
    "name": "cluster-admin"
  },
  "spec": {
    "role_ref": {
      "name": "cluster-admin",
      "type": "ClusterRole"
    },
    "subjects": [
      {
        "name": "cluster-admins",
        "type": "Group"
      }
    ]
  }
}