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:

  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.

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"
      }
    ]
  }
}

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:

  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
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:

  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
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:

  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
    - 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.

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

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 
name: alice
{
  "name": "alice"
}

Spec attributes for user resources

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

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"
}

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"
}
username
description Name of the user. Cannot contain special characters.
required true
type String
example 
username: alice
{
  "username": "alice"
}

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 
api_version: core/v2
{
  "api_version": "core/v2"
}
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 namespace attribute in the resource metadata.
required Required for role definitions in wrapped-json or yaml format for use with sensuctl create.
type Map of key-value pairs
example 
metadata:
  annotations:
    managed-by: prod-admin
  created_by: admin
  labels:
    environment: prod1
    region: us-west-1
    sensu.io/managed_by: sensuctl
  name: prod-user
  namespace: production
{
  "metadata": {
    "annotations": {
      "managed-by": "prod-admin"
    },
    "created_by": "admin",
    "labels": {
      "environment": "prod1",
      "region": "us-west-1",
      "sensu.io/managed_by": "sensuctl"
    },
    "name": "prod-user",
    "namespace": "production"
  }
}
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 
spec:
  rules:
  - resource_names: null
    resources:
    - checks
    - entities
    - events
    - filters
    - handlers
    - hooks
    - mutators
    - pipelines
    - searches
    - service-components
    - silenced
    - sumo-logic-metrics-handlers
    - tcp-stream-handlers
    verbs:
    - get
    - list
    - create
    - update
    - delete
{
  "spec": {
    "rules": [
      {
        "resource_names": null,
        "resources": [
          "checks",
          "entities",
          "events",
          "filters",
          "handlers",
          "hooks",
          "mutators",
          "pipelines",
          "searches",
          "service-components",
          "silenced",
          "sumo-logic-metrics-handlers",
          "tcp-stream-handlers"
        ],
        "verbs": [
          "get",
          "list",
          "create",
          "update",
          "delete"
        ]
      }
    ]
  }
}
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) 
type: Role
{
  "type": "Role"
}
example
(cluster role)		 
type: ClusterRole
{
  "type": "ClusterRole"
}

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 
annotations:
  managed-by: prod-admin
{
  "annotations": {
    "managed-by": "prod-admin"
  }
}
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 
created_by: admin
{
  "created_by": "admin"
}
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 
labels:
  environment: prod1
  region: us-west-1
  sensu.io/managed_by: sensuctl
{
  "labels": {
    "environment": "prod1",
    "region": "us-west-1",
    "sensu.io/managed_by": "sensuctl"
  }
}
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 
name: prod-user
{
  "name": "prod-user"
}
namespace
description Sensu RBAC namespace that the role belongs to.

NOTE: Cluster role definitions do not include a namespace attribute in the resource metadata.
required false
type String
default default
example 
namespace: production
{
  "namespace": "production"
}

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:
- resource_names:
  - check-cpu
  resources:
  - checks
  - entities
  - events
  - filters
  - handlers
  - hooks
  - mutators
  - pipelines
  - searches
  - service-components
  - silenced
  - sumo-logic-metrics-handlers
  - tcp-stream-handlers
  verbs:
  - get
  - list
  - create
  - update
  - delete
{
  "rules": [
    {
      "resource_names": [
        "check-cpu"
      ],
      "resources": [
        "checks",
        "entities",
        "events",
        "filters",
        "handlers",
        "hooks",
        "mutators",
        "pipelines",
        "searches",
        "service-components",
        "silenced",
        "sumo-logic-metrics-handlers",
        "tcp-stream-handlers"
      ],
      "verbs": [
        "get",
        "list",
        "create",
        "update",
        "delete"
      ]
    }
  ]
}

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 
resources:
- checks
- entities
- events
- filters
- handlers
- hooks
- mutators
- pipelines
- searches
- service-components
- silenced
- sumo-logic-metrics-handlers
- tcp-stream-handlers
{
  "resources": [
    "checks",
    "entities",
    "events",
    "filters",
    "handlers",
    "hooks",
    "mutators",
    "pipelines",
    "searches",
    "service-components",
    "silenced",
    "sumo-logic-metrics-handlers",
    "tcp-stream-handlers"
  ]
}
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 
resource_names:
- check-cpu
{
  "resource_names": [
    "check-cpu"
  ]
}
verbs
description Type of access the rule will apply.
required true
type Array
allowed values get, list, create, update, delete
example 
verbs:
- get
- list
- create
- update
- delete
{
  "verbs": [
    "get",
    "list",
    "create",
    "update",
    "delete"
  ]
}

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 
api_version: core/v2
{
  "api_version": "core/v2"
}
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 namespace attribute in the resource metadata.
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 
metadata:
  annotations:
    managed-by: prod-admin
  created_by: admin
  labels:
    environment: prod1
    region: us-west-1
    sensu.io/managed_by: sensuctl
  name: prod-user
  namespace: production
{
  "metadata": {
    "annotations": {
      "managed-by": "prod-admin"
    },
    "created_by": "admin",
    "labels": {
      "environment": "prod1",
      "region": "us-west-1",
      "sensu.io/managed_by": "sensuctl"
    },
    "name": "prod-user",
    "namespace": "production"
  }
}
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) 
spec:
  role_ref:
    name: prod-admin
    type: Role
  subjects:
  - name: oncall
    type: Group
  - name: angela
    type: User
{
  "spec": {
    "role_ref": {
      "name": "prod-admin",
      "type": "Role"
    },
    "subjects": [
      {
        "name": "oncall",
        "type": "Group"
      },
      {
        "name": "angela",
        "type": "User"
      }
    ]
  }
}
example (cluster role) 
spec:
  role_ref:
    name: global-event-reader
    type: ClusterRole
  subjects:
  - name: global-event-readers
    type: Group
  - name: angela
    type: User
{
  "spec": {
    "role_ref": {
      "name": "global-event-reader",
      "type": "ClusterRole"
    },
    "subjects": [
      {
        "name": "global-event-readers",
        "type": "Group"
      },
      {
        "name": "angela",
        "type": "User"
      }
    ]
  }
}
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) 
type: RoleBinding
{
  "type": "RoleBinding"
}
example (cluster role binding) 
type: ClusterRoleBinding
{
  "type": "ClusterRoleBinding"
}

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 
annotations:
  managed-by: prod-admin
{
  "annotations": {
    "managed-by": "prod-admin"
  }
}
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 
created_by: admin
{
  "created_by": "admin"
}
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 
labels:
  environment: prod1
  region: us-west-1
  sensu.io/managed_by: sensuctl
{
  "labels": {
    "environment": "prod1",
    "region": "us-west-1",
    "sensu.io/managed_by": "sensuctl"
  }
}
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 
name: prod-user
{
  "name": "prod-user"
}
namespace
description Sensu RBAC namespace that the role binding belongs to.

NOTE: Cluster role binding definitions do not include a namespace attribute in the resource metadata.
required false
type String
default default
example 
namespace: production
{
  "namespace": "production"
}

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) 
role_ref:
  name: prod-admin
  type: Role
{
  "role_ref": {
    "name": "prod-admin",
    "type": "Role"
  }
}
example (cluster role binding) 
role_ref:
  name: global-event-reader
  type: ClusterRole
{
  "role_ref": {
    "name": "global-event-reader",
    "type": "ClusterRole"
  }
}
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 
subjects:
- name: oncall
  type: Group
- name: angela
  type: User
{
  "subjects": [
    {
      "name": "oncall",
      "type": "Group"
    },
    {
      "name": "angela",
      "type": "User"
    }
  ]
}

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 
name: event-reader
{
  "name": "event-reader"
}
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 
type: Role
{
  "type": "Role"
}

subjects attributes

name
description Name of the user resource or group resource to bind in the role binding or cluster role binding.
required true
type String
example 
name: alice
{
  "name": "alice"
}
example with prefix 
name: ad:alice
{
  "name": "ad:alice"
}
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 
type: Group
{
  "type": "Group"
}