Skip to content

Commit cd35b25

Browse files
hc-github-team-secure-boundaryhc-github-team-secure-boundary
authored
Merge pull request #5520 from hashicorp/backport/rab-docs-aws-dhc-policy/ghastly-ample-moose
This pull request was automerged via backport-assistant
2 parents c1127e8 + efb0e56 commit cd35b25

File tree

2 files changed

+134
-14
lines changed

2 files changed

+134
-14
lines changed

‎website/content/docs/commands/host-catalogs/create.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,7 @@ $ boundary host-catalogs create plugin [options] [args]
7171
- `-scope-id=<string>` - The scope in which you want to create the host catalog.
7272
The default scope is `global`.
7373
You can also specify the scope using the **BOUNDARY_SCOPE_ID** environment variable.
74+
- `-worker-filter=<string>` A boolean expression to filter which workers can handle dynamic host catalog commands for this host catalog.
7475

7576
#### Attribute options
7677

‎website/content/docs/concepts/host-discovery/aws.mdx‎

Lines changed: 133 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,121 @@ a dynamic host catalog to integrate with AWS, you create a host catalog of the `
1313
and set the `plugin-name` value to `aws`. You must also provide the specific
1414
fields needed for Boundary to authenticate with AWS.
1515

16+
Boundary supports two methods of authenticating to AWS:
17+
18+
1. **Static credentials** using an IAM user and its access key
19+
1. **Dynamic credentials** using credentials generated by `AssumeRole`
20+
21+
HashiCorp recommends using dynamic credentials when possible. Select a credential type to continue:
22+
23+
<Tabs>
24+
<Tab heading="Static credentials" group="static">
25+
26+
### Required IAM Privileges
27+
28+
Boundary needs the following IAM privileges, at the very least, to be attached to a configured IAM user.
29+
30+
Configure `DescribeInstances` to `*`. `DescribeInstances` cannot be scoped to a resource ARN.
31+
32+
Example policy:
33+
34+
```json
35+
{
36+
"Version": "2012-10-17",
37+
"Statement": [
38+
{
39+
"Action": [
40+
"ec2:DescribeInstances"
41+
],
42+
"Effect": "Allow",
43+
"Resource": "*"
44+
}
45+
]
46+
}
47+
```
48+
49+
To allow static credential rotation, add the `iam:GetUser`, `iam:CreateAccessKey`, and `iam:DeleteAccessKey` policies:
50+
51+
```json
52+
{
53+
"Version": "2012-10-17",
54+
"Statement": [
55+
{
56+
"Action": [
57+
"iam:DeleteAccessKey",
58+
"iam:GetUser",
59+
"iam:CreateAccessKey"
60+
],
61+
"Effect": "Allow",
62+
"Resource": "arn:aws:iam::123456789012:user/JohnDoe"
63+
}
64+
]
65+
}
66+
```
67+
68+
</Tab>
69+
<Tab heading="Dynamic credentials" group="dynamic">
70+
71+
<Note>
72+
73+
[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.
74+
75+
</Note>
76+
77+
This feature requires a self-managed Boundary [worker](/boundary/docs/install-boundary/configure-workers).
78+
79+
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.
80+
81+
Perform the following steps to set up a host catalog using [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html):
82+
83+
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.
84+
85+
1. Create an IAM role with the `AmazonEC2ReadOnlyAccess` policy attached. This policy should match the following:
86+
87+
```json
88+
{
89+
"Version": "2012-10-17",
90+
"Statement": [
91+
{
92+
"Effect": "Allow",
93+
"Action": [
94+
"ec2:Describe*",
95+
"ec2:GetSecurityGroupsForVpc"
96+
],
97+
"Resource": "*"
98+
},
99+
{
100+
"Effect": "Allow",
101+
"Action": "elasticloadbalancing:Describe*",
102+
"Resource": "*"
103+
},
104+
{
105+
"Effect": "Allow",
106+
"Action": [
107+
"cloudwatch:ListMetrics",
108+
"cloudwatch:GetMetricStatistics",
109+
"cloudwatch:Describe*"
110+
],
111+
"Resource": "*"
112+
},
113+
{
114+
"Effect": "Allow",
115+
"Action": "autoscaling:Describe*",
116+
"Resource": "*"
117+
}
118+
]
119+
}
120+
```
121+
122+
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.
123+
124+
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.
125+
126+
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.
127+
128+
</Tab>
129+
</Tabs>
130+
16131
Complete the following steps to create a dynamic host catalog for AWS:
17132

18133
<Tabs>
@@ -34,21 +149,21 @@ Complete the following steps to create a dynamic host catalog for AWS:
34149
- **Use Assume Role (Dynamic Credentials)**: Authenticates to the host catalog using credentials that AWS `AssumeRole` generates.
35150

36151
<Tabs>
37-
<Tab heading="Static credentials">
152+
<Tab heading="Static credentials" group="static">
38153

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

43158
</Tab>
44-
<Tab heading="Dynamic credentials">
159+
<Tab heading="Dynamic credentials" group="dynamic">
45160

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

@@ -63,7 +178,7 @@ Complete the following steps to create a dynamic host catalog for AWS:
63178
The required fields for creating a dynamic host catalog depend on whether you configure static or dynamic credentials.
64179

65180
<Tabs>
66-
<Tab heading="Static credentials">
181+
<Tab heading="Static credentials" group="static">
67182

68183
1. Log in to Boundary.
69184
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
94209

95210
</Tab>
96211

97-
<Tab heading="Dynamic credentials">
212+
<Tab heading="Dynamic credentials" group="dynamic">
98213

99214
1. Log in to Boundary.
100215
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
108223
-attr role_arn=AWS_ROLE_ARN_VALUE \
109224
-attr role_external_id=AWS_ROLE_EXTERNAL_ID_VALUE \
110225
-attr role_session_name=AWS_ROLE_SESSION_NAME_VALUE \
111-
-attr role_tags=AWS_ROLE_TAGS_VALUE
226+
-attr role_tags=AWS_ROLE_TAGS_VALUE \
227+
-worker-filter '"aws" in "/tags/type"'
112228
```
113229

114230
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
122238
- `role_external_id`: The external ID that you configured for the `AssumeRole` provider.
123239
- `role_session_name`: The session name that you configured for the `AssumeRole` provider.
124240
- `role_tags`: The key-value pair tags that you configured for the `AssumeRole` provider.
241+
- `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.
125242

126243
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.
127244

@@ -137,16 +254,16 @@ The required fields for creating a dynamic host catalog depend on whether you co
137254
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.
138255

139256
<Tabs>
140-
<Tab heading="Static credentials">
257+
<Tab heading="Static credentials" group="static">
141258

142259
Apply the following Terraform policy:
143260

144261
```hcl
145262
resource "boundary_host_catalog_plugin" "aws_host_catalog" {
146-
name = "AWS Catalog"
147-
description = "AWS Host Catalog"
148-
scope_id = boundary_scope.project.id
149-
plugin_name = "aws"
263+
name = "AWS Catalog"
264+
description = "AWS Host Catalog"
265+
scope_id = boundary_scope.project.id
266+
plugin_name = "aws"
150267
151268
# recommended to pass in aws secrets using a file() or using environment variables
152269
attributes_json = jsonencode({
@@ -170,7 +287,7 @@ Replace the values in the configuration with the following required AWS secrets
170287
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.
171288

172289
</Tab>
173-
<Tab heading="Dynamic credentials">
290+
<Tab heading="Dynamic credentials" group="dynamic">
174291

175292
Apply the following Terraform policy:
176293

@@ -180,6 +297,7 @@ Apply the following Terraform policy:
180297
description = "AWS Host Catalog"
181298
scope_id = boundary_scope.project.id
182299
plugin_name = "aws"
300+
worker_filter = "\"aws\" in \"/tags/type\""
183301
184302
attributes_json = jsonencode({
185303
"region" = "eu-west-2",
@@ -196,6 +314,7 @@ The `scope_id` and `plugin_name` fields are required when you create a dynamic h
196314

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

317+
- `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.
199318
- `disable_credential_rotation`: When set to `true`, Boundary does not rotate the credentials with AWS automatically.
200319
You must disable credential rotation to use dynamic credentials.
201320
- `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
213332
</Tabs>
214333

215334
## Create a host set to connect with AWS
216-
[Host sets](/boundary/docs/concepts/domain-model/host-sets) specify which AWS
217-
filters should be used to identify the discovered hosts that should be added as members.
335+
336+
[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.
218337

219338
Complete the following steps to create a host set:
220339

0 commit comments

Comments
 (0)