Manage scopes

8min
|
Terraform
Boundary

Scopes are a foundational part of Boundary. By modeling permission boundaries as a container, scopes allow users to partition resources and assign ownership of resources to principals.

There are three types of scopes within Boundary:

Global (global)
Org
Project

Note

Within the software itself and in the documentation, Boundary uses org instead of organization to remove ambiguity between different regional spellings of the word.

Scopes hierarchy:

The global scope is the outermost scope. There is only one global scope, and it cannot be deleted. It is the entry point for initial administration, setup, and management of the org scopes.
The global scope can contain multiple org scopes. Orgs are used to hold IAM-related resources and project scopes.
Each org scope can contain multiple project scopes. Projects are used to hold infrastructure-related resources.

Some resources can only be associated with a specific level of scope. For example, targets can only be created within a project, while users can be created at the global-level or an org-level. See the domain model for detailed resource-specific information.

In this tutorial, you will create two scopes: an org and a project.

All resource IDs in this tutorial are illustrations only. IDs are uniquely generated for every resource upon creation, except for the resources generated in dev mode. Be sure to use the resource IDs generated for your environment. For example, if you execute boundary users create, use the resource ID of the user printed in stdout, not the ID in the example command.

Prerequisites

To perform the tasks described in this tutorial, you need to have a Boundary environment. Refer to the Getting Started tutorial to learn about installation and Boundary's dev mode.

To complete this tutorial, you need:

A Boundary binary in your PATH. This tutorial uses the 0.8.1 version of Boundary.
Boundary must be running in dev mode.
Terraform 0.13.0 or greater provides an optional workflow for these tutorials. The binary must be available in your PATH. A Recovery Key must also be copied from the output of boundary dev. See the tutorial introduction if you do not have a recovery key.

Create an org

Start by creating an org under the global scope.

The CLI and Admin Console create administrative roles automatically when a scope is generated. This allows the user that created the scope to immediately manage it.

$ boundary authenticate password -auth-method-id ampw_1234567890 -login-name adminPlease enter the password (it will be hidden): <password> Authentication information:  Account ID:      acctpw_1234567890  Auth Method ID:  ampw_1234567890  Expiration Time: Fri, 03 Jun 2022 10:40:20 MDT  User ID:         u_1234567890 The token was successfully stored in the chosen keyring and is not displayed here.

Create a new org under the global scope named "IT_Support" with the description "IT Support Team".

$ boundary scopes create -scope-id=global -name=IT_Support -description="IT Support Team" Scope information:  Created Time:        Fri, 27 May 2022 10:40:27 MDT  Description:         IT Support Team  ID:                  o_u54jrD6ydN  Name:                IT_Support  Updated Time:        Fri, 27 May 2022 10:40:27 MDT  Version:             1   Scope (parent):    ID:                global    Name:              global    Type:              global   Authorized Actions:    no-op    read    update    delete

List the existing scopes.

$ boundary scopes list Scope information:  ID:                    o_1234567890    Version:             1    Name:                Generated org scope    Description:         Provides an initial org scope in Boundary    Authorized Actions:      no-op      read      update      delete   ID:                    o_u54jrD6ydN    Version:             1    Name:                IT_Support    Description:         IT Support Team    Authorized Actions:      no-op      read      update      delete

In this example, the generated scope ID for IT_Support is o_u54jrD6ydN. Notice that org ID starts with o_.

Copy the ID of the IT_Support org and save it as the environment variable ORG_ID.

$ export ORG_ID=<IT_Support_Org_ID>

Example:

$ export ORG_ID="o_u54jrD6ydN"

The CLI and Admin Console create administrative roles automatically when a scope is generated. This allows the user that created the scope to immediately manage it.

Log into the Boundary Admin Console at the global scope. In dev mode the Admin Console is found at http://localhost:9200. The username is admin and the password is password.
Click New button.
Enter the Name and Description for the new org you wish to create. For example, enter IT_Support in the Name field, and IT Support Team in the Description field.
Click Save. You should be automatically directed into the newly created org.

The CLI and Admin Console create administrative roles automatically when a scope is generated. This allows the user that created the scope to immediately manage it. The Boundary Terraform provider skips creation of those roles so that resources are not created outside of Terraform's management. You must explicitly define these roles in this section, and in the next section where you create a project scope.

This tutorial recommends creating a working directory to store the Terraform configuration within. Change into this directory and use it as the working directory for the remainder of these tutorials.

$ mkdir boundary-administration && cd boundary-administration/

Next, create a terraform configuration file named main.tf.

$ touch main.tf

Open main.tf in your code editor.

This tutorial uses version 1.0.7 of the Boundary provider.

Define the provider version at the top of main.tf.

terraform {  required_providers {    boundary = {      source  = "hashicorp/boundary"      version = "1.0.7"    }  }}

To allow Terraform to configure Boundary, the provider block defines the Boundary server connection details, such as the address (127.0.0.1:9200, because Boundary is running in dev mode) and the authentication details.

This configuration uses Boundary's recovery key workflow, instead of defining a username and password. This key should have been copied when boundary dev was executed. If you did not copy the key, restart boundary dev and copy its value.

Add the following provider config below the Terraform version.

provider "boundary" {  addr             = "http://127.0.0.1:9200"  recovery_kms_hcl = <<EOTkms "aead" {  purpose = "recovery"  aead_type = "aes-gcm"  key = "XGcczs8FJ7lIwd8PQJaP34go/ILiPIeMs+7anHkK+vE="  key_id = "global_recovery"}EOT}

The key in this example was generated by boundary dev. In non-dev environments, this key is defined by the user within Boundary's configuration file.

Next, define a boundary_scope resource to create a new org under the global scope named, "IT_Support" with description, "IT Support Team".

resource "boundary_scope" "org" {  scope_id                 = "global"  name                     = "IT_Support"  description              = "IT Support Team"  auto_create_default_role = true  auto_create_admin_role   = true}

Create a project

Next, create a new project named QA_Tests under the "IT_Support" scope with the description "Manage QA machines".

To create a project under the IT_Support org, execute the boundary scopes create command.

$ boundary scopes create -scope-id=$ORG_ID -name=QA_Tests -description="Manage QA machines" Scope information:  Created Time:        Fri, 27 May 2022 10:43:28 MDT  Description:         Manage QA machines  ID:                  p_oMgeFL2hP6  Name:                QA_Tests  Updated Time:        Fri, 27 May 2022 10:43:28 MDT  Version:             1   Scope (parent):    ID:                o_u54jrD6ydN    Name:              IT_Support    Parent Scope ID:   global    Type:              org   Authorized Actions:    no-op    read    update    delete

List the project under the IT_Support org to verify.

$ boundary scopes list -scope-id=$ORG_ID Scope information:  ID:                    p_oMgeFL2hP6    Version:             1    Name:                QA_Tests    Description:         Manage QA machines    Authorized Actions:      no-op      read      update      delete

In this example, the generated project ID is p_MoXk2hMkhW. Notice that project ID starts with p_.

Copy the ID of the QA_Tests project and save it as an environment variable, PROJECT_ID.

$ export PROJECT_ID=<QA_Tests_Project_ID>

Example:

$ export PROJECT_ID="p_oMgeFL2hP6"

Similar to creating a new org, define a boundary_scope resource which retrieves the parent org ID dynamically via boundary_scope.org.id.

resource "boundary_scope" "project" {  name             = "QA_Tests"  description      = "Manage QA machines"   # scope_id is taken from the org resource defined for 'IT_Support'  scope_id                 = boundary_scope.org.id  auto_create_admin_role   = true  auto_create_default_role = true}

The entire main.tf file contents are printed below for reference.

terraform {  required_providers {    boundary = {      source  = "hashicorp/boundary"      version = "1.0.7"    }  }} provider "boundary" {  addr             = "http://127.0.0.1:9200"  recovery_kms_hcl = <<EOTkms "aead" {  purpose = "recovery"  aead_type = "aes-gcm"  key = "Zg5vogpvOjhM4USNEa21f2zLiKJlWl8Ulklp29gEAcI="  key_id = "global_recovery"}EOT} resource "boundary_scope" "org" {  scope_id                 = "global"  name                     = "IT_Support"  description              = "IT Support Team"  auto_create_default_role = true  auto_create_admin_role   = true} resource "boundary_scope" "project" {  name             = "QA_Tests"  description      = "Manage QA machines"  scope_id                 = boundary_scope.org.id  auto_create_admin_role   = true  auto_create_default_role = true}

Save this file.

Next, initalize Terraform within the working directory where main.tf is located.

$ terraform init Initializing the backend... Initializing provider plugins...- Finding hashicorp/boundary versions matching "1.0.7"...- Installing hashicorp/boundary v1.0.7...- Installed hashicorp/boundary v1.0.7 (signed by HashiCorp) Terraform has created a lock file .terraform.lock.hcl to record the providerselections it made above. Include this file in your version control repositoryso that Terraform can guarantee to make the same selections by default whenyou run "terraform init" in the future. Terraform has been successfully initialized! You may now begin working with Terraform. Try running "terraform plan" to seeany changes that are required for your infrastructure. All Terraform commandsshould now work. If you ever set or change modules or backend configuration for Terraform,rerun this command to reinitialize your working directory. If you forget, othercommands will detect it and remind you to do so if necessary.

Now apply the Terraform config. Enter yes when prompted for confirmation.

$ terraform apply  Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:  + create Terraform will perform the following actions:   # boundary_scope.org will be created  + resource "boundary_scope" "org" {      + auto_create_admin_role   = true      + auto_create_default_role = true      + description              = "IT Support Team"      + id                       = (known after apply)      + name                     = "IT_Support"      + scope_id                 = "global"    }   # boundary_scope.project will be created  + resource "boundary_scope" "project" {      + auto_create_admin_role   = true      + auto_create_default_role = true      + description              = "Manage QA machines"      + id                       = (known after apply)      + name                     = "QA_Tests"      + scope_id                 = (known after apply)    } Plan: 2 to add, 0 to change, 0 to destroy. Do you want to perform these actions?  Terraform will perform the actions described above.  Only 'yes' will be accepted to approve.   Enter a value: yes boundary_scope.org: Creating...boundary_scope.org: Creation complete after 0s [id=o_DusYGH4a9K]boundary_scope.project: Creating...boundary_scope.project: Creation complete after 0s [id=p_DkX4anJefM] Apply complete! Resources: 2 added, 0 changed, 0 destroyed.

Next steps

You created a new org, IT_Support which has the QA_Tests project. Those new scopes can help create logical groupings of Boundary resources such as targets, users, groups, and roles.

You are now ready to define scope-level resources and manage them per scope. Next, the Manage Targets tutorial demonstrates adding Targets to Boundary.

Manage Boundary Community Edition

Manage targets