---
layout: docs
page_title: AWS dynamic host catalogs
description: >-
  Use dynamic host catalogs to automatically discover AWS EC2 instances and add them as hosts. Create a host catalog and host set for AWS resources.
---

⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️
> [!IMPORTANT]  
> **Documentation Update:** Product documentation previously located in `/website` has moved to the [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs) repository, where all product documentation is now centralized. Please make contributions directly to `web-unified-docs`, since changes to `/website` in this repository will not appear on developer.hashicorp.com.
⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️
# AWS dynamic host catalogs
Boundary uses dynamic host catalogs to automatically discover AWS EC2 instances and add them as hosts.

## Create a host catalog to connect with AWS
Boundary uses plugins to integrate with a variety of providers. To use
a dynamic host catalog to integrate with AWS, you create a host catalog of the `plugin` type
and set the `plugin-name` value to `aws`. You must also provide the specific
fields needed for Boundary to authenticate with AWS.

Boundary supports two methods of authenticating to AWS:

1. **Static credentials** using an IAM user and its access key
1. **Dynamic credentials** using credentials generated by `AssumeRole`

HashiCorp recommends using dynamic credentials when possible. Select a credential type to continue:

<Tabs>
<Tab heading="Static credentials" group="static">

### Required IAM Privileges

Boundary needs the following IAM privileges, at the very least, to be attached to a configured IAM user.

Configure `DescribeInstances` to `*`. `DescribeInstances` cannot be scoped to a resource ARN.

Example policy:

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
        "ec2:DescribeInstances"
      ],
      "Effect": "Allow",
      "Resource": "*"
    }
  ]
}
```

To allow static credential rotation, add the `iam:GetUser`, `iam:CreateAccessKey`, and `iam:DeleteAccessKey` policies:

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
        "iam:DeleteAccessKey",
        "iam:GetUser",
        "iam:CreateAccessKey"
      ],
      "Effect": "Allow",
      "Resource": "arn:aws:iam::123456789012:user/JohnDoe"
    }
  ]
}
```

</Tab>
<Tab heading="Dynamic credentials" group="dynamic">

<Note>

  [Cross-account access](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies-cross-account-resource-access.html) for AWS IAM roles is not currently supported.

</Note>

This feature requires a self-managed Boundary [worker](/boundary/docs/deploy/self-managed/deploy-workers).

To set up a dynamic host catalog using an AWS role, a self-managed worker must assume the role. You must assign the role to the self-managed worker AWS instance, and then supply a worker filter that matches the AWS worker when you set up the dynamic host catalog.

Perform the following steps to set up a host catalog using [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html):

1. Deploy a self-managed worker in your AWS account. The worker must be in the same VPC as the hosts you want to access using the dynamic host catalog. Consider [adding worker tags](/boundary/docs/workers/worker-tags) to make it easier to route traffic through it using a worker filter later on.

1. Create an IAM role with the `AmazonEC2ReadOnlyAccess` policy attached, or define a custom policy with the `ec2:DescribeInstances` action allowed for all resources. This policy should contain the following, at least:

   ```json
   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Action": [
           "ec2:DescribeInstances"
         ],
         "Effect": "Allow",
         "Resource": "*"
       }
     ]
   }
   ```

   Refer to the AWS [Create a role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html) documentation to learn more.

1. Attach the role to the IAM instance configured as your self-managed worker. Follow the AWS [Attach an IAM role to an instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/attach-iam-role.html) to learn more.

1. Continue to the next step to set up the dynamic host catalog. You must add a worker tag when setting up the host catalog to route traffic through the worker that is assuming the role.

</Tab>
</Tabs>

Complete the following steps to create a dynamic host catalog for AWS:

<Tabs>
<Tab heading="UI" group="ui">

1. Log in to Boundary.
1. Select the org, and then select the project you want to create a host catalog for.
1. Select **Host Catalogs**.
1. Select **New Host Catalog**.
1. Complete the following fields:
   - **Name**: (Optional) An optional name for identification purposes.
   If you enter a name, it must be unique.
   - **Description**: (Optional) An optional description of the host catalog for identification purposes.
   - **Type**: (Required) Select **Dynamic** to create a dynamic host catalog.
   - **Provider**: (Required) Select **AWS** to create a dynamic host catalog for your AWS resources.
   - **AWS Region**: (Required) Enter the AWS region of the hosts you want to add to the host catalog.
   - **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.

  <Tabs>
  <Tab heading="Static credentials" group="static">

    - **Access Key ID**: (Required) The access key ID for the IAM user to use with this host catalog.
    - **Secret Access Key**: (Required) The secret access key for the IAM user to use with this host catalog.
    - **Worker Filter**: (Optional) An optional filter to route requests to a designated worker.

  </Tab>
  <Tab heading="Dynamic credentials" group="dynamic">

    - **Role ARN**: (Required) - The AWS role ARN to use for `AssumeRole` authentication.
    If you provide a `role_arn` value, you must also set `disable_credential_rotation` to `true`.
    - **Role external ID**: (Optional) - The external ID for the `AssumeRole` provider.
    - **Role session name**: (Optional) - The session name for the `AssumeRole` provider.
    - **Role tags**: (Optional) - The key-value pair tags for the `AssumeRole` provider.
    - **Worker Filter**: (Optional) - An optional filter to route requests to a designated worker. The filter should match the worker assigned the IAM role.
    - **Disable credential rotation**: - When enabled, Boundary does not rotate the credentials with AWS automatically.
    Credential rotation is automatically disabled when you use dynamic credentials.

  </Tab>
  </Tabs>

1. Select **Save**.

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

The required fields for creating a dynamic host catalog depend on whether you configure static or dynamic credentials.

<Tabs>
<Tab heading="Static credentials" group="static">

1. Log in to Boundary.
1. Use the following command to create a dynamic host catalog for AWS using static credentials:

   ```shell-session
   $ boundary host-catalogs create plugin \
     -scope-id $BOUNDARY_PROJECT_ID \
     -plugin-name aws \
     -attr disable_credential_rotation=true \
     -attr region=us-east-1 \
     -secret access_key_id=env://AWS_ACCESS_KEY_ID \
     -secret secret_access_key=env://AWS_SECRET_ACCESS_KEY
   ```

  The `scope-id` and `plugin-name` fields are required when you create a
  dynamic host catalog.

  The fields following the `attr` and `secret` flags are specific to AWS and are required by
  Boundary for authentication.
  Replace the values in the command with the following required AWS secrets and any attributes you want to associate with the host catalog:

    - `disable_credential_rotation`: When set to `true`, Boundary does not rotate the credentials with AWS automatically.
    - `region`: The region to configure the host catalog for. All host sets in this catalog are configured for this region.
    - `access_key_id`: The access key ID for the IAM user to use with this host catalog.
    - `secret_access_key`: The secret access key for the IAM user to use with this host catalog.

  Refer to the [host catalogs](/boundary/docs/domain-model/host-catalogs) domain model documentation for additional fields that you can use when you create host catalogs.

</Tab>

<Tab heading="Dynamic credentials" group="dynamic">

1. Log in to Boundary.
1. Use the following command to create a dynamic host catalog using dynamic credentials:

  ```shell-session
  $ boundary host-catalogs create plugin \
    -scope-id $BOUNDARY_PROJECT_ID \
    -plugin-name aws \
    -attr disable_credential_rotation=true \
    -attr region=us-east-1 \
    -attr role_arn=AWS_ROLE_ARN_VALUE \
    -attr role_external_id=AWS_ROLE_EXTERNAL_ID_VALUE \
    -attr role_session_name=AWS_ROLE_SESSION_NAME_VALUE \
    -attr role_tags=AWS_ROLE_TAGS_VALUE \
    -worker-filter '"aws" in "/tags/type"'
    ```

  The `scope-id` and `plugin-name` fields are required when you create a dynamic host catalog.

  Replace the values in the command with the following required AWS secrets and any attributes you want to associate with the host catalog:

    - `disable_credential_rotation`: When set to `true`, Boundary does not rotate the credentials with AWS automatically.
    You must disable credential rotation to use dynamic credentials.
    - `region`: The region to configure the host catalog for. All host sets in this catalog will be configured for this region.
    - `role_arn`: The AWS role ARN used for `AssumeRole` authentication. If you provide a `role_arn` value, you must also set `disable_credential_rotation` to `true`.
    - `role_external_id`: The external ID that you configured for the `AssumeRole` provider.
    - `role_session_name`: The session name that you configured for the `AssumeRole` provider.
    - `role_tags`: The key-value pair tags that you configured for the `AssumeRole` provider.
    - `worker-filter` A boolean expression to filter which workers can handle dynamic host catalog commands for this host catalog. This should match a valid filter expression for the self-managed worker deployed in AWS. Refer to worker [Filter examples](/boundary/docs/workers/worker-tags#filter-workers-using-tags) to learn more.

  Refer to the [host catalogs](/boundary/docs/domain-model/host-catalogs) domain model documentation for additional fields that you can use when you create host catalogs.

</Tab>
</Tabs>

</Tab>

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

The required fields for creating a dynamic host catalog depend on whether you configure static or dynamic credentials.

Refer to the [Boundary Terraform provider documentation](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs) to learn about the requirements for the following example attributes.

<Tabs>
<Tab heading="Static credentials" group="static">

Apply the following Terraform policy:

  ```hcl
  resource "boundary_host_catalog_plugin" "aws_host_catalog" {
    name          = "AWS Catalog"
    description   = "AWS Host Catalog"
    scope_id      = boundary_scope.project.id
    plugin_name   = "aws"

    # recommended to pass in aws secrets using a file() or using environment variables
    attributes_json = jsonencode({
      "region" = "eu-west-2",
      "disable_credential_rotation" = true })
    secrets_json = jsonencode({
      "access_key_id" = "AWS_ACCESS_KEY_ID_VALUE",
      "secret_access_key" = "AWS_SECRET_ACCESS_KEY_VALUE"})
  }
  ```

The `scope_id` and `plugin_name` fields are required when you create a dynamic host catalog.

Replace the values in the configuration with the following required AWS secrets and any attributes you want to associate with the host catalog:

  - `disable_credential_rotation`: When set to `true`, Boundary does not rotate the credentials with AWS automatically.
  - `region`: The region to configure the host catalog for. All host sets in this catalog are configured for this region.
  - `access_key_id`: The access key ID for the IAM user to use with this host catalog.
  - `secret_access_key`: The secret access key for the IAM user to use with this host catalog.

Refer to the [host catalogs](/boundary/docs/domain-model/host-catalogs) domain model documentation for additional fields that you can use when you create host catalogs.

</Tab>
<Tab heading="Dynamic credentials" group="dynamic">

Apply the following Terraform policy:

  ```hcl
  resource "boundary_host_catalog_plugin" "aws_host_catalog" {
    name        = "AWS Catalog"
    description = "AWS Host Catalog"
    scope_id    = boundary_scope.project.id
    plugin_name = "aws"
    worker_filter = "\"aws\" in \"/tags/type\""

    attributes_json = jsonencode({
      "region" = "eu-west-2",
      "disable_credential_rotation" = true,
      "role_arn" = "AWS_ROLE_ARN_VALUE",
      "role_external_id" = "AWS_ROLE_EXTERNAL_ID_VALUE",
      "role_session_name" = "AWS_ROLE_SESSION_NAME_VALUE",
      "role_tags" = "AWS_ROLE_TAGS_VALUE"
    })
  }
  ```

The `scope_id` and `plugin_name` fields are required when you create a dynamic host catalog.

Replace the values in the configuration with the following required AWS secrets and any attributes you want to associate with the host catalog:

  - `worker_filter`: A boolean expression to filter which workers can handle dynamic host catalog commands for this host catalog. This should match a valid filter expression for the self-managed worker deployed in AWS. Refer to worker [Filter examples](/boundary/docs/workers/worker-tags#filter-workers-using-tags) to learn more.
  - `disable_credential_rotation`: When set to `true`, Boundary does not rotate the credentials with AWS automatically.
  You must disable credential rotation to use dynamic credentials.
  - `region`: The region to configure the host catalog for. All host sets in this catalog are configured for this region.
  - `role_arn`: The AWS role ARN used for `AssumeRole` authentication. If you provide a `role_arn` value, you must also set `disable_credential_rotation` to `true`.
  - `role_external_id`: The external ID that you configured for the `AssumeRole` provider.
  - `role_session_name`: The session name that you configured for the `AssumeRole` provider.
  - `role_tags`: The key-value pair tags that you configured for the `AssumeRole` provider.

Refer to the [host catalogs](/boundary/docs/domain-model/host-catalogs) domain model documentation for additional fields that you can use when you create host catalogs.

</Tab>
</Tabs>

</Tab>
</Tabs>

## Create a host set to connect with AWS

[Host sets](/boundary/docs/domain-model/host-sets) specify which AWS filters should be used to identify the discovered hosts that should be added as members.

Complete the following steps to create a host set:

<Tabs>
<Tab heading="UI" group="ui">

1. Log in to Boundary.
1. Select the org, and then select the project you want to create a host set for.
1. Select **Host Catalogs**.
1. Select the dynamic host catalog to which you want add a host set.
1. Click the **Host Sets** tab, and then click **New**.
1. Complete the following fields:
    - **Name**: (Optional) An optional name for identification purposes.
    If you enter a name, it must be unique.
    - **Description**: (Optional) An optional description of the host catalog for identification purposes.
1. Click **Save**.

</Tab>

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

1. Log in to Boundary.
1. Use the following command to create a host set:

  ```shell-session
  $ boundary host-sets create plugin \
    -host-catalog-id $BOUNDARY_HOST_CATALOG_ID \
    -attr filters=tag-key=foo,bar \
    -attr filters=tag-key=baz
  ```

  The `host-catalog-id` value is a required field that specifies in which host catalog to create this host set.

  Like with the host catalog, the fields passed in after the `attr` flag are specific to AWS.

  The `filters` field contains string filters in the format key=val1,val2. The key corresponds to a filter option, and the value(s) are a comma-separated list.
  For a list of filter options, refer to the [describe-instances in the AWS CLI reference](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html).

  When the values in a single `filters` field are separated by a comma, either can be true for the host to match.
  When multiple filters fields are provided, they must all match for a host to match.
  In the example above, an instance must have either tags `foo` or `bar`, and must have the tag `baz`.

  Refer to the [host catalogs](/boundary/docs/domain-model/host-catalogs) domain model documentation for additional fields that you can use when you create host catalogs.

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

Apply the following Terraform policy:

```hcl
resource "boundary_host_set_plugin" "aws_host_set" {
  name        = "AWS Host Set"
  description = "AWS Host Set"
  host_catalog_id  = boundary_host_catalog_plugin.aws_host_catalog.id
  attributes_json = jsonencode({
  "filters" = ["tag-key=foo,bar", "tag-key=baz"] })
}
```

The `host_catalog_id` value is a required field that specifies in which host catalog to create this host set.

The `filters` field contains string filters in the format key=val1,val2.
The key corresponds to a filter option, and the value(s) are a comma-separated list.
For a list of filter options, refer to the [describe-instances in the AWS CLI reference](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html).

When the values in a single `filters` field are separated by a comma, either can be true for the host to match.
When multiple filters fields are provided, they must all match for a host to match.
In the example above, an instance must have either tags `foo` or `bar`, and must have the tag `baz`.

Refer to the [host catalogs](/boundary/docs/domain-model/host-catalogs) domain model documentation for additional fields that you can use when you create host catalogs.


</Tab>
</Tabs>

## More information

Refer to [Filtering and listing resources](/boundary/docs/filtering) for more information about Boundary's filter syntax and best practices.
