Role-based access control (RBAC) reference
Sensu’s role-based access control (RBAC) helps different teams and projects share a Sensu instance. Use RBAC to specify the actions users are allowed to take against specific Sensu 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 can be scoped to resource types, like checks, handlers, and users. List resource types in the rules arrays of role and cluster role definitions to configure permissions.
Namespaced resource types
Namespaced resources belong to a single namespace. You can set permissions for namespaced resources with roles and cluster roles.
Resource 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 |
pipelines |
Resources composed of event processing workflows |
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 |
sumo-logic-metrics-handlers |
Persistent handlers for transmitting metrics to Sumo Logic |
tcp-stream-handlers |
Persistent handlers for sending events to TCP sockets for remote storage |
Cluster-wide resource types
Cluster-wide resources cannot be assigned to a namespace. You can set permissions for cluster-wide resources only with cluster roles.
Resource 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 set permissions for special resource types with 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 to one or more roles or cluster roles. You can also assign users to one or more groups. Users inherit all permissions from each role or cluster role they are assigned to, whether they are assigned as users or as a member of a group.
Users can use their assigned Sensu username and password to configure sensuctl and 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
Sensu automatically creates an administrator user and an agent
user during installation.
Administrator user
During the Sensu backend installation process, you create a username and password for an admin
user.
The admin
user is automatically added to the cluster-admins
group and the cluster-admin
cluster role, which are both listed in the cluster role binding cluster-admin
.
The group, cluster role, and cluster role binding assignments give the admin
user permissions to manage all aspects of Sensu, as well as create new users.
After you configure sensuctl, you can change the admin
user’s password with the change-password
command.
agent
user
Sensu creates a default agent
user with the password P@ssw0rd!
during startup.
The user/password combination corresponds to the defaults the Sensu agent uses.
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.
Configure the agent
user’s credentials with the user
and password
agent configuration options.
View users
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
Test and change user passwords
To test the password for a user created with Sensu’s built-in basic authentication, run:
sensuctl user test-creds <USERNAME> --password '<PASSWORD>'
An empty response indicates the user’s password is valid.
A request-unauthorized
response indicates the user’s password is invalid.
NOTE: The sensuctl user test-creds
command tests passwords for users created with Sensu’s built-in basic authentication.
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 a user’s password:
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.
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:
sensuctl user create alice --password='<PASSWORD>' --groups=ops,dev
NOTE: Passwords must have at least eight characters.
You can create any number of users, each with their own passwords. As a general rule, users have no permissions by default. Users are granted permissions by role bindings or cluster role bindings.
Disable users
To disable a user, run:
sensuctl user disable <USERNAME>
To reinstate a disabled user, run:
sensuctl user reinstate <USERNAME>
Assign user permissions
To assign permissions to a user:
- Create the user.
- Create a role (or a cluster role for cluster-wide access).
- Create a role binding (or cluster role binding) to assign the role to the user.
Groups
A group is a set of users within Sensu. You can assign groups to one or more roles, and users can belong to one or more groups.
Groups inherit all permissions from each role they are assigned to.
NOTE: Groups are not a resource type within Sensu. Instead, groups are created and managed 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.
Add groups to users
Use sensuctl to add a group to a user:
sensuctl user add-group <USERNAME> <GROUP>
You can also set a user’s list of groups to a specific list:
sensuctl user set-groups <USERNAME> <GROUP1>[,<GROUP2>, ...<GROUP2>]
Remove groups from users
Use sensuctl to remove groups from users.
To remove a group from a user:
sensuctl user remove-group <USERNAME> <GROUP>
To remove all groups from a user:
sensuctl user remove-groups <USERNAME>
Roles
A role is a set of permissions that control access to Sensu resources within a single namespace. Use role bindings to assign roles to users and groups.
To create and manage roles within a single namespace, create a role with roles
permissions within that namespace.
To create and manage roles cluster-wide, configure sensuctl as the default admin
user or create a cluster role with roles
permissions.
To avoid recreating commonly used roles in every namespace, create a cluster role and use a role binding (not a cluster role binding) to restrict permissions within a specific namespace.
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
- pipelines
- rolebindings
- roles
- silenced
- sumo-logic-metrics-handlers
- tcp-stream-handlers
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",
"pipelines",
"rolebindings",
"roles",
"silenced",
"sumo-logic-metrics-handlers",
"tcp-stream-handlers"
],
"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
Default roles
Every Sensu backend includes the system:pipeline
role, which is a facility that allows the EventFilter engine to load events from Sensu’s event store.
The system:pipeline
role is an implementation detail and should not be assigned to Sensu users.
View roles
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 get help managing roles with sensuctl:
sensuctl role help
Edit roles
To edit a role:
sensuctl edit role <ROLE> <flags>
To get more information about available flags, run:
sensuctl edit --help
Create roles
You can use sensuctl to create roles. Read Create a role and role binding for an example.
Delete roles
To delete a role:
sensuctl role delete <ROLE>
Cluster roles
A cluster role is a set of permissions that control access to Sensu resources. Cluster roles can include permissions for cluster-wide resources in addition to namespaced resources.
You can also use cluster roles (in conjunction with cluster role bindings) to grant access to namespaced resources across all namespaces.
This allows you to run commmands like sensuctl check list --all-namespaces
.
To create and manage cluster roles, configure sensuctl as the default admin
user or create a cluster role with permissions for clusterroles
.
To create and manage roles cluster-wide, configure sensuctl as the default admin
user or create a cluster role with roles
permissions.
To avoid recreating commonly used roles in every namespace, create a cluster role and use a role binding (not a cluster role binding) to restrict permissions within a specific namespace.
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
- pipelines
- rolebindings
- roles
- silenced
- cluster
- clusterrolebindings
- clusterroles
- namespaces
- users
- authproviders
- license
- sumo-logic-metrics-handlers
- tcp-stream-handlers
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",
"pipelines",
"rolebindings",
"roles",
"silenced",
"cluster",
"clusterrolebindings",
"clusterroles",
"namespaces",
"users",
"authproviders",
"license",
"sumo-logic-metrics-handlers",
"tcp-stream-handlers"
],
"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 cluster roles
Every Sensu backend includes the following cluster roles:
Cluster role name | Description |
---|---|
cluster-admin |
Full access to all resource types across namespaces, including access to cluster-wide resource types. |
admin |
Full access to all resource types. Apply this cluster role within a namespace with a role binding (not a cluster role binding). |
edit |
Read and write access to most resource types except roles and role bindings. Apply this cluster role within a namespace with a role binding (not a cluster role binding). |
view |
Read-only access to most resource types except roles and role bindings. Apply this cluster role within a namespace with a role binding (not a cluster role binding). |
system:agent |
Used internally by Sensu agents. Configure an agent’s user credentials with the user and password agent configuration flags. |
system:user |
Get and update permissions for local resources for the current user. |
View cluster roles
Use sensuctl to list all cluster roles within Sensu:
sensuctl cluster-role list
To review the permissions and scope for a specific cluster role:
sensuctl cluster-role info <CLUSTER-ROLE>
To get help managing roles with sensuctl:
sensuctl cluster-role help
Create cluster roles
You can use sensuctl to create cluster roles. Read Create a cluster role and cluster role binding for an example.
Delete cluster roles
To delete a cluster role:
sensuctl cluster-role delete <CLUSTER-ROLE>
Role bindings
A role binding assigns a role or a cluster role to users and groups within a single namespace.
To create and manage role bindings within a namespace, create a role with rolebindings
permissions within that namespace, and log in by configuring sensuctl.
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).
Make sure to include the groups_prefix and username_prefix for the authentication provider when you create Sensu role bindings.
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
Default role bindings
Every Sensu backend includes the system:pipeline
role binding, a facility that allows the EventFilter engine to load events from Sensu’s event store.
The system:pipeline
role binding is an implementation detail and should not be applied to Sensu users. |
View role bindings
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 <ROLE-BINDING>
To get help managing role bindings with sensuctl:
sensuctl role-binding help
Create role bindings
You can use sensuctl to create role bindings that assign a role to users and groups. Read Create a role and role binding for an example.
Delete role bindings
To delete a role binding:
sensuctl role-binding delete <ROLE-BINDING>
Cluster role bindings
A cluster role binding assigns a cluster role to users and groups across namespaces and resource types.
To create and manage cluster role bindings, configure sensuctl as the default admin
user or create a cluster role with permissions for clusterrolebindings
.
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).
Make sure to include the groups_prefix and username_prefix for the authentication provider when creating Sensu cluster role bindings.
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"
}
]
}
}
NOTE: If you are using Active Directory (AD) or Lightweight Directory Access Protocol (LDAP) authentication, the names of users and groups listed in the subjects array must exactly match the user and group names the authentication provider returns to the Sensu backend.
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 cluster role bindings
Every Sensu backend includes the following cluster role bindings:
Cluster role binding name | Description |
---|---|
cluster-admin |
ClusterRoleBinding |
system:agent |
ClusterRoleBinding |
system:user |
ClusterRoleBinding |
View cluster role bindings
Use sensuctl to list all cluster role bindings within Sensu:
sensuctl cluster-role-binding list
To review the details for a specific role binding:
sensuctl cluster-role-binding info <CLUSTER-ROLE-BINDING>
To get help managing cluster role bindings with sensuctl:
sensuctl cluster-role-binding help
Create cluster role bindings
You can use sensuctl to create cluster role bindings that assign cluster roles to users and groups. Read Create a cluster role and cluster role binding for an example.
Delete cluster role bindings
To delete a role binding:
sensuctl cluster-role-binding delete <CLUSTER-ROLE-BINDING>
Create a role and role binding
This example will create a role and a role binding that assigns the role to a group. As a result, all users who are assigned the group will have get, list, create, update, and delete permissions for all resources in the production namespace.
The following command creates a prod-admin
role restricted to the production namespace:
sensuctl role create prod-admin --verb='get,list,create,update,delete' --resource='*' --namespace production
The command creates the following role resource definition:
---
type: Role
api_version: core/v2
metadata:
name: prod-admin
namespace: production
spec:
rules:
- resources:
- '*'
verbs:
- get
- list
- create
- update
- delete
{
"type": "Role",
"api_version": "core/v2",
"metadata": {
"name": "prod-admin",
"namespace": "production"
},
"spec": {
"rules": [
{
"resources": [
"*"
],
"verbs": [
"get",
"list",
"create",
"update",
"delete"
]
}
]
}
}
Run the following command to create a role binding (or cluster role binding) to assign the prod-admin
role created above to a group named oncall
:
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:
name: prod-admin-oncall
spec:
role_ref:
name: prod-admin
type: Role
subjects:
- name: oncall
type: Group
{
"type": "RoleBinding",
"api_version": "core/v2",
"metadata": {
"name": "prod-admin-oncall"
},
"spec": {
"role_ref": {
"name": "prod-admin",
"type": "Role"
},
"subjects": [
{
"name": "oncall",
"type": "Group"
}
]
}
}
Role bindings can also assign cluster roles to users and groups within a single namespace.
For example, to create a role binding that assigns the global-event-reader
cluster role to the user angela
and the event-readers
group, run:
sensuctl role-binding create event-readers-binding --cluster-role=global-event-reader --user=angela --group=read-events-only
This command creates a role binding resource definition similar to the following:
---
type: RoleBinding
api_version: core/v2
metadata:
name: event-readers-binding
namespace: default
spec:
role_ref:
name: global-event-reader
type: ClusterRole
subjects:
- name: read-events-only
type: Group
- name: angela
type: User
{
"type": "RoleBinding",
"api_version": "core/v2",
"metadata": {
"name": "event-readers-binding",
"namespace": "default"
},
"spec": {
"role_ref": {
"name": "global-event-reader",
"type": "ClusterRole"
},
"subjects": [
{
"name": "read-events-only",
"type": "Group"
},
{
"name": "angela",
"type": "User"
}
]
}
}
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
spec:
rules:
- resources:
- checks
- hooks
- filters
- events
- filters
- mutators
- pipelines
- handlers
- sumo-logic-metrics-handlers
- tcp-stream-handlers
verbs:
- get
- list
- create
- update
- delete
{
"type": "Role",
"api_version": "core/v2",
"metadata": {
"name": "workflow-creator"
},
"spec": {
"rules": [
{
"resources": [
"checks",
"hooks",
"filters",
"events",
"filters",
"mutators",
"pipelines",
"handlers",
"sumo-logic-metrics-handlers",
"tcp-stream-handlers"
],
"verbs": [
"get",
"list",
"create",
"update",
"delete"
]
}
]
}
}
---
type: RoleBinding
api_version: core/v2
metadata:
name: dev-binding-with-groups-prefix
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"
},
"spec": {
"role_ref": {
"name": "workflow-creator",
"type": "Role"
},
"subjects": [
{
"name": "ad:dev",
"type": "Group"
}
]
}
}
Create a cluster role and cluster role binding
This example will create a cluster role and a cluster role role binding that assigns the cluster role to a user and a group. As a result, the individual user and all users who are assigned the group will have read-only access to events (and only events) across all namespaces in Sensu.
For example, the following command creates a global-event-reader
cluster role that can read events in all namespaces:
sensuctl cluster-role create global-event-reader --verb='get,list' --resource='events'
The command creates the following cluster role resource definition:
---
type: ClusterRole
api_version: core/v2
metadata:
name: global-event-reader
spec:
rules:
- resources:
- events
verbs:
- get
- list
{
"type": "ClusterRole",
"api_version": "core/v2",
"metadata": {
"name": "global-event-reader"
},
"spec": {
"rules": [
{
"resources": [
"events"
],
"verbs": [
"get",
"list"
]
}
]
}
}
Next, run the following command to assign the global-event-reader
cluster role to the user angela
and the group global-event-readers
:
sensuctl cluster-role-binding create global-event-reader-binding --cluster-role=global-event-reader --user=angela --group=global-event-readers
This command creates a cluster role binding resource definition similar to the following:
---
type: ClusterRoleBinding
api_version: core/v2
metadata:
name: global-event-reader-binding
spec:
role_ref:
name: global-event-reader
type: ClusterRole
subjects:
- name: global-event-readers
type: Group
- name: angela
type: User
{
"type": "ClusterRoleBinding",
"api_version": "core/v2",
"metadata": {
"name": "global-event-reader-binding"
},
"spec": {
"role_ref": {
"name": "global-event-reader",
"type": "ClusterRole"
},
"subjects": [
{
"name": "global-event-readers",
"type": "Group"
},
{
"name": "angela",
"type": "User"
}
]
}
}
Assign user permissions within a namespace
To assign permissions to a user:
- Create the user.
- Create a role.
- 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
spec:
rules:
- resources:
- assets
- checks
- entities
- events
- filters
- handlers
- hooks
- mutators
- pipelines
- rolebindings
- roles
- searches
- silenced
- sumo-logic-metrics-handlers
- tcp-stream-handlers
verbs:
- get
- list
- create
- update
- delete
{
"type": "Role",
"api_version": "core/v2",
"metadata": {
"name": "default-admin"
},
"spec": {
"rules": [
{
"resources": [
"assets",
"checks",
"entities",
"events",
"filters",
"handlers",
"hooks",
"mutators",
"pipelines",
"rolebindings",
"roles",
"searches",
"silenced",
"sumo-logic-metrics-handlers",
"tcp-stream-handlers"
],
"verbs": [
"get",
"list",
"create",
"update",
"delete"
]
}
]
}
}
---
type: RoleBinding
api_version: core/v2
metadata:
name: alice-default-admin
spec:
role_ref:
name: default-admin
type: Role
subjects:
- name: alice
type: User
{
"type": "RoleBinding",
"api_version": "core/v2",
"metadata": {
"name": "alice-default-admin"
},
"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:
- Create at least one user assigned to a group.
- Create a role.
- 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
spec:
rules:
- resources:
- assets
- checks
- entities
- events
- filters
- handlers
- hooks
- mutators
- pipelines
- rolebindings
- roles
- searches
- silenced
- sumo-logic-metrics-handlers
- tcp-stream-handlers
verbs:
- get
- list
- create
- update
- delete
{
"type": "Role",
"api_version": "core/v2",
"metadata": {
"name": "default-admin"
},
"spec": {
"rules": [
{
"resources": [
"assets",
"checks",
"entities",
"events",
"filters",
"handlers",
"hooks",
"mutators",
"pipelines",
"rolebindings",
"roles",
"searches",
"silenced",
"sumo-logic-metrics-handlers",
"tcp-stream-handlers"
],
"verbs": [
"get",
"list",
"create",
"update",
"delete"
]
}
]
}
}
---
type: RoleBinding
api_version: core/v2
metadata:
name: ops-default-admin
spec:
role_ref:
name: default-admin
type: Role
subjects:
- name: ops
type: Group
{
"type": "RoleBinding",
"api_version": "core/v2",
"metadata": {
"name": "ops-default-admin"
},
"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:
- Create at least one user assigned to a group.
- Create a cluster role.
- 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
- pipelines
- rolebindings
- roles
- silenced
- cluster
- clusterrolebindings
- clusterroles
- namespaces
- users
- authproviders
- license
- sumo-logic-metrics-handlers
- tcp-stream-handlers
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",
"pipelines",
"rolebindings",
"roles",
"silenced",
"cluster",
"clusterrolebindings",
"clusterroles",
"namespaces",
"users",
"authproviders",
"license",
"sumo-logic-metrics-handlers",
"tpc-stream-handlers"
],
"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
- pipelines
- rule-templates
- searches
- secrets
- service-components
- silenced
- sumo-logic-metrics-handlers
- tcp-stream-handlers
- 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",
"pipelines",
"rule-templates",
"searches",
"secrets",
"service-components",
"silenced",
"sumo-logic-metrics-handlers",
"tcp-stream-handlers",
"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.
-
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.
-
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" ] } ] } }
-
Create a role binding in each team namespace to assign the
silencing-script
cluster role to the team’ssilencing-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 usersilencing-service-team-1
):--- type: RoleBinding api_version: core/v2 metadata: name: silencing-script-binding-team-1 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" }, "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.
User specification
Top-level attributes for user resources
api_version | |
---|---|
description | Top-level attribute that specifies the Sensu API group and version. For users in this version of Sensu, this attribute should always be core/v2 . |
required | Required for user definitions in wrapped-json or yaml format for use with sensuctl create . |
type | String |
example |
|
metadata | |
---|---|
description | Top-level collection of metadata about the user, including name . The metadata map is always at the top level of the user definition. This means that in wrapped-json and yaml formats, the metadata scope occurs outside the spec scope. Read metadata attributes for user resources for details. |
required | Required for user definitions in wrapped-json or yaml format for use with sensuctl create . |
type | Map of key-value pairs |
example |
|
spec | |
---|---|
description | Top-level map that includes the user spec attributes. |
required | Required for user definitions in wrapped-json or yaml format for use with sensuctl create . |
type | Map of key-value pairs |
example |
|
type | |
---|---|
description | Top-level attribute that specifies the sensuctl create resource type. Users should always be type User . |
required | Required for user definitions in wrapped-json or yaml format for use with sensuctl create . |
type | String |
example |
|
Metadata attributes for user resources
name | |
---|---|
description | Unique string used to identify the user. User resource names cannot contain special characters or spaces (validated with Go regex \A[\w\.\-]+\z ). Each user resource must have a unique name. |
required | true |
type | String |
example |
|
Spec attributes for user resources
disabled | |
---|---|
description | If true , the user’s account is disabled. Otherwise, false . |
required | false |
type | Boolean |
default | false |
example |
|
groups | |
---|---|
description | Groups to which the user belongs. |
required | false |
type | Array |
example |
|
password | |
---|---|
description | User’s password. Passwords must have at least eight characters.
NOTE: You only need to set either the |
required | true |
type | String |
example |
|
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 |
required | false |
type | String |
example |
|
username | |
---|---|
description | Name of the user. Cannot contain special characters. |
required | true |
type | String |
example |
|
Role and cluster role specification
Top-level attributes for role and cluster role resources
api_version | |
---|---|
description | Top-level attribute that specifies the Sensu API group and version. For role and cluster role resources in this version of Sensu, this attribute should always be core/v2 . |
required | Required for role and cluster role definitions in wrapped-json or yaml format for use with sensuctl create . |
type | String |
example |
|
metadata | |
---|---|
description | Top-level collection of metadata about the role or cluster role. The metadata map is always at the top level of the role or cluster role definition. This means that in wrapped-json and yaml formats, the metadata scope occurs outside the spec scope. Read metadata attributes for role and cluster role resources for details.
NOTE: Cluster role definitions do not include a |
required | Required for role definitions in wrapped-json or yaml format for use with sensuctl create . |
type | Map of key-value pairs |
example |
|
spec | |
---|---|
description | Top-level map that includes the role or cluster role spec attributes. |
required | Required for role or cluster role definitions in wrapped-json or yaml format for use with sensuctl create . |
type | Map of key-value pairs |
example |
|
type | |
---|---|
description | Top-level attribute that specifies the sensuctl create resource type. Roles should always be type Role . Cluster roles should always be type ClusterRole . |
required | Required for role and cluster role definitions in wrapped-json or yaml format for use with sensuctl create . |
type | String |
example (role) |
|
example (cluster role) |
|
Metadata attributes for role and cluster role resources
annotations | |
---|---|
description | Non-identifying metadata to include with observation event data that you can access with event filters. You can use annotations to add data that’s meaningful to people or external tools that interact with Sensu. In contrast to labels, you cannot use annotations in API response filtering, sensuctl response filtering, or web UI views. |
required | false |
type | Map of key-value pairs. Keys and values can be any valid UTF-8 string. |
default | null |
example |
|
created_by | |
---|---|
description | Username of the Sensu user who created or last updated the role or cluster role. Sensu automatically populates the created_by field when the role or cluster role is created or updated. |
required | false |
type | String |
example |
|
labels | |
---|---|
description | Custom attributes to include with observation event data that you can use for response and web UI view filtering. If you include labels in your event data, you can filter API responses, sensuctl responses, and web UI views based on them. In other words, labels allow you to create meaningful groupings for your data. Limit labels to metadata you need to use for response filtering. For complex, non-identifying metadata that you will not need to use in response filtering, use annotations rather than labels. |
required | false |
type | Map of key-value pairs. Keys can contain only letters, numbers, and underscores and must start with a letter. Values can be any valid UTF-8 string. |
default | null |
example |
|
name | |
---|---|
description | Unique string used to identify the role or cluster role. Role and cluster role names cannot contain special characters or spaces (validated with Go regex \A[\w\.\-]+\z ). Each role must have a unique name within its namespace. Each cluster role must have a unique name. |
required | true |
type | String |
example |
|
namespace | |
---|---|
description | Sensu RBAC namespace that the role belongs to.
NOTE: Cluster role definitions do not include a |
required | false |
type | String |
default | default |
example |
|
Spec attributes for role and cluster role resources
rules | |
---|---|
description | Rule set that the role or cluster role applies. A rule is an explicit statement that grants a particular access to a resource. Read rules attributes for more information. |
required | true |
type | Array |
example |
|
Rules attributes
resources | |
---|---|
description | Types of resources that the rule has permission to access. Read resource types to learn more about available types. |
required | true |
type | Array |
allowed values (roles) | Namespaced resource types and the special resource type * . |
allowed values (cluster roles) | Namespaced resource types, cluster-wide resource types, and the special resource type * . |
example |
|
resource_names | |
---|---|
description | Names of specific individual resources that the rule has permission to access. Resource name permissions are only taken into account for requests that use get , update , and delete verbs. |
required | false |
type | Array |
example |
|
verbs | |
---|---|
description | Type of access the rule will apply. |
required | true |
type | Array |
allowed values | get , list , create , update , delete |
example |
|
Role binding and cluster role binding specification
Top-level attributes for role binding and cluster role binding resources
api_version | |
---|---|
description | Top-level attribute that specifies the Sensu API group and version. For role binding and cluster role binding resources in this version of Sensu, this attribute should always be core/v2 . |
required | Required for role binding and cluster role binding definitions in wrapped-json or yaml format for use with sensuctl create . |
type | String |
example |
|
metadata | |
---|---|
description | Top-level collection of metadata about the role binding or cluster role binding. The metadata map is always at the top level of the role binding or cluster role binding definition. This means that in wrapped-json and yaml formats, the metadata scope occurs outside the spec scope. Read metadata attributes for role binding and cluster role binding resources for details.
NOTE: Cluster role binding definitions do not include a |
required | Required for role binding and cluster role binding definitions in wrapped-json or yaml format for use with sensuctl create . |
type | Map of key-value pairs |
example |
|
spec | |
---|---|
description | Top-level map that includes the role binding and cluster role binding spec attributes. |
required | Required for role binding or cluster role binding definitions in wrapped-json or yaml format for use with sensuctl create . |
type | Map of key-value pairs |
example (role) |
|
example (cluster role) |
|
type | |
---|---|
description | Top-level attribute that specifies the sensuctl create resource type. Role bindings should always be type RoleBinding . Cluster role bindings should always be type ClusterRoleBinding . |
required | Required for role binding and cluster role binding definitions in wrapped-json or yaml format for use with sensuctl create . |
type | String |
example (role binding) |
|
example (cluster role binding) |
|
Metadata attributes for role binding and cluster role binding resources
annotations | |
---|---|
description | Non-identifying metadata to include with observation event data that you can access with event filters. You can use annotations to add data that’s meaningful to people or external tools that interact with Sensu. In contrast to labels, you cannot use annotations in API response filtering, sensuctl response filtering, or web UI views. |
required | false |
type | Map of key-value pairs. Keys and values can be any valid UTF-8 string. |
default | null |
example |
|
created_by | |
---|---|
description | Username of the Sensu user who created or last updated the role binding or cluster role binding. Sensu automatically populates the created_by field when the role binding or cluster role binding is created or updated. |
required | false |
type | String |
example |
|
labels | |
---|---|
description | Custom attributes to include with observation event data that you can use for response and web UI view filtering. If you include labels in your event data, you can filter API responses, sensuctl responses, and web UI views based on them. In other words, labels allow you to create meaningful groupings for your data. Limit labels to metadata you need to use for response filtering. For complex, non-identifying metadata that you will not need to use in response filtering, use annotations rather than labels. |
required | false |
type | Map of key-value pairs. Keys can contain only letters, numbers, and underscores and must start with a letter. Values can be any valid UTF-8 string. |
default | null |
example |
|
name | |
---|---|
description | Unique string used to identify the role binding or cluster role binding. Role binding and cluster role binding names cannot contain special characters or spaces (validated with Go regex \A[\w\.\-]+\z ). Each role binding must have a unique name within its namespace. Each cluster role binding must have a unique name. |
required | true |
type | String |
example |
|
namespace | |
---|---|
description | Sensu RBAC namespace that the role binding belongs to.
NOTE: Cluster role binding definitions do not include a |
required | false |
type | String |
default | default |
example |
|
Spec attributes for role binding and cluster role binding resources
role_ref | |
---|---|
description | Name and type for the role or cluster role to bind to the users and groups listed in the subjects array. Read role_ref attributes for more information. |
required | true |
type | Hash |
example (role binding) |
|
example (cluster role binding) |
|
subjects | |
---|---|
description | Users and groups to bind with the role or cluster role listed in the role_ref attribute. Read subjects attributes for more information. |
required | true |
type | Array |
example |
|
role_ref
attributes
name | |
---|---|
description | Name of the role or cluster role to bind in the role binding or cluster role binding. |
required | true |
type | String |
example |
|
type | |
---|---|
description | The sensuctl create resource type for the role or cluster role. Use Role if you are binding a role. Use ClusterRole if you are binding a cluster role. |
required | true |
type | String |
example |
|
subjects
attributes
name | |
---|---|
description | Name of the user resource or group resource to bind in the role binding or cluster role binding.
NOTE: If you are using Active Directory (AD) or Lightweight Directory Access Protocol (LDAP) authentication, names of users and groups are case-sensitive. The user and group names listed in the cluster role binding configuration must exactly match the user and group names the authentication provider returns to the Sensu backend. |
required | true |
type | String |
example |
|
example with prefix |
|
type | |
---|---|
description | The sensuctl create resource type for the user or group to bind. Use User if you are binding a user. Use Group if you are binding a group. |
required | true |
type | String |
example |
|