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 1/7] 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. + + + From 3fb1894725f32f59e3c7da4fdb4188aae3ff5246 Mon Sep 17 00:00:00 2001 From: Dan Heath <76443935+Dan-Heath@users.noreply.github.com> Date: Fri, 10 Jan 2025 11:18:23 -0500 Subject: [PATCH 2/7] docs: Update field definitions --- .../docs/concepts/host-discovery/azure.mdx | 27 ++++++++++--------- 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/website/content/docs/concepts/host-discovery/azure.mdx b/website/content/docs/concepts/host-discovery/azure.mdx index f744ef9929..1e3e0ddaa4 100644 --- a/website/content/docs/concepts/host-discovery/azure.mdx +++ b/website/content/docs/concepts/host-discovery/azure.mdx @@ -28,11 +28,12 @@ Complete the following steps to create a dynamic host catalog for Azure: - **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. + - **Tenant/Directory ID**: (Required) The ARM tenant (directory) ID for your Azure Active Directory application. + - **Subscription ID**: (Required) The ARM subscription ID for the subscription that has read access. + - **Client/Application ID**: (Required) The client (application) ID of the Azure service principal that Boundary should use to authenticate and discover hosts. + - **Client Secret Value**: (Required) The ARM client secret value that Azure generates for authentication. - **Disable credential rotation**: When enabled, Boundary does not rotate the credentials with Azure automatically. + Azure host catalogs do not currently support credential rotation. 1. Select **Save**. @@ -57,10 +58,11 @@ Complete the following steps to create a dynamic host catalog for Azure: 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 + Azure host catalogs do not currently support credential rotation. + - `tenant_id`: (Required) The ARM tenant (directory) ID for your Azure Active Directory application. + - `subscription_id`: (Required) The ARM subscription ID for the subscription that has read access. + - `client_id`: (Required) The client (application) ID of the Azure service principal that Boundary should use to authenticate and discover hosts. + - `secret_value`: (Required) The ARM client secret value that Azure generates for authentication. 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. @@ -95,10 +97,11 @@ The fields following the `attr` and `secret` flags are specific to Azure and are 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 +Azure host catalogs do not currently support credential rotation. +- `tenant_id`: (Required) The ARM tenant (directory) ID for your Azure Active Directory application. +- `subscription_id`: (Required) The ARM subscription ID for the subscription that has read access. +- `client_id`: (Required) The client (application) ID of the Azure service principal that Boundary should use to authenticate and discover hosts. +- `secret_value`: (Required) The ARM client secret value that Azure generates for authentication. 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. From 1252481645090ad9899b700e40418cd3e9ef4e8a Mon Sep 17 00:00:00 2001 From: Dan Heath <76443935+Dan-Heath@users.noreply.github.com> Date: Tue, 28 Jan 2025 16:14:43 -0500 Subject: [PATCH 3/7] docs: Add GCP workflows --- .../docs/concepts/host-discovery/gcp.mdx | 478 ++++++++++++++---- .../docs/concepts/host-discovery/index.mdx | 6 +- 2 files changed, 370 insertions(+), 114 deletions(-) diff --git a/website/content/docs/concepts/host-discovery/gcp.mdx b/website/content/docs/concepts/host-discovery/gcp.mdx index 891e8d1c15..7d7f3f135e 100644 --- a/website/content/docs/concepts/host-discovery/gcp.mdx +++ b/website/content/docs/concepts/host-discovery/gcp.mdx @@ -5,38 +5,262 @@ description: >- Use dynamic host catalogs to automatically discover GCP Compute Engine VM instances and add them as hosts. Create a host catalog and host set for GCP resources. --- # GCP dynamic host catalogs + Boundary uses dynamic host catalogs to automatically discover GCP Compute Engine VM instances and add them as hosts. +You can authenticate to GCP using a service account, service impersonation, or the GCP Application Default Credentials (ADC): + + + + +To authenticate using the service account, create a service account in GCP and download the private key file. + +The service account should have the following roles: + + - `roles/compute.viewer`: (Required) To list Compute Engine VM instance in the project. + - `roles/iam.serviceAccountKeyAdmin`: (Optional) To rotate the service account key if `disable_credential_rotation` is set to `false`. + + + + + +Service account impersonation allows Boundary to authenticate with GCP using a service account that impersonates another service account. +Impersonation is useful when you want to restrict the permissions of the service account Boundary uses. + +You must create two service accounts to authenticate using service impersonation: + +- `Base service account`: The service account Boundary uses to authenticate with GCP. The service account should have the following roles: + - `roles/iam.serviceAccountTokenCreator`: (Required) To create a token for the target service account. + - `roles/iam.serviceAccountKeyAdmin`: (Optional) To rotate the service account key if `disable_credential_rotation` is set to `false`. + +- `Target service account`: The service account to impersonate. The service account should have the following role: + - `roles/compute.viewer`: (Required) To list Compute Engine VM instance in the project. + + + + + +If you run Boundary on a GCP VM instance, you can use Application Default Credentials (ADC) to authenticate with GCP. +Boundary uses the service account associated with the VM instance to authenticate with GCP. + + + + + + +If you downloaded the private key from GCP, it may contain extra `/n` characters that cause an error. +You can use `jq` to remove the extra `/n` characters. + + + ## Create a host catalog to connect with GCP -Boundary uses plugins to integrate with a variety of providers. To use -a dynamic host catalog to integrate with GCP, you create a host catalog of the `plugin` type -and set the `plugin-name` value to `gcp`. You must also provide the specific -fields needed for Boundary to authenticate with GCP. -### Authentication with service account -Create a service account in GCP and download the private key file. The service account should have the following roles: -- `roles/compute.viewer` (Required): To list Compute Engine VM instance in the project. -- `roles/iam.serviceAccountKeyAdmin` (Optional): - To rotate the service account key if `disable_credential_rotation` is set to `false`. +Boundary uses plugins to integrate with a variety of providers. +To use a dynamic host catalog to integrate with GCP, you create a host catalog of the `plugin` type and set the `plugin-name` value to `gcp`. + +You must also provide the specific fields needed for Boundary to authenticate with GCP. +The required fields depend on whether you authenticate using the service account, service impersonation, or the GCP Application Default Credentials (ADC). -Pass the following fields to Boundary for authentication: +Complete the following steps to create a dynamic host catalog for GCP: - - -```shell-session -$ boundary host-catalogs create plugin \ - -scope-id $BOUNDARY_PROJECT_ID \ - -plugin-name gcp \ - -attr disable_credential_rotation=true \ - -attr zone=us-central1-a \ - -attr project_id=env://GCP_PROJECT_ID \ - -attr client_email=env://CLIENT_EMAIL \ - -secret private_key_id=env://PRIVATE_KEY_ID \ - -secret private_key=file://$PRIVATE_KEY_FILE_PATH -``` + + +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 description of the host catalog 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 **GCP** to create a dynamic host catalog for your GCP resources. + + + + + - **Project ID**: (Required) The project ID of any instances that you want to add to the host catalog. + - **Zone**: (Required) The GCP zone of the instances that you want to add to the host catalog. + - **Client Email**: The unique email address that is used to identify the service account. + It is required when you authenticate using the service account. + - **Target Service Account ID**: Skip this field when you configure authentication using the service account. + It is only used when you authenticate using service account impersonation. + - **Private Key ID**: The unique identifier of the private key. + It is required when you authenticate using the service account. + - **Private Key**: The private key used to obtain an OAuth 2.0 access token. + The key must be PEM encoded. + It is required when you authenticate using the service account. + + If you downloaded the private key from GCP, it may contain extra `/n` characters that cause an error. + You can use `jq` to remove the extra `/n` characters. + + + + + + - **Project ID**: (Required) The project ID of any instances that you want to add to the host catalog. + - **Zone**: (Required) The GCP zone of the instances that you want to add to the host catalog. + - **Client Email**: The unique email address that is used to identify the base service account. + It is required when you authenticate using service account impersonation. + - **Target Service Account ID**: The unique identifier for the service account that is impersonated. + It is required when you authenticate using service account impersonation. + - **Private Key ID**: The unique identifier of the private key for the base service account. + It is required when you authenticate using service account impersonation. + - **Private Key**: The private key used to obtain an OAuth 2.0 access token. + The key must be PEM encoded. + It is required when you authenticate using service account impersonation. + + If you downloaded the private key from GCP, it may contain extra `/n` characters that cause an error. + You can use `jq` to remove the extra `/n` characters. + + + + + + - **Project ID**: (Required) The project ID of any instances that you want to add to the host catalog. + - **Zone**: (Required) The GCP zone of the instances that you want to add to the host catalog. + - **Client Email**: (Optional) The unique email address that is used to identify the base service account. + - **Target Service Account ID**: Skip this field when you configure authentication using the ADC. + It is only used when you authenticate using service account impersonation. + - **Private Key ID**: (Optional) The unique identifier of the private key for the base service account. + - **Private Key**: (Optional) The private key used to obtain an OAuth 2.0 access token. + The key must be PEM encoded. + + If you downloaded the private key from GCP, it may contain extra `/n` characters that cause an error. + You can use `jq` to remove the extra `/n` characters. + + + + + - **Worker Filter**: (Optional) An optional filter to route requests to a designated worker. + - **Disable credential rotation**: (Optional) When enabled, Boundary does not rotate the credentials with GCP automatically. +1. Select **Save**. + + + + + + + + +1. Log in to Boundary. +1. Use the following command to create a dynamic host catalog for GCP: + + ```shell-session + $ boundary host-catalogs create plugin \ + -scope-id $BOUNDARY_PROJECT_ID \ + -plugin-name gcp \ + -attr disable_credential_rotation=true \ + -attr zone=us-central1-a \ + -attr project_id=env://GCP_PROJECT_ID \ + -attr client_email=env://CLIENT_EMAIL \ + -secret private_key_id=env://PRIVATE_KEY_ID \ + -secret private_key=file://$PRIVATE_KEY_FILE_PATH + ``` + + 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 GCP and are used by Boundary for authentication: + + - `disable_credential_rotation`: (Optional) When set to `true`, Boundary does not rotate the credentials automatically. + - `zone`: (Required) The GCP zone of the instances that you want to add to the host catalog. + - `project_id`: (Required) The project ID of any instances that you want to add to the host catalog. + - `client_email`: The unique email address that is used to identify the service account. + It is required when you authenticate using the service account. + - `private_key_id`: The unique identifier of the private key. + It is required when you authenticate using the service account. + - `private_key`: The private key used to obtain an OAuth 2.0 access token. + The key must be PEM encoded. + It is required when you authenticate using the service account. + + If you downloaded the private key from GCP, it may contain extra `/n` characters that cause an error. + You can use `jq` to remove the extra `/n` characters. + + 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 for GCP: + + ```shell-session + $ boundary host-catalogs create plugin \ + -scope-id $BOUNDARY_PROJECT_ID \ + -plugin-name gcp \ + -attr disable_credential_rotation=true \ + -attr zone=us-central1-a \ + -attr project_id=env://GCP_PROJECT_ID \ + -attr client_email=env://BASE_SERVICE_ACCOUNT_EMAIL \ + -attr target_service_account_id=env://TARGET_SERVICE_ACCOUNT_EMAIL \ + -secret private_key_id=env://BASE_SERVICE_ACCOUNT_PRIVATE_KEY_ID \ + -secret private_key=file://$BASE_SERVICE_ACCOUNT_PRIVATE_KEY_FILE_PATH + ``` + + 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 GCP and are required by Boundary for authentication: + + - `disable_credential_rotation`: (Optional) When set to `true`, Boundary does not rotate the credentials with GCP automatically. + - `zone`: (Required) The deployment area within a region. + All host sets in this catalog are configured for this zone. + - `project_id`: (Required) The project ID associated with the service account. + - `client_email`: The email address used to uniquely identify the base service account. + It is required when you authenticate using service account impersonation. + - `target_service_account_id`: The email address of the service account to impersonate. + It is required when you authenticate using service account impersonation. + - `private_key_id`: The ID of the private key for the base service account to use with this host catalog. + It is required when you authenticate using service account impersonation. + - `private_key`: The private key for the base service account to use with this host catalog. + It is required when you authenticate using service account impersonation. + + If you downloaded the private key from GCP, it may contain extra `/n` characters that cause an error. + You can use `jq` to remove the extra `/n` characters. + + 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 for GCP: + + ```shell-session + $ boundary host-catalogs create plugin \ + -scope-id $BOUNDARY_PROJECT_ID \ + -plugin-name gcp \ + -attr disable_credential_rotation=true \ + -attr zone=us-central1-a \ + -attr project_id=env://GCP_PROJECT_ID + ``` + + The `scope-id` and `plugin-name` fields are required when you create a dynamic host catalog. + + The fields following the `attr` flag are specific to GCP and are required by Boundary for authentication: + + - `disable_credential_rotation`: (Optional) When set to `true`, Boundary does not rotate the credentials with GCP automatically. + - `zone`: (Required) The deployment area within a region. + All host sets in this catalog are configured for this zone. + - `project_id`: (Required) The project ID associated with the service account. + + 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" "gcp_host_catalog" { @@ -56,40 +280,33 @@ $ boundary host-catalogs create plugin \ } ``` - - - -### Authentication with service account impersonation -Service account impersonation allows Boundary to authenticate with GCP using a service account that impersonates another service account. -Impersonation is useful when you want to restrict the permissions of the service account Boundary uses. Two service accounts are required: + The `scope_id` and `plugin_name` fields are required when you create a dynamic host catalog. -- `Base service account`: The service account Boundary uses to authenticate with GCP. The service account should have the following roles: - - `roles/iam.serviceAccountTokenCreator` (Required) - To create a token for the target service account. - - `roles/iam.serviceAccountKeyAdmin` (Optional) - To rotate the service account key if `disable_credential_rotation` is set to `false`. + The fields following `attributes_json` and `secrets_json` are specific to GCP and are used by Boundary for authentication: -- `Target service account`: The service account to impersonate. The service account should have the following roles: - - `roles/compute.viewer` (Required): To list Compute Engine VM instance in the project. + - `zone`: (Required) The GCP zone of the instances that you want to add to the host catalog. + - `project_id`: (Required) The project ID of any instances that you want to add to the host catalog. + - `client_email`: The unique email address that is used to identify the service account. + It is required when you authenticate using the service account. + - `disable_credential_rotation`: (Optional) When set to `true`, Boundary does not rotate the credentials automatically. + - `private_key_id`: The unique identifier of the private key. + It is required when you authenticate using the service account. + - `private_key`: The private key used to obtain an OAuth 2.0 access token. + The key must be PEM encoded. + It is required when you authenticate using the service account. -Pass the following fields to Boundary for authentication: + If you downloaded the private key from GCP, it may contain extra `/n` characters that cause an error. + You can use `jq` to remove the extra `/n` characters. - - - -```shell-session -$ boundary host-catalogs create plugin \ - -scope-id $BOUNDARY_PROJECT_ID \ - -plugin-name gcp \ - -attr disable_credential_rotation=true \ - -attr zone=us-central1-a \ - -attr project_id=env://GCP_PROJECT_ID \ - -attr client_email=env://BASE_SERVICE_ACCOUNT_EMAIL \ - -attr target_service_account_id=env://TARGET_SERVICE_ACCOUNT_EMAIL \ - -secret private_key_id=env://BASE_SERVICE_ACCOUNT_PRIVATE_KEY_ID \ - -secret private_key=file://$BASE_SERVICE_ACCOUNT_PRIVATE_KEY_FILE_PATH -``` +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" "gcp_host_catalog" { @@ -110,29 +327,35 @@ $ boundary host-catalogs create plugin \ } ``` - - +The `scope_id` and `plugin_name` fields are required when you create a dynamic host catalog. -### Authentication with Application Default Credentials (ADC) -If you run Boundary on a GCP VM instance, you can use Application Default Credentials (ADC) to authenticate with GCP. -Boundary uses the service account associated with the VM instance to authenticate with GCP. +The fields following `attributes_json` and `secrets_json` are specific to GCP and are required by Boundary for authentication: -Pass the following fields to Boundary for authentication: +- `zone`: (Required) The deployment area within a region. All host sets in this + catalog are configured for this zone. +- `project_id`: (Required) The project ID associated with the service account. +- `client_email`: The email address used to uniquely identify the base service account. +It is required when you authenticate using service account impersonation. +- `target_service_account_id`: The email address of the service account to impersonate. +It is required when you authenticate using service account impersonation. +- `disable_credential_rotation`: (Optional) When set to `true`, Boundary does not rotate the credentials with GCP automatically. +- `private_key_id`: The ID of the private key for the base service account to use with this host catalog. +It is required when you authenticate using service account impersonation. +- `private_key`: The private key for the base service account to use with this host catalog. +It is required when you authenticate using service account impersonation. + + If you downloaded the private key from GCP, it may contain extra `/n` characters that cause an error. + You can use `jq` to remove the extra `/n` characters. - - - -```shell-session -$ boundary host-catalogs create plugin \ - -scope-id $BOUNDARY_PROJECT_ID \ - -plugin-name gcp \ - -attr disable_credential_rotation=true \ - -attr zone=us-central1-a \ - -attr project_id=env://GCP_PROJECT_ID -``` +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" "gcp_host_catalog" { @@ -148,47 +371,83 @@ $ boundary host-catalogs create plugin \ } ``` - - - -The `scope-id` and `plugin-name` fields are required when you create a - dynamic 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 GCP and are required by - Boundary for authentication. +The fields following `attributes_json` are specific to GCP and are required by Boundary for authentication: -- `zone` (Required): The deployment area within a region. All host sets in this - catalog are configured for this zone. -- `project_id` (Required): The project ID associated with the service account. -- `disable_credential_rotation` (Optional): When set to `true`, Boundary does not rotate the credentials with GCP automatically. -- `client_email` (Optional): Boundary uses this email address associated with the service account. - The email address used to uniquely identify the service account. -- `target_service_account_id` (Optional): Boundary uses this email address of the service account to impersonate. - This is used for authentication with service account impersonation. -- `private_key_id` (Optional): The ID of the private key for the service account to use with this host catalog. -- `private_key` (Optional): The private key for the service account to use with this host catalog. +- `zone`: (Required) The GCP zone of the instances that you want to add to the host catalog. +- `project_id`: (Required) The project ID of any instances that you want to add to the host catalog. +- `disable_credential_rotation`: (Optional) When set to `true`, Boundary does not rotate the credentials with GCP automatically. 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 GCP -[Host sets](/boundary/docs/concepts/domain-model/host-sets) specify which GCP - filters Boundary should use to identify which discovered hosts that should be added as members. -Create a host set using the following command: +[Host sets](/boundary/docs/concepts/domain-model/host-sets) specify which GCP filters Boundary should use to identify which discovered hosts that should be added as members. + +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 to 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=labels.env=prod \ - -attr filters=labels.app=web -``` +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=labels.env=prod \ + -attr filters=labels.app=web + ``` + + 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 GCP. + + The `filters` field contains string filters in the format key=val1. + The key corresponds to a filter option. + For a list of filter options, refer to the [GCP API documentation](https://cloud.google.com/compute/docs/reference/rest/v1/instances/list#filter). + When you apply multiple filters, the plugin applies a logical `AND` operation to combine the filters. + + If there is no explicit instance status filter, the default status is set to `status="RUNNING"`. + The default status ensures that Boundary only filters running instances, saving time when processing results. + + We recommend using labels as filters because they are more flexible and can filter on multiple values as in the following examples: + + - `-attr filters=labels.env=dev` + - `-attr filters=labels.env=prod AND labels.app=web` + + For more fields that you can use when creating host sets, refer to [the domain model documentation](/boundary/docs/concepts/domain-model/host-sets). +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" "gcp_host_set" { name = "GCP Host Set" @@ -199,27 +458,24 @@ resource "boundary_host_set_plugin" "gcp_host_set" { } ``` - - +The `host_catalog_id` value is a required field that specifies in which host catalog to create this host set. -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 `attributes_json` flag are specific to GCP. -Like with the host catalog, the fields passed in after the `attr` flag are - specific to GCP. +The `filters` field contains string filters in the format key=val1. +The key corresponds to a filter option. +For a list of filter options, refer to the [GCP API documentation](https://cloud.google.com/compute/docs/reference/rest/v1/instances/list#filter). +When you apply multiple filters, the plugin applies a logical `AND` operation to combine the filters. -The `filters` field contains string filters in the format key=val1. The key corresponds to - a filter option. For a list of filter options, refer to the - [GCP API documentation](https://cloud.google.com/compute/docs/reference/rest/v1/instances/list#filter). - When you apply multiple filters, the plugin applies a logical `AND` operation to combine the filters. +If there is no explicit instance status filter, the default status is set to `status="RUNNING"`. +The default status ensures that Boundary only filters running instances, saving time when processing results. - If there is no explicit instance status filter, the default status is set to `status="RUNNING"`. - This ensures that Boundary only filters running instances, saving time when processing results. +We recommend using labels as filters because they are more flexible and can filter on multiple values as in the following examples: - We recommend using labels as filters because they are more flexible and can filter on multiple values - as in the following examples: - `-attr filters=labels.env=dev` - `-attr filters=labels.env=prod AND labels.app=web` -For more fields that you can use when creating host sets, refer to - [the domain model documentation](/boundary/docs/concepts/domain-model/host-sets). +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/index.mdx b/website/content/docs/concepts/host-discovery/index.mdx index 0b085ad659..a1a57dbf16 100644 --- a/website/content/docs/concepts/host-discovery/index.mdx +++ b/website/content/docs/concepts/host-discovery/index.mdx @@ -54,12 +54,12 @@ external resources should be ingested into the catalog by with an attributes filter. These filters specify which discovered hosts should be members of the host set. -Boundary currently supports dynamic host catalog for AWS and -Azure and we will continue to grow this ecosystem to support additional providers. +Boundary currently supports dynamic host catalog for AWS, Azure, and GCP. +We will continue to grow this ecosystem to support additional providers. ## Next steps To get started with dynamic host catalogs, refer to the following topics: - + - [AWS dynamic host catalogs](/boundary/docs/concepts/host-discovery/aws) - [Azure dynamic host catalogs](/boundary/docs/concepts/host-discovery/azure) - [GCP dynamic host catalogs](/boundary/docs/concepts/host-discovery/gcp) From 4caedc293fd145445ba33aaa2abe29b54e06c3ca Mon Sep 17 00:00:00 2001 From: Dan Heath <76443935+Dan-Heath@users.noreply.github.com> Date: Tue, 28 Jan 2025 16:30:27 -0500 Subject: [PATCH 4/7] docs: Add note about required fields --- website/content/docs/concepts/host-discovery/gcp.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/website/content/docs/concepts/host-discovery/gcp.mdx b/website/content/docs/concepts/host-discovery/gcp.mdx index 7d7f3f135e..4b330635e7 100644 --- a/website/content/docs/concepts/host-discovery/gcp.mdx +++ b/website/content/docs/concepts/host-discovery/gcp.mdx @@ -77,6 +77,8 @@ Complete the following steps to create a dynamic host catalog for GCP: - **Type**: (Required) Select **Dynamic** to create a dynamic host catalog. - **Provider**: (Required) Select **GCP** to create a dynamic host catalog for your GCP resources. + The required fields for creating a dynamic host catalog depend on the type of authentication you configure. + @@ -141,6 +143,8 @@ Complete the following steps to create a dynamic host catalog for GCP: +The required fields for creating a dynamic host catalog depend on the type of authentication you configure. + @@ -255,6 +259,8 @@ Complete the following steps to create a dynamic host catalog for GCP: +The required fields for creating a dynamic host catalog depend on the type of authentication you configure. + From c1a6286447f52d4ef78fd551e6c8d42b54b4ae49 Mon Sep 17 00:00:00 2001 From: stellarsquall Date: Wed, 29 Jan 2025 15:16:26 -0700 Subject: [PATCH 5/7] adds jq private key example code --- website/content/docs/concepts/host-discovery/gcp.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/website/content/docs/concepts/host-discovery/gcp.mdx b/website/content/docs/concepts/host-discovery/gcp.mdx index 4b330635e7..0d8adcb64e 100644 --- a/website/content/docs/concepts/host-discovery/gcp.mdx +++ b/website/content/docs/concepts/host-discovery/gcp.mdx @@ -49,7 +49,11 @@ Boundary uses the service account associated with the VM instance to authenticat If you downloaded the private key from GCP, it may contain extra `/n` characters that cause an error. -You can use `jq` to remove the extra `/n` characters. +You can use the `jq` utility to remove the extra `/n` characters. For example: + +```shell-session +$ jq -r '.private_key' my-gcp-private-key.json +``` From b5f69be317409d6669e1414cfddcc443380e1961 Mon Sep 17 00:00:00 2001 From: stellarsquall Date: Thu, 30 Jan 2025 12:38:22 -0700 Subject: [PATCH 6/7] use : operator for label filters --- .../content/docs/concepts/host-discovery/gcp.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/website/content/docs/concepts/host-discovery/gcp.mdx b/website/content/docs/concepts/host-discovery/gcp.mdx index 0d8adcb64e..29b349e4a3 100644 --- a/website/content/docs/concepts/host-discovery/gcp.mdx +++ b/website/content/docs/concepts/host-discovery/gcp.mdx @@ -428,15 +428,15 @@ Complete the following steps to create a host set: ```shell-session $ boundary host-sets create plugin \ -host-catalog-id $BOUNDARY_HOST_CATALOG_ID \ - -attr filters=labels.env=prod \ - -attr filters=labels.app=web + -attr filters=labels.env:prod \ + -attr filters=labels.app:web ``` 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 GCP. - The `filters` field contains string filters in the format key=val1. + The `filters` field contains string filters in the format key=val. The key corresponds to a filter option. For a list of filter options, refer to the [GCP API documentation](https://cloud.google.com/compute/docs/reference/rest/v1/instances/list#filter). When you apply multiple filters, the plugin applies a logical `AND` operation to combine the filters. @@ -446,8 +446,8 @@ Complete the following steps to create a host set: We recommend using labels as filters because they are more flexible and can filter on multiple values as in the following examples: - - `-attr filters=labels.env=dev` - - `-attr filters=labels.env=prod AND labels.app=web` + - `-attr filters=labels.env:dev` + - `-attr filters="labels.env:prod AND labels.app:web"` For more fields that you can use when creating host sets, refer to [the domain model documentation](/boundary/docs/concepts/domain-model/host-sets). @@ -464,7 +464,7 @@ resource "boundary_host_set_plugin" "gcp_host_set" { description = "GCP Host Set" host_catalog_id = boundary_scope.gcp_host_catalog.id attributes_json = jsonencode({ - "filters" = ["labels.env=prod", "labels.app=web"] }) + "filters" = ["labels.env:prod", "labels.app:web"] }) } ``` @@ -482,8 +482,8 @@ The default status ensures that Boundary only filters running instances, saving We recommend using labels as filters because they are more flexible and can filter on multiple values as in the following examples: - - `-attr filters=labels.env=dev` - - `-attr filters=labels.env=prod AND labels.app=web` + - `-attr filters=labels.env:dev` + - `-attr filters="labels.env:prod AND labels.app:web"` For more fields that you can use when creating host sets, refer to [the domain model documentation](/boundary/docs/concepts/domain-model/host-sets). From 2c36a099583a90bb09c9362cf9b6e428d506df3e Mon Sep 17 00:00:00 2001 From: stellarsquall Date: Thu, 30 Jan 2025 14:19:26 -0700 Subject: [PATCH 7/7] use generic TF variables, CLI attr fixes --- .../docs/concepts/host-discovery/aws.mdx | 29 ++++++++++--------- .../docs/concepts/host-discovery/azure.mdx | 9 +++--- .../docs/concepts/host-discovery/gcp.mdx | 25 +++++++++------- 3 files changed, 34 insertions(+), 29 deletions(-) diff --git a/website/content/docs/concepts/host-discovery/aws.mdx b/website/content/docs/concepts/host-discovery/aws.mdx index 2f7e426ab2..62eb7f8f86 100644 --- a/website/content/docs/concepts/host-discovery/aws.mdx +++ b/website/content/docs/concepts/host-discovery/aws.mdx @@ -105,10 +105,10 @@ The required fields for creating a dynamic host catalog depend on whether you co -plugin-name aws \ -attr disable_credential_rotation=true \ -attr region=us-east-1 \ - -role_arn \ - -role_external_id \ - -role_session_name \ - -role_tags + -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 ``` The `scope-id` and `plugin-name` fields are required when you create a dynamic host catalog. @@ -148,16 +148,17 @@ Apply the following Terraform policy: 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({ "region" = "eu-west-2", "disable_credential_rotation" = true }) secrets_json = jsonencode({ - "access_key_id" = var.aws_access, - "secret_access_key" = var.aws_secret}) + "access_key_id" = "AWS_ACCESS_KEY_ID_VALUE", + "secret_access_key" = "AWS_SECRET_ACCESS_KEY_VALUE"}) } ``` -The `scope-id` and `plugin-name` fields are required when you create a dynamic host catalog. +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: @@ -184,14 +185,14 @@ Apply the following Terraform policy: "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}) + "role_arn" = "AWS_ROLE_ARN_VALUE", + "role_external_id" = "AWS_ROLE_EXTERNAL_ID_VALUE", + "role_session_name" = "AWS_ROLE_SESSION_NAME_VALUE", + "role_tags" = "AWS_ROLE_TAGS_VALUE"}) } ``` -The `scope-id` and `plugin-name` fields are required when you create a dynamic host catalog. +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: @@ -267,13 +268,13 @@ Apply the following Terraform policy: resource "boundary_host_set_plugin" "aws_host_set" { name = "AWS Host Set" description = "AWS Host Set" - host_catalog_id = boundary_scope.aws_host_catalog.id + host_catalog_id = boundary_host_catalog_plugin.aws_host_catalog.id attributes_json = jsonencode({ "filters" = ["tag-key=foo,bar", "tag-key=baz"] }) } ``` -The `host-catalog-id` value is a required field that specifies in which host catalog to create this 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. diff --git a/website/content/docs/concepts/host-discovery/azure.mdx b/website/content/docs/concepts/host-discovery/azure.mdx index 1e3e0ddaa4..5010b4a104 100644 --- a/website/content/docs/concepts/host-discovery/azure.mdx +++ b/website/content/docs/concepts/host-discovery/azure.mdx @@ -80,6 +80,7 @@ resource "boundary_host_catalog_plugin" "azure_host_catalog" { scope_id = boundary_scope.project.id plugin_name = "azure" + # recommended to pass in aws secrets using a file() or using environment variables attributes_json = jsonencode({ "tenant_id" = "ARM_TENANT_ID", "subscription_id" = "ARM_SUBSCRIPTION_ID" @@ -90,10 +91,10 @@ resource "boundary_host_catalog_plugin" "azure_host_catalog" { } ``` -The `scope-id` and `plugin-name` fields are required when you create a +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 +The fields following the `attributes_json` and `secrets_json` 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. @@ -173,10 +174,10 @@ Apply the following Terraform policy: } ``` -The `host-catalog-id` value is a required field that specifies in which host catalog to +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 fields following the `attributes_json` 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. diff --git a/website/content/docs/concepts/host-discovery/gcp.mdx b/website/content/docs/concepts/host-discovery/gcp.mdx index 29b349e4a3..8a94aeb616 100644 --- a/website/content/docs/concepts/host-discovery/gcp.mdx +++ b/website/content/docs/concepts/host-discovery/gcp.mdx @@ -279,14 +279,15 @@ Apply the following Terraform policy: scope_id = boundary_scope.project.id plugin_name = "gcp" + # recommended to pass in aws secrets using a file() or using environment variables attributes_json = jsonencode({ "zone" = "us-central1-a ", - "project_id" = var.gcp_project_id, - "client_email" = var.gcp_client_email, + "project_id" = "GCP_PROJECT_ID_VALUE", + "client_email" = "GCP_CLIENT_EMAIL_VALUE", "disable_credential_rotation" = true }) secrets_json = jsonencode({ - "private_key_id" = var.private_key_id, - "private_key" = var.private_key}) + "private_key_id" = "GCP_PRIVATE_KEY_ID_VALUE", + "private_key" = "GCP_PRIVATE_KEY_VALUE"}) } ``` @@ -325,15 +326,16 @@ Apply the following Terraform policy: scope_id = boundary_scope.project.id plugin_name = "gcp" + # recommended to pass in aws secrets using a file() or using environment variables attributes_json = jsonencode({ "zone" = "us-central1-a ", - "project_id" = var.gcp_project_id, - "client_email" = var.gcp_base_service_account_email, - "target_service_account_id" = var.gcp_target_service_account_email, + "project_id" = "GCP_PROJECT_ID_VALUE", + "client_email" = "GCP_BASE_SERVICE_ACCOUNT_EMAIL_VALUE", + "target_service_account_id" = "GCP_TARGET_SERVICE_ACCOUNT_EMAIL_VALUE", "disable_credential_rotation" = true }) secrets_json = jsonencode({ - "private_key_id" = var.base_service_account_private_key_id, - "private_key" = var.base_service_account_private_key}) + "private_key_id" = "BASE_SERVICE_ACCOUNT_PRIVATE_KEY_ID_VALUE", + "private_key" = "BASE_SERVICE_ACCOUNT_PRIVATE_KEY_VALUE"}) } ``` @@ -374,9 +376,10 @@ Apply the following Terraform policy: scope_id = boundary_scope.project.id plugin_name = "gcp" + # recommended to pass in aws secrets using a file() or using environment variables attributes_json = jsonencode({ "zone" = "us-central1-a ", - "project_id" = var.gcp_project_id, + "project_id" = "GCP_PROJECT_ID_VALUE", "disable_credential_rotation" = true }) } ``` @@ -462,7 +465,7 @@ Apply the following Terraform policy: resource "boundary_host_set_plugin" "gcp_host_set" { name = "GCP Host Set" description = "GCP Host Set" - host_catalog_id = boundary_scope.gcp_host_catalog.id + host_catalog_id = boundary_host_catalog_plugin.gcp_host_catalog.id attributes_json = jsonencode({ "filters" = ["labels.env:prod", "labels.app:web"] }) }