From f99aed507840aa5b756b7316c5a2f0beb09d5d4c Mon Sep 17 00:00:00 2001 From: Dan Heath <76443935+Dan-Heath@users.noreply.github.com> Date: Thu, 9 Jan 2025 16:54:50 -0500 Subject: [PATCH] docs: Update DHC workflows --- .../docs/concepts/host-discovery/aws.mdx | 272 ++++++++++++++---- .../docs/concepts/host-discovery/azure.mdx | 131 +++++++-- 2 files changed, 324 insertions(+), 79 deletions(-) diff --git a/website/content/docs/concepts/host-discovery/aws.mdx b/website/content/docs/concepts/host-discovery/aws.mdx index 0a25143c4a..2f7e426ab2 100644 --- a/website/content/docs/concepts/host-discovery/aws.mdx +++ b/website/content/docs/concepts/host-discovery/aws.mdx @@ -13,21 +13,133 @@ 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. +Complete the following steps to create a dynamic host catalog for AWS: + - - -```shell-session -$ boundary host-catalogs create plugin \ - -scope-id $BOUNDARY_PROJECT_ID \ - -plugin-name aws \ - -attr disable_credential_rotation=true \ - -attr region=us-east-1 \ - -secret access_key_id=env://AWS_ACCESS_KEY_ID \ - -secret secret_access_key=env://AWS_SECRET_ACCESS_KEY -``` + + +1. Log in to Boundary. +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. + + + + + - **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. + - **Disable credential rotation**: - When enabled, Boundary does not rotate the credentials with AWS automatically. + Credential rotation is automatically disabled when you use dynamic credentials. + + + + +1. Select **Save**. + + + + +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: + + ```shell-session + $ boundary host-catalogs create plugin \ + -scope-id $BOUNDARY_PROJECT_ID \ + -plugin-name aws \ + -attr disable_credential_rotation=true \ + -attr region=us-east-1 \ + -secret access_key_id=env://AWS_ACCESS_KEY_ID \ + -secret secret_access_key=env://AWS_SECRET_ACCESS_KEY + ``` + + 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. + + + + + +1. Log in to Boundary. +1. Use the following command to create a dynamic host catalog using dynamic credentials: + + ```shell-session + $ boundary host-catalogs create plugin \ + -scope-id $BOUNDARY_PROJECT_ID \ + -plugin-name aws \ + -attr disable_credential_rotation=true \ + -attr region=us-east-1 \ + -role_arn \ + -role_external_id \ + -role_session_name \ + -role_tags + ``` + + 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. + + 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. + + + + +Apply the following Terraform policy: ```hcl resource "boundary_host_catalog_plugin" "aws_host_catalog" { @@ -45,49 +157,112 @@ $ boundary host-catalogs create plugin \ } ``` +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. + - + -The `scope-id` and `plugin-name` fields are required when you create a - dynamic host catalog. +Apply the following Terraform policy: -The fields following the `attr` and `secret` flags are specific to AWS and are required by - Boundary for authentication. + ```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" -- `disable_credential_rotation`: When set to `true`, Boundary will not rotate the credentials with AWS automatically. -- `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. -- `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. + attributes_json = jsonencode({ + "region" = "eu-west-2", + "disable_credential_rotation" = true }) + secrets_json = jsonencode({ + "role_arn" = var.aws_access, + "role_external_id" = var.aws_secret, + "role_session_name" = var.aws_secret, + "role_tags" = var.aws_secret}) + } + ``` + +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. + 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. + + + + + + ## 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. -Create a host set using the following command: +Complete the following steps to create a host set: + + +1. Log in to Boundary. +1. Select the org, and then select the project you want to create a host set for. +1. Select **Host Catalogs**. +1. Select the dynamic host catalog to which you want add a host set. +1. Click the **Host Sets** tab, and then click **New**. +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. +1. Click **Save**. + + + -```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 -``` +1. Log in to Boundary. +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). +Apply the following Terraform policy: + ```hcl resource "boundary_host_set_plugin" "aws_host_set" { name = "AWS Host Set" @@ -98,23 +273,18 @@ resource "boundary_host_set_plugin" "aws_host_set" { } ``` - - +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). -The `host-catalog-id` value is a required field that specifies in which host catalog to - create this host set. +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`. -Like with the host catalog, the fields passed in after the `attr` flag are - specific to AWS. +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 `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). + + diff --git a/website/content/docs/concepts/host-discovery/azure.mdx b/website/content/docs/concepts/host-discovery/azure.mdx index 397e212351..f744ef9929 100644 --- a/website/content/docs/concepts/host-discovery/azure.mdx +++ b/website/content/docs/concepts/host-discovery/azure.mdx @@ -13,22 +13,63 @@ dynamic host catalog to integrate with Azure, you create a host catalog of the `plugin` type and set the `plugin-name` value to `azure`. You must also provide the specific fields needed for Boundary to authenticate with Azure. +Complete the following steps to create a dynamic host catalog for Azure: + - - -```shell-session -$ boundary host-catalogs create plugin \ - -scope-id $PROJECT_ID \ - -plugin-name azure \ - -attr disable_credential_rotation=true \ - -attr tenant_id=env://ARM_TENANT_ID \ - -attr subscription_id=env://ARM_SUBSCRIPTION_ID \ - -attr client_id=env://ARM_CLIENT_ID \ - -secret secret_value=env://ARM_CLIENT_SECRET -``` + + +1. Log in to Boundary. +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 **Azure** to create a dynamic host catalog for your Azure resources. + - **Tenant/Directory ID**: (Required) The directory ID for your Azure Active Directory application. + - **Subscription ID**: (Required) The subscription ID for the subscription that has read access. + - **Client/Application ID**: (Required) The client or application ID of the Azure service principal that Boundary should use to authenticate and discover hosts. + - **Client Secret Value**: (Required) The client secret value that Azure generates for authentication. + - **Disable credential rotation**: When enabled, Boundary does not rotate the credentials with Azure automatically. +1. Select **Save**. + + + + +1. Log in to Boundary. +1. Use the following command to create a dynamic host catalog for Azure: + + ```shell-session + $ boundary host-catalogs create plugin \ + -scope-id $PROJECT_ID \ + -plugin-name azure \ + -attr disable_credential_rotation=true \ + -attr tenant_id=env://ARM_TENANT_ID \ + -attr subscription_id=env://ARM_SUBSCRIPTION_ID \ + -attr client_id=env://ARM_CLIENT_ID \ + -secret secret_value=env://ARM_CLIENT_SECRET + ``` + + 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 Azure and are required by Boundary for authentication. + + - `disable_credential_rotation`: When set to `true`, Boundary does not rotate the credentials automatically. + - `tenant_id`: The ARM Tenant(Directory) ID + - `subscription_id`: The ARM Subscription ID + - `client_id`: The ARM Client (Application) ID + - `secret_value`: The ARM Client Secret + + 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. - + + +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" "azure_host_catalog" { @@ -47,16 +88,13 @@ resource "boundary_host_catalog_plugin" "azure_host_catalog" { } ``` - - - 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 Azure and are required by Boundary for authentication. -- `disable_credential_rotation`: When set to `true`, Boundary will not rotate the credentials automatically. +- `disable_credential_rotation`: When set to `true`, Boundary does not rotate the credentials automatically. - `tenant_id`: The ARM Tenant(Directory) ID - `subscription_id`: The ARM Subscription ID - `client_id`: The ARM Client (Application) ID @@ -64,27 +102,64 @@ The fields following the `attr` and `secret` flags are specific to Azure and are 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. + + + ## Create a host set to connect with Azure [Host sets](/boundary/docs/concepts/domain-model/host-sets) specify which Azure Resource Manager (ARM) filters should be used to identify the discovered hosts that should be added as members. -Create a host set using the following command: +Complete the following steps to create a host set: + + + +1. Log in to Boundary. +1. Select the org, and then select the project you want to create a host set for. +1. Select **Host Catalogs**. +1. Select the dynamic host catalog to which you want add a host set. +1. Click the **Host Sets** tab, and then click **New**. +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. +1. Click **Save**. + - -```shell-session -$ boundary host-sets create plugin \ - -name database \ - -host-catalog-id $HOST_CATALOG_ID \ - -attr filter="tagName eq 'service-type' and tagValue eq 'database'" -``` +1. Log in to Boundary. +1. Use the following command to create a host set: + + ```shell-session + $ boundary host-sets create plugin \ + -name database \ + -host-catalog-id $HOST_CATALOG_ID \ + -attr filter="tagName eq 'service-type' and tagValue eq 'database'" + ``` + + The `host-catalog-id` value is a required field that specifies in which host catalog to create this host set. + + The fields following the `attr` flag are specific to Azure. + + The `filter` field represents the ARM filter used to select resources that should be a part of this host set. + There are some limitations with the filtering syntax. + Specifically, when you use tags, other types of filters (such as on resource type) are not allowed. + As a result, it is generally useful to filter directly on tag names or values as in the following examples: + - `tagName eq 'application'` + - `tagName eq 'application' and tagValue eq 'app2'` + + 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. + +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_set_plugin" "azure_host_set" { name = "Azure Set" @@ -95,9 +170,6 @@ $ boundary host-sets create plugin \ } ``` - - - The `host-catalog-id` value is a required field that specifies in which host catalog to create this host set. @@ -112,3 +184,6 @@ The `filter` field represents the ARM filter used to select resources that shoul - `tagName eq 'application' and tagValue eq 'app2'` 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. + + +