CyberCoveLLC/threshold
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs: add AWS DHC policy examples (#5514)

Browse Source 
* adds IAM policy examples

* adds missing worker-filter command option

* Apply suggestions from code review

Co-authored-by: Dan Heath <76443935+Dan-Heath@users.noreply.github.com>

* adds cross-account access note, style fixes

* Update website/content/docs/concepts/host-discovery/aws.mdx

Co-authored-by: Dan Heath <76443935+Dan-Heath@users.noreply.github.com>

---------

Co-authored-by: Dan Heath <76443935+Dan-Heath@users.noreply.github.com>
This commit is contained in:
Robin BeckandDan Heath authored and GitHub committed 2025-02-05 14:03:12 -07:00
1 parent 35943cb408
commit 2d802fe3f5
2 files changed
+134 -14
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

website/content/docs/commands/host-catalogs/create.mdx
+1
View File
@@ -71,6 +71,7 @@ $ boundary host-catalogs create plugin [options] [args]
- `-scope-id=<string>` - The scope in which you want to create the host catalog.
The default scope is `global`.
You can also specify the scope using the **BOUNDARY_SCOPE_ID** environment variable.
- `-worker-filter=<string>` A boolean expression to filter which workers can handle dynamic host catalog commands for this host catalog.
#### Attribute options
website/content/docs/concepts/host-discovery/aws.mdx
+133 -14
View File
@@ -13,6 +13,121 @@ a dynamic host catalog to integrate with AWS, you create a host catalog of the `
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/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. This policy should match the following:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:Describe*",
"ec2:GetSecurityGroupsForVpc"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "elasticloadbalancing:Describe*",
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"cloudwatch:ListMetrics",
"cloudwatch:GetMetricStatistics",
"cloudwatch:Describe*"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "autoscaling:Describe*",
"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>
@@ -34,21 +149,21 @@ Complete the following steps to create a dynamic host catalog for AWS:
- **Use Assume Role (Dynamic Credentials)**: Authenticates to the host catalog using credentials that AWS `AssumeRole` generates.
<Tabs>
<Tab heading="Static credentials">
<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">
<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.
- **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.
@@ -63,7 +178,7 @@ Complete the following steps to create a dynamic host catalog for AWS:
The required fields for creating a dynamic host catalog depend on whether you configure static or dynamic credentials.
<Tabs>
<Tab heading="Static credentials">
<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:
@@ -94,7 +209,7 @@ The required fields for creating a dynamic host catalog depend on whether you co
</Tab>
<Tab heading="Dynamic credentials">
<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:
@@ -108,7 +223,8 @@ The required fields for creating a dynamic host catalog depend on whether you co
-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
-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.
@@ -122,6 +238,7 @@ The required fields for creating a dynamic host catalog depend on whether you co
- `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.
@@ -137,16 +254,16 @@ The required fields for creating a dynamic host catalog depend on whether you co
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">
<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"
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({
@@ -170,7 +287,7 @@ Replace the values in the configuration with the following required AWS secrets
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.
</Tab>
<Tab heading="Dynamic credentials">
<Tab heading="Dynamic credentials" group="dynamic">
Apply the following Terraform policy:
@@ -180,6 +297,7 @@ Apply the following Terraform policy:
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",
@@ -196,6 +314,7 @@ The `scope_id` and `plugin_name` fields are required when you create a dynamic h
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/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.
@@ -213,8 +332,8 @@ Refer to [the domain model documentation](/boundary/docs/concepts/domain-model/h
</Tabs>
## Create a host set to connect with AWS
[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.
[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.
Complete the following steps to create a host set: