AWS cross-account discovery

Cross-account discovery enables Boundary dynamic host catalogs to discover and sync AWS EC2 instances across multiple AWS accounts and IAM roles using a single self-managed Boundary worker.

To set up an AWS dynamic host catalog using cross-account discovery, refer to the AWS dynamic host catalogs configuration guide.

Introduction

Organizations that operate multi-account AWS environments often distribute workloads and EC2 instances across different accounts for security, billing, or organizational boundaries.

Standard dynamic host catalog discovery in Boundary authenticates using a single IAM identity, a configured IAM user or an IAM instance role assigned to a self-managed worker. With single-role discovery, the plugin only queries instances in the account associated with that single role.

Cross-account discovery extends this model by using a two-hop role assumption chain through the AWS Security Token Service (AssumeRole). A single self-managed Boundary worker deployed in a central principal account can assume a target IAM role in any other AWS account, or a different role in the same account. This configuration lets you discover hosts across account boundaries without requiring separate workers in every AWS account.

Architecture and components

Cross-account discovery relies on two IAM roles and their associated policies:

• Principal account and role: The AWS account and IAM role where you deploy the self-managed Boundary worker. The worker assumes the principal account role, and the role's IAM policy grants permission to call sts:AssumeRole into one or more target roles.
• Target account and role: The AWS account and IAM role where the discovered EC2 instances reside. The target role has permissions to run ec2:DescribeInstances and includes a trust policy that permits the principal role to assume it.

Discovery workflow

When you configure a dynamic host catalog with cross-account attributes, Boundary performs discovery through the following workflow:

1. Worker routing: Boundary evaluates the dynamic host catalog's worker filter expression and routes the discovery request to the matching self-managed worker deployed in the principal account.
2. Principal authentication: The Boundary AWS plugin authenticates to AWS using the IAM instance profile or credentials of the self-managed worker in the principal account.
3. Target role assumption: The AWS plugin uses the principal credentials to call sts:AssumeRole on the target IAM role ARN (target_role_arn).
4. Instance discovery: Using the temporary credentials returned by sts:AssumeRole, the AWS plugin calls ec2:DescribeInstances in the target region, target_region, or the default catalog region.
5. Host synchronization: Boundary ingests the discovered EC2 instances into the dynamic host catalog and applies host set filters to map instances to host set members.

Catalog-to-account mapping

Boundary maintains a one-to-one relationship between a dynamic host catalog and the account where hosts are discovered:

• When you configure a target_role_arn, the host catalog is dedicated to discovering hosts from that target account or role.
• Boundary uses the principal account solely as a conduit for authentication and role assumption. Hosts discovered by that catalog belong to the target account.
• To discover hosts across multiple target accounts, create a separate dynamic host catalog for each target account that references the same principal role and worker.

The following diagram illustrates cross-account discovery with one principal account (Account A) and two target accounts (Accounts B and C), showing the 1:1 relationship between dynamic host catalogs and AWS accounts:

In this architecture:

• Host Catalog 1 routes to the self-managed Boundary worker in the principal account to discover Account A instances directly.
• Host Catalogs 2 and 3 also route to the same worker, which assumes Target Role B and Target Role C via sts:AssumeRole to discover instances in Target Accounts B and C, respectively.