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 admin
Please 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, which you can verify by checking the name of the selected org in the upper-left corner.

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 = <<EOT
kms "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.

main.tf

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

provider "boundary" {
  addr             = "http://127.0.0.1:9200"
  recovery_kms_hcl = <<EOT
kms "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 provider
selections it made above. Include this file in your version control repository
so that Terraform can guarantee to make the same selections by default when
you run "terraform init" in the future.

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should 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, other
commands 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