Role-based access control
- Namespaces: Managing namespaces | Specification | Examples
- Resources: Namespaced resource types | Cluster-wide resource types
- Users: Managing users | Specification | Examples | Groups
- Roles and cluster roles: Managing roles | Specification | Examples
- Role bindings and cluster role bindings: Managing role bindings | Specification | Examples
- Example workflows
Sensu role-based access control (RBAC) helps different teams and projects share a Sensu instance. RBAC allows management and access of users and resources based on namespaces, groups, roles, and bindings.
- Namespaces partition resources within Sensu. Sensu entities, checks, handlers, and other namespaced resources belong to a single namespace.
- Roles create sets of permissions (get, delete, etc.) tied to resource types. Cluster roles apply permissions across namespaces and include access to cluster-wide resources like users and namespaces.
- Users represent a person or agent that interacts with Sensu. Users can belong to one or more groups.
- Role bindings assign a role to a set of users and groups within a namespace; cluster role bindings assign a cluster role to a set of users and groups cluster-wide.
Sensu access controls apply to sensuctl, the Sensu API, and the Sensu dashboard. In addition to built-in RBAC, Sensu includes commercial support for authentication using external authentication providers.
Namespaces
Namespaces help teams use different resources (entities, checks, handlers, etc.) within Sensu and impose their own controls on those resources. A Sensu instance can have multiple namespaces, each with their own set of managed resources. Resource names need to be unique within a namespace, but not across namespaces.
To create and manage namespaces, configure sensuctl as the default admin
user or create a cluster role with namespaces
permissions.
Default namespace
Every Sensu backend includes a default
namespace.
All resources created without a specified namespace are created within the default
namespace.
Viewing namespaces
You can use sensuctl to view all namespaces within Sensu:
sensuctl namespace list
NOTE: For users on supported Sensu Go distributions,sensuctl namespace list
will list only the namespaces that the current user has access to.
Creating a namespace
You can use sensuctl to create a namespace.
For example, the following command creates a namespace called production
:
sensuctl namespace create production
Namespace names can contain alphanumeric characters and hyphens, but must begin and end with an alphanumeric character.
Managing namespaces
You can use sensuctl to view, create, and delete namespaces.
To delete a namespace:
sensuctl namespace delete [NAMESPACE-NAME]
To get help managing namespaces with sensuctl:
sensuctl namespace help
Assigning a resource to a namespace
You can assign a resource to a namespace in the resource definition. Only resources belonging to a namespaced resource type (like checks, filters, and handlers) can be assigned to a namespace.
For example, to assign a check called check-cpu
to the production
namespace, include the namespace
attribute in the check definition:
type: CheckConfig
api_version: core/v2
metadata:
name: check-cpu
namespace: production
spec:
check_hooks: null
command: check-cpu.sh -w 75 -c 90
handlers:
- slack
interval: 30
subscriptions:
- system
timeout: 0
ttl: 0
{
"type": "CheckConfig",
"api_version": "core/v2",
"metadata": {
"name": "check-cpu",
"namespace": "production"
},
"spec": {
"check_hooks": null,
"command": "check-cpu.sh -w 75 -c 90",
"handlers": ["slack"],
"interval": 30,
"subscriptions": ["system"],
"timeout": 0,
"ttl": 0
}
}
See the reference docs for the corresponding resource type to create resource definitions.
PRO TIP: By omitting the namespace
attribute from resource definitions, you can use the senusctl create --namespace
flag to specify the namespace for a group of resources at the time of creation, allowing you to replicate resources across namespaces without manual editing. See the sensuctl reference for more information.
Namespace specification
Attributes
name | |
---|---|
description | The name of the namespace. Names can contain alphanumeric characters and hyphens, but must begin and end with an alphanumeric character. |
required | true |
type | String |
example |
|
Namespace example
The following examples are in yml
and wrapped-json
formats for use with sensuctl create
.
type: Namespace
api_version: core/v2
metadata: {}
spec:
name: default
{
"type": "Namespace",
"api_version": "core/v2",
"metadata": {},
"spec": {
"name": "default"
}
}
Resources
Permissions within Sensu are scoped to resource types, like checks, handlers, and users. You can use resource types to configure permissions in Sensu roles and cluster roles.
Namespaced resource types
Namespaced resources must belong to a single namespace and can be accessed by roles and cluster roles.
Type | Description |
---|---|
assets |
Asset resources within a namespace |
checks |
Check resources within a namespace |
entities |
Entity resources within a namespace |
events |
Event resources within a namespace |
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 |
silenced |
Silencing resources within a namespace |
Cluster-wide resource types
Cluster-wide resources cannot be assigned to a namespace and can only be accessed by cluster roles.
Type | Description |
---|---|
cluster |
Sensu clusters running multiple Sensu backends |
clusterrolebindings |
Cluster-wide role assigners |
clusterroles |
Cluster-wide permission sets |
etcd-replicators |
Mirror RBAC resource changes to follower clusters |
namespaces |
Resource partitions within a Sensu instance |
users |
People or agents interacting with Sensu |
authproviders |
Authentication provider configuration (commercial feature) |
license |
Sensu commercial license |
Special resource types
Special resources types can be accessed by both roles and cluster roles.
Type | Description |
---|---|
* |
All resources within Sensu. The * type takes precedence over other rules within the same role. If you wish to deny a certain type, you can’t use the * type and must explicitly allow every type required. When applied to a role, the * type applies only to namespaced resource types. When applied to a cluster role, the * type applies to both namespaced resource types and cluster-wide resource types. |
Users
A user represents a person or an agent which interacts with Sensu. Users and groups can be assigned one or more roles and inherit all permissions from each role assigned to them.
You can use your Sensu username and password to configure sensuctl or log in to the dashboard.
Default user
By default, Sensu includes a global admin
user that you can use to manage Sensu and create new users.
attribute | value |
---|---|
username | admin |
password | P@ssw0rd! |
groups | cluster-admins |
cluster role | cluster-admin |
cluster role binding | cluster-admin |
We strongly recommended changing the default password for the admin user immediately.
Once authenticated, you can change the password using the change-password
command.
sensuctl user change-password
Sensu also includes an agent
user that is used internally by the Sensu agent.
You can configure an agent’s user credentials using the user
and password
agent configuration flags.
Viewing users
You can use sensuctl to see a list of all users within Sensu.
The following example returns a list of users in yaml
format for use with sensuctl create
.
sensuctl user list --format yaml
Creating a user
You can use sensuctl to create a user.
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
Assigning user permissions
To assign permissions to a user:
- Create the user.
- Create a role or (for cluster-wide access) a cluster role.
- Create a role binding (or cluster role binding) to assign the role to the user.
Managing users
To test the password for a user:
sensuctl user test-creds USERNAME --password 'password'
An empty response indicates valid credentials; a request-unauthorized response indicates invalid credentials.
To change the password for a user:
sensuctl user change-password USERNAME --current-password CURRENT_PASSWORD --new-password NEW_PASSWORD
To disable a user:
sensuctl user disable USERNAME
To re-enable a disabled user:
sensuctl user reinstate USERNAME
User specification
Attributes
username | |
---|---|
description | The name of the user. Cannot contain special characters. |
required | true |
type | String |
example |
|
password | |
---|---|
description | The user’s password. Passwords must have at least eight characters. |
required | true |
type | String |
example |
|
groups | |
---|---|
description | Groups to which the user belongs. |
required | false |
type | Array |
example |
|
disabled | |
---|---|
description | The state of the user’s account. |
required | false |
type | Boolean |
default | false |
example |
|
User example
The following examples are in yml
and wrapped-json
formats for use with sensuctl create
.
type: User
api_version: core/v2
metadata: {}
spec:
disabled: false
groups:
- ops
- dev
password: P@ssw0rd!
username: alice
{
"type": "User",
"api_version": "core/v2",
"metadata": {},
"spec": {
"username": "alice",
"password": "P@ssw0rd!",
"disabled": false,
"groups": ["ops", "dev"]
}
}
Groups
A group is a set of users within Sensu. Groups can be assigned one or more roles and inherit all permissions from each role assigned to them. Users can be assigned to one or more groups. Groups are not a resource type within Sensu; you can create and manage groups only within user definitions.
Default group
Sensu includes a default cluster-admins
group that contains the default admin
user and a system:agents
group used internally by Sensu agents.
Assigning a user to a group
Groups are created and managed within user definitions. You can use sensuctl to add users to groups.
To add a user to a group:
sensuctl user add-group USERNAME GROUP
To set the groups for a user:
sensuctl user set-groups USERNAME GROUP1[,GROUP2, ...[,GROUPN]]
Removing a user from a group
You can use sensuctl to remove users from groups.
To remove a user from a group:
sensuctl user remove-group USERNAME GROUP
To remove a user from all groups:
sensuctl user remove-groups USERNAME
Roles and cluster roles
A role is a set of permissions controlling access to Sensu resources. Roles specify permissions for resources within a namespace while cluster roles can include permissions for cluster-wide resources. You can use role bindings to assign roles to user and groups. To avoid re-creating commonly used roles in each namespace, create a cluster role and use a role binding (not a cluster role binding) to restrict permissions within a specific namespace.
To create and manage roles cluster-wide, configure sensuctl as the default admin
user or create a cluster role with roles
permissions.
To create and manage roles within a namespace, create a role with roles
permissions within that namespace.
Cluster roles
Cluster roles can specify access permissions for cluster-wide resources like users and namespaces as well as namespaced resources like checks and handlers. They can also be used to grant access to namespaced resources across all namespaces (needed to run sensuctl check list --all-namespaces
, for example) when used in conjunction with cluster role bindings.
Cluster roles use the same specification as roles and can be managed using the same sensuctl commands with cluster-role
substituted for role
.
To create and manage cluster roles, configure sensuctl as the default admin
user or create a cluster role with permissions for clusterroles
.
Default roles
Every Sensu backend includes:
Role name | Type | Description |
---|---|---|
cluster-admin |
ClusterRole |
Full access to all resource types across namespaces, including access to cluster-wide resource types. |
admin |
ClusterRole |
Full access to all resource types. You can apply this cluster role within a namespace by using a role binding (not a cluster role binding). |
edit |
ClusterRole |
Read and write access to most resources with the exception of roles and role bindings. You can apply this cluster role within a namespace by using a role binding (not a cluster role binding). |
view |
ClusterRole |
Read-only permission to most resource types with the exception of roles and role bindings. You can apply this cluster role within a namespace by using a role binding (not a cluster role binding). |
system:agent |
ClusterRole |
Used internally by Sensu agents. You can configure an agent’s user credentials using the user and password agent configuration flags. |
Viewing roles
You can use sensuctl to see a list of roles within Sensu:
sensuctl role list
To see the permissions and scope for a specific role:
sensuctl role info admin
To view cluster roles, use the cluster-role
command:
sensuctl cluster-role list
Creating a role
You can use sensuctl to create a role. For example, the following command creates an admin role restricted to the production namespace.
sensuctl role create prod-admin --verb get,list,create,update,delete --resource * --namespace production
Once you’ve create the 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 the following role binding.
sensuctl role-binding create prod-admin-oncall --role=prod-admin --group=oncall
Creating a cluster-wide role
You can use sensuctl to create a cluster role. For example, the following command creates a global event reader role that can read only events across all namespaces within Sensu.
sensuctl cluster-role create global-event-reader --verb get,list --resource events
Managing roles
You can use sensuctl to view, create, edit, and delete roles.
To use any of these commands with cluster roles, substitute the cluster-role
command for the role
command.
To edit a role:
sensuctl edit roles [ROLE-NAME] [flags]
To delete a role:
sensuctl role delete [ROLE-NAME]
To get help managing roles with sensuctl:
sensuctl role help
Role and cluster role specification
Role attributes
name | |
---|---|
description | Name of the role |
required | true |
type | String |
example |
|
namespace | |
---|---|
description | Namespace the role is restricted to. This attribute is not available for cluster roles. |
required | false |
type | String |
example |
|
rules | |
---|---|
description | The rulesets that a role applies. |
required | true |
type | Array |
example |
|
Rule attributes
A rule is an explicit statement which grants a particular permission to a resource.
verbs | |
---|---|
description | The permissions to be applied by the rule: get , list , create , update , or delete . |
required | true |
type | Array |
example |
|
resources | |
---|---|
description | The type of resource that the rule has permission to access. Roles can only access namespaced resource types while cluster roles can access namespaced and cluster-wide resource types. See resource types for available types. |
required | true |
type | Array |
example |
|
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 |
|
Role example
The following examples are in yml
and wrapped-json
formats for use with sensuctl create
.
type: Role
api_version: core/v2
metadata:
name: namespaced-resources-all-verbs
namespace: default
spec:
rules:
- resource_names: []
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",
"namespace": "default"
},
"spec": {
"rules": [
{
"resource_names": [],
"resources": [
"assets", "checks", "entities", "events", "filters", "handlers",
"hooks", "mutators", "rolebindings", "roles", "silenced"
],
"verbs": ["get", "list", "create", "update", "delete"]
}
]
}
}
Cluster role example
The following examples are in yml
and wrapped-json
formats for use with sensuctl create
.
type: ClusterRole
api_version: core/v2
metadata:
name: all-resources-all-verbs
spec:
rules:
- resource_names: []
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": [
{
"resource_names": [],
"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"]
}
]
}
}
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.
To create and manage role bindings within a namespace, create a role with rolebindings
permissions within that namespace, and log in by configuring sensuctl.
Cluster role bindings
Cluster role bindings can assign a cluster role to users and groups.
Cluster role bindings use the same specification as role bindings and can be managed using the same sensuctl commands with cluster-role-binding
substituted for role-binding
.
To create and manage cluster role bindings, configure sensuctl as the default admin
user or create a cluster role with permissions for clusterrolebindings
.
Viewing role bindings
You can use sensuctl to see a list of role bindings within Sensu:
sensuctl role-binding list
To see the details for a specific role binding:
sensuctl role-binding info [BINDING-NAME]
To see a list of cluster role bindings:
sensuctl cluster-role-binding list
Creating a role binding
You can use sensuctl to see a create a role binding that assigns a role:
sensuctl role-binding create [NAME] --role=NAME [--user=username] [--group=groupname]
Or a role binding that assigns a cluster role:
sensuctl role-binding create [NAME] --cluster-role=NAME [--user=username] [--group=groupname]
To create a cluster role binding:
sensuctl cluster-role-binding create [NAME] --cluster-role=NAME [--user=username] [--group=groupname]
Managing role bindings
You can use sensuctl to see a list, create, and delete role bindings and cluster role bindings.
To use any of these commands with cluster roles, substitute the cluster-role-binding
command for the role-binding
command.
To delete a role binding:
sensuctl role-binding delete [ROLE-NAME]
To get help managing role bindings with sensuctl:
sensuctl role-binding help
Role binding and cluster role binding specification
roleRef | |
---|---|
description | References a role in the current namespace or a cluster role. |
required | true |
type | Hash |
example |
|
subjects | |
---|---|
description | The users or groups being assigned. |
required | true |
type | Array |
example |
|
roleRef
specification
type | |
---|---|
description | Role for a role binding or ClusterRole for a cluster role binding. |
required | true |
type | String |
example |
|
name | |
---|---|
description | The name of the role or cluster role being assigned. |
required | true |
type | String |
example |
|
subjects
specification
type | |
---|---|
description | User for assigning a user or Group for assigning a group. |
required | true |
type | String |
example |
|
name | |
---|---|
description | Username or group name. |
required | true |
type | String |
example |
|
example with prefix |
|
Role binding example
The following examples are in yml
and wrapped-json
formats for use with sensuctl create
.
type: RoleBinding
api_version: core/v2
metadata:
name: event-reader-binding
namespace: default
spec:
role_ref:
name: event-reader
type: Role
subjects:
- name: bob
type: User
{
"type": "RoleBinding",
"api_version": "core/v2",
"metadata": {
"name": "event-reader-binding",
"namespace": "default"
},
"spec": {
"role_ref": {
"name": "event-reader",
"type": "Role"
},
"subjects": [
{
"name": "bob",
"type": "User"
}
]
}
}
Cluster role binding example
The following examples are in yml
and wrapped-json
formats for use with sensuctl create
.
type: ClusterRoleBinding
api_version: core/v2
metadata:
name: cluster-admin
spec:
role_ref:
name: cluster-admin
type: ClusterRole
subjects:
- name: cluster-admins
type: Group
{
"type": "ClusterRoleBinding",
"api_version": "core/v2",
"metadata": {
"name": "cluster-admin"
},
"spec": {
"role_ref": {
"name": "cluster-admin",
"type": "ClusterRole"
},
"subjects": [
{
"name": "cluster-admins",
"type": "Group"
}
]
}
}
Role and role binding examples
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": [
{
"resource_names": [],
"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"
}
]
}
}
Role and role binding examples with a group prefix
In the following code example, if a groups prefix of ad
is configured for Active Directory authentication, this 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": [
{
"resource_names": [],
"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"
}
]
}
}
Example workflows
- Assigning user permissions within a namespace
- Assigning group permissions within a namespace
- Assigning group permissions across all namespaces
Assigning 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"
}
}
{
"type": "Role",
"api_version": "core/v2",
"metadata": {
"name": "default-admin",
"namespace": "default"
},
"spec": {
"rules": [
{
"resource_names": [],
"resources": [
"assets", "checks", "entities", "events", "filters", "handlers",
"hooks", "mutators", "rolebindings", "roles", "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"
}
]
}
}
Assigning group permissions within a namespace
To assign permissions to group of users:
- Create at least once 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"
}
}
{
"type": "Role",
"api_version": "core/v2",
"metadata": {
"name": "default-admin",
"namespace": "default"
},
"spec": {
"rules": [
{
"resource_names": [],
"resources": [
"assets", "checks", "entities", "events", "filters", "handlers",
"hooks", "mutators", "rolebindings", "roles", "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"
}
]
}
}
PRO TIP: To avoid re-creating commonly used roles in each namespace, create a cluster role and use a role binding to restrict permissions within a specific namespace.
Assigning group permissions across all namespaces
To assign cluster-wide permissions to group of users:
- Create at least once 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",
"groups": ["ops"]
}
}
{
"type": "ClusterRole",
"api_version": "core/v2",
"metadata": {
"name": "default-admin"
},
"spec": {
"rules": [
{
"resource_names": [],
"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"
}
]
}
}