Role-based access control (RBAC) reference

Sensu’s role-based access control (RBAC) helps different teams and projects share a Sensu instance. RBAC allows you to specify actions users are allowed to take against resources, within namespaces or across all namespaces, based on roles bound to the user or to one or more groups the user is a member of.

  • Roles create sets of permissions (for example, get and delete) 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.

RBAC configuration applies to sensuctl, the API, and the web UI.

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. You can access namespaced resources by roles and cluster roles.

type description
assets Dynamic runtime asset resources within a namespace
checks Check resources within a namespace
entities Entity resources within a namespace
events Event resources within a namespace
extensions Placeholder type
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
rule-templates Resources applied to service components for business service monitoring
searches Saved web UI search queries
secrets Secrets (for example, username or password)
service-components Resources that represent elements in a business service
silenced Silencing resources within a namespace

Cluster-wide resource types

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

type description
apikeys Persistent universally unique identifier (UUID) for authentication
authproviders Authentication provider configuration
clusterrolebindings Cluster-wide role assigners
clusterroles Cluster-wide permission sets
clusters Sensu clusters running multiple Sensu backends
config Global configuration for web UI display
etcd-replicators Mirror RBAC resource changes to follower clusters
license Sensu commercial license
namespaces Resource partitions within a Sensu instance
provider PostgreSQL event store provider
providers Secrets providers
users People or agents that interact with Sensu

Special resource types

You can access special resource types 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 want to deny a certain type, you can’t use the * type. Instead, you 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 that interacts with Sensu. You can assign users and groups to one or more roles. Users and groups inherit all permissions from each role assigned to them.

Use your Sensu username and password to configure sensuctl or log in to the web UI.

User example

The following example shows a user resource definition:

---
type: User
api_version: core/v2
metadata: {}
spec:
  disabled: false
  groups:
  - ops
  - dev
  password: user_password
  password_hash: $5f$14$.brXRviMZpbaleSq9kjoUuwm67V/s4IziOLGHjEqxJbzPsreQAyNm
  username: alice
{
  "type": "User",
  "api_version": "core/v2",
  "metadata": {},
  "spec": {
    "username": "alice",
    "password": "user_password",
    "password_hash": "$5f$14$.brXRviMZpbaleSq9kjoUuwm67V/s4IziOLGHjEqxJbzPsreQAyNm",
    "disabled": false,
    "groups": ["ops", "dev"]
  }
}

To create this user with sensuctl create, first save the definition to a file like users.yml or users.json.

Then, run:

sensuctl create --file users.yml
sensuctl create --file users.json

Default users

During the Sensu backend installation process, you create an administrator username and password and a default namespace.

This is the admin user that you can use to manage all aspects of Sensu and create new users.

attribute value
username YOUR_USERNAME
password YOUR_PASSWORD
groups cluster-admins
cluster role cluster-admin
cluster role binding cluster-admin

After you configure sensuctl, you can change the admin user’s password with the change-password command.

Sensu also creates a default agent user with the password P@ssw0rd!. This user/password combination corresponds to the defaults the Sensu agent uses. You can configure the Sensu agent’s user credentials with the user and password agent configuration flags.

Manage users

To test the password for a user created with Sensu’s built-in basic authentication:

sensuctl user test-creds USERNAME --password 'password'

An empty response indicates valid credentials. A request-unauthorized response indicates invalid credentials.

NOTE: The sensuctl user test-creds command tests passwords for users created with Sensu’s built-in basic authentication provider. It does not test user credentials defined via an authentication provider like Lightweight Directory Access Protocol (LDAP), Active Directory (AD), or OpenID Connect 1.0 protocol (OIDC).

To change the password for a user:

sensuctl user change-password USERNAME --current-password CURRENT_PASSWORD --new-password NEW_PASSWORD

You can also use sensuctl to reset a user’s password or generate a password hash.

To disable a user:

sensuctl user disable USERNAME

To re-enable a disabled user:

sensuctl user reinstate USERNAME

View users

You can use sensuctl to list all users within Sensu.

To return a list of users in yaml or wrapped-json format for use with sensuctl create:

sensuctl user list --format yaml
sensuctl user list --format wrapped-json

Create users

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

Passwords must have at least eight characters.

sensuctl user create alice --password='password' --groups=ops,dev

You can create any number of users, each with their own passwords. Users are granted permissions by role bindings or cluster role bindings, but as a general rule, users have no permissions by default.

By default, the agent user belongs to the system:agent group. The system:agent cluster role binding grants the system:agent cluster role to the members of this group. To grant agent users the permissions they need to report events into any namespace, add agent users to the system:agent group.

Assign user permissions

To assign permissions to a user:

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

User specification

Attributes

username
description Name of the user. Cannot contain special characters.
required true
type String
example
username: alice
{
  "username": "alice"
}

password
description User’s password. Passwords must have at least eight characters.

NOTE: You only need to set either the password or the password_hash (not both). We recommend using the password_hash because it eliminates the need to store cleartext passwords.

required true
type String
example
password: user_password
{
  "password": "user_password"
}
groups
description Groups to which the user belongs.
required false
type Array
example
groups:
- dev
- ops
{
  "groups": [
    "dev",
    "ops"
  ]
}
disabled
description If true, the user’s account is disabled. Otherwise, false.
required false
type Boolean
default false
example
disabled: false
{
  "disabled": false
}

password_hash
description Bcrypt password hash. You can use the password_hash in your user definitions instead of storing cleartext passwords.

NOTE: You only need to set either the password or the password_hash (not both). We recommend using the password_hash because it eliminates the need to store cleartext passwords.

required false
type String
example
password_hash: $5f$14$.brXRviMZpbaleSq9kjoUuwm67V/s4IziOLGHjEqxJbzPsreQAyNm
{
  "password_hash": "$5f$14$.brXRviMZpbaleSq9kjoUuwm67V/s4IziOLGHjEqxJbzPsreQAyNm"
}

Groups

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

Groups are not a resource type within Sensu. You can create and manage groups only within user definitions.

Default groups

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

Manage groups

Assign 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]]

Remove 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 that control access to Sensu resources. Roles specify permissions for resources within a namespace. Cluster roles can include permissions for cluster-wide resources.

You can use role bindings to assign roles to user and groups. To avoid recreating 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 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 (for example, to run sensuctl check list --all-namespaces) 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.

Role example

The following example shows a role resource definition:

---
type: Role
api_version: core/v2
metadata:
  name: namespaced-resources-all-verbs
spec:
  rules:
  - resources:
    - assets
    - checks
    - entities
    - events
    - filters
    - handlers
    - hooks
    - mutators
    - rolebindings
    - roles
    - silenced
    verbs:
    - get
    - list
    - create
    - update
    - delete
{
  "type": "Role",
  "api_version": "core/v2",
  "metadata": {
    "name": "namespaced-resources-all-verbs"
  },
  "spec": {
    "rules": [
      {
        "resources": [
          "assets",
          "checks",
          "entities",
          "events",
          "filters",
          "handlers",
          "hooks",
          "mutators",
          "rolebindings",
          "roles",
          "silenced"
        ],
        "verbs": [
          "get",
          "list",
          "create",
          "update",
          "delete"
        ]
      }
    ]
  }
}

To create this role with sensuctl create, first save the definition to a file like roles.yml or roles.json.

Then, run:

sensuctl create --file roles.yml
sensuctl create --file roles.json

Cluster role example

The following example shows a cluster role resource definition:

---
type: ClusterRole
api_version: core/v2
metadata:
  name: all-resources-all-verbs
spec:
  rules:
  - resources:
    - assets
    - checks
    - entities
    - events
    - filters
    - handlers
    - hooks
    - mutators
    - rolebindings
    - roles
    - silenced
    - cluster
    - clusterrolebindings
    - clusterroles
    - namespaces
    - users
    - authproviders
    - license
    verbs:
    - get
    - list
    - create
    - update
    - delete
{
  "type": "ClusterRole",
  "api_version": "core/v2",
  "metadata": {
    "name": "all-resources-all-verbs"
  },
  "spec": {
    "rules": [
      {
        "resources": [
          "assets",
          "checks",
          "entities",
          "events",
          "filters",
          "handlers",
          "hooks",
          "mutators",
          "rolebindings",
          "roles",
          "silenced",
          "cluster",
          "clusterrolebindings",
          "clusterroles",
          "namespaces",
          "users",
          "authproviders",
          "license"
        ],
        "verbs": [
          "get",
          "list",
          "create",
          "update",
          "delete"
        ]
      }
    ]
  }
}

To create this cluster role with sensuctl create, first save the definition to a file like cluster_roles.yml or cluster_roles.json.

Then, run:

sensuctl create --file cluster_roles.yml
sensuctl create --file cluster_roles.json

Default roles and cluster roles

Every Sensu backend includes:

role name type description
system:pipeline Role Facility that allows the EventFilter engine to load events from Sensu’s event store. system:pipeline is an implementation detail and should not be assigned to Sensu users.
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 except 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. You can configure an agent’s user credentials using the user and password agent configuration flags.
system:user ClusterRole Get and update permissions for local resources for the current user.

Manage roles and cluster roles

You can use sensuctl to view, create, edit, and delete roles and cluster roles.

NOTE: To use any of these example commands with cluster roles, substitute the cluster-role command for the role command.

To get help managing roles with sensuctl:

sensuctl role help

To edit a role:

sensuctl edit role [ROLE-NAME] <flags>

View roles and cluster roles

You can use sensuctl to list all roles within Sensu:

sensuctl role list

To review 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

Create roles

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

This command creates the following role resource definition, which provides get, list, create, update, and delete permissions for all resources in the production namespace:

---
type: Role
api_version: core/v2
metadata:
  created_by: admin
  name: prod-admin
  namespace: production
spec:
  rules:
  - resources:
    - '*'
    verbs:
    - get
    - list
    - create
    - update
    - delete
{
  "type": "Role",
  "api_version": "core/v2",
  "metadata": {
    "created_by": "admin",
    "name": "prod-admin",
    "namespace": "production"
  },
  "spec": {
    "rules": [
      {
        "resources": [
          "*"
        ],
        "verbs": [
          "get",
          "list",
          "create",
          "update",
          "delete"
        ]
      }
    ]
  }
}

After you create a role, create a role binding (or cluster role binding) to assign the role to users and groups. For example, to assign the prod-admin role created above to the oncall group, create this role binding:

sensuctl role-binding create prod-admin-oncall --role=prod-admin --group=oncall

This command creates the following role binding resource definition:

---
type: RoleBinding
api_version: core/v2
metadata:
  created_by: admin
  name: prod-admin-oncall
  namespace: production
spec:
  role_ref:
    name: prod-admin
    type: Role
  subjects:
  - name: oncall
    type: Group
{
  "type": "RoleBinding",
  "api_version": "core/v2",
  "metadata": {
    "created_by": "admin",
    "name": "prod-admin-oncall",
    "namespace": "production"
  },
  "spec": {
    "role_ref": {
      "name": "prod-admin",
      "type": "Role"
    },
    "subjects": [
      {
        "name": "oncall",
        "type": "Group"
      }
    ]
  }
}

Create cluster-wide roles

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'

This command creates the following cluster-wide role resource definition:

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

Delete roles and cluster roles

To delete a role:

sensuctl role delete [ROLE-NAME]

Role and cluster role specification

Role and cluster role attributes

name
description Name of the role.
required true
type String
example
name: admin
{
  "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
{
  "namespace": "production"
}
rules
description Rulesets that the role applies.
required true
type Array
example
rules:
- verbs:
  - get
  - list
  resources:
  - checks
  resource_names:
  - ''
{
  "rules": [
    {
      "verbs": [
        "get",
        "list"
      ],
      "resources": [
        "checks"
      ],
      "resource_names": [
        ""
      ]
    }
  ]
}

Rule attributes

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

verbs
description Permissions to be applied by the rule: get, list, create, update, or delete.
required true
type Array
example
verbs:
- get
- list
{
  "verbs": [
    "get",
    "list"
  ]
}
resources
description Type of resource that the rule has permission to access. Roles can only access namespaced resource types. Cluster roles can access namespaced and cluster-wide resource types. Read resource types to learn about available types.
required true
type Array
example
resources:
- checks
{
  "resources": [
    "checks"
  ]
}
resource_names
description Specific resource names that the rule has permission to access. Resource name permissions are only taken into account for requests using get, update, and delete verbs.
required false
type Array
example
resource_names:
- check-cpu
{
  "resource_names": [
    "check-cpu"
  ]
}

Role bindings and cluster role bindings

A role binding assigns a role or cluster role to users and groups within a namespace. A cluster role binding assigns a cluster role to users and groups across namespaces and resource types.

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 role bindings within a namespace, create a role with rolebindings permissions within that namespace, and log in by configuring sensuctl.

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

Make sure to include the groups prefix and username prefix for the authentication provider when creating Sensu role bindings and cluster role bindings. Without an assigned role or cluster role, users can sign in to the web UI but can’t access any Sensu resources. With the correct roles and bindings configured, users can log in to sensuctl and the web UI using their single-sign-on username and password (no prefixes required).

Role binding example

The following example shows a role binding resource definition:

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

To create this role binding with sensuctl create, first save the definition to a file like rolebindings.yml or rolebindings.json.

Then, run:

sensuctl create --file rolebindings.yml
sensuctl create --file rolebindings.json

Cluster role binding example

The following example shows a cluster role binding resource definition:

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

To create this cluster role binding with sensuctl create, first save the definition to a file like clusterrolebindings.yml or clusterrolebindings.json.

Then, run:

sensuctl create --file clusterrolebindings.yml
sensuctl create --file clusterrolebindings.json

Default role bindings and cluster role bindings

Every Sensu backend includes:

role name type description
system:pipeline RoleBinding Facility that allows the EventFilter engine to load events from Sensu’s event store. system:pipeline is an implementation detail and should not be applied to Sensu users.
cluster-admin ClusterRoleBinding Full access to all resource types across namespaces, including access to cluster-wide resource types.
system:agent ClusterRoleBinding Full access to all events. Used internally by Sensu agents.
system:user ClusterRoleBinding Get and update permissions for local resources for the current user.

Manage role bindings and cluster role bindings

You can use sensuctl to view, create, and delete role bindings and cluster role bindings.

NOTE: To use any of these commands with cluster roles, substitute the cluster-role-binding command for the role-binding command.

To get help managing role bindings with sensuctl:

sensuctl role-binding help

View role bindings and cluster role bindings

You can use sensuctl to list all role bindings within Sensu:

sensuctl role-binding list

To review the details for a specific role binding:

sensuctl role-binding info [BINDING-NAME]

To list cluster role bindings:

sensuctl cluster-role-binding list

Create role bindings and cluster role bindings

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

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

This command creates a role binding resource definition similar to the following:

---
type: RoleBinding
api_version: core/v2
metadata:
  name: NAME
spec:
  role_ref:
    name: NAME
    type: Role
  subjects:
  - name: groupname
    type: Group
  - name: username
    type: User
{
  "type": "RoleBinding",
  "api_version": "core/v2",
  "metadata": {
    "name": "NAME"
  },
  "spec": {
    "role_ref": {
      "name": "NAME",
      "type": "Role"
    },
    "subjects": [
      {
        "name": "groupname",
        "type": "Group"
      },
      {
        "name": "username",
        "type": "User"
      }
    ]
  }
}

To create a role binding that assigns a cluster role:

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

This command creates a role binding resource definition similar to the following:

---
type: RoleBinding
api_version: core/v2
metadata:
  name: NAME
spec:
  role_ref:
    name: NAME
    type: ClusterRole
  subjects:
  - name: groupname
    type: Group
  - name: username
    type: User
{
  "type": "RoleBinding",
  "api_version": "core/v2",
  "metadata": {
    "name": "NAME"
  },
  "spec": {
    "role_ref": {
      "name": "NAME",
      "type": "ClusterRole"
    },
    "subjects": [
      {
        "name": "groupname",
        "type": "Group"
      },
      {
        "name": "username",
        "type": "User"
      }
    ]
  }
}

To create a cluster role binding:

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

This command creates a cluster role binding resource definition similar to the following:

---
type: ClusterRoleBinding
api_version: core/v2
metadata:
  name: NAME
spec:
  role_ref:
    name: NAME
    type: ClusterRole
  subjects:
  - name: groupname
    type: Group
  - name: username
    type: User
{
  "type": "ClusterRoleBinding",
  "api_version": "core/v2",
  "metadata": {
    "name": "NAME"
  },
  "spec": {
    "role_ref": {
      "name": "NAME",
      "type": "ClusterRole"
    },
    "subjects": [
      {
        "name": "groupname",
        "type": "Group"
      },
      {
        "name": "username",
        "type": "User"
      }
    ]
  }
}

Delete role bindings and cluster role bindings

To delete a role binding:

sensuctl role-binding delete [ROLE-NAME]

Role binding and cluster role binding specification

roleRef
description Reference a role in the current namespace or a cluster role.
required true
type Hash
example
roleRef:
  type: Role
  name: event-reader
{
  "roleRef": {
    "type": "Role",
    "name": "event-reader"
  }
}
subjects
description Users or groups being assigned.
required true
type Array
example
subjects:
- type: User
  name: alice
{
  "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
{
  "type": "Role"
}
name
description Name of the role or cluster role being assigned.
required true
type String
example
name: event-reader
{
  "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
{
  "type": "User"
}
name
description Username or group name.
required true
type String
example
name: alice
{
  "name": "alice"
}
example with prefix
name: ad:alice
{
  "name": "ad:alice"
}

Create a role and role binding

The following role and role binding give a dev group access to create and manage Sensu workflows within the default namespace.

---
type: Role
api_version: core/v2
metadata:
  name: workflow-creator
  namespace: default
spec:
  rules:
    - resources:
      - checks
      - hooks
      - filters
      - events
      - filters
      - mutators
      - handlers
      verbs:
      - get
      - list
      - create
      - update
      - delete
{
  "type": "Role",
  "api_version": "core/v2",
  "metadata": {
    "name": "workflow-creator",
    "namespace": "default"
  },
  "spec": {
    "rules": [
      {
        "resources": [
          "checks",
          "hooks",
          "filters",
          "events",
          "filters",
          "mutators",
          "handlers"
        ],
        "verbs": [
          "get",
          "list",
          "create",
          "update",
          "delete"
        ]
      }
    ]
  }
}
---
type: RoleBinding
api_version: core/v2
metadata:
  name: dev-binding
  namespace: default
spec:
  role_ref:
    name: workflow-creator
    type: Role
  subjects:
  - name: dev
    type: Group
{
  "type": "RoleBinding",
  "api_version": "core/v2",
  "metadata": {
    "name": "dev-binding",
    "namespace": "default"
  },
  "spec": {
    "role_ref": {
      "name": "workflow-creator",
      "type": "Role"
    },
    "subjects": [
      {
        "name": "dev",
        "type": "Group"
      }
    ]
  }
}

Create a role and role binding with a group prefix

In this example, if a groups_prefix of ad is configured for Active Directory authentication, the role and role binding will give a dev group access to create and manage Sensu workflows within the default namespace.

---
type: Role
api_version: core/v2
metadata:
  name: workflow-creator
  namespace: default
spec:
  rules:
  - resources:
    - checks
    - hooks
    - filters
    - events
    - filters
    - mutators
    - handlers
    verbs:
    - get
    - list
    - create
    - update
    - delete
{
  "type": "Role",
  "api_version": "core/v2",
  "metadata": {
    "name": "workflow-creator",
    "namespace": "default"
  },
  "spec": {
    "rules": [
      {
        "resources": [
          "checks",
          "hooks",
          "filters",
          "events",
          "filters",
          "mutators",
          "handlers"
        ],
        "verbs": [
          "get",
          "list",
          "create",
          "update",
          "delete"
        ]
      }
    ]
  }
}
---
type: RoleBinding
api_version: core/v2
metadata:
  name: dev-binding-with-groups-prefix
  namespace: default
spec:
  role_ref:
    name: workflow-creator
    type: Role
  subjects:
  - name: ad:dev
    type: Group
{
  "type": "RoleBinding",
  "api_version": "core/v2",
  "metadata": {
    "name": "dev-binding-with-groups-prefix",
    "namespace": "default"
  },
  "spec": {
    "role_ref": {
      "name": "workflow-creator",
      "type": "Role"
    },
    "subjects": [
      {
        "name": "ad:dev",
        "type": "Group"
      }
    ]
  }
}

Assign user permissions within a namespace

To assign permissions to a user:

  1. Create the user.
  2. Create a role.
  3. Create a role binding to assign the role to the user.

For example, the following configuration creates a user alice, a role default-admin, and a role binding alice-default-admin, giving alice full permissions for namespaced resource types within the default namespace. You can add these resources to Sensu using sensuctl create.

---
type: User
api_version: core/v2
metadata: {}
spec:
  disabled: false
  username: alice
  password: user_password
{
  "type": "User",
  "api_version": "core/v2",
  "metadata": {},
  "spec": {
    "disabled": false,
    "username": "alice",
    "password": "user_password"
  }
}
---
type: Role
api_version: core/v2
metadata:
  name: default-admin
  namespace: default
spec:
  rules:
  - resources:
    - assets
    - checks
    - entities
    - events
    - filters
    - handlers
    - hooks
    - mutators
    - rolebindings
    - roles
    - searches
    - silenced
    verbs:
    - get
    - list
    - create
    - update
    - delete
{
  "type": "Role",
  "api_version": "core/v2",
  "metadata": {
    "name": "default-admin",
    "namespace": "default"
  },
  "spec": {
    "rules": [
      {
        "resources": [
          "assets",
          "checks",
          "entities",
          "events",
          "filters",
          "handlers",
          "hooks",
          "mutators",
          "rolebindings",
          "roles",
          "searches",
          "silenced"
        ],
        "verbs": [
          "get",
          "list",
          "create",
          "update",
          "delete"
        ]
      }
    ]
  }
}
---
type: RoleBinding
api_version: core/v2
metadata:
  name: alice-default-admin
  namespace: default
spec:
  role_ref:
    name: default-admin
    type: Role
  subjects:
  - name: alice
    type: User
{
  "type": "RoleBinding",
  "api_version": "core/v2",
  "metadata": {
    "name": "alice-default-admin",
    "namespace": "default"
  },
  "spec": {
    "role_ref": {
      "name": "default-admin",
      "type": "Role"
    },
    "subjects": [
      {
        "name": "alice",
        "type": "User"
      }
    ]
  }
}

Assign group permissions within a namespace

To assign permissions to group of users:

  1. Create at least one user assigned to a group.
  2. Create a role.
  3. Create a role binding to assign the role to the group.

For example, the following configuration creates a user alice assigned to the group ops, a role default-admin, and a role binding ops-default-admin, giving the ops group full permissions for namespaced resource types within the default namespace. You can add these resources to Sensu using sensuctl create.

---
type: User
api_version: core/v2
metadata: {}
spec:
  disabled: false
  username: alice
  password: user_password
  groups:
  - ops
{
  "type": "User",
  "api_version": "core/v2",
  "metadata": {},
  "spec": {
    "disabled": false,
    "username": "alice",
    "password": "user_password",
    "groups": [
      "ops"
    ]
  }
}
---
type: Role
api_version: core/v2
metadata:
  name: default-admin
  namespace: default
spec:
  rules:
  - resources:
    - assets
    - checks
    - entities
    - events
    - filters
    - handlers
    - hooks
    - mutators
    - rolebindings
    - roles
    - searches
    - silenced
    verbs:
    - get
    - list
    - create
    - update
    - delete
{
  "type": "Role",
  "api_version": "core/v2",
  "metadata": {
    "name": "default-admin",
    "namespace": "default"
  },
  "spec": {
    "rules": [
      {
        "resources": [
          "assets",
          "checks",
          "entities",
          "events",
          "filters",
          "handlers",
          "hooks",
          "mutators",
          "rolebindings",
          "roles",
          "searches",
          "silenced"
        ],
        "verbs": [
          "get",
          "list",
          "create",
          "update",
          "delete"
        ]
      }
    ]
  }
}
---
type: RoleBinding
api_version: core/v2
metadata:
  name: ops-default-admin
  namespace: default
spec:
  role_ref:
    name: default-admin
    type: Role
  subjects:
  - name: ops
    type: Group
{
  "type": "RoleBinding",
  "api_version": "core/v2",
  "metadata": {
    "name": "ops-default-admin",
    "namespace": "default"
  },
  "spec": {
    "role_ref": {
      "name": "default-admin",
      "type": "Role"
    },
    "subjects": [
      {
        "name": "ops",
        "type": "Group"
      }
    ]
  }
}

PRO TIP: To avoid recreating commonly used roles in each namespace, create a cluster role and use a role binding to restrict permissions within a specific namespace.

Assign group permissions across all namespaces

To assign cluster-wide permissions to group of users:

  1. Create at least one user assigned to a group.
  2. Create a cluster role.
  3. Create a cluster role binding to assign the role to the group.

For example, the following configuration creates a user alice assigned to the group ops, a cluster role default-admin, and a cluster role binding ops-default-admin, giving the ops group full permissions for namespaced resource types and cluster-wide resource types across all namespaces. You can add these resources to Sensu using sensuctl create.

---
type: User
api_version: core/v2
metadata: {}
spec:
  disabled: false
  username: alice
  password: user_password
  groups:
  - ops
{
  "type": "User",
  "api_version": "core/v2",
  "metadata": {},
  "spec": {
    "disabled": false,
    "username": "alice",
    "password": "user_password",
    "groups": [
      "ops"
    ]
  }
}
---
type: ClusterRole
api_version: core/v2
metadata:
  name: default-admin
spec:
  rules:
  - resources:
    - assets
    - checks
    - entities
    - events
    - filters
    - handlers
    - hooks
    - mutators
    - rolebindings
    - roles
    - silenced
    - cluster
    - clusterrolebindings
    - clusterroles
    - namespaces
    - users
    - authproviders
    - license
    verbs:
    - get
    - list
    - create
    - update
    - delete
{
  "type": "ClusterRole",
  "api_version": "core/v2",
  "metadata": {
    "name": "default-admin"
  },
  "spec": {
    "rules": [
      {
        "resources": [
          "assets",
          "checks",
          "entities",
          "events",
          "filters",
          "handlers",
          "hooks",
          "mutators",
          "rolebindings",
          "roles",
          "silenced",
          "cluster",
          "clusterrolebindings",
          "clusterroles",
          "namespaces",
          "users",
          "authproviders",
          "license"
        ],
        "verbs": [
          "get",
          "list",
          "create",
          "update",
          "delete"
        ]
      }
    ]
  }
}
---
type: ClusterRoleBinding
api_version: core/v2
metadata:
  name: ops-default-admin
spec:
  role_ref:
    name: default-admin
    type: ClusterRole
  subjects:
  - name: ops
    type: Group
{
  "type": "ClusterRoleBinding",
  "api_version": "core/v2",
  "metadata": {
    "name": "ops-default-admin"
  },
  "spec": {
    "role_ref": {
      "name": "default-admin",
      "type": "ClusterRole"
    },
    "subjects": [
      {
        "name": "ops",
        "type": "Group"
      }
    ]
  }
}

Assign different permissions for different resource types

You can assign different permissions for different resource types in a role or cluster role definition. To do this, you’ll still create at least one user assigned to a group, a role or cluster role, and a role binding or cluster role binding. However, in this case, the role or cluster role will include more than one rule.

For example, you may want users in a testing group to be able to get and list all resource types but create, update, and delete only silenced entries across all namespaces. Create a user alice assigned to the group ops_testing, a cluster role manage_silences with two rules (one for all resources and one just for silences), and a cluster role binding ops_testing_manage_silences:

---
type: User
api_version: core/v2
metadata: {}
spec:
  disabled: false
  username: alice
  password: user_password
  groups:
  - ops_testing
{
  "type": "User",
  "api_version": "core/v2",
  "metadata": {},
  "spec": {
    "disabled": false,
    "username": "alice",
    "password": "user_password",
    "groups": [
      "ops_testing"
    ]
  }
}
---
type: ClusterRole
api_version: core/v2
metadata:
  name: manage_silences
spec:
  rules:
  - verbs:
    - get
    - list
    resources:
    - '*'
  - verbs:
    - create
    - update
    - delete
    resources:
    - silenced
{
  "type": "ClusterRole",
  "api_version": "core/v2",
  "metadata": {
    "name": "manage_silences"
  },
  "spec": {
    "rules": [
      {
        "verbs": [
          "get",
          "list"
        ],
        "resources": [
          "*"
        ]
      },
      {
        "verbs": [
          "create",
          "update",
          "delete"
        ],
        "resources": [
          "silenced"
        ]
      }
    ]
  }
}
---
type: ClusterRoleBinding
api_version: core/v2
metadata:
  name: ops_testing_manage_silences
spec:
  role_ref:
    name: manage_silences
    type: ClusterRole
  subjects:
  - name: ops_testing
    type: Group
{
  "type": "ClusterRoleBinding",
  "api_version": "core/v2",
  "metadata": {
    "name": "ops_testing_manage_silences"
  },
  "spec": {
    "role_ref": {
      "name": "manage_silences",
      "type": "ClusterRole"
    },
    "subjects": [
      {
        "name": "ops_testing",
        "type": "Group"
      }
    ]
  }
}

Create as many rules as you need in the role or cluster role. For example, you can configure a role or cluster role that includes one rule for each verb, with each rule listing only the resources that verb should apply to.

Here’s another example that includes three rules. Each rule specifies different access permissions for the resource types listed in the rule. In addition, the user group would have no access at all for the two resources that are not listed: API keys and licences.

---
type: User
api_version: core/v2
metadata: {}
spec:
  disabled: false
  username: alice
  password: user_password
  groups:
  - ops
{
  "type": "User",
  "api_version": "core/v2",
  "metadata": {},
  "spec": {
    "disabled": false,
    "username": "alice",
    "password": "user_password",
    "groups": [
      "ops"
    ]
  }
}
---
type: ClusterRole
api_version: core/v2
metadata:
  name: ops_access
spec:
  rules:
  - verbs:
    - get
    - list
    resources:
    - entities
    - events
    - rolebindings
    - roles
    - clusterrolebindings
    - clusterroles
    - config
    - users
  - verbs:
    - get
    - list
    - create
    - update
    - delete
    resources:
    - assets
    - checks
    - filters
    - handlers
    - hooks
    - mutators
    - rule-templates
    - searches
    - secrets
    - service-components
    - silenced
    - clusters
    - etcd-replicators
    - providers
  - verbs:
    - get
    - list
    - create
    - update
    resources:
    - authproviders
    - namespaces
    - provider
{
  "type": "ClusterRole",
  "api_version": "core/v2",
  "metadata": {
    "name": "ops_access"
  },
  "spec": {
    "rules": [
      {
        "verbs": [
          "get",
          "list"
        ],
        "resources": [
          "entities",
          "events",
          "rolebindings",
          "roles",
          "clusterrolebindings",
          "clusterroles",
          "config",
          "users"
        ]
      },
      {
        "verbs": [
          "get",
          "list",
          "create",
          "update",
          "delete"
        ],
        "resources": [
          "assets",
          "checks",
          "filters",
          "handlers",
          "hooks",
          "mutators",
          "rule-templates",
          "searches",
          "secrets",
          "service-components",
          "silenced",
          "clusters",
          "etcd-replicators",
          "providers"
        ]
      },
      {
        "verbs": [
          "get",
          "list",
          "create",
          "update"
        ],
        "resources": [
          "authproviders",
          "namespaces",
          "provider"
        ]
      }
    ]
  }
}
---
type: ClusterRoleBinding
api_version: core/v2
metadata:
  name: ops_access_assignment
spec:
  role_ref:
    name: ops_access
    type: ClusterRole
  subjects:
  - name: ops
    type: Group
{
  "type": "ClusterRoleBinding",
  "api_version": "core/v2",
  "metadata": {
    "name": "ops_access_assignment"
  },
  "spec": {
    "role_ref": {
      "name": "ops_access",
      "type": "ClusterRole"
    },
    "subjects": [
      {
        "name": "ops",
        "type": "Group"
      }
    ]
  }
}

Reuse cluster roles across namespaces

Reusing cluster roles across namespaces can reduce the number of resources you need to manage.

For example, suppose you have three teams, each with its own namespace. You write a script that uses limited service accounts to create and delete silences. You want to use the script for all three team namespaces, so you create a role with the required permissions and a role binding in each namespace: six new resources. If you need to change the permissions for the script, you will need to update each role in the team namespaces (three resources).

A better approach is to create a single cluster role that grants the required permissions, plus one role binding in each namespace to tie the permissions to the namespace’s limited service account. With this configuration, you only need to update one resource to make permission changes: the silencing-script cluster role. Sensu will automatically apply updates in each team’s namespace using the role bindings that define each limited service account as a subject of the cluster role.

  1. Create a limited service account user in each namespace:

    sensuctl user create silencing-service-team-1 --password='password'

    This creates the following user definition:

    ---
    type: User
    api_version: core/v2
    metadata:
      name: silencing-service-team-1
    spec:
      disabled: false
      username: silencing-service-team-1
    {
      "type": "User",
      "api_version": "core/v2",
      "metadata": {
        "name": "silencing-service-team-1"
      },
      "spec": {
        "disabled": false,
        "username": "silencing-service-team-1"
      }
    }

    Repeat this step to create a limited service account user in each team’s namespace.

  2. Create a cluster role with get, list, create, update, and delete permissions for silences:

    sensuctl cluster-role create silencing-script --verb get,list,create,update,delete --resource silenced

    This command creates the cluster role that has the permissions the silencing service accounts will need:

    ---
    type: ClusterRole
    api_version: core/v2
    metadata:
      name: silencing-script
    spec:
      rules:
      - resources:
        - silenced
        verbs:
        - get
        - list
        - create
        - update
        - delete
    {
      "type": "ClusterRole",
      "api_version": "core/v2",
      "metadata": {
        "name": "silencing-script"
      },
      "spec": {
        "rules": [
          {
            "resources": [
              "silenced"
            ],
            "verbs": [
              "get",
              "list",
              "create",
              "update",
              "delete"
            ]
          }
        ]
      }
    }
  3. Create a role binding in each team namespace to assign the silencing-script cluster role to the team’s silencing-service user. For example, use this command to create the role binding for Team 1:

    sensuctl role-binding create silencing-script-binding-team-1 --cluster-role silencing-script --user silencing-service-team-1 --namespace team1

    This command creates the role binding that ties the correct permissions (via the silencing-script cluster role) with your service account (via the user silencing-service-team-1):

    ---
    type: RoleBinding
    api_version: core/v2
    metadata:
      name: silencing-script-binding-team-1
      namespace: team1
    spec:
      role_ref:
        name: silencing-script
        type: ClusterRole
      subjects:
      - name: silencing-service-team-1
        type: User
    {
      "type": "RoleBinding",
      "api_version": "core/v2",
      "metadata": {
        "name": "silencing-script-binding-team-1",
        "namespace": "team1"
      },
      "spec": {
        "role_ref": {
          "name": "silencing-script",
          "type": "ClusterRole"
        },
        "subjects": [
          {
            "name": "silencing-service-team-1",
            "type": "User"
          }
        ]
      }
    }

    Repeat this step to create a role binding for the silencing-script cluster role and the limited service account user in each team’s namespace.