Manage targets

10min
|
Boundary
Terraform

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 Boundary on the CLI, the admin console, and using our Terraform provider.

Warning

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

Prerequisites

This tutorial assumes that you successfully completed the Manage Scopes tutorial.

Setup a PostgreSQL target

Deploy a postgres database container, which will be configured as a target.

Launch the container by passing the postgres password, sample database name, and URL port mapping as options. In this example the sample database is named "sample".

Export the database URL as an environment variable.

$ export PG_URL="postgres://postgres:secret@localhost:16001/sampledb?sslmode=disable"

Next, start the Postgres container.

$ docker run -d \
   -e POSTGRES_PASSWORD=secret \
   -e POSTGRES_DB="sampledb" \
   --name postgres \
   -p 16001:5432 \
   postgres

Check that the container is running.

$ docker ps --format "table {{.ID}}\t{{.Names}}\t{{.Image}}\t{{.Status}}"
CONTAINER ID   NAMES       IMAGE      STATUS
af573c7093cd   postgres   postgres   Up About a minute

Add hosts to project

Hosts and host sets are defined within a host catalog, so you need to create a 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, "postgres" with description, "Postgres host" under the newly created host catalog.

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

Example output:

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

 Host information:
   Created Time:        Fri, 27 May 2022 10:48:29 MDT
   Description:         Postgres host
   Host Catalog ID:     hcst_xM3iCCkf1K
   ID:                  hst_U1qYKzKfXO
   Name:                postgres
   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:           127.0.0.1

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

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

Example output:

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

 Host information:
   Created Time:        Fri, 27 May 2022 10:49:40 MDT
   Description:         Localhost for testing
   Host Catalog ID:     hcst_xM3iCCkf1K
   ID:                  hst_FrdNPd9Zm9
   Name:                localhost
   Type:                static
   Updated Time:        Fri, 27 May 2022 10:49:40 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:           localhost

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 click New.
Enter postgres in the Name field, Postgres host in the Description field, and 127.0.0.1 in the Address field.
Click Save.
Select Host Catalogs > DevOps and then select New Host from the Manage menu.
Enter localhost in the Name field, Localhost for testing in the Description field, and localhost in the Address.
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 two host definitions, one for postgres and another for localhost.

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" "postgres" {
  name            = "postgres"
  description     = "Postgres host"
  address         = "127.0.0.1"
  host_catalog_id = boundary_host_catalog_static.devops.id
}

resource "boundary_host_static" "localhost" {
  name            = "localhost"
  description     = "Localhost for testing"
  address         = "localhost"
  host_catalog_id = boundary_host_catalog_static.devops.id
}

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, "test-machines".

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

Example output:

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

 Host Set information:
   Created Time:        Fri, 27 May 2022 10:51:02 MDT
   Description:         Test machine host set
   Host Catalog ID:     hcst_xM3iCCkf1K
   ID:                  hsst_X8gmzYXbO4
   Name:                test-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 test-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=<test-machines_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:                localhost
    Description:         Localhost for testing
    Authorized Actions:
      no-op
      read
      update
      delete

  ID:                    hst_U1qYKzKfXO
    Version:             1
    Type:                static
    Name:                postgres
    Description:         Postgres host
    Authorized Actions:
      no-op
      read
      update
      delete

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

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.

$ boundary host-sets add-hosts \
  -id=$HOST_SET_ID \
  -host=<postgres_host_id> \
  -host=<localhost_host_id>

Example:

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

 Host Set information:
   Created Time:        Fri, 27 May 2022 10:51:02 MDT
   Description:         Test machine host set
   Host Catalog ID:     hcst_xM3iCCkf1K
   ID:                  hsst_X8gmzYXbO4
   Name:                test-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
     hst_FrdNPd9Zm9

In your Terraform configuration file, define a boundary_host_set_static resource 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_static.devops.id).

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

Define a target

Finally, create a target associated with the QA_Tests project.

Targets

Create a target named, "postgres" with description, "Postgres target". Set the default port to be 16001. To allow unlimited number of session connections, set the session connection limit to -1.

$ boundary targets create tcp \
  -name="postgres" \
  -description="Postgres target" \
  -default-port=16001 \
  -scope-id=$PROJECT_ID \
  -session-connection-limit="-1"

Example output:

 Target information:
   Created Time:               Fri, 27 May 2022 11:02:22 MDT
   Description:                Postgres target
   ID:                         ttcp_34yV5O9cwt
   Name:                       postgres
   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:             16001

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=<postgres_TARGET_ID>

Example:

$ export TARGET_ID="ttcp_34yV5O9cwt"

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

$ 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:                Postgres target
   ID:                         ttcp_34yV5O9cwt
   Name:                       postgres
   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:             16001

In your Terraform configuration file, define a boundary_target resource 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.

resource "boundary_target" "postgres" {
  type                     = "tcp"
  name                     = "postgres"
  description              = "Postgres target"
  scope_id                 = boundary_scope.project.id
  session_connection_limit = -1
  default_port             = 16001
  host_source_ids = [
    boundary_host_set_static.test-machines.id
  ]
}

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 = <<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
}

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

resource "boundary_host_static" "postgres" {
  name            = "postgres"
  description     = "Postgres host"
  address         = "127.0.0.1"
  host_catalog_id = boundary_host_catalog_static.devops.id
}

resource "boundary_host_static" "localhost" {
  name            = "localhost"
  description     = "Localhost for testing"
  address         = "localhost"
  host_catalog_id = boundary_host_catalog_static.devops.id
}

resource "boundary_host_set_static" "test-machines" {
  name            = "test-machines"
  description     = "Host set for postgres"
  host_catalog_id = boundary_host_catalog_static.devops.id
  host_ids = [
      boundary_host_static.postgres.id,
      boundary_host_static.localhost.id,
  ]
}
    
resource "boundary_target" "postgres" {
  type                     = "tcp"
  name                     = "postgres"
  description              = "Postgres target"
  scope_id                 = boundary_scope.project.id
  session_connection_limit = -1
  default_port             = 16001
  host_source_ids = [
    boundary_host_set_static.test-machines.id
  ]
}

Save this file.

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

$ terraform apply
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.test-machines will be created
  + resource "boundary_host_set_static" "test-machines" {
      + description     = "Host set for postgres"
      + host_catalog_id = (known after apply)
      + host_ids        = (known after apply)
      + id              = (known after apply)
      + name            = "test-machines"
      + type            = "static"
    }

  # boundary_host_static.localhost will be created
  + resource "boundary_host_static" "localhost" {
      + address         = "localhost"
      + description     = "Localhost for testing"
      + host_catalog_id = (known after apply)
      + id              = (known after apply)
      + name            = "localhost"
      + type            = "static"
    }

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

  # boundary_target.postgres will be created
  + resource "boundary_target" "postgres" {
      + default_port             = 16001
      + description              = "Postgres target"
      + host_source_ids          = (known after apply)
      + id                       = (known after apply)
      + name                     = "postgres"
      + 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.postgres: Creating...
boundary_host_static.localhost: Creating...
boundary_host_static.localhost: Creation complete after 0s [id=hst_rKcwslUEXf]
boundary_host_static.postgres: Creation complete after 0s [id=hst_xoKMbUsmQw]
boundary_host_set_static.test-machines: Creating...
boundary_host_set_static.test-machines: Creation complete after 0s [id=hsst_Nafr6vOzgF]
boundary_target.postgres: Creating...
boundary_target.postgres: Creation complete after 0s [id=ttcp_ge1Mowyrej]

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

Manage targets

First, verify you can connect to the target. Then update the target description.

Open a session to the postgres target using boundary connect. When prompted, enter the password secret to connect.

$ boundary connect postgres -target-id $TARGET_ID -username postgres
Password for user postgres:
psql (13.2)
Type "help" for help.

postgres=#

Note

If you followed the Admin Console workflow and did not export the TARGET_ID environment variable, supply it directly instead. In this example the target ID is ttcp_34yV5O9cwt.

After successfully testing the connection, terminate the session by executing \q.

Targets can be managed using arguments to the boundary targets command, such as update, delete, add-host-sources and delete-host-sources.

Update the target description.

$ boundary targets update tcp -id $TARGET_ID -description "updated postgres target"

Target information:
  Created Time:               Mon, 23 Jan 2023 17:47:38 MST
  Description:                updated postgres target
  ID:                         ttcp_UYMMW2Z13C
  Name:                       postgres
  Session Connection Limit:   -1
  Session Max Seconds:        28800
  Type:                       tcp
  Updated Time:               Mon, 23 Jan 2023 17:48:42 MST
  Version:                    3

  Scope:
    ID:                       p_OVOOKRiV5J
    Name:                     QA_Tests
    Parent Scope ID:          o_8EhpHB3qEN
    Type:                     project

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

  Host Sources:
    Host Catalog ID:          hcst_k9Ezh5xv0k
    ID:                       hsst_FWqrawz1hn

  Attributes:
    Default Port:             16001

Open a session to the postgres target using the Boundary Desktop App.

Open the Desktop App and enter http://127.0.0.1:9200 for the Cluster URL.

Desktop Cluster URL

Select the IT_Support scope in the upper-left corner of the app.

Navigate to the Targets view.

Boundary Desktop Targets

Click Connect beside the postgres target.

Connect to target

Copy the Proxy URL, such as 127.0.0.1:59801.

Next, open a new terminal session. Use the psql client to establish a session with the postgres container via the local proxy created by Boundary. Enter the password secret when prompted for the sampledb database password.

$ psql -h 127.0.0.1 -p 59801 -d sampledb -U postgres
Password for user postgres:
psql (14.2, server 15.1 (Debian 15.1-1.pgdg110+1))
WARNING: psql major version 14, server major version 15.
         Some psql features might not work.
Type "help" for help.

sampledb=#

Connect to postgres

Enter \q when finished to close the session, or cancel the session from the Desktop app.

From the Desktop app, select the postgres target to check its details.

Desktop target details

You should see the description Postgres target beneath the target name.

Targets can be managed using the Admin Console UI.

Open the Admin Console in your web browser and navigate to the Targets view.

Next, click the postgres target to view its details. Select Edit Form to update the target details.

Enter updated postgres target and click Save.

Open the Boundary Desktop app again and refresh the Targets view. You will see the updated postgres target description in the postgres target details.

Next steps

This tutorial demonstrated the steps to define and manage targets under a scope (QA_Tests). Targets represent network services a user can connect to, such as the postgres Docker container.

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

Manage scopes

Manage users and groups