[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/install-boundary/configure-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/concepts/filtering/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:
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.
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.
- **Worker Filter**: (Optional) - An optional filter to route requests to a designated worker. The filter should match the worker assigned the IAM role.
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 domain model documentation](/boundary/docs/concepts/domain-model/host-catalogs) for additional fields that you can use when you create host catalogs.
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/concepts/filtering/worker-tags#filter-workers-using-tags) to learn more.
Refer to [the domain model documentation](/boundary/docs/concepts/domain-model/host-catalogs) for additional fields that you can use when you create host catalogs.
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.
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 domain model documentation](/boundary/docs/concepts/domain-model/host-catalogs) for additional fields that you can use when you create host catalogs.
- `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/concepts/filtering/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 domain model documentation](/boundary/docs/concepts/domain-model/host-catalogs) for additional fields that you can use when you create host catalogs.
[Host sets](/boundary/docs/concepts/domain-model/host-sets) specify which AWS filters should be used to identify the discovered hosts that should be added as members.
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`.
For more fields that you can use when creating host sets, refer to [the domain model documentation](/boundary/docs/concepts/domain-model/host-sets).
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).
