Manage Targets with HCP Boundary

10min
HCP
Terraform
Boundary

Targets are Boundary resources that contain one or more 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 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 HCP Boundary on the CLI, the admin console, and using our Terraform provider.

All resource IDs in this tutorial are illustrations only. IDs are uniquely generated for every resource upon creation. 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.

Resources

Prerequisites

This tutorial assumes you have:

Access to an HCP Boundary instance.
Successfully completed the Manage Scopes tutorial.
A publicly accessible Ubuntu instance.
An ssh key-pair that can be used to authenticate with the Ubuntu instance.

Note: Ubuntu is used in this tutorial for demonstration purposes only. You can follow this guide to create a publicly accessible EC2 instance to use for this tutorial.

Add hosts to project

Hosts and host sets are defined within a host catalog. To get started, you will need to create the host catalog first.

Scenario

To start this tutorial, be sure to Login to the Boundary Console first.

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

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

Example output:

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

 Host Catalog information:
   Created Time:        Fri, 27 May 2022 10:46:07 MDT
   Description:         For DevOps usage
   ID:                  hcst_xM3iCCkf1K
   Name:                DevOps
   Type:                static
   Updated Time:        Fri, 27 May 2022 10:46:07 MDT
   Version:             1

   Scope:
     ID:                p_oMgeFL2hP6
     Name:              QA_Tests
     Parent Scope ID:   o_u54jrD6ydN
     Type:              project

   Authorized Actions:
     no-op
     read
     update
     delete

   Authorized Actions on Host Catalog's Collections:
     host-sets:
       create
       list
     hosts:
       create
       list

Copy the generated host catalog ID and save it as an environment variabe, HOST_CATALOG_ID.
```
$ export HOST_CATALOG_ID=<host_catalog_id>
```
Example:
```
$ export HOST_CATALOG_ID="hcst_xM3iCCkf1K"
```

Now, create a new host named, "ubuntu" with description, "Ubuntu host" under the newly created host catalog. Enter in your Ubuntu instance's public IP address (such as 50.16.114.201) in the address field.

$ boundary hosts create static \
  -name=ubuntu \
  -description="Ubuntu host" \
  -address="ubuntu-public-ip-address" \
  -host-catalog-id=$HOST_CATALOG_ID

Example output:

$ boundary hosts create static \
  -name=ubuntu \
  -description="Ubuntu host" \
  -address="50.16.114.201" \
  -host-catalog-id=$HOST_CATALOG_ID

 Host information:
   Created Time:        Fri, 27 May 2022 10:48:29 MDT
   Description:         Ubuntu host
   Host Catalog ID:     hcst_xM3iCCkf1K
   ID:                  hst_U1qYKzKfXO
   Name:                ubuntu
   Type:                static
   Updated Time:        Fri, 27 May 2022 10:48:29 MDT
   Version:             1

   Scope:
     ID:                p_oMgeFL2hP6
     Name:              QA_Tests
     Parent Scope ID:   o_u54jrD6ydN
     Type:              project

   Authorized Actions:
     no-op
     read
     update
     delete

   Attributes:
     address:           50.16.114.201

Select the project you wish to define a host (in this case, QA_Tests).
Select Host Catalogs.
Choose New.
Enter DevOps in the Name field, and For DevOps usage in the Description field.
Click Save.
Select the Hosts tab, and then select New.
Enter ubuntu in the Name field, Ubuntu host in the Description field, and the public IP address of the Ubuntu instance (such as 50.16.114.201) in the Address field.
Click Save.

In your Terraform main.tf configuration file, define a boundary_host_catalog_static resource to create a new host catalog in the "IT_Support" project, and define a boundary_host_static resource to create a host definition for the ubuntu host.

To define this same host using our Terraform provider:

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

resource "boundary_host_static" "ubuntu" {
  name            = "ubuntu"
  description     = "Ubuntu host"
  address         = "<ubuntu-public-ip-address>"
  host_catalog_id = boundary_host_catalog_static.devops.id
}

Replace <ubuntu-public-ip-address> with your Ubuntu instance's public IP address.

Create a host set

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

Scenario

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.

Create a host set named, "ubuntu-machines".

$ boundary host-sets create static \
  -name="ubuntu-machines" \
  -description="Ubuntu host set" \
  -host-catalog-id=$HOST_CATALOG_ID

Example output:

$ boundary host-sets create static \
  -name="ubuntu-machines" \
  -description="Ubuntu host set" \
  -host-catalog-id=$HOST_CATALOG_ID

 Host Set information:
   Created Time:        Fri, 27 May 2022 10:51:02 MDT
   Description:         Ubuntu host set
   Host Catalog ID:     hcst_xM3iCCkf1K
   ID:                  hsst_X8gmzYXbO4
   Name:                ubuntu-machines
   Type:                static
   Updated Time:        Fri, 27 May 2022 10:51:02 MDT
   Version:             1

   Scope:
     ID:                p_oMgeFL2hP6
     Name:              QA_Tests
     Parent Scope ID:   o_u54jrD6ydN
     Type:              project

   Authorized Actions:
     no-op
     read
     update
     delete
     add-hosts
     set-hosts
     remove-hosts

Copy the ubuntu-machines host set ID and save it as an environment variable, HOST_SET_ID.. In the example, the ID is hsst_X8gmzYXbO4.

$ export HOST_SET_ID=<ubuntu_HOST_SET_ID>

Example:

$ export HOST_SET_ID="hsst_X8gmzYXbO4"

Retrieve the host IDs.

$ boundary hosts list -host-catalog-id=$HOST_CATALOG_ID

Host information:
  ID:                    hst_FrdNPd9Zm9
    Version:             1
    Type:                static
    Name:                ubuntu
    Description:         Ubuntu host for testing
    Authorized Actions:
      no-op
      read
      update
      delete

In the example output, the ubuntu host ID is hst_U1qYKzKfXO.

Copy the generated host ID and create an environment variable called HOST_ID using copied value.
```
$ export HOST_ID=<ubuntu_host_id>
```

Add the ubuntu host to the ubuntu-machines host set.

$ boundary host-sets add-hosts \
  -id=$HOST_SET_ID \
  -host=$HOST_ID

Example:

$ boundary host-sets add-hosts \
  -id=$HOST_SET_ID \
  -host=hst_U1qYKzKfXO

 Host Set information:
   Created Time:        Fri, 27 May 2022 10:51:02 MDT
   Description:         Ubuntu host set
   Host Catalog ID:     hcst_xM3iCCkf1K
   ID:                  hsst_X8gmzYXbO4
   Name:                ubuntu-machines
   Type:                static
   Updated Time:        Fri, 27 May 2022 10:59:00 MDT
   Version:             2

   Scope:
     ID:                p_oMgeFL2hP6
     Name:              QA_Tests
     Parent Scope ID:   o_u54jrD6ydN
     Type:              project

   Authorized Actions:
     no-op
     read
     update
     delete
     add-hosts
     set-hosts
     remove-hosts

   Host IDs:
     hst_U1qYKzKfXO

In your Terraform configuration file, define a boundary_host_set_static resource to create a new host set, and use boundary_host.ubuntu.id to retrieve the host ID and attach them to the DevOps host catalog (boundary_host_catalog_static.devops.id).

resource "boundary_host_set_static" "ubuntu-machines" {
  name            = "ubuntu-machines"
  description     = "Host set for ubuntu"
  host_catalog_id = boundary_host_catalog_static.devops.id
  host_ids = [
      boundary_host_static.ubuntu.id
  ]
}

Define a target

Finally, create a target associated with the QA_Tests project.

Targets

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.

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

Example output:

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

 Target information:
   Created Time:               Fri, 27 May 2022 11:02:22 MDT
   Description:                Test target
   ID:                         ttcp_34yV5O9cwt
   Name:                       tests
   Session Connection Limit:   -1
   Session Max Seconds:        28800
   Type:                       tcp
   Updated Time:               Fri, 27 May 2022 11:02:22 MDT
   Version:                    1

   Scope:
     ID:                       p_oMgeFL2hP6
     Name:                     QA_Tests
     Parent Scope ID:          o_u54jrD6ydN
     Type:                     project

   Authorized Actions:
     no-op
     read
     update
     delete
     add-host-sources
     set-host-sources
     remove-host-sources
     add-credential-libraries
     set-credential-libraries
     remove-credential-libraries
     add-credential-sources
     set-credential-sources
     remove-credential-sources
     authorize-session

   Attributes:
     Default Port:             22

In this example, the generated target ID is ttcp_34yV5O9cwt. Notice that target IDs starts with ttcp_.

Copy the ID of the tests target and save it as an environment variable, TARGET_ID.

$ export TARGET_ID=<tests_TARGET_ID>

Example:

$ export TARGET_ID="ttcp_34yV5O9cwt"

Add the ubuntu-machines host set to the tests target.

$ boundary targets add-host-sources -id=$TARGET_ID -host-source=$HOST_SET_ID

 Target information:
   Created Time:               Fri, 27 May 2022 11:02:22 MDT
   Description:                Test target
   ID:                         ttcp_34yV5O9cwt
   Name:                       tests
   Session Connection Limit:   -1
   Session Max Seconds:        28800
   Type:                       tcp
   Updated Time:               Fri, 27 May 2022 11:07:59 MDT
   Version:                    2

   Scope:
     ID:                       p_oMgeFL2hP6
     Name:                     QA_Tests
     Parent Scope ID:          o_u54jrD6ydN
     Type:                     project

   Authorized Actions:
     no-op
     read
     update
     delete
     add-host-sources
     set-host-sources
     remove-host-sources
     add-credential-libraries
     set-credential-libraries
     remove-credential-libraries
     add-credential-sources
     set-credential-sources
     remove-credential-sources
     authorize-session

   Host Sources:
     Host Catalog ID:          hcst_xM3iCCkf1K
     ID:                       hsst_X8gmzYXbO4

   Attributes:
     Default Port:             22

In your Terraform configuration file, define a boundary_target resource to define a new target, and use boundary_host_set.ubuntu.id to retrieve the the ubuntu host set ID and set it to host_set_ids.

resource "boundary_target" "ubuntu" {
  type                     = "tcp"
  name                     = "ubuntu"
  description              = "Ubuntu target"
  scope_id                 = boundary_scope.project.id
  session_connection_limit = -1
  default_port             = 22
  host_source_ids = [
    boundary_host_set_static.ubuntu-machines.id
  ]
}

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

main.tf

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

variable "boundary_addr" {
  type = string
}

variable "auth_method_id" {
  type = string
}

variable "password_auth_method_login_name" {
  type = string
}

variable "password_auth_method_password" {
  type = string
}

provider "boundary" {
  addr                            = var.boundary_addr
  auth_method_id                  = var.auth_method_id
  password_auth_method_login_name = var.password_auth_method_login_name
  password_auth_method_password   = var.password_auth_method_password
}

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
}

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

resource "boundary_host_static" "ubuntu" {
  name            = "ubuntu"
  description     = "Ubuntu host"
  address         = "50.16.114.201"
  host_catalog_id = boundary_host_catalog_static.devops.id
}

resource "boundary_host_set_static" "ubuntu-machines" {
  name            = "ubuntu-machines"
  description     = "Host set for Ubuntu"
  host_catalog_id = boundary_host_catalog_static.devops.id
  host_ids = [
      boundary_host_static.ubuntu.id
  ]
}

resource "boundary_target" "ubuntu" {
  type                     = "tcp"
  name                     = "ubuntu-target"
  description              = "Ubuntu target"
  scope_id                 = boundary_scope.project.id
  session_connection_limit = -1
  default_port             = 22
  host_source_ids = [
    boundary_host_set_static.ubuntu-machines.id
  ]
}

Save this file.

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

$ terraform apply -var "boundary_addr=$BOUDNARY_ADDR" -var "auth_method_id=$BOUNDARY_AUTH_METHOD_ID" -var "password_auth_method_login_name=admin" -var "password_auth_method_password=password"

boundary_scope.org: Refreshing state... [id=o_g7eiK1eamt]
boundary_scope.project: Refreshing state... [id=p_VRM1S65q8w]

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_host_catalog_static.devops will be created
  + resource "boundary_host_catalog_static" "devops" {
      + description = "For DevOps usage"
      + id          = (known after apply)
      + name        = "DevOps"
      + scope_id    = "p_VRM1S65q8w"
    }

  # boundary_host_set_static.ubuntu-machines will be created
  + resource "boundary_host_set_static" "ubuntu-machines" {
      + description     = "Host set for Ubuntu"
      + host_catalog_id = (known after apply)
      + host_ids        = (known after apply)
      + id              = (known after apply)
      + name            = "ubuntu-machines"
      + type            = "static"
    }

  # boundary_host_static.ubuntu will be created
  + resource "boundary_host_static" "ubuntu" {
      + address         = "50.16.114.201"
      + description     = "Ubuntu host"
      + host_catalog_id = (known after apply)
      + id              = (known after apply)
      + name            = "ubuntu"
      + type            = "static"
    }

  # boundary_target.ubuntu will be created
  + resource "boundary_target" "ubuntu" {
      + default_port             = 22
      + description              = "Ubuntu target"
      + host_source_ids          = (known after apply)
      + id                       = (known after apply)
      + name                     = "tests"
      + scope_id                 = "p_VRM1S65q8w"
      + session_connection_limit = -1
      + session_max_seconds      = (known after apply)
      + type                     = "tcp"
    }

Plan: 5 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_host_catalog_static.devops: Creating...
boundary_host_catalog_static.devops: Creation complete after 0s [id=hcst_W71jEjUw4n]
boundary_host_static.ubuntu: Creating...
boundary_host_static.ubuntu: Creation complete after 0s [id=hst_xoKMbUsmQw]
boundary_host_set_static.ubuntu-machines: Creating...
boundary_host_set_static.ubuntu-machines: Creation complete after 0s [id=hsst_Nafr6vOzgF]
boundary_target.ubuntu: Creating...
boundary_target.ubuntu: Creation complete after 0s [id=ttcp_ge1Mowyrej]

Apply complete! Resources: 5 added, 0 changed, 0 destroyed.

Next steps

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

In the Manage Users and Groups tutorial, you will add and manage users in the org scope.