From 277f0a00352cd0a87add3fb811e161868aac4e39 Mon Sep 17 00:00:00 2001 From: Todd Date: Tue, 18 Jul 2023 12:18:51 -0700 Subject: [PATCH] Add new host discovery documentation layout (#3429) * Add new host discovery documentation layout Co-authored-by: Dan Heath <76443935+Dan-Heath@users.noreply.github.com> --- .../docs/concepts/host-discovery/aws.mdx | 116 ++++++++++++++++++ .../docs/concepts/host-discovery/azure.mdx | 114 +++++++++++++++++ .../index.mdx} | 23 ++-- website/data/docs-nav-data.json | 21 +++- 4 files changed, 261 insertions(+), 13 deletions(-) create mode 100644 website/content/docs/concepts/host-discovery/aws.mdx create mode 100644 website/content/docs/concepts/host-discovery/azure.mdx rename website/content/docs/concepts/{host-discovery.mdx => host-discovery/index.mdx} (70%) diff --git a/website/content/docs/concepts/host-discovery/aws.mdx b/website/content/docs/concepts/host-discovery/aws.mdx new file mode 100644 index 0000000000..36d88d65d0 --- /dev/null +++ b/website/content/docs/concepts/host-discovery/aws.mdx @@ -0,0 +1,116 @@ +--- +layout: docs +page_title: AWS dynamic host catalogs +description: |- + An overview of AWS host discovery in Boundary +--- +# AWS dynamic host catalogs +Boundary uses dynamic host catalogs to automatically discover AWS EC2 instances and add them as hosts. + +## Create a host catalog to connect with AWS +Boundary uses plugins to integrate with a variety of providers. To use +a dynamic host catalog to integrate with AWS, you create a host catalog of the `plugin` type +and set the `plugin-name` value to `aws`. You must also provide the specific +fields needed for Boundary to authenticate with 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 +``` + + + + + ```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" + + 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}) + } + ``` + + + + +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. + +- `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. +- `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. + +## 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: + + + + +```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 +``` + + + + +```hcl +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 + 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. + +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). diff --git a/website/content/docs/concepts/host-discovery/azure.mdx b/website/content/docs/concepts/host-discovery/azure.mdx new file mode 100644 index 0000000000..c401237528 --- /dev/null +++ b/website/content/docs/concepts/host-discovery/azure.mdx @@ -0,0 +1,114 @@ +--- +layout: docs +page_title: Azure dynamic host catalogs +description: |- + An overview of Azure host discovery in Boundary +--- +# Azure dynamic host catalogs +Boundary uses dynamic host catalogs to automatically discover Azure resources available through Azure Resource Manager (ARM) and add them as hosts. + +## Create a host catalog to connect with Azure +Boundary uses plugins to integrate with a variety of providers. To use a +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. + + + + +```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 +``` + + + + +```hcl +resource "boundary_host_catalog_plugin" "azure_host_catalog" { + name = "Azure Catalog" + description = "Azure Host Catalog" + scope_id = boundary_scope.project.id + plugin_name = "azure" + + attributes_json = jsonencode({ + "tenant_id" = "ARM_TENANT_ID", + "subscription_id" = "ARM_SUBSCRIPTION_ID" + "client_id" = "ARM_CLIENT_ID" + "disable_credential_rotation" = true }) + secrets_json = jsonencode({ + "secret_value" = "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 will 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. + +## 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: + + + + + + +```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'" +``` + + + + +```hcl + resource "boundary_host_set_plugin" "azure_host_set" { + name = "Azure Set" + description = "Azure Host Set" + host_catalog_id = boundary_scope.azure_host_catalog.id + attributes_json = jsonencode({ + "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. diff --git a/website/content/docs/concepts/host-discovery.mdx b/website/content/docs/concepts/host-discovery/index.mdx similarity index 70% rename from website/content/docs/concepts/host-discovery.mdx rename to website/content/docs/concepts/host-discovery/index.mdx index 531d614a0e..116707fa1d 100644 --- a/website/content/docs/concepts/host-discovery.mdx +++ b/website/content/docs/concepts/host-discovery/index.mdx @@ -10,7 +10,11 @@ description: |- Traditionally, connecting to remote hosts and services requires knowledge of the endpoint’s connection info (e.g. the IP address and port of the service). This creates complexity when managing the onboarding of new resources at scale -or dealing with dynamic services whose connection info frequently changes. +or dealing with dynamic, ephemeral services whose connection info frequently changes. +Furthermore, the increased operational overhead of having to manually manage and update +new or old resources is an inefficient use of time. +Resources should be tagged appropriately so that, depending on their identity, users +automatically have the resources that they are allowed to connect to. **Host discovery** focuses on automating the process of onboarding new or changed infrastructure resources – and their connection info – to Boundary @@ -33,7 +37,7 @@ infrastructure targets can be automated with This allows for dynamic configuration of a host and target without the need for prior knowledge of the target’s connection info. -**[Runtime host discovery via dynamic host catalogs](/boundary/tutorials/access-management/azure-host-catalogs)**: +**[Runtime host discovery via dynamic host catalogs](/boundary/tutorials/access-management/aws-host-catalogs)**: Boundary dynamic host catalogs automate the ingestion of resources from infrastructure providers into Boundary. Boundary hosts are automatically created, updated and added to host sets in order to reflect the connection @@ -44,14 +48,15 @@ configure new or changed resources. ## Dynamic host catalogs Dynamic host catalogs are an agentless workflow for Boundary to securely query infrastructure providers at runtime to discover and configure -new services. Boundary dynamic host catalogs are written in go-plugin and run -as separate processes. Boundary administrators can define rules for which +new services. Boundary administrators can define rules for which external resources should be ingested into the catalog by -[creating dynamic host](/boundary/docs/concepts/domain-model/host-sets) - sets with an attributes filter. Attributes specify the fields which the plugin - should use to lookup which hosts should be members of this host set. +[creating a host sets](/boundary/docs/concepts/domain-model/host-sets) +with an attributes filter. These filters specify which discovered hosts +should be members of the host set. -Currently, Boundary supports dynamic host catalog implementations for AWS and +Boundary currently supports dynamic host catalog for AWS and Azure and we will continue to grow this ecosystem to support additional providers. -You can get started with dynamic host catalogs [here](/boundary/tutorials/access-management/azure-host-catalogs). +You can get started with dynamic host catalogs for AWS +[here](/boundary/tutorials/access-management/aws-host-catalogs) +and for Azure [here](/boundary/tutorials/access-management/azure-host-catalogs). diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index b11999be5c..b9ed7c1c8a 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -136,10 +136,6 @@ "title": "Identity and access management", "path": "concepts/iam" }, - { - "title": "Host discovery", - "path": "concepts/host-discovery" - }, { "title": "Credential management", "path": "concepts/credential-management" @@ -148,6 +144,23 @@ "title": "Auditing", "path": "concepts/auditing" }, + { + "title": "Host discovery", + "routes": [ + { + "title": "Overview", + "path": "concepts/host-discovery" + }, + { + "title": "AWS dynamic hosts", + "path": "concepts/host-discovery/aws" + }, + { + "title": "Azure dynamic hosts", + "path": "concepts/host-discovery/azure" + } + ] + }, { "title": "Security", "routes": [