DOCSEARCHbyAlgolia
Submit Docs

HashiCorp Boundary

repository·main·Indexed 26 days ago

https://github.com/hashicorp/boundary

An identity-aware proxy providing secure, just-in-time access to network resources. Boundary integrates with IdPs via OIDC and manages credentials through static stores or HashiCorp Vault, allowing access to hosts and critical systems without requiring agents on target machines.

Tokens
40.1K
Snippets
62
Records
272
Agent score
84%

What's inside Boundary

  1. Boundary Architecture and Components

    main

    Boundary is an identity-aware proxy consisting of two primary server components:

    • Controller: Serves the API and coordinates session requests.
    • Workers: Perform the actual session handling.

    A single Boundary binary can act as a Controller, a Worker, or both. Boundary does not require an agent to be installed on the target hosts or services, making it suitable for managed cloud services and container-based workflows.

  2. Use the oplog package for data replication and verification

    main
    The oplog package is used to write operation log entries to the Boundary RDBMS. These entries facilitate data replication and verification. The package uses an optimistic locking mechanism via 'tickets' to ensure data integrity during concurrent writes.

  3. Quickstart with Boundary Dev mode

    main

    Boundary provides a dev mode for rapid testing and development. Running in dev mode starts both a Controller and a Worker with a single command. It automatically manages a PostgreSQL Docker container for storage and uses an internal KMS with ephemeral keys.

    When started, the Controller listens on http://127.0.0.1:9200 for API requests, and the Worker listens on http://127.0.0.1:9202 for session requests. The process will output default credentials (login name and password) for authentication.

    boundary dev

  4. Install and set up Enos for Boundary testing

    main

    Enos is a quality testing framework used to perform infrastructure integration testing for Boundary. To set up a local development environment, you need Terraform, Vault, Enos, and core utilities. If you require AWS access, you must also install the doormat-cli.

    Requirements:

    • Terraform >= 1.0
    • Vault >= 1.12.2
    • Enos >= v0.0.28
    • Doormat
    • Boundary CLI installed locally
    brew tap hashicorp/tap
brew install hashicorp/tap/terraform
brew install hashicorp/tap/vault
brew install enos coreutils jq

# (Optional) Set license key
export ENOS_VAR_boundary_license=${license_key}

# Install doormat cli for AWS access
brew tap hashicorp/security git@github.com:hashicorp/homebrew-security.git
brew install hashicorp/security/doormat-cli

  6. Use `comment on` statements correctly

    main

    To document database objects using comment on:

    • Keep the comment on statement, object type, object name, and is statement on the same line.
    • Place the comment on statement directly below the database object it describes.
    • Do not leave blank lines between the object declaration and its comment on statement.
    • Place the actual comment text on a new indented line.
    create table imaginary_basket (
  public_id wt_public_id primary key
);
comment on table imaginary_basket is
  'imaginary_basket is a table where each row is a resource that represents an imaginary shopping basket.';

  7. Update Boundary storage protobufs

    main

    Modify the storage protobufs to include the new field. Storage protobufs are located in internal/proto/controller/storage.

    Requirements:

    • GORM Tags: Define a gorm tag for the new field using the @gotags annotation.
    • Mask Mapping: Define a custom_options.v1.mask_mapping for the field. This maps the storage this field to the API that field.
    • Build: Run make proto after modifying the storage protobufs.
    make proto

  9. Run SQL tests for database logic

    main
    Use the make or make test command to execute the SQL test suite. This suite tests database logic, including PL/pgSQL functions, triggers, constraints, and indexes. Running this command will automatically start a Docker postgres container for initialization and a Docker pgtap container to execute the tests.
    make test

  10. Configure the EC2 instance for Enos testing

    main

    Once the AWS infrastructure is provisioned, perform the following setup on the EC2 instance:

    1. Update sudo password: Run sudo passwd ec2-user and enter a new password.
    2. Install Git: sudo yum install git
    3. Install Homebrew: Follow the instructions at https://brew.sh/. Ensure you follow the post-install instructions provided in the CLI (e.g., installing gcc and other utilities).
    4. Install Enos dependencies:
      • Refer to the Enos README for the full list.
      • Note: You do not need to install doormat.
      • You must create, add, and use a GitHub token on the EC2 instance (see GitHub SSH key documentation).
      • Install nvm and use Node.js version 20:
        nvm install 20
nvm use 20

    After these steps, you should be able to run Enos instances from the enos directory.

    sudo passwd ec2-user
sudo yum install git
nvm install 20
nvm use 20

  11. Build Boundary from source

    main

    To build Boundary from source, ensure you have Go v1.21 or greater and Docker installed. You also need either the Boundary UI dependencies or the gh CLI to fetch UI assets.

    Use make tools to install the specific tool versions used by the Boundary team, and make install to build the binary. Note that make tools may overwrite existing tools in your Go binary directory.

    make tools
make install
# After build, run in dev mode:
$GOPATH/bin/boundary dev

  12. Set up an AWS environment for running IPv6-only Enos tests

    main

    To run IPv6-only Enos tests without a native IPv6 connection, you must provision a specific AWS environment. Follow these infrastructure steps:

    1. Create an IPv6-enabled VPC.
    2. Create an IPv6-enabled subnet.
    3. Create an Internet Gateway and configure the appropriate routes.
    4. Launch a t2.medium EC2 instance with the following configuration:
      • Attach it to the created VPC.
      • Assign a public IPv4 address.
      • Assign a public IPv6 address.
      • Use at least 20GB of storage.
    5. Create an IAM policy with the required permissions (see below) and attach it to the EC2 instance.
    {
	"Version": "2012-10-17",
	"Statement": [
		{
			"Sid": "VisualEditor0",
			"Effect": "Allow",
			"Action": [
				"ec2:DescribeImages",
				"ec2:DescribeInstanceTypeOfferings",
				"ec2:DescribeAvailabilityZones",
				"ec2:CreateVpc",
				"kms:CreateKey",
				"ec2:CreateTags",
				"kms:DescribeKey",
				"ec2:DescribeVpcs",
				"kms:ScheduleKeyDeletion",
				"kms:GetKeyPolicy",
				"kms:GetKeyRotationStatus",
				"kms:ListResourceTags",
				"kms:CreateAlias",
				"ec2:DeleteVpc",
				"ec2:ModifyVpcAttribute",
				"kms:ListAliases",
				"ec2:DescribeVpcAttribute",
				"kms:DeleteAlias",
				"ec2:CreateSubnet",
				"ec2:CreateInternetGateway",
				"ec2:CreateSecurityGroup",
				"ec2:DescribeSecurityGroups",
				"ec2:AttachInternetGateway",
				"ec2:DescribeSubnets",
				"ec2:DescribeNetworkInterfaces",
				"ec2:DeleteSubnet",
				"ec2:DeleteSecurityGroup",
				"ec2:RevokeSecurityGroupEgress",
				"ec2:ModifySubnetAttribute",
				"ec2:DetachInternetGateway",
				"ec2:AuthorizeSecurityGroupIngress",
				"ec2:DeleteInternetGateway",
				"ec2:AuthorizeSecurityGroupEgress",
				"ec2:DescribeInternetGateways",
				"ec2:DescribeRouteTables",
				"ec2:CreateRoute",
				"ec2:RevokeSecurityGroupIngress",
				"iam:CreateUser",
				"iam:DeleteUser",
				"iam:TagUser",
				"iam:GetUser",
				"iam:ListGroupsForUser",
				"iam:CreateAccessKey",
				"iam:DeleteAccessKey",
				"iam:PutUserPolicy",
				"iam:GetUserPolicy",
				"iam:DeleteUserPolicy",
				"ec2:DeleteRoute",
				"ec2:RunInstances",
				"ec2:DescribeInstances",
				"rds:CreateDBSubnetGroup",
				"iam:CreateRole",
				"elasticloadbalancing:DescribeTargetGroups",
				"ec2:TerminateInstances",
				"ec2:DescribeInstanceTypes",
				"rds:DescribeDBSubnetGroups",
				"iam:GetRole",
				"elasticloadbalancing:CreateTargetGroup",
				"elasticloadbalancing:DeleteTargetGroup",
				"rds:DeleteDBSubnetGroup",
				"iam:ListInstanceProfilesForRole",
				"iam:DeleteRole",
				"ec2:DescribeTags",
				"rds:ListTagsForResource",
				"iam:ListRolePolicies",
				"elasticloadbalancing:AddTags",
				"ec2:DescribeInstanceAttribute",
				"rds:CreateDBInstance",
				"iam:ListAttachedRolePolicies",
				"elasticloadbalancing:ModifyTargetGroupAttributes",
				"rds:DeleteDBInstance",
				"ec2:DescribeVolumes",
				"rds:AddTagsToResource",
				"iam:PutRolePolicy",
				"iam:DeleteRolePolicy",
				"iam:CreateInstanceProfile",
				"iam:DeleteInstanceProfile",
				"elasticloadbalancing:DescribeTargetGroupAttributes",
				"ec2:DescribeInstanceCreditSpecifications",
				"rds:DescribeDBInstances",
				"iam:GetRolePolicy",
				"iam:GetInstanceProfile",
				"elasticloadbalancing:DescribeTags",
				"iam:RemoveRoleFromInstanceProfile",
				"iam:AddRoleToInstanceProfile",
				"elasticloadbalancing:DescribeLoadBalancers",
				"elasticloadbalancing:RegisterTargets",
				"elasticloadbalancing:CreateLoadBalancer",
				"elasticloadbalancing:DeregisterTargets",
				"elasticloadbalancing:ModifyLoadBalancerAttributes",
				"elasticloadbalancing:DeleteLoadBalancer",
				"elasticloadbalancing:DescribeLoadBalancerAttributes",
				"elasticloadbalancing:CreateListener",
				"elasticloadbalancing:DescribeListeners",
				"elasticloadbalancing:DeleteListener",
				"ec2:AssociateRouteTable",
				"ec2:DisassociateRouteTable",
				"ec2:CreateIpam",
				"ec2:DeleteIpam",
				"ec2:ModifyIpam",
				"ec2:DescribeIpams",
				"ec2:CreateIpamPool",
				"ec2:DeleteIpamPool",
				"ec2:ModifyIpamPool",
				"ec2:DescribeIpamPools",
				"ec2:AllocateIpamPoolCidr",
				"ec2:ProvisionIpamPoolCidr",
				"s3:CreateBucket",
				"s3:DeleteBucket",
				"s3:ListBucket",
				"s3:ListAllMyBuckets",
				"s3:GetAccelerateConfiguration",
				"s3:PutAccelerateConfiguration",
				"s3:GetLifecycleConfiguration",
				"s3:PutLifecycleConfiguration",
				"s3:GetReplicationConfiguration",
				"s3:PutReplicationConfiguration",
				"s3:GetBucket*",
				"s3:PutBucket*",
				"s3:GetEncryptionConfiguration",
				"s3:PutEncryptionConfiguration",
				"ec2:AttachNetworkInterface",
				"ec2:DetachNetworkInterface",
				"iam:CreateServiceLinkedRole",
				"iam:DeleteServiceLinkedRole",
				"iam:PassRole"
			],
			"Resource": "*"
		"]
	}
]
}