Manage Custom Roles with Terraform

A role is a named set of permissions that you assign to organisation members. Bahriya ships four built-in system roles (Owner, Admin, Member, Viewer), and you can define your own custom roles to grant exactly the access a team needs — for example a "Deployer" who can manage containers but not billing.

Updated 5 Jul 20262 min read

A role is a named set of permissions that you assign to organisation members. Bahriya ships four built-in system roles (Owner, Admin, Member, Viewer), and you can define your own custom roles to grant exactly the access a team needs — for example a "Deployer" who can manage containers but not billing.

The bahriya_role resource manages custom role definitions as code. System roles are managed by Bahriya and cannot be created, changed, or deleted through Terraform.

Required fields

Field	Type	Description
`name`	string	Human-readable role name.
`permissions`	block list	One or more permission grants (see below).

Optional fields

Field	Type	Description
`description`	string	What the role is for.

Computed (read-only) fields

Field	Type	Description
`id`	string	UUID of the role.
`handle`	string	Machine slug, derived from the name. Immutable.
`issystem`	bool	Always `false` for roles you create.
`created` / `updated`	string	Timestamps.

The `permissions` block

Each permissions block is one grant, with three fields:

Field	Values	Description
`level`	`organisation` \| `project`	The scope the grant applies at.
`resource`	resource kind	e.g. `attachables_registries`, `deployables_container_http`, `deployables_memcached`, `billing`, `user`.
`permission`	`create` \| `read` \| `update` \| `delete`	The action allowed.

Example

A "Deployer" role that can fully manage containers in any project, read registries and secrets, but nothing else:

resource "bahriya_role" "deployer" {
  name        = "Deployer"
  description = "Manage containers; read-only on credentials."
 
  permissions {
    level      = "project"
    resource   = "deployables_container_http"
    permission = "create"
  }
  permissions {
    level      = "project"
    resource   = "deployables_container_http"
    permission = "update"
  }
  permissions {
    level      = "project"
    resource   = "deployables_container_http"
    permission = "delete"
  }
 
  permissions {
    level      = "organisation"
    resource   = "attachables_registries"
    permission = "read"
  }
  permissions {
    level      = "organisation"
    resource   = "attachables_secrets"
    permission = "read"
  }
}

Assigning the role

bahriya_role defines the role; it does not assign members to it. Assign a member to a role imperatively with the Reis CLI:

reis role:assign --user <user-id> --role deployer

See the Reis role commands for details.

Notes

Custom roles only. Trying to import and modify a system role (owner/admin/member/viewer) returns an error — those are read-only.
A role cannot be deleted while it is still assigned to members. Reassign those members first.
The handle is generated from the name and never changes, so it is safe to reference in scripts and the CLI.
Roles are organisation-scoped. The level on each grant decides whether it applies org-wide or per-project.