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 diff --git a/website/content/docs/concepts/host-discovery/aws.mdx b/website/content/docs/concepts/host-discovery/aws.mdx index 62eb7f8f86..f475e0d81d 100644 --- a/website/content/docs/concepts/host-discovery/aws.mdx +++ b/website/content/docs/concepts/host-discovery/aws.mdx @@ -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: + + + + +### 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" + } + ] +} +``` + + + + + + + [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): + +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. + + + + Complete the following steps to create a dynamic host catalog for AWS: @@ -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. - + - **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 +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. - + 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 - + 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. - + 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. - + 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 ## 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: