Skip to content

Managing roles


Roles are groups of permissions that can be assign to users in order to determine which actions they can take on Tsuru. Those roles can be created with multiples permissions and then applied to one or more users while the reach of those roles can be determined by the context attach to them. You can check the role managing options with Tsuru`s client command tsuru role


Tsuru has a fixed number of permissions that may change which releases (mostly adding new ones). Permissions in tsuru work in a hierarchical fashion and are represented using a dot notation. Granting access to a top-level permission implies access to all permissions below it.

To list all permissions available you can use Tsuru`s client and execute a tsuru permission list. It will list all the permissions available on the current installation of Tsuru

As an example, consider the following permissions:

  • app.update.env.set
  • app.update.env.unset
  • app.deploy

If an user has access only to app.update.env.set, only this specific action is available to them. However, it's also possible to grant access to the broader app.update permission which will allow users to both set and unset environment variables, but not deploy the applications. If we want to allow a user to execute all actions related to an application, the even broader permission app can be used.


When applying permissions to a user one do so in regard to a context. Each permission declares which contexts can be used and it's possible see the available contexts using the command tsuru permission-list. When a permission is assigned to a user it needs a context and a value for the chosen context. Examples of available contexts are:

  • team
  • app
  • global

If a user have the app.deploy permission for the team named myteam it means that they can only deploy applications which myteam has access. The same way, it's possible to assign the same app.deploy permission to a user with the context app for one application named myappname. This means the user can now deploy this specific application called myappname.

The global context is a special case. It's available to all permissions and means that the permission always applies. In the previous scenario, if a user have the app.deploy permission with a global context it means that they can deploy any application.

Create role

tsuru role add <ROLE-NAME> <CONTEXT>
tsuru role add app_reader_restarter team

Not possible yet

After the role is created, all wanted permissions should be added the this role

tsuru role permission add <ROLE-NAME> <PERMISSIONS>...
tsuru role permission add app_reader_restarter app.update.restart

Not possible yet

Once all the permissions are added, the role can be assign to an user/token/group and attached to one of the possible contexts

Update role

You can update roles with new permissions, context, description or change its name. To add new permissions you can just repeat the step above made during the role creation. Other changes are made with the client command tsuru role update

tsuru role update <ROLE-NAME> [-d/--description <DESCRIPTION>] [-c/--context <CONTEXT>] [-n/--name <NEW-NAME>]
tsuru role update app_reader_restarter -c app

Not possible yet

Remove role

Once a role is not needed anymore, it can be removed

tsuru role remove <ROLE-NAME>
tsuru role remove app_reader_restarter

Not possible yet