Common workflows for managing targets, identities, and sessions within Boundary.

Boundary Resource Management Workflows

Introduction to Boundary common workflow tutorials.

Introduction

Scopes are a fundamental part of Boundary which allow users to partition resources and assign ownership.

Manage Scopes

Configure targets to define an endpoint with a default port and protocol to establish a session.

Manage Targets

Define users and groups to assign role-based access controls.

Manage Users and Groups

Define roles to manage the permissions given to principals (users and groups).

Manage Roles and Permissions

Sessions are Boundary resources created when connecting to a target.

Manage Sessions

Learn the standard operational tasks to manage and configure your Boundary environment.

Common Administration Workflows

Instructions to configure Open-ID Connect (OIDC) authentication methods with 
Boundary, such as Auth0, Okta or Azure Active Directory.

OIDC Authentication

Instructions to configure Open-ID Connect (OIDC) Managed Groups using Identity 
Providers (IdP) like Auth0, Okta or Azure Active Directory.

Manage OIDC IdP Groups

Instructions to integrate Vault and Boundary in dev mode to enable credential 
brokering.

Vault Credential Brokering Quickstart

Instructions to configure dynamic host catalogs using cloud providers like  Microsoft Azure and Amazon Web Services (AWS).

Dynamic Host Catalogs

Instructions to deploy a Boundary environment and configure target-aware workers 
and query targets after applying worker filters.

Target-Aware Workers

Step-by-step instructions to successfully upgrade Boundary to its
latest version, including database backup and data migration.

Upgrade and Database Migration

Quick start with a new identity-based access management tool.

Getting Started

What is Boundary and what security challenge it solves?

Introduction to Boundary

Visit the Boundary downloads page and download the appropriate installer or package for your platform.

Install Boundary

Start and authenticate to a local Boundary dev environment.

Start a Development Environment

Explore the Boundary admin console to manage resources.

Admin Console

After starting Boundary in dev mode and logging in, you can connect to your first target.

Connect to Your First Target

Install the Boundary Desktop app and connect to a running controller instance.

Install Boundary Desktop

Configure your Boundary environment using Terraform to codify the initial setup to make the process repeatable.

Configure Boundary using Terraform

Resources and further tracks now that you're confident using Boundary.

Next Steps

Use Terraform with other Hashicorp products including Vault, Boundary, Consul, Packer, and Hashicorp Cloud Platform.

HashiCorp Products - Better Together

Configure the AWS Secrets Engine in Vault through Terraform, then use the short-lived, Vault-generated, dynamic secrets to provision EC2 instances

Inject Secrets into Terraform Using the Vault Provider

Dynamically generate, manage, and revoke credentials for Terraform Cloud (TFC)
and Terraform Enterprise (TFE).

Terraform Cloud Secrets Engine

Use HashiCorp Terraform's Vault provider to codify Vault management to
increase repeatability while reducing human errors.

Codify Management of Vault Using Terraform

Codify Management of Vault Enterprise Using Terraform

This tutorial discusses the concepts necessary to help users
understand Vault's AppRole authentication pattern and how to use it to
securely introduce a Vault authentication token to a target server,
application, or container.

AppRole With Terraform & Chef

Automate HashiCorp Cloud Platform (HCP) Vault managed service deployment on AWS using the Terraform Vault provider.

Deploy HCP Vault with Terraform

Deploy a Consul-backed Vault cluster on Kubernetes, by linking Terraform Cloud workspaces with run triggers. Share Kubernetes cluster credentials between workspaces within an organization using data resources.

Deploy Consul and Vault on Kubernetes with Run Triggers

Automate updates to network infrastructure including dynamic load balancing and firewall rules with Consul-Terraform-Sync.

Network Infrastructure Automation with Consul-Terraform-Sync Intro

Discover Consul-Terraform-Sync different run modes and inspect task execution status using REST API.

Consul-Terraform-Sync Run Modes and Status Inspection

Register external services with Consul using the Terraform Consul provider.

Use Terraform to Register External Services

Automate the deployment of a Consul managed service on AWS using the Terraform HashiCorp Cloud Platform (HCP) Consul provider.

Deploy HCP Consul with Terraform

Create an image with Packer, containing SSH keys, a new user, and a demo webapp, and deploy it with Terraform.

Provision Infrastructure with Packer

Configure AWS application load balancers to release an application in a rolling upgrade with near-zero downtime. Incrementally promote a new canary application version to production by building a feature toggle with Terraform.

Use Application Load Balancers for Blue-Green and Canary Deployments

Use Terraform to interact with security tooling like HashiCorp Vault and Boundary. Manage Vault and Vault Enterprise. Configure Vault to use AppRole with Chef. Deploy Consul-backed Vault on Kubernetes.

Interact with Security tools

Learn about identity-based secure access management with Boundary.


Boundary provides a dev mode to enable quick testing and exploration. Dev mode
provides admin credentials for password authentication.

In this tutorial, you will start Boundary in dev mode and authenticate as the
admin user.

## Prerequisites

1. [Docker](https://docs.docker.com/get-docker/) is installed
1. A route to download the [Postgres Docker image](https://hub.docker.com/_/postgres) image or a local image cached
1. A [Boundary binary](https://www.boundaryproject.io/downloads) in your `PATH`

> **NOTE:** An interactive tutorial is also available to demonstrate the basic
> working of Boundary. Click the **Show Terminal** button to start.

<LabToggleButton />

## Start a dev environment

A deployment of a highly available (HA) Boundary service requires multiple
**controllers** and **workers** to construct a cluster.

![Boundary components](/img/boundary/boundary-components-min.png)

- **Controllers** are responsible for understanding configuration,
  authenticating and authorizing users, and serving user API requests (e.g. to
  initiate a session).

- Boundary clusters require an accessible **key management service** (KMS) and
  **database** shared by controllers. Boundary's database maintains the state of
  Boundary's resources, identities, and access policies. Boundary's KMS is
  customer-defined and serves as Boundary's root-of-trust for at-rest and
  in-transit encryption.

- **Workers** are responsible for the actual session recording/proxying
  capability and other tasks that involve storage.

Dev mode brings up a fully functioning instance of Boundary which includes:

- A controller server
- A worker server
- A Postgres database

These components are ephemeral; therefore, data is not persisted and convenient
for quick testing.

!> Dev mode is not suitable for production environments.

Check the help message for `boundary dev` command.

```shell-session
$ boundary dev -h
```

There are optional flags available to configure Boundary environment through the
command line.

<CodeBlockConfig hideClipboard>

```shell-session
Command Options:

  -api-listen-address=<string>
      Address to bind to for controller "api" purpose. This can also be
      specified via the BOUNDARY_DEV_CONTROLLER_API_LISTEN_ADDRESS environment
      variable.

  -cluster-listen-address=<string>
      Address to bind to for controller "cluster" purpose. This can also
      be specified via the BOUNDARY_DEV_CONTROLLER_CLUSTER_LISTEN_ADDRESS
      environment variable.

  -combine-logs
      If set, both startup information and logs will be sent to stdout. If not
      set (the default), startup information will go to stdout and logs will
      be sent to stderr. The default is false.

  # ...snip...
```

</CodeBlockConfig>

Start Boundary in development mode.

```shell-session
$ boundary dev

==> Boundary server configuration:

        [Controller] AEAD Key Bytes: kNN1tkw9/umvdErDRcOBf8lUZ5JBktLANvc2HOR6yDU=
          [Recovery] AEAD Key Bytes: jWXmQsLNAt9le4EOPL0zlxqwVUOpBIG4T0sKOcIbsvI=
       [Worker-Auth] AEAD Key Bytes: DYI2kzy0HYXpwpk8M4BHHVKE11Ay5YV76fvAknRcE9s=
               [Recovery] AEAD Type: aes-gcm
                   [Root] AEAD Type: aes-gcm
            [Worker-Auth] AEAD Type: aes-gcm
                                Cgo: disabled
     Controller Public Cluster Addr: 127.0.0.1:9201
             Dev Database Container: jolly_goldstine
                   Dev Database Url: postgres://postgres:password@localhost:55001/boundary?sslmode=disable
         Generated Admin Login Name: admin
           Generated Admin Password: password
          Generated Host Catalog Id: hcst_1234567890
                  Generated Host Id: hst_1234567890
              Generated Host Set Id: hsst_1234567890
      Generated Oidc Auth Method Id: amoidc_1234567890
             Generated Org Scope Id: o_1234567890
  Generated Password Auth Method Id: ampw_1234567890
         Generated Project Scope Id: p_1234567890
                Generated Target Id: ttcp_1234567890
  Generated Unprivileged Login Name: user
    Generated Unprivileged Password: password
                         Listener 1: tcp (addr: "127.0.0.1:9200", cors_allowed_headers: "[]", cors_allowed_origins: "[*]", cors_enabled: "true", max_request_duration: "1m30s", purpose: "api")
                         Listener 2: tcp (addr: "127.0.0.1:9201", max_request_duration: "1m30s", purpose: "cluster")
                         Listener 3: tcp (addr: "127.0.0.1:9202", max_request_duration: "1m30s", purpose: "proxy")
                          Log Level: info
                              Mlock: supported: false, enabled: false
                            Version: Boundary v0.7.1
                        Version Sha: abd695e5bc42d01e4412bf6c76211c3fc93a93d7
           Worker Public Proxy Addr: 127.0.0.1:9202

==> Boundary server started! Log data will stream in below:

{
  "id": "qqVn6GnPe3",
  "source": "https://hashicorp.com/boundary/dev-controller/boundary-dev",
  "specversion": "1.0",
  "type": "system",
  "data": {
    "version": "v0.1",
    "op": "worker.(Worker).createClientConn",
    "data": {
      "address": "127.0.0.1:9201",
      "msg": "connected to controller"
    }
  },
  "datacontentype": "text/plain",
  "time": "2021-12-06T11:18:33.041494-07:00"
}
{
  "id": "HXvjcn1uZ1",
  "source": "https://hashicorp.com/boundary/dev-controller/boundary-dev",
  "specversion": "1.0",
  "type": "system",
  "data": {
    "version": "v0.1",
    "op": "controller.(interceptingListener).Accept",
    "data": {
      "msg": "worker successfully authed",
      "name": "dev-worker"
    }
  },
  "datacontentype": "text/plain",
  "time": "2021-12-06T11:18:33.058218-07:00"
}
```

<Accordion heading='Troubleshooting "Error creating dev database container" on Windows' collapse>


!> On Windows systems you may encounter the following error when running
`boundary dev`:

<CodeBlockConfig hideClipboard>

```shell-session
$ boundary dev

Error creating dev database container: unable to start dev database with dialect postgres: could not start resource: : Post "http://localhost:2375/images/create?fromImage=postgres&tag=12": dial tcp [::1]:2375: connectex: No connection could be made because the target machine actively refused it.
```

</CodeBlockConfig>

!> If the error is similar to the one printed above, the Docker daemon may need
to be exposed on port 2375 without TLS.

Open Docker Desktop, and navigate to the **Settings** panel by clicking on the gear
icon at the top-right of the screen.

Under **General** settings, click the checkbox next to _Expose deamon on
tcp://localhost:2375 without TLS_ to enable the setting. Then click **Apply &
Restart** to restart Docker Desktop. The screenshot below shows the setting that
should be enabled.

![](/img/boundary/boundary-docker-expose-daemon-0.png)

After Docker Desktop restarts, attempt running `boundary dev` again.

</Accordion>


Boundary starts in dev mode with default authentication credentials and
a set of pre-defined [resources](https://boundaryproject.io/docs/concepts/domain-model).

These admin credentials enable you to log in the Boundary console.

- Generated Auth Method Id: `ampw_1234567890`
- Generated Auth Method Login Name: `admin`
- Generated Auth Method Password: `password`

-> The default login name and password can be overwritten with `-login-name` and
`-password` flags (e.g. `boundary dev -login-name="dev-admin" -password="p@ssw0rd"`).

## Login to the Boundary console

You can authenticate to the Boundary console via the Admin console or the CLI.

<Tabs>
<Tab heading="Admin console">


1. In a browser window, navigate to the Boundary Admin console at `http://127.0.0.1:9200`

   This launches the Boundary Admin console.

   ![](/img/boundary/boundary-ui-login.png)

1. Enter `admin` in the **Username** field.

   This is the _Generated Auth Method Login Name_.

1. Enter `password` in the **Password** field.

   This is the _Generated Auth Method Password_.

1. Click **Authenticate**.

   You are presented with the _global_ scope, which contains the _Generated org scope_
   with the ID `o_1234567890`.

   ![Organizations](/img/boundary/boundary-ui-org.png)

</Tab>


<Tab heading="CLI command">


Display the help message for `boundary authenticate` command.

```shell-session
$ boundary authenticate help

Usage: boundary authenticate [sub command] [options] [args]

  This command authenticates the Boundary commandline client using a specified auth method. Examples:

    Authenticate with password auth method:

      $ boundary authenticate password -auth-method-id ampw_1234567890 -login-name foo -password "bar"

  Please see the auth method subcommand help for detailed usage information.

Subcommands:
    password    Invoke the password auth method to authenticate with Boundary
```

The CLI supports password authentication.

Authenticate with the password method using `auth-method-id`, `login-name`, and
`password` options.

```shell-session
$ boundary authenticate password \
    -auth-method-id=ampw_1234567890 \
    -login-name=admin \
    -password=password
```

- The `auth-method-id` is the Generated Auth Method Id: `ampw_1234567890`
- The `login-name` is the Generated Auth Method Login Name: `admin`
- The `password` is the Generated Auth Method Password: `password`

**Example output:**

<CodeBlockConfig hideClipboard>

```shell-session
Authentication information:
  Account ID:      acctpw_1234567890
  Auth Method ID:  ampw_1234567890
  Expiration Time: Mon, 13 Dec 2021 11:20:22 MST
  User ID:         u_1234567890

The token was successfully stored in the chosen keyring and is not displayed here.
```

</CodeBlockConfig>

The login saves a token to the KMS running on the system. Future requests use
this token to authenticate until it expires.

</Tab>
</Tabs>


## Troubleshooting

Boundary clusters require an accessible **key management service** (KMS). An
error may occur if this service is not running.

-> If you are having problems logging in with `boundary authenticate`,
especially on Unix-like operating systems other than MacOS, you may be having
problems with your local key store. See the [Run and Login to
Boundary](https://www.boundaryproject.io/docs/getting-started/run-and-login)
page in Boundary's documentation for more details.

Click on the error message below for step-by-step solutions to continue the
Getting Started tutorials.

<Accordion heading="ERROR MESSAGE: Error reading auth token from system
credential store" collapse="true">


In a Unix shell this error implies that the freedesktop.org Secret Service
implementation is not available. To fix this issue you can either bypass the
keyring or enable the system KMS.

### Method 1: Bypass the keyring

The CLI can bypass the operating system's keyring manager by overriding the
keyring type and managing the token in the environment variable.

Set the `BOUNDARY_TOKEN` environment variable to the authentication token.

```shell-session
$ export BOUNDARY_TOKEN=$(boundary authenticate password \
  -auth-method-id=ampw_1234567890 \
  -login-name=admin \
  -password=password \
  -keyring-type=none \
  -format=json | jq -r ".item.attributes.token")
```

The keyring is bypassed by setting `keyring-type` to disabled (`none`). The
results are formatted to json `-format=json`, and parsed by `jq` for the `token`
value.

### Method 2: Enable the system KMS

You can fix this error by installing the `dbus-x11` and `gnome-keyring` packages
and manually invoking the keyring daemon.

On Ubuntu, install the `dbus-x11` and `gnome-keyring` packages.

```shell-session
$ sudo apt install dbus-x11 gnome-keyring
```

Create the variable `KEYRING_PASSWORD` with a password.

```shell-session
$ KEYRING_PASSWORD="FOOBAR\n"
```

~> You can prevent the password from being captured on the command line by
running the `gnome-keyring-daemon` command directly and entering in the password
when requested, followed by a newline (return) and an EOF (`Ctrl+D`).

Substitute `FOOBAR` with a password of your choice. Leave the `\n`.

Create a default keyring and unlock it with a password.

```shell-session
$ eval "$(printf '$KEYRING_PASSWORD' | gnome-keyring-daemon --unlock)"
```

Connect to the keyring daemon and initialize it with the same password.

```shell-session
$ eval "$(printf 'KEYRING_PASSWORD' | gnome-keyring-daemon --start)"
```

Run this in any shell where the Boundary CLI is invoked.

</Accordion>


## Next steps

You started Boundary in dev mode and authenticated as the admin user. Next you
will manage resources using the [Boundary admin
console](/tutorials/boundary/getting-started-console).



Boundary must first be installed on your machine. Boundary is available as source
code, as a pre-compiled binary, or in packaged formats.

This tutorial will not cover how to compile Boundary from source, but compiling from
source is covered in the [README](https://github.com/hashicorp/boundary#build-and-start-boundary-in-dev-mode) for those who
want to be sure they're compiling source they trust into the final binary.

<Tabs>
<Tab heading="Manual">

To install Boundary, find the [appropriate
package](https://www.boundaryproject.io/downloads) for your system and
download it. Boundary is packaged as a zip archive.

After downloading Boundary, unzip the package. Boundary runs as a single binary
named `boundary`. Make sure that the `boundary` binary is available on your
`PATH`. You can check the locations available on your path by running this
command.

```shell-session
$ echo $PATH
```

**Example output:**

```shell-session hideClipboard
/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
```

The output is a list of locations separated by colons. You can make Boundary
available by moving the binary to one of the listed locations, or by adding
Boundary's location to your `PATH`.

-> **Tip (Linux-based or Mac):** Permanently add a new location to your path by
editing your shell's settings file (usually called something like `~/.bashrc`,
where the part of the file name after the `.` and before `rc` is the name of
your shell). In that file you will see a line that starts with `export PATH=`,
followed by a colon-separated list of locations. Add the location of the Boundary
binary to that list and save the file. Then reload your shell's configuration
with the command `source ~/.bashrc`, replacing `bash` with the name of your
shell.

-> **Tip (Windows):** Add a location to your path via the GUI by navigating to
`Environment Variables` in your system settings, and looking for the variable
called `PATH`. You will see a semicolon-separated list of locations. Add the
Boundary binary's location to that list and then launch a new console window.

</Tab>
<Tab heading="macOS">

[Homebrew](https://brew.sh) is a free and open-source package management system
for Mac OS X. Install the official [boundary
formula](https://github.com/hashicorp/homebrew-tap) from the terminal.

```shell-session
$ brew install hashicorp/tap/boundary
```

~> **NOTE:** This installs a signed binary and is automatically updated with
every new official release.

To update to the latest, run

```shell-session
$ brew upgrade hashicorp/tap/boundary
```

</Tab>
<Tab heading="Windows">

[Scoop](https://scoop.sh/) is a free and open-source package management system
for Windows. Install Boundary from the command-line.

```shell-session
$ scoop install boundary
```

~> **NOTE:** The [Scoop main bucket
repository](https://github.com/ScoopInstaller/Main/blob/master/bucket/boundary.json)
is **NOT** maintained by HashiCorp. The latest version of Boundary is always
available by manual installation.

</Tab>
<Tab heading="Linux">

HashiCorp officially maintains and signs packages for the following Linux distributions.

<Tabs>
<Tab heading="Ubuntu/Debian">

Add the HashiCorp [GPG key][gpg-key].

```shell-session
$ curl -fsSL https://apt.releases.hashicorp.com/gpg | sudo apt-key add -
```

Add the official HashiCorp Linux repository.

```shell-session
$ sudo apt-add-repository "deb [arch=amd64] https://apt.releases.hashicorp.com $(lsb_release -cs) main"
```

Update and install.

```shell-session
$ sudo apt-get update && sudo apt-get install boundary
```

</Tab>
<Tab heading="CentOS/RHEL">

Install `yum-config-manager` to manage your repositories.

```shell-session
$ sudo yum install -y yum-utils
```

Use `yum-config-manager` to add the official HashiCorp Linux repository.

```shell-session
$ sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo
```

Install.

```shell-session
$ sudo yum -y install boundary
```

</Tab>
<Tab heading="Fedora">

Install `dnf config-manager` to manage your repositories.

```shell-session
$ sudo dnf install -y dnf-plugins-core
```

Use `dnf config-manager` to add the official HashiCorp Linux repository.

```shell-session
$ sudo dnf config-manager --add-repo https://rpm.releases.hashicorp.com/fedora/hashicorp.repo
```

Install.

```shell-session
sudo dnf -y install boundary
```

</Tab>
<Tab heading="Amazon Linux">

Install `yum-config-manager` to manage your repositories.

```shell-session
$ sudo yum install -y yum-utils
```

Use `yum-config-manager` to add the official HashiCorp Linux repository.

```shell-session
$ sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/AmazonLinux/hashicorp.repo
```

Install.

```shell-session
$ sudo yum -y install boundary
```

</Tab>
</Tabs>

-> **TIP:** Now that you have added the HashiCorp repository, you can install
[Terraform](/tutorials/terraform/install-cli), [Consul](/tutorials/consul/get-started-install), [Nomad](/tutorials/nomad/get-started-install) and [Packer](/tutorials/packer/get-started-install) with the same command.

</Tab>
</Tabs>


## Verify the installation

After installing Boundary, verify the installation worked by opening a new
command prompt or console, and checking that `boundary` is available.

-> **Tip:** If you receive an error that Boundary is not
found, try logging out and logging back in to your system (particularly
necessary sometimes for Windows).

```shell-session
$ boundary
Usage: boundary <command> [args]

Commands:
    accounts           Manage Boundary accounts
    auth-methods       Manage Boundary auth-methods
    auth-tokens        Manage Boundary auth-tokens
    authenticate       Authenticate the Boundary command-line client
    config             Manage resources related to Boundary's local configuration
    connect            Authorize a session against a target and launch a proxied connection
    database           Manage Boundary's database
    dev                Start a Boundary dev environment
    groups             Manage Boundary groups
    host-catalogs      Manage Boundary host-catalogs
    host-sets          Manage Boundary host-sets
    hosts              Manage Boundary hosts
    proxy              Launch the Boundary CLI in proxy mode
    roles              Manage Boundary roles
    scopes             Manage Boundary scopes
    server             Start a Boundary server
    sessions           Manage Boundary sessions
    targets            Manage Boundary targets
    users              Manage Boundary users
```

You have successfully downloaded and installed Boundary! Continue to the next
tutorial to set up your first Boundary project.


[gpg-key]: https://apt.releases.hashicorp.com/gpg 'HashiCorp GPG key'



Boundary enables simple and secure access to dynamic infrastructure by:

- **Identity-based access controls:** Streamline just-in-time access to
privileged sessions (e.g. TCP, SSH, RDP) for users and applications. Tightly
control access permissions with extensible role-based access controls.

- **Access Automation:** Define your perimeter of resources, identities, and
access controls as code through Boundary's fully-instrumented Terraform
Provider, REST API, CLI, and SDK. Automate the discovery of new resources and
enforcement of existing policies as resources are provisioned.

- **Session Visibility:** Security administrators gain monitor and managed the
privileged sessions established with Boundary. Export session logs to your
analytics tool of choice.

![Boundary Workflow](/img/boundary/boundary-workflow.png)

Traditional approaches like SSH bastion hosts or VPNs that require distributing
and managing credentials, configure network controls like firewalls, and expose
the private network.  Boundary provides a secure way to access to hosts and
critical systems without having to manage credentials or expose your network.

![Boundary overview](/img/boundary/boundary-overview-2.png)

Refer to the [Boundary documentation
page](https://boundaryproject.io/docs/concepts).

The Boundary getting started tutorials will walk you through your first
Boundary project, highlighting major features of Boundary.



The [Getting Started tutorials](/collections/boundary/getting-started) gave you
a tour of the admin console and examined different [Boundary
resources](/tutorials/boundary/getting-started-console#boundary-resource-summary).

A sequence of tutorials will demonstrate the common Boundary resource management
operations. Go through the tutorials in sequential order to create a complete
set of resources shown in the diagram below.

![Resources](/img/boundary/boundary-resource-mgmt.png)

The [Manage Sessions](/tutorials/boundary/manage-sessions) tutorial will connect to
the target and learn how to manage the active sessions.



[Scopes](https://boundaryproject.io/docs/concepts/domain-model/scopes) are a
foundational part of Boundary. They 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:

- There is only one `global` scope. It is the entry point for initial
  administration/setup and to manage the org scopes.
- Under the `global` scope, you can create multiple org scopes. Orgs are used to
  hold IAM-related resources and project scopes.
- Under each org scope, you can create 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](https://boundaryproject.io/docs/concepts/domain-model/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](https://boundaryproject.io/docs/concepts/domain-model) for detailed
resource-specific information.

In this tutorial, you're going to 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 with the exception being generated
resources in `dev` mode. Be sure to use the resource IDs that are generated for
your environment when running this tutorial. For example, if you run `boundary users create`, use the resource ID of the user seen 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](/tutorials/boundary/getting-started-install) tutorial to install and
start a Boundary.

## Create an org

In this tutorial, you are going to create an org under the `global` scope.

The CLI and admin console will create certain administrative roles
automatically when a scope is created so that the user that created the
scope can immediately manage it. The Terraform provider skips
creation of those roles so that resources are not created outside of Terraform's
purview. To simplify this tutorial, you are telling Terraform to allow these
roles to be created in both this section and in the next section where you
create a project scope.

<Tabs>
<Tab heading="CLI" group="cli">


~> To start this tutorial, be sure to [Login to the Boundary Console](/tutorials/boundary/getting-started-dev#login-to-the-boundary-console)
first.

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

```shell-session
$ boundary scopes create -scope-id=global -name=IT_Support -description="IT Support Team"
```

**Example output:**

```plaintext hideClipboard
Scope information:
  Created Time:        Thu, 10 Dec 2020 21:24:52 PST
  Description:         IT Support Team
  ID:                  o_BdK14OKdM4
  Name:                IT_Support
  Updated Time:        Thu, 10 Dec 2020 21:24:52 PST
  Version:             1

  Scope (parent):
    ID:                global
    Name:              global
    Type:              global
```

List the existing scopes.

```shell-session
$ boundary scopes list
```

**Example output:**

```plaintext hideClipboard
Scope information:
  ID:             o_1234567890
    Version:      1
    Name:         Generated org scope
    Description:  Provides an initial org scope in Boundary

  ID:             o_BdK14OKdM4
    Version:      1
    Name:         IT_Support
    Description:  IT Support Team
```

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

Copy the ID of the `IT_Support` org and save it as an environment variabe,
`ORG_ID`.

```shell-session
$ export ORG_ID=<IT_Support_Org_ID>
```

**Example:**

```shell-session
$ export ORG_ID="o_BdK14OKdM4"
```

</Tab>
<Tab heading="Admin Console" group="admin">


1. Log into the Boundary admin console at the global level.
1. Click **New** button.
   ![New org](/img/boundary/boundary-ui-new-org-0.png)

1. 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.
   ![New org](/img/boundary/boundary-ui-new-org-1.png)

1. Click **Save**. You should be automatically directed into the newly created
   org.
   ![New org](/img/boundary/boundary-ui-new-org-2.png)

</Tab>
<Tab heading="Terraform" group="terraform">


In your Terraform configuration file, define a [`boundary_scope`
resource](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs/resources/scope)
to create a new org under the `global` scope named, "IT_Support" with
description, "IT Support Team".

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

</Tab>
</Tabs>


## Create a project

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

<Tabs>
<Tab heading="CLI" group="cli">


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

```shell-session
$ boundary scopes create -scope-id=$ORG_ID -name=QA_Tests \
    -description="Manage QA machines"
```

**Example output:**

```shell-session hideClipboard
Scope information:
  Created Time:        Thu, 10 Dec 2020 21:33:29 PST
  Description:         Manage QA machines
  ID:                  p_HtkJjpSlic
  Name:                QA_Tests
  Updated Time:        Thu, 10 Dec 2020 21:33:29 PST
  Version:             1

  Scope (parent):
    ID:                o_BdK14OKdM4
    Name:              IT_Support
    Parent Scope ID:   global
    Type:              org
```

List the project under the `IT_Support` org to verify.

```shell-session
$ boundary scopes list -scope-id=$ORG_ID
```

**Example output:**

```plaintext hideClipboard
Scope information:
  ID:             p_HtkJjpSlic
    Version:      1
    Name:         QA_Tests
    Description:  Manage QA machines
```

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

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

```shell-session
$ export PROJECT_ID=<QA_Tests_Project_ID>
```

**Example:**

```shell-session
$ export PROJECT_ID="p_HtkJjpSlic"
```

</Tab>
<Tab heading="Admin Console" group="admin">


1. Select **Projects** and click **New**.
   ![New Project](/img/boundary/boundary-ui-project-0.png)

1. Enter `QA_Tests` in the **Name** field, and `Manage QA machines` in the
   **Description** field.
   ![New Project](/img/boundary/boundary-ui-project-1.png)

1. Click **Save**.
   ![New Project](/img/boundary/boundary-ui-project-2.png)

   By default, you cannot edit the details to help prevent unintended edits. To
   edit the newly created project, click the **Edit Form** button.

</Tab>
<Tab heading="Terraform" group="terraform">


Similar to creating a new org, define a [`boundary_scope`
resource](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs/resources/scope)
which retrieves the parent org ID dynamically via `boundary_scope.org.id`.

```hcl
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
}
```

</Tab>
</Tabs>


## 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.



[Targets](https://www.boundaryproject.io/docs/concepts/domain-model/targets) are
Boundary resources that contain one or more [host
sets](https://www.boundaryproject.io/docs/concepts/domain-model/host-sets). A
target allows Boundary users to define an endpoint with a default port and a
protocol to establish a session. Unless specified with a `-host-id` flag,
Boundary will choose one
[Host](https://www.boundaryproject.io/docs/concepts/domain-model/hosts) in the
host set to connect to at random.

This tutorial demonstrates the basics of how to define a host, host set, and a
target in Boundary on the CLI, the admin console, and using our [Terraform
provider](https://github.com/hashicorp/terraform-provider-boundary).

!> All resource IDs in this tutorial are illustrations only. IDs are uniquely
generated for every resource upon creation with the exception being generated
resources in development mode. Be sure to use the resource IDs that are
generated for your environment.

You will create a host catalog, a host set containing hosts, and a
target.

![Scenario](/img/boundary/boundary-manage-hosts-scenario-2.png)

## Prerequisites

This tutorial assumes that you successfully completed the [Manage
Scopes](/tutorials/boundary/manage-scopes) tutorial.

## Add hosts to project

Hosts and host sets are defined within a host catalog, so you need to create a
host catalog first.

![Scenario](/img/boundary/boundary-manage-hosts-scenario-0.png)

<Tabs>
<Tab heading="CLI" group="cli">


1. Create a host catalog named, "DevOps" with description, "For DevOps usage" in
   the `QA_Tests` project.

   ```shell-session
   $ boundary host-catalogs create static -scope-id=$PROJECT_ID -name=DevOps \
       -description="For DevOps usage"
   ```

   **Example output:**

   ```shell-session hideClipboard
   Host Catalog information:
     Created Time:        Thu, 10 Dec 2020 22:27:25 PST
     Description:         For DevOps usage
     ID:                  hcst_v1nKf0BbNW
     Name:                DevOps
     Type:                static
     Updated Time:        Thu, 10 Dec 2020 22:27:25 PST
     Version:             1

     Scope:
       ID:                p_HtkJjpSlic
       Name:              QA_Tests
       Parent Scope ID:   o_BdK14OKdM4
       Type:              project
   ```

1. Copy the generated host catalog ID and save it as an environment variabe,
   `HOST_CATALOG_ID`.

   ```shell-session
   $ export HOST_CATALOG_ID=<host_catalog_id>
   ```

   **Example:**

   ```shell-session
   $ export HOST_CATALOG_ID="hcst_v1nKf0BbNW"
   ```

1. Now, create a new host named, "postgres" with description, "Postgres host"
   under the newly created host catalog.

   ```shell-session
   $ boundary hosts create static -name=postgres -description="Postgres host" \
       -address="127.0.0.1" -host-catalog-id=$HOST_CATALOG_ID
   ```

   **Example output:**

   ```shell-session hideClipboard
   Host information:
     Created Time:        Thu, 10 Dec 2020 22:38:58 PST
     Description:         Postgres host
     Host Catalog ID:     hcst_v1nKf0BbNW
     ID:                  hst_npr0tiLp3y
     Name:                postgres
     Type:                static
     Updated Time:        Thu, 10 Dec 2020 22:38:58 PST
     Version:             1

     Scope:
       ID:                p_HtkJjpSlic
       Name:              QA_Tests
       Parent Scope ID:   o_BdK14OKdM4
       Type:              project

     Attributes:
       address:           127.0.0.1
   ```

1. Repeat the step to create another host named, "localhost".

   ```shell-session
   $ boundary hosts create static -name=localhost -description="Localhost for testing" \
       -address="localhost" -host-catalog-id=$HOST_CATALOG_ID
   ```

   **Example output:**

   ```shell-session hideClipboard
   Host information:
     Created Time:        Thu, 11 Dec 2020 14:53:57 PST
     Description:         Localhost for testing
     Host Catalog ID:     hcst_v1nKf0BbNW
     ID:                  hst_4FEMYKB6Fn
     Name:                localhost
     Type:                static
     Updated Time:        Thu, 11 Dec 2020 14:53:57 PST
     Version:             1

     Scope:
       ID:                p_HtkJjpSlic
       Name:              QA_Tests
       Parent Scope ID:   o_BdK14OKdM4
       Type:              project

     Attributes:
       address:           localhost
   ```

</Tab>
<Tab heading="Admin Console" group="admin">


1. Select the project you wish to define a host (in this case, `QA_Tests`).

1. Select **Host Catalogs**.

1. Choose **New**.
   ![Host Catalog](/img/boundary/boundary-ui-host-catalog-0.png)

1. Enter `DevOps` in the **Name** field, and `For DevOps usage` in the
   **Description** field.
   ![Host Catalog](/img/boundary/boundary-ui-host-catalog-1.png)

1. Click **Save**.

1. Select the **Hosts** tab, and then select **New**.
   ![Host Catalog](/img/boundary/boundary-ui-host-0.png)

1. Enter `postgres` in the **Name** field, `Postgres host` in the
   **Description** field, and `127.0.0.1` in the **Address** field.
   ![Host Catalog](/img/boundary/boundary-ui-host-1.png)

1. Click **Save**.

1. Select **Host Catalogs > DevOps** and then select **New Host** from the
   **Manage** menu.
   ![Host Catalog](/img/boundary/boundary-ui-host-4.png)

1. Enter `localhost` in the **Name** field, `Localhost for testing` in the
   **Description** field, and `localhost` in the **Address**.
   ![Host Catalog](/img/boundary/boundary-ui-host-5.png)

1. Click **Save**.

</Tab>
<Tab heading="Terraform" group="terraform">


In your Terraform configuration file, define a [`boundary_host_catalog`
resource](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs/resources/host_catalog)
to create a new host catalog in the "IT_Support" project, and define a
[`boundary_host`
resource](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs/resources/host)
to create a `postgres` host definition.

To define this same host using our Terraform provider:

```hcl
# 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
# }

resource "boundary_host_catalog" "devops" {
  name        = "DevOps"
  description = "For DevOps usage"
  type        = "static"
  scope_id    = boundary_scope.project.id
}

resource "boundary_host" "postgres" {
  type            = "static"
  name            = "postgres"
  description     = "Postgres host"
  address         = "127.0.0.1"
  host_catalog_id = boundary_host_catalog.devops.id
}

resource "boundary_host" "localhost" {
  type            = "static"
  name            = "localhost"
  description     = "Localhost for testing"
  address         = "localhost"
  host_catalog_id = boundary_host_catalog.devops.id
}
```

</Tab>
</Tabs>


## Create a host set

A host set groups together hosts. These hosts provide logically equivalent services.

![Scenario](/img/boundary/boundary-manage-hosts-scenario-1.png)

-> **NOTE:** A target works off of host sets. Therefore, even if there is only
one host, you still create a host set containing one host.

<Tabs>
<Tab heading="CLI" group="cli">


1. Create a host set named, "test-machines".

   ```shell-session
   $ boundary host-sets create static -name="test-machines" \
       -description="Test machine host set" -host-catalog-id=$HOST_CATALOG_ID
   ```

   **Example output:**

   ```shell-session hideClipboard
   Host Set information:
     Created Time:        Tue, 15 Dec 2020 19:19:28 PST
     Description:         Test machine host set
     Host Catalog ID:     hcst_AmJAzZBMiF
     ID:                  hsst_HgbteKKh8X
     Name:                test-machines
     Type:                static
     Updated Time:        Tue, 15 Dec 2020 19:19:28 PST
     Version:             1

     Scope:
       ID:                p_HtkJjpSlic
       Name:              QA_Tests
       Parent Scope ID:   o_BdK14OKdM4
       Type:              project
   ```

   Copy the `test-machines` host set ID. In the example, the ID is
   `hsst_HgbteKKh8X`.

1. Retrieve the host IDs.

   ```shell-session
   $ boundary hosts list -host-catalog-id=$HOST_CATALOG_ID
   ```

   **Example output:**

   ```shell-session hideClipboard
   Host information:
     ID:             hst_0OhAUtkL5T
       Version:      1
       Type:         static
       Name:         postgres
       Description:  Postgres host

     ID:             hst_l8I0VY4Gq8
       Version:      1
       Type:         static
       Name:         localhost
       Description:  Localhost for testing
   ```

   In the example output, the `postgres` host ID is `hst_0OhAUtkL5T` and the
   `localhost` host ID is `hst_l8I0VY4Gq8`. You will pass these IDs in the next
   step.

1. Add `postgres` and `localhost` hosts to the `test-machines` host set. Be sure
   to replace `<postgres_host_id>` and `<localhost_host_id>` with the host IDs you
   just retrieved.

   ```shell-session
   $ boundary host-sets add-hosts -id=<host_set_id> -host=<postgres_host_id> \
      -host=<localhost_host_id>
   ```

   **Example:**

   ```shell-session hideClipboard
   $ boundary host-sets add-hosts -id=hsst_q68hY6ua75 -host=hst_0OhAUtkL5T -host=hst_l8I0VY4Gq8

   Host Set information:
     Created Time:        Thu, 17 Dec 2020 15:22:19 PST
     Description:         Test machine host set
     Host Catalog ID:     hcst_AmJAzZBMiF
     ID:                  hsst_q68hY6ua75
     Name:                test-machines
     Type:                static
     Updated Time:        Thu, 17 Dec 2020 15:34:56 PST
     Version:             2

     Scope:
       ID:                p_HtkJjpSlic
       Name:              QA_Tests
       Parent Scope ID:   o_hGyyUbrL5i
       Type:              project

     Host IDs:
       hst_0OhAUtkL5T
       hst_l8I0VY4Gq8
   ```

</Tab>
<Tab heading="Admin Console" group="admin">


1. Select the **Host Sets** tab, and then select **New**.
   ![Host Set](/img/boundary/boundary-ui-host-set-0.png)

1. Enter `test-machines` in the **Name** field, and `Test machine host set` in the
   **Description** field.
   ![Host Set](/img/boundary/boundary-ui-host-set-1.png)

1. Click **Save**.

1. Select the **Hosts** tab.

1. From the **Manage** menu, select **Add Existing Host**.
   ![Host Set](/img/boundary/boundary-ui-host-2.png)

1. Select the check-box for **Postgres host** and **Localhost for testing**.
   ![Host Set](/img/boundary/boundary-ui-host-3.png)

1. Click **Add Hosts**.

</Tab>
<Tab heading="Terraform" group="terraform">


In your Terraform configuration file, define a [`boundary_host_set`
resource](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs/resources/host_set)
to create a new host set, and use `boundary_host.postgres.id` and
`boundary_host.localhost.id` to retrieve the host IDs and attach them to the
DevOps host catalog (`boundary_host_catalog.devops.id`).

```hcl
# resource "boundary_host_catalog" "devops" {
#   name        = "DevOps"
#   description = "For DevOps usage"
#   type        = "static"
#   scope_id    = boundary_scope.project.id
# }

# resource "boundary_host" "postgres" {
#   type            = "static"
#   name            = "postgres"
#   description     = "Postgres host"
#   address         = "127.0.0.1"
#   host_catalog_id = boundary_host_catalog.devops.id
# }

# resource "boundary_host" "localhost" {
#   type            = "static"
#   name            = "localhost"
#   description     = "Localhost for testing"
#   address         = "localhost"
#   host_catalog_id = boundary_host_catalog.devops.id
# }

resource "boundary_host_set" "test-machines" {
  type            = "static"
  name            = "test-machines"
  description     = "Host set for postgres"
  host_catalog_id = boundary_host_catalog.devops.id
  host_ids = [
      boundary_host.postgres.id,
      boundary_host.localhost.id,
  ]
}
```

</Tab>
</Tabs>


## Define a target

Finally, create a target associated with the `QA_Tests` project.

![Scenario](/img/boundary/boundary-manage-hosts-scenario-2.png)

<Tabs>
<Tab heading="CLI" group="cli">


1. Create a target named, "tests" with description, "Test target". Set the
   default port to be `22`. To allow unlimited number of session connections, set
   the session connection limit to `-1`.

   ```shell-session
   $ boundary targets create tcp -name="tests" -description="Test target" \
       -default-port=22 -scope-id=$PROJECT_ID -session-connection-limit="-1"
   ```

   **Example output:**

   ```shell-session hideClipboard
   Target information:
     Created Time:               Tue, 15 Dec 2020 23:47:27 PST
     Description:                Test target
     ID:                         ttcp_YhaBHowuuU
     Name:                       tests
     Session Connection Limit:   -1
     Session Max Seconds:        28800
     Type:                       tcp
     Updated Time:               Tue, 15 Dec 2020 23:47:27 PST
     Version:                    1

     Scope:
       ID:                       p_HtkJjpSlic
       Name:                     QA_Tests
       Parent Scope ID:          o_BdK14OKdM4
       Type:                     project
     Attributes:
       Default Port:             22
   ```

1. Add the `test-machines` host set to the `tests` target. Replace
   `<target_id>` with your tests target ID, and `<host_set_id>` with your
   test-machines host set ID.

   ```shell-session hideClipboard
   $ boundary targets add-host-sets -id=<target_id> -host-set=<host_set_id>
   ```

   **Example:**

   ```shell-session hideClipboard
   $ boundary targets add-host-sets -id=ttcp_q6EIuyrFGi -host-set=hsst_q68hY6ua75

   Target information:
     Created Time:               Thu, 17 Dec 2020 15:57:51 PST
     Description:                Test target
     ID:                         ttcp_q6EIuyrFGi
     Name:                       tests
     Session Connection Limit:   -1
     Session Max Seconds:        28800
     Type:                       tcp
     Updated Time:               Thu, 17 Dec 2020 16:15:22 PST
     Version:                    2

     Scope:
       ID:                       p_HtkJjpSlic
       Name:                     QA_Tests
       Parent Scope ID:          o_BdK14OKdM4
       Type:                     project

     Host Sets:
       Host Catalog ID:          hcst_v1nKf0BbNW
       ID:                       hsst_q68hY6ua75

     Attributes:
       Default Port:             22
   ```

</Tab>
<Tab heading="Admin Console" group="admin">


1. Select **Target** and select **New**.
   ![Target](/img/boundary/boundary-ui-target-0.png)

1. Enter `tests` in the **Name** field, `Test target` in the
   **Description** filed, `-1` in the **Maximum Connections** field, and `22` in
   the **Default Port** field.
   ![Target](/img/boundary/boundary-ui-target-1.png)

1. Click **Save**.

1. Select the **Host Sets** tab and then **Add Host Sets**.
   ![Target](/img/boundary/boundary-ui-target-4.png)

1. Select the check-box for **Test machine host set**.
   ![Target](/img/boundary/boundary-ui-target-5.png)

1. Click **Add Host Sets** to assign the target.

</Tab>
<Tab heading="Terraform" group="terraform">


In your Terraform configuration file, define a [`boundary_target`
resource](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs/resources/target)
to define a new target, and use `boundary_host_set.postgres.id` to retrieve the
the `postgres` host set ID and set it to `host_set_ids`.

```hcl
# 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
# }

# resource "boundary_host_set" "test-machines" {
#   type            = "static"
#   name            = "test-machines"
#   description     = "Test machine host set"
#   host_catalog_id = boundary_host_catalog.devops.id
#   host_ids = [ boundary_host.postgres.id ]
# }

resource "boundary_target" "tests" {
  type                     = "tcp"
  name                     = "tests"
  description              = "Test target"
  scope_id                 = boundary_scope.project.id
  session_connection_limit = -1
  default_port             = 22
  host_set_ids = [
    boundary_host_set.test-machines.id
  ]
}
```

</Tab>
</Tabs>


## Next steps

This tutorial demonstrated the steps to define targets under a scope
(`QA_Tests`). Targets represent network services a user can connect to.

You have not added users yet. So, the next step is to add users to the
scope.


Learn about automated host discovery in the latest HashiCorp Boundary release

Learn Boundary

Getting Started

Featured Tutorials

Dynamic Host Catalogs

Vault Credential Brokering Quickstart

OIDC Authentication

Boundary Resource Management Workflows

Basic Administration

Introduction

Manage Scopes

Manage Targets

Common Administration Workflows

Infrastructure

Security

Networking

Applications

Learn about automated host discovery in the latest HashiCorp Boundary release

Learn Boundary

Getting Started

Featured Tutorials

Dynamic Host Catalogs

Vault Credential Brokering Quickstart

OIDC Authentication

Boundary Resource Management Workflows

Basic Administration

Introduction

Manage Scopes

Manage Targets

Common Administration Workflows