Skip to main content
Acquisition complete HashiCorp officially joins the IBM family. Learn more
Boundary
Host management

Dynamic host catalogs on AWS

  • 20min
  • |
  • Boundary

Deployment

Dynamic updates to host catalogs distinguish Boundary from traditional access methods that rely on manual target configuration. Dynamic host catalogs enable integrations with major cloud providers for seamless onboarding of cloud tenant identities, roles, and targets.

Boundary supports automated discovery of target hosts and services for major cloud providers including Amazon Web Services (AWS), Microsoft Azure, and Google Cloud Platform (GCP). Dynamic connections to any service registry ensure that hosts and host catalogs are consistently up-to-date. This critical workflow offers access-on-demand and eliminates the need to manually configure targets for dynamic, cloud-based infrastructure.

In this tutorial you will configure a dynamic host catalog using Amazon Web Services.

Dynamic hosts catalog overview

  1. Get setup
  2. Dynamic host catalogs background
  3. Set up cloud hosts
  4. Build a host catalog
  5. Verify catalog membership

Prerequisites

  • A Boundary binary greater than 0.18.0 in your PATH

  • This tutorial assumes you can connect to an HCP Boundary cluster, a Boundary Enterprise cluster, or launch Boundary in dev mode.

  • An Amazon Web Services test account. This tutorial requires the creation of new cloud resources and will incur costs associated with the deployment and management of these resources.

  • Installing the AWS CLI provides an optional workflow for this tutorial. If you use the AWS CLI, CloudFormation must also be available within your PATH.

  • Installing Terraform 0.14.9 or greater provides an optional workflow for this tutorial. The binary must be available in your PATH.

Get setup

In this tutorial, you will test dynamic host catalog integrations using HCP Boundary, a Boundary Enterpise cluster, or by running a Boundary controller locally using dev mode. Select a tutorial Deployment option at the top of this page to proceed.

Dynamic host catalogs background

In a cloud operating model, infrastructure resources are highly dynamic and ephemeral. Boundary lacks an on-target agent or daemon, and cannot recognize when a host service migrates or is redeployed. Instead, Boundary relies on an external entity, such as manual configuration by an administrator or IaC (infrastructure as code) application like Terraform, to ensure host definitions route to the appropriate network location. Many other secure access solutions follow this pattern.

Dynamic host catalog plugins are an alternative way to automate the discovery and configuration of Boundary hosts and targets by delegating the host registry and their connection information to a cloud infrastructure provider. Administrators supply credentials for the catalog provider and a set of tag-based rules for discovering resources in the catalog. For example, "this catalog contains EC2 instance types in AWS’s us-west-2 region within the Marketing subscription". This model does not rely on IaC target discovery or agent-based target discovery.

Boundary uses Go-Plugin to implement a plugin model for expanding the dynamic host catalog ecosystem. Plugins enable a future ecosystem of partner and community contributed integrations across each step in the Boundary access workflow.

Host tag filtering

To maintain a dynamic host catalog, you should tag hosts in a logical way that enables sorting into host sets identifiable by filters.

For example, this tutorial configures hosts on AWS using the following tags:

Boundary hosts will be sorted into any host catalogs and host sets you configure using these filtering attributes.

AWS IAM credential types

You can select from dynamic credential or static credential types for setting up access to your AWS account.

  • Dynamic credentials use an IAM role.
  • Static credentials use IAM user account credentials.

HashiCorp recommends using dynamic credentials when possible to configure dynamic host catalogs. Select a credential type to continue.

Note

You must configure a self-managed Boundary worker to set up dynamic credentials.

Dynamic credentials use an AWS IAM role to generate credentials. This role must be assumed by a self-managed Boundary worker. Boundary uses this worker when setting up the dynamic host catalog and when syncing hosts from AWS.

This tutorial deploys a worker as part of the lab environment.

To set up dynamic credentials for this tutorial, you will:

  1. Deploy the hosts and worker using the provided lab environment.
  2. Register the self-managed Boundary worker deployed in AWS.
  3. Create an AWS IAM role with the AmazonEC2ReadOnlyAccess policy attached.
  4. Attach the role to the IAM instance you configured as a worker.
  5. Configure a Boundary dynamic host catalog.

Set up cloud hosts

Warning

This tutorial deploys cloud machines to test host catalog plugin configuration. You are responsible for any costs incurred by following the steps in this tutorial. Recommendations for destroying the associated cloud resources are detailed in the Cleanup and teardown section.

You need an Amazon Web Services account to set up the Boundary AWS host plugin.

This tutorial enables configuration of the test hosts using the AWS CLI, Terraform, or the AWS Console UI.

You will need access to an AWS account and sample application to set up the AWS hosts plugin for Boundary. If you don't have an account, sign up for AWS. A free account is suitable for the steps outlined in this tutorial, but please note that you are responsible for any charges incurred by following the steps in this tutorial.

This tutorial sets up permissions and hosts for host catalogs using the AWS CLI and CloudFormation.

You must complete the following tasks to set up hosts using the AWS CLI:

  1. Deploy and tag the host set members appropriately.
  2. Configure user permissions for Boundary.
  3. Configure the approriate IAM policy for dynamic or static credential types.

First, ensure to configure the AWS CLI with your account credentials. You will need the AWS Access Key, Secret Access Key, and (if needed) a Session Token.

You can set up the CLI in any of the following ways:

  • Execute aws configure and pass the access values.
  • Export the access values as environment variables.
  • Configure the AWS credentials file.

For more information on setting up the AWS CLI to interact with AWS, check the Configuring the AWS CLI documentation.

Create hosts

This tutorial deploys tagged hosts to test the dynamic host catalog integration.

To deploy a set of pre-configured hosts, a CloudFormation template file is available for use with AWS. CloudFormation is used to deploy the EC2 instances in this tutorial.

Clone the sample template repository.

$ git clone https://github.com/hashicorp-education/learn-boundary-cloud-host-catalogs

$ git clone https://github.com/hashicorp-education/learn-boundary-cloud-host-catalogs

Navigate into the aws directory.

$ cd learn-boundary-cloud-host-catalogs/aws/

$ cd learn-boundary-cloud-host-catalogs/aws/

The provided aws-dynamic-hosts.json template will be used to deploy a CloudFormation resource stack that contains the hosts to be included in our Boundary host catalog.

This tutorial uses the us-east-1a availability zone to deploy the EC2 instances, but you can use any region you want. To change the region, open the aws-dynamic-hosts.json file and update the AvailabilityZone.

Next, create a keypair to be used for the instances. Alternatively, you may open the aws-dynamic-hosts.json file and update the boundary-keypair to match the name of an existing EC2 keypair.

$ aws ec2 create-key-pair \
    --key-name boundary-keypair \
    --key-type rsa \
    --query "KeyMaterial" \
    --output text > boundary-keypair.pem

$ aws ec2 create-key-pair \
    --key-name boundary-keypair \
    --key-type rsa \
    --query "KeyMaterial" \
    --output text > boundary-keypair.pem

Note

The boundary-keypair.pem file was created within your working directory. You may need access to this keypair later on, so note its location and retain the private key for the duration of the tutorial. The tutorial deletes this keypair in the Cleanup and teardown section. If you choose to keep this keypair, consider moving it into another directory like ~/.aws/. Do not check this key into source control.

Ensure you are within the learn-boundary-cloud-host-catalogs/aws/ directory where the aws-dynamic-hosts.json file is located.

Deploy a new resource stack using the provided aws-dynamic-hosts.json template.

$ aws cloudformation create-stack \
  --stack-name boundary-dynamic-hosts \
  --template-body file://./aws-dynamic-hosts.json

$ aws cloudformation create-stack \
  --stack-name boundary-dynamic-hosts \
  --template-body file://./aws-dynamic-hosts.json

Example output:

$ aws cloudformation create-stack \
  --stack-name boundary-dynamic-hosts \
  --template-body file://./aws-dynamic-hosts.json
{
    "StackId": "arn:aws:cloudformation:us-east-1:157470686136:stack/boundary-dynamic-hosts/c29af940-78b6-11ec-849d-12bc7613d5b9"
}

$ aws cloudformation create-stack \
  --stack-name boundary-dynamic-hosts \
  --template-body file://./aws-dynamic-hosts.json
{
    "StackId": "arn:aws:cloudformation:us-east-1:157470686136:stack/boundary-dynamic-hosts/c29af940-78b6-11ec-849d-12bc7613d5b9"
}

The deployment may take a few minutes.

Check that the stack was successfully created.

$ aws cloudformation list-stacks
{
    "StackSummaries": [
        {
            "StackId": "arn:aws:cloudformation:us-east-1:157470686136:stack/boundary-dynamic-hosts/da9ebb30-78a7-11ec-bb47-0eddcb3d6bf3",
            "StackName": "boundary-dynamic-hosts",
            "TemplateDescription": "AWS CloudFormation template for Boundary Dynamic Hosts tutorial. Deploying this template will incur costs to your AWS account.",
            "CreationTime": "2022-01-18T22:43:11.249000+00:00",
            "StackStatus": "CREATE_COMPLETE",
            "DriftInformation": {
                "StackDriftStatus": "NOT_CHECKED"
            }
        }
    ]
}

$ aws cloudformation list-stacks
{
    "StackSummaries": [
        {
            "StackId": "arn:aws:cloudformation:us-east-1:157470686136:stack/boundary-dynamic-hosts/da9ebb30-78a7-11ec-bb47-0eddcb3d6bf3",
            "StackName": "boundary-dynamic-hosts",
            "TemplateDescription": "AWS CloudFormation template for Boundary Dynamic Hosts tutorial. Deploying this template will incur costs to your AWS account.",
            "CreationTime": "2022-01-18T22:43:11.249000+00:00",
            "StackStatus": "CREATE_COMPLETE",
            "DriftInformation": {
                "StackDriftStatus": "NOT_CHECKED"
            }
        }
    ]
}

Verify that the hosts were successfully created by printing their "Name" tag using aws ec2 describe-instances. The following command will only print running instances, and will also report the availability zone and instance ID in table format.

$ aws ec2 describe-instances \
  --output table \
  --filters Name=instance-state-name,Values=running \
  --filters Name=tag-key,Values=Name \
  --query 'Reservations[*].Instances[*].{Instance:InstanceId,AZ:Placement.AvailabilityZone,Name:Tags[?Key==`Name`]|[0].Value}'

$ aws ec2 describe-instances \
  --output table \
  --filters Name=instance-state-name,Values=running \
  --filters Name=tag-key,Values=Name \
  --query 'Reservations[*].Instances[*].{Instance:InstanceId,AZ:Placement.AvailabilityZone,Name:Tags[?Key==`Name`]|[0].Value}'

$ aws ec2 describe-instances \
  --output table \
  --filters Name=instance-state-name,Values=running \
  --filters Name=tag-key,Values=Name \
  --query 'Reservations[*].Instances[*].{Instance:InstanceId,AZ:Placement.AvailabilityZone,Name:Tags[?Key==`Name`]|[0].Value}'
----------------------------------------------------------------
|                       DescribeInstances                      |
+------------+-----------------------+-------------------------+
|     AZ     |       Instance        |          Name           |
+------------+-----------------------+-------------------------+
|  us-east-1a|  i-06f5a1240a2e0c3fb  |  boundary-3-production  |
|  us-east-1a|  i-0657b0de7662f9863  |  boundary-1-dev         |
|  us-east-1a|  i-0ac5cfcae66bdacf5  |  boundary-2-dev         |
|  us-east-1a|  i-0b6d3ad435c586783  |  boundary-4-production  |
|  us-east-1a|  i-0b5c5867836d3ad43  |  boundary-worker        |
+------------+-----------------------+-------------------------+

$ aws ec2 describe-instances \
  --output table \
  --filters Name=instance-state-name,Values=running \
  --filters Name=tag-key,Values=Name \
  --query 'Reservations[*].Instances[*].{Instance:InstanceId,AZ:Placement.AvailabilityZone,Name:Tags[?Key==`Name`]|[0].Value}'
----------------------------------------------------------------
|                       DescribeInstances                      |
+------------+-----------------------+-------------------------+
|     AZ     |       Instance        |          Name           |
+------------+-----------------------+-------------------------+
|  us-east-1a|  i-06f5a1240a2e0c3fb  |  boundary-3-production  |
|  us-east-1a|  i-0657b0de7662f9863  |  boundary-1-dev         |
|  us-east-1a|  i-0ac5cfcae66bdacf5  |  boundary-2-dev         |
|  us-east-1a|  i-0b6d3ad435c586783  |  boundary-4-production  |
|  us-east-1a|  i-0b5c5867836d3ad43  |  boundary-worker        |
+------------+-----------------------+-------------------------+

Configure IAM policy

Select from dynamic credential or static credential types for setting up access to your AWS account.

You configure Dynamic credentials using an IAM role. You can configure Static credentials with IAM user account credentials.

HashiCorp recommends using dynamic credentials when possible to configure dynamic host catalogs. Select a credential type to continue.

After configuring the self-managed AWS worker, you should next configure an IAM role with the AmazonEC2ReadOnlyAccess policy attached.

Configure an IAM role

Sign in to the AWS web console.

Navigate to the Identity and Access Management (IAM) dashboard.

Create a new role:

  1. Click on Roles, then click the New Role button.
  2. Under Trusted entity type, select AWS service.
  3. Under the Use case dropdown, select EC2. Then select the EC2 use case. Click Next. New role trused entity typeNew role trused entity type
  4. Search for the AmazonEC2ReadOnlyAccess policy, then select the checkbox beside it. Click Next. New role permissions policyNew role permissions policy
  5. Name the role, such as boundary-worker-dhc. Verify that the trust policy for Select trusted entities matches the following:
    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "sts:AssumeRole"
            ],
            "Principal": {
                "Service": [
                    "ec2.amazonaws.com"
                ]
            }
        }
    ]
}

    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "sts:AssumeRole"
            ],
            "Principal": {
                "Service": [
                    "ec2.amazonaws.com"
                ]
            }
        }
    ]
}
  6. Click Create role.

Assign the new role to the EC2 instance you configured as a worker:

  1. Navigate to the EC2 console.
  2. In the navigation pane, click Instances.
  3. Select the instance configured as the Boundary worker.
  4. Click Actions, then Security, then Modify IAM role.
  5. For IAM role, select the role name you configured, such as boundary-worker-dhc.
  6. Click Update IAM role.

Configure a Boundary worker

To configure a self-managed worker, you should gather the following from Boundary:

  • Cluster URL (Boundary address)
  • Auth method ID (from the Admin Console)
  • Admin login name and password

Visit the Getting Started on HCP tutorial if you need to locate any of these values.

The worker is deployed within your AWS account with access to the hosts you want to sync with Boundary.

This tutorial deploys a self-managed worker using Amazon Linux, but you can deploy a worker using a Linux, MacOS, Windows, BSD, or Solaris instance.

Warning

For the purposes of this tutorial the security group policy for the AWS worker instance accepts incoming TCP connections on port 9202 to allow Boundary client connections. For HCP and Enterprise users, multi-hop sessions can also provide access to network resources without allowing inbound connections to workers.

AWS Worker Security Group

Locate the worker auth token

You must register the worker with Boundary to route traffic through it and access your hosts.

When the worker is started it outputs its authorization request as Worker Auth Registration Request. This is saved to a file, auth_request_token, defined by the auth_storage_path in the worker configuration file.

First, locate the public IP address and private key of your self-managed worker.

Use the describe-instances command to locate the instance's public IP address:

$ aws ec2 describe-instances --filters "Name=tag:Name,Values=boundary-worker" --query 'Reservations[*].Instances[*].PublicIpAddress' --output text
32.218.141.47

$ aws ec2 describe-instances --filters "Name=tag:Name,Values=boundary-worker" --query 'Reservations[*].Instances[*].PublicIpAddress' --output text
32.218.141.47

The private key for the worker instance should match the keypair you created or supplied in the aws-dynamic-hosts.yaml config file for CloudFormation. Locate your copy of the boundary-keypair.pem private key to log into the worker instance.

Substitute the worker public IP address and path to your worker's private key in the following command. This will print the auth_request_token by fetching its value from the worker using its SSH credentials:

$ ssh ec2-user@<WORKER_PUBIC_IP> -i worker_private_key.pem "cat /boundary-worker/config/worker_auth_token"
The authenticity of host '3.218.141.47 (3.218.141.47)' can't be established.
ED25519 key fingerprint is SHA256:07W+OOT7+Klh3EBpDfzWmZd9jEm7zCUoRzCztuKJlwo.
This key is not known by any other names.
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
Warning: Permanently added '3.218.141.47' (ED25519) to the list of known hosts.
GzusqckarbczHoLGQ4UA25uSR5BjuYpKpJcLt9zu2StdyMoiyRJwkZXTHZAwk2JLFfVkMy3qcBDEqMsdMYCYX3DJafMc6za9R6N9nSZcPyerGWD9wXs71CY7VtBbtxnFBsnGJHK562XcDexZHT5M8GqA7W2j7cJyqVHwSBgnSddqi59HEVG8oMpyJCBETT3FNrMyTCkw22tL5FMpbX6b8t4xTkLZNB8iwscCJnaQ7BLMUfcpbMXGLahtNvk3jtZWJMyeQEn8ym51ewmxNwvtvZahNFzemMrYSQTB3aXqu

$ ssh ec2-user@<WORKER_PUBIC_IP> -i worker_private_key.pem "cat /boundary-worker/config/worker_auth_token"
The authenticity of host '3.218.141.47 (3.218.141.47)' can't be established.
ED25519 key fingerprint is SHA256:07W+OOT7+Klh3EBpDfzWmZd9jEm7zCUoRzCztuKJlwo.
This key is not known by any other names.
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
Warning: Permanently added '3.218.141.47' (ED25519) to the list of known hosts.
GzusqckarbczHoLGQ4UA25uSR5BjuYpKpJcLt9zu2StdyMoiyRJwkZXTHZAwk2JLFfVkMy3qcBDEqMsdMYCYX3DJafMc6za9R6N9nSZcPyerGWD9wXs71CY7VtBbtxnFBsnGJHK562XcDexZHT5M8GqA7W2j7cJyqVHwSBgnSddqi59HEVG8oMpyJCBETT3FNrMyTCkw22tL5FMpbX6b8t4xTkLZNB8iwscCJnaQ7BLMUfcpbMXGLahtNvk3jtZWJMyeQEn8ym51ewmxNwvtvZahNFzemMrYSQTB3aXqu

Note the Worker Auth Registration Request: value in the output. You can also find this value in the /boundary/auth_request_token file on the worker. Copy this value.

Register the worker

Authenticate to the Boundary Admin UI as the admin user.

Enter the admin username and password and click Authenticate.

Once logged in, navigate to the Workers page.

Click New.

You can use the new workers page to construct the contents of the worker.hcl file.

Do not fill in any of the worker fields.

Providing the following details will construct the worker config file contents for you:

  • Worker public address
  • Config file path
  • Worker tags

The instructions on this page provide details for installing the Boundary Enterprise binary and deploying the constructed config file.

Because the worker has already been deployed, only the Worker Auth Registration Request key needs to be provided on this page.

Scroll down to the bottom of the New Worker page and paste the Worker Auth Registration Request key you copied earlier.

Click Register Worker.

Register worker with auth token Register worker with auth token

Click Done and notice the new worker on the Workers page.

Workers page with local worker Workers page with local worker

Troubleshooting missing worker details

The worker's Tags should be updated on the Workers page within about a minute.

If these tags are missing, click the Refresh button and check again.

If they are still missing, locate your worker's public IP address, then restart the worker service:

$ ssh ec2-user@<WORKER_PUBLIC_IP_ADDRESS> -i worker_private_key.pem "sudo systemctl restart boundary-worker.service"

$ ssh ec2-user@<WORKER_PUBLIC_IP_ADDRESS> -i worker_private_key.pem "sudo systemctl restart boundary-worker.service"

Then click the Refresh button again and verify that the tags exist. Clicking on the worker's ID will display the worker's details page, which also reports when the worker was last seen.

Host catalog plugins

For Boundary, the process for creating a dynamic host catalog has two steps:

  1. Create a plugin-type host catalog
  2. Create a host set that defines membership using filters

A plugin-type host catalog can be created using some cloud provider resource details, and the host set is then defined using a filter that selects hosts for membership based on the tags defined when you set up the hosts.

Host set filter expressions are defined by the plugin provider, in this case AWS. The AWS plugin uses simple filter queries to specify tags associated with hosts based on tag:Name=Value.

For example, a host set filter that selects all hosts tagged with "service-type": "database" is written as:

tag:service-type=database

Resources within AWS can generally be filtered by tag names and values, and filters can be designed to use either/or selectors for tag values. This process is described in the Boundary AWS Host Plugin documentation.

To learn more about AWS filters for listing resources, visit the describe-instances CLI documentation page and the Describe Instances AWS EC2 API docs.

Build a host catalog

With the cloud provider details gathered, you can create a plugin host catalog that will contain the host sets for the database and application filters.

Create a host catalog plugin

  1. Authenticate to the Boundary Admin UI as the admin user.

  2. Once logged in, select the org and project you want to create a dynamic host catalog for.

  3. Navigate to the Host Catalogs page. Click New Host Catalog.

  4. Select Dynamic for the host catalog type. Select from the static or dynamic credential type tabs to learn how you should fill out the new catalog form.

Complete the following fields:

  • Name: AWS Catalog

  • Description: AWS host catalog

  • Type: Dynamic

  • Provider: AWS

  • AWS Region: us-east-1 (or other appropriate region)

  • Credential type: (Required) Select the type of credential you want to use to authenticate to the host catalog. The required fields for configuring the host catalog vary depending on whether you configure static or dynamic credentials:

    • Use an access key (Static Credentials): Authenticates to the host catalog using an access key that you generate in AWS.
    • Use Assume Role (Dynamic Credentials): Authenticates to the host catalog using credentials that AWS AssumeRole generates.
    • Role ARN: YOUR_IAM_ROLE_ARN
    • Role external ID: YOUR_IAM_ROLE_EXTERNAL_ID
    • Worker Filter: "aws" in "/tags/cloud"
    • Disable credential rotation: true Credential rotation must be disabled when you use dynamic credentials.

    When you create a host catalog, it's important that the worker filter you define matches a filter expression for your AWS worker. In the Deploy a worker section, you deployed a worker with the following tags:

    tags {
    "Name":"boundary-worker","service-type":"worker","cloud":"aws"
  }

    tags {
    "Name":"boundary-worker","service-type":"worker","cloud":"aws"
  }

    When you configure the host catalog, Boundary will use any available worker to attempt to refresh the catalog, unless you specify which worker should be used.

    An appropriate filter expression to select this worker can select its tags:

    "aws" in "/tags/cloud"

    You can also select the correct worker using other filter expressions. To learn more, refer to the Worker tags documentation.

Create the host sets

With the dynamic host catalog created, host sets can now be defined that correspond to the service-type and application tags added to the hosts.

Recall the three host sets we wish to create:

  • All hosts with a service-type tag of database
  • All hosts with an application tag of dev
  • All hosts with an application tag of production

The respective host set filters can be constructed as:

  1. Authenticate to the Boundary Admin UI as the admin user.

  2. Once logged in, select the org and project that contains your dynamic host catalog.

  3. Navigate to the Host Catalogs page. Click on the AWS Catalog.

  4. Click the Host Sets tab. Click the New button to create a new host set.

    Complete the following fields:

    • Name: database
    • Filter: tag:service-type=database

  5. Click Add beside the filter field to add the filter.

  6. Click Save.

Wait a moment, then click on the Hosts tab, which should contain the following hosts:

  • boundary-1-dev
  • boundary-2-dev
  • boundary-3-production
  • boundary-4-production

Note

It may take up to five minutes for the host catalog to sync with the cloud provider. Refresh the page if the hosts do not initially appear in the catalog.

Now follow the same steps to create two more host sets for the following host set filters:

  1. The dev host set.

    • Name: dev
    • Filter: tag:application=dev

  2. The production host set.

    • Name: production
    • Filter: tag:application=production

Check the hosts that are included in these host sets and move on to the next section.

Verify catalog membership

With the database, dev, and prod host sets defined within the AWS host catalog, the next step is to verify that the four instances listed as members of the catalog are dynamically included in the correct host sets.

Host membership can be verified by reading the host set details and verifying its membership IDs.

Check the database host set

First, verify that the database host set contains all four members of the aws host catalog.

  1. Navigate to the Host Catalogs page and click on the AWS Catalog.

  2. Click on the Host Sets tab.

  3. Click on the Database Host Set host set, then click on the Hosts tab.

  4. Verify the host set contains the following hosts:

  • boundary-1-dev
  • boundary-2-dev
  • boundary-3-production
  • boundary-4-production

If any of these hosts are missing, expand the troubleshooting accordion to diagnose what could be wrong.

If the host catalog is misconfigured, hosts will not be discoverable by Boundary.

At this point in the tutorial hosts are contained within the host catalog, but not appearing in one or more host sets. This means that the host set itself is likely misconfigured.

Navigate to the database host set Details page. Check the Filter section, and verify it matches the correctly defined filter:

tag:service-type=database

If the tag is incorrectly assigned, you should update the affected host set to fix the filter by clicking the Edit button.

After you update the filter, click Save. Boundary will automatically refresh the host set.

Note

Depending on the type of configuration issue, you will need to wait approximately 5 - 10 minutes for the existing host catalog or host sets to sync with the provider and refresh their values. If you do not want to wait, you can create a new host catalog and host set from scratch, but these will also take several minutes to sync upon creation.

Check that the updated filter is working by navigating back to the Hosts tab.

If the dev or production host sets are affected by incorrect filters, follow the same procedure to update their filters accordingly.

Check the dev host set

Next, check the dev host set members.

  1. Navigate to the Host Catalogs page and click on the AWS Catalog.

  2. Click on the Host Sets tab.

  3. Click on the Dev Host Set host set, then click on the Hosts tab.

  4. Verify the host set contains the following hosts:

  • boundary-1-dev
  • boundary-2-dev

If any of these hosts are missing, expand the troubleshooting accordion above to diagnose what could be wrong.

Check the production host set

Lastly, check the production host set members.

  1. Navigate to the Host Catalogs page and click on the AWS Catalog.

  2. Click on the Host Sets tab.

  3. Click on the Production Host Set host set, then click on the Hosts tab.

  4. Verify the host set contains the following host:

  • boundary-3-production

Notice the Host IDs section of this output. Even though there are two production instances, only one is listed in the host set.

To figure out what could be wrong, compare the members of the production host set to the members of the database host set. Remember, members of the production and dev host sets are a subset of the database host set.

For example, by comparing the Host IDs of the dev host catalog to the production catalog, a host ID such as hplg_7KjFRrcLxD should be missing from the production host set, although it is contained within the database host set.

Update the misconfigured host

Check the details for the missing host using the CLI or the AWS Console.

$ boundary hosts read -id hplg_7KjFRrcLxD

Host information:
  Created Time:        Tue, 18 Jul 2023 10:37:22 MDT
  External ID:         i-08c588f2d58120192
  Host Catalog ID:     hcplg_Ia7R4E39oF
  ID:                  hplg_7KjFRrcLxD
  Type:                plugin
  Updated Time:        Tue, 18 Jul 2023 10:37:22 MDT
  Version:             1

  Scope:
    ID:                p_1234567890
    Name:              Generated project scope
    Parent Scope ID:   o_1234567890
    Type:              project

  Plugin:
    ID:                pl_1PRTDb78iY
    Name:              aws

  Authorized Actions:
    no-op
    read

  Host Set IDs:
    hsplg_qnQM03I6yT

  IP Addresses:
    172.31.71.39
    3.239.215.108

  DNS Names:
    ec2-3-239-215-108.compute-1.amazonaws.com
    ip-172-31-71-39.ec2.internal

$ boundary hosts read -id hplg_7KjFRrcLxD

Host information:
  Created Time:        Tue, 18 Jul 2023 10:37:22 MDT
  External ID:         i-08c588f2d58120192
  Host Catalog ID:     hcplg_Ia7R4E39oF
  ID:                  hplg_7KjFRrcLxD
  Type:                plugin
  Updated Time:        Tue, 18 Jul 2023 10:37:22 MDT
  Version:             1

  Scope:
    ID:                p_1234567890
    Name:              Generated project scope
    Parent Scope ID:   o_1234567890
    Type:              project

  Plugin:
    ID:                pl_1PRTDb78iY
    Name:              aws

  Authorized Actions:
    no-op
    read

  Host Set IDs:
    hsplg_qnQM03I6yT

  IP Addresses:
    172.31.71.39
    3.239.215.108

  DNS Names:
    ec2-3-239-215-108.compute-1.amazonaws.com
    ip-172-31-71-39.ec2.internal

The External ID: field shows the ID of the misconfigured host (i-08c588f2d58120192 in this example). Copy this value.

Recall that host set membership is defined based on the instance tags.

Describe the instance's details, and query for its tag values.

$ aws ec2 describe-instances \
  --instance-ids i-08c588f2d58120192 \
  --output table \
  --query 'Reservations[*].Instances[*].Tags[?contains(Key, `aws`) == `false`]'

$ aws ec2 describe-instances \
  --instance-ids i-08c588f2d58120192 \
  --output table \
  --query 'Reservations[*].Instances[*].Tags[?contains(Key, `aws`) == `false`]'

Sample output:

$ aws ec2 describe-instances \
  --instance-ids i-08c588f2d58120192 \
  --output table \
  --query 'Reservations[*].Instances[*].Tags[?contains(Key, `aws`) == `false`]'

-------------------------------------------
|            DescribeInstances            |
+---------------+-------------------------+
|      Key      |          Value          |
+---------------+-------------------------+
|  service-type |  database               |
|  Name         |  boundary-4-production  |
|  application  |  prod                   |
+---------------+-------------------------+

$ aws ec2 describe-instances \
  --instance-ids i-08c588f2d58120192 \
  --output table \
  --query 'Reservations[*].Instances[*].Tags[?contains(Key, `aws`) == `false`]'

-------------------------------------------
|            DescribeInstances            |
+---------------+-------------------------+
|      Key      |          Value          |
+---------------+-------------------------+
|  service-type |  database               |
|  Name         |  boundary-4-production  |
|  application  |  prod                   |
+---------------+-------------------------+

Notice that the application tag is misconfigured as prod, instead of production. An easy mistake to make!

Remember the filter defined for the production host set:

tag:application=production

The tag's value must equal production exactly to be included in this host set.

Update the application tag to production for the misconfigured instance using the aws ec2 create-tags command, which will overwrite the existing tag value.

$ aws ec2 create-tags --resources i-08c588f2d58120192 --tags Key=application,Value=production

$ aws ec2 create-tags --resources i-08c588f2d58120192 --tags Key=application,Value=production

Re-run the describe-instances command to directly query for the updated tag values.

Sample output:

$ aws ec2 describe-instances \
  --instance-ids i-08c588f2d58120192 \
  --output table \
  --query 'Reservations[*].Instances[*].Tags[?contains(Key, `aws`) == `false`]'

-------------------------------------------
|            DescribeInstances            |
+---------------+-------------------------+
|      Key      |          Value          |
+---------------+-------------------------+
|  application  |  production             |
|  service-type |  database               |
|  Name         |  boundary-4-production  |
+---------------+-------------------------+

$ aws ec2 describe-instances \
  --instance-ids i-08c588f2d58120192 \
  --output table \
  --query 'Reservations[*].Instances[*].Tags[?contains(Key, `aws`) == `false`]'

-------------------------------------------
|            DescribeInstances            |
+---------------+-------------------------+
|      Key      |          Value          |
+---------------+-------------------------+
|  application  |  production             |
|  service-type |  database               |
|  Name         |  boundary-4-production  |
+---------------+-------------------------+

Boundary will update the production host set automatically the next time it refreshes. This process could take up to ten minutes.

After waiting, navigate back to the production host set and verify that its Hosts tab contains the boundary-4-production host as a member.

Cleanup and teardown

  1. Delete the CloudFormation boundary-dynamic-hosts stack

    $ aws cloudformation delete-stack --stack-name boundary-dynamic-hosts

    $ aws cloudformation delete-stack --stack-name boundary-dynamic-hosts

    Wait a minute, then check that the StackStatus has changed to DELETE_COMPLETE.

    $ aws cloudformation list-stacks
{
  "StackSummaries": [
      {
          "StackId": "arn:aws:cloudformation:us-east-1:157470686136:stack/boundary-dynamic-hosts/05ea64a0-7bbf-11ec-9531-120baac28e1f",
          "StackName": "boundary-dynamic-hosts",
          "TemplateDescription": "AWS CloudFormation template for Boundary Dynamic Hosts tutorial. Deploying this template will incur costs to your AWS account.",
          "CreationTime": "2022-01-22T20:08:11.060000+00:00",
          "DeletionTime": "2022-01-22T21:22:37.577000+00:00",
          "StackStatus": "DELETE_COMPLETE",
          "DriftInformation": {
              "StackDriftStatus": "NOT_CHECKED"
          }
      }
  ]
}

    $ aws cloudformation list-stacks
{
  "StackSummaries": [
      {
          "StackId": "arn:aws:cloudformation:us-east-1:157470686136:stack/boundary-dynamic-hosts/05ea64a0-7bbf-11ec-9531-120baac28e1f",
          "StackName": "boundary-dynamic-hosts",
          "TemplateDescription": "AWS CloudFormation template for Boundary Dynamic Hosts tutorial. Deploying this template will incur costs to your AWS account.",
          "CreationTime": "2022-01-22T20:08:11.060000+00:00",
          "DeletionTime": "2022-01-22T21:22:37.577000+00:00",
          "StackStatus": "DELETE_COMPLETE",
          "DriftInformation": {
              "StackDriftStatus": "NOT_CHECKED"
          }
      }
  ]
}

  2. Delete the boundary-keypair EC2 keypair.

    $ aws ec2 delete-key-pair --key-name boundary-keypair

    $ aws ec2 delete-key-pair --key-name boundary-keypair

  3. Delete the boundary user access key.

    Before you delete the boundary user, you must delete all items attached to the user. For more information on deleting an IAM user, check the User Guide docs.

    First list the boundary user access keys.

    $ aws iam list-access-keys --user-name boundary
{
  "AccessKeyMetadata": [
      {
          "UserName": "boundary",
          "AccessKeyId": "AKIASWVU2XLZLFLIDMVW",
          "Status": "Active",
          "CreateDate": "2022-01-19T02:26:11+00:00"
      }
  ]
}

    $ aws iam list-access-keys --user-name boundary
{
  "AccessKeyMetadata": [
      {
          "UserName": "boundary",
          "AccessKeyId": "AKIASWVU2XLZLFLIDMVW",
          "Status": "Active",
          "CreateDate": "2022-01-19T02:26:11+00:00"
      }
  ]
}

    Copy the AccessKeyId value (AKIASWVU2XLZLFLIDMVW in this example).

    Now delete the access key.

    $ aws iam delete-access-key --user-name boundary --access-key-id AKIASWVU2XLZLFLIDMVW

    $ aws iam delete-access-key --user-name boundary --access-key-id AKIASWVU2XLZLFLIDMVW

  4. Delete the BoundaryDescribeInstances policy.

    $ aws iam delete-user-policy --user-name boundary --policy-name BoundaryDescribeInstances

    $ aws iam delete-user-policy --user-name boundary --policy-name BoundaryDescribeInstances

  5. Delete the boundary IAM user.

    $ aws iam delete-user --user-name boundary

    $ aws iam delete-user --user-name boundary

  6. Stop Boundary

Next steps

This tutorial demonstrated the steps to set up a dynamic host catalog using the AWS host plugin. You deployed and tagged hosts within AWS, configured a plugin-type host catalog within Boundary, and created three host sets that filtered for the hosts based on their tag values.

To learn more about integrating Boundary with cloud providers like AWS and Azure, check out the OIDC Authentication tutorial.

Previous

Worker-aware targets

 Next

Dynamic host catalogs on Azure

Deployment