From 7322e165a6fb18442a454720ad334106edbe81de Mon Sep 17 00:00:00 2001 From: stellarsquall Date: Wed, 5 Feb 2025 00:18:17 +0000 Subject: [PATCH 1/5] backport of commit 22114124acf546cc3f52b19bfc25fd1d06e14022 --- .../docs/concepts/host-discovery/aws.mdx | 145 ++++++++++++++++-- 1 file changed, 131 insertions(+), 14 deletions(-) diff --git a/website/content/docs/concepts/host-discovery/aws.mdx b/website/content/docs/concepts/host-discovery/aws.mdx index 62eb7f8f86..96e342d763 100644 --- a/website/content/docs/concepts/host-discovery/aws.mdx +++ b/website/content/docs/concepts/host-discovery/aws.mdx @@ -13,6 +13,119 @@ 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. + + + + +### 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 enable allow for 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" + } + ] +} +``` + + + + + + + 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 setting 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. Attached 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. + + + + Complete the following steps to create a dynamic host catalog for AWS: @@ -34,21 +147,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. - + - **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. - + - **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 +176,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. - + 1. Log in to Boundary. 1. Use the following command to create a dynamic host catalog for AWS using static credentials: @@ -94,7 +207,7 @@ The required fields for creating a dynamic host catalog depend on whether you co - + 1. Log in to Boundary. 1. Use the following command to create a dynamic host catalog using dynamic credentials: @@ -108,7 +221,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 +236,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 +252,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. - + 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 +285,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. - + Apply the following Terraform policy: @@ -180,6 +295,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 +312,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 +330,8 @@ Refer to [the domain model documentation](/boundary/docs/concepts/domain-model/h ## 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: From f3d664e27c451df7e2acb13dd361fb69ec9f9749 Mon Sep 17 00:00:00 2001 From: stellarsquall Date: Wed, 5 Feb 2025 00:18:50 +0000 Subject: [PATCH 2/5] backport of commit cdfb6133a456a0c8eb1d36a25645abf11e1da850 --- website/content/docs/commands/host-catalogs/create.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/website/content/docs/commands/host-catalogs/create.mdx b/website/content/docs/commands/host-catalogs/create.mdx index 05a61b5eb1..2d46414aff 100644 --- a/website/content/docs/commands/host-catalogs/create.mdx +++ b/website/content/docs/commands/host-catalogs/create.mdx @@ -71,6 +71,7 @@ $ boundary host-catalogs create plugin [options] [args] - `-scope-id=` - 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=` A boolean expression to filter which workers can handle dynamic host catalog commands for this host catalog. #### Attribute options From e124ffac67e8456582cfcf5901c799da6426329f Mon Sep 17 00:00:00 2001 From: Robin Beck Date: Wed, 5 Feb 2025 17:58:45 +0000 Subject: [PATCH 3/5] backport of commit 82e01d822ef5c9db1dea33e2c49d01d1355c735f --- website/content/docs/concepts/host-discovery/aws.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/website/content/docs/concepts/host-discovery/aws.mdx b/website/content/docs/concepts/host-discovery/aws.mdx index 96e342d763..ca819f8530 100644 --- a/website/content/docs/concepts/host-discovery/aws.mdx +++ b/website/content/docs/concepts/host-discovery/aws.mdx @@ -15,10 +15,10 @@ 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`. +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. +HashiCorp recommends using dynamic credentials when possible. Select a credential type to continue: @@ -74,7 +74,7 @@ To enable allow for static credential rotation, add the `iam:GetUser`, `iam:Crea -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 setting up the dynamic host catalog. +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): From 4761e8436392d2e2939e91cf83bf6f4516fd9113 Mon Sep 17 00:00:00 2001 From: stellarsquall Date: Wed, 5 Feb 2025 20:12:47 +0000 Subject: [PATCH 4/5] backport of commit 3ba473ceb8714077b69bbaaab406cb05cc4b1016 --- website/content/docs/concepts/host-discovery/aws.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/website/content/docs/concepts/host-discovery/aws.mdx b/website/content/docs/concepts/host-discovery/aws.mdx index ca819f8530..84309bc1e2 100644 --- a/website/content/docs/concepts/host-discovery/aws.mdx +++ b/website/content/docs/concepts/host-discovery/aws.mdx @@ -46,7 +46,7 @@ Example policy: } ``` -To enable allow for static credential rotation, add the `iam:GetUser`, `iam:CreateAccessKey`, and `iam:DeleteAccessKey` policies: +To allow static credential rotation, add the `iam:GetUser`, `iam:CreateAccessKey`, and `iam:DeleteAccessKey` policies: ```json { @@ -70,10 +70,12 @@ To enable allow for static credential rotation, add the `iam:GetUser`, `iam:Crea - This feature requires a self-managed Boundary [worker](/boundary/docs/install-boundary/configure-workers). + [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. +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): From efb0e56afec748b3d20852fd09531aa16b6e5b56 Mon Sep 17 00:00:00 2001 From: Robin Beck Date: Wed, 5 Feb 2025 20:55:42 +0000 Subject: [PATCH 5/5] backport of commit 0c96b6870d158a007b7b3b91bb643a0566f57fa6 --- website/content/docs/concepts/host-discovery/aws.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/concepts/host-discovery/aws.mdx b/website/content/docs/concepts/host-discovery/aws.mdx index 84309bc1e2..f475e0d81d 100644 --- a/website/content/docs/concepts/host-discovery/aws.mdx +++ b/website/content/docs/concepts/host-discovery/aws.mdx @@ -121,7 +121,7 @@ Perform the following steps to set up a host catalog using [AssumeRole](https:// 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. Attached 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. 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.