---
page_title: "boundary_role Resource - terraform-provider-boundary"
subcategory: ""
description: |-
  The role resource allows you to configure a Boundary role.
---

# Resource `boundary_role`

The role resource allows you to configure a Boundary role.

## Example Usage

Basic usage:

```terraform
resource "boundary_scope" "org" {
  name                     = "organization_one"
  description              = "My first scope!"
  scope_id                 = "global"
  auto_create_admin_role   = true
  auto_create_default_role = true
}

resource "boundary_role" "example" {
  name        = "My role"
  description = "My first role!"
  scope_id    = boundary_scope.org.id
}
```

Usage with a user resource:

```terraform
resource "boundary_scope" "org" {
  name                     = "organization_one"
  description              = "My first scope!"
  scope_id                 = "global"
  auto_create_admin_role   = true
  auto_create_default_role = true
}

resource "boundary_user" "foo" {
  name     = "User 1"
  scope_id = boundary_scope.org.id
}

resource "boundary_user" "bar" {
  name     = "User 2"
  scope_id = boundary_scope.org.id
}

resource "boundary_role" "example" {
  name          = "My role"
  description   = "My first role!"
  principal_ids = [boundary_user.foo.id, boundary_user.bar.id]
  scope_id      = boundary_scope.org.id
}
```

Usage with user and grants resource:

```terraform
resource "boundary_scope" "org" {
  name                     = "organization_one"
  description              = "My first scope!"
  scope_id                 = "global"
  auto_create_admin_role   = true
  auto_create_default_role = true
}

resource "boundary_user" "readonly" {
  name        = "readonly"
  description = "A readonly user"
  scope_id    = boundary_scope.org.id
}

resource "boundary_role" "readonly" {
  name          = "readonly"
  description   = "A readonly role"
  principal_ids = [boundary_user.readonly.id]
  grant_strings = ["ids=*;type=*;actions=read"]
  scope_id      = boundary_scope.org.id
}
```

Usage for a project-specific role:

```terraform
resource "boundary_scope" "org" {
  name                     = "organization_one"
  description              = "My first scope!"
  scope_id                 = "global"
  auto_create_admin_role   = true
  auto_create_default_role = true
}

resource "boundary_scope" "project" {
  name                   = "project_one"
  description            = "My first scope!"
  scope_id               = boundary_scope.org.id
  auto_create_admin_role = true
}

resource "boundary_user" "readonly" {
  name        = "readonly"
  description = "A readonly user"
  scope_id    = boundary_scope.org.id
}

resource "boundary_role" "readonly" {
  name          = "readonly"
  description   = "A readonly role"
  principal_ids = [boundary_user.readonly.id]
  grant_strings = ["ids=*;type=*;actions=read"]
  scope_id      = boundary_scope.project.id
}
```

<!-- schema generated by tfplugindocs -->
## Schema

### Required

- `scope_id` (String) The scope ID in which the resource is created. Defaults to the provider's `default_scope` if unset.

### Optional

- `description` (String) The role description.
- `grant_scope_ids` (Set of String) A list of scopes for which the grants in this role should apply, which can include the special values "this", "children", or "descendants"
- `grant_strings` (Set of String) A list of stringified grants for the role.
- `name` (String) The role name. Defaults to the resource name.
- `principal_ids` (Set of String) A list of principal (user or group) IDs to add as principals on the role.

### Read-Only

- `id` (String) The ID of the role.

## Import

Import is supported using the following syntax:

```shell
terraform import boundary_role.foo <my-id>
```