docs: IA reorganization (#5838)
* docs: IA reorganization * docs: Updates * docs: Updates * docs: Fix links * docs: Updates * docs: Fix a typo * docs: Fix client agent topic * docs: Update Client Agent nav * docs: Fix conflict * docs: Fix a typo in Client Agent docs (#5853) * docs: Fix client agent topic * docs: Updates * docs: Updates * docs: Updates * docs: Updates * docs: Fixes get started and operations links * docs: Update nav * docs: Partials * docs: Unix partials * docs: Worker partials * docs: Updates * docs: Update workers and targets * docs: Updates * docs: Updates * docs: Fixes link * docs: Updates after sync review * docs: Updates from review feedback * docs: Move worker filter examples * docs: Fix links * docs: Updates for filters based on working session * docs: Fixes broken links * docs: Add links to other filter topics * docs: Update list intro * docs: Adds link * docs: Fixes redirects * docs: Fixes redirects * docs: Deleted mysql page from TOC * docs: Add versioned redirect * docs: Adds versioned redirects * docs: Adds versioned redirects * docs: Update redirects * docs: Update redirects * docs: Redirect fixes * docs: Update redirect format * docs: Fix a typo * docs: Fixes redirects * docs: Fixes redirect * docs: Adds links out to client agent troubleshooting * uses /etc/boundary.d/ as recommended installation directory (#6003) * docs: Updates legacy io links * docs: Fixes redirects * docs: Fix redirect * docs: Restoring deleted file --------- Co-authored-by: Robin Beck <stellarsquall@users.noreply.github.com>
This commit is contained in:
Dan HeathandRobin Beck authored and 
GitHub committed
1 parent
21fce7c5eb
commit
5ce6515156
253 files changed
+7897
-5673
No files matched your search
@@ -0,0 +1,350 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Configure controllers
|
||||
description: >-
|
||||
Configure Boundary controllers for a self-managed deployment, including TLS, KMS, and database parameters. Start the service, authenticate, and manage resources.
|
||||
---
|
||||
|
||||
# Configure controllers
|
||||
|
||||
Refer to the following sections to configure your Boundary controllers.
|
||||
|
||||
## Prepare TLS certificates
|
||||
|
||||
HashiCorp recommends that the Boundary controller nodes handle TLS using PKI for user connections.
|
||||
Further, we strongly recommend that you use certificates that an appropriate certificate authority (CA) generated and signed.
|
||||
|
||||
To use TLS, you must have two files on each Boundary controller node.
|
||||
You may have to create a new directory to store the certificate material at `/etc/boundary.d/tls`.
|
||||
Place the files in the following paths:
|
||||
|
||||
- `/etc/boundary.d/tls/boundary-cert.pem`
|
||||
|
||||
Place the Boundary TLS certificate with a Common Name (CN) and Subject Alternate Name (SAN) that matches your planned primary DNS record in this path so that the Boundary controllers and any SANs can access it.
|
||||
|
||||
- `/etc/boundary.d/tls/boundary-key.pem`
|
||||
|
||||
Place the Boundary TLS certificate's private key in this path.
|
||||
|
||||
If you do not generate unique TLS key material for each node, you should securely distribute the key material to each of the Boundary controller nodes.
|
||||
|
||||
## Prepare KMS keys
|
||||
|
||||
Boundary controllers require the two following different cryptographic keys:
|
||||
|
||||
- **Root key**: The root KMS key acts as a KEK (Key Encrypting Key) for the scope-specific KEKs, which are also referred to as the scope's root keys.
|
||||
When you create a scope, Boundary also creates the root KEK and the various DEKs (Data Encryption Keys).
|
||||
It encrypts the DEKs using the scope's KEK, and then encrypts the KEK with the KMS key marked for the root purpose.
|
||||
- **Recovery key**: You use the recovery KMS key to authenticate Boundary client rescue and recovery operation workflows.
|
||||
The recovery key includes a nonce and creation time as an encrypted payload.
|
||||
Boundary formats the payload as a token and sends it to the controller.
|
||||
The time and nonce ensure that an adversary cannot replay a value, and also ensure that a client must individually authenticate each operation, so that revoking access to the KMS has an immediate result.
|
||||
|
||||
The following keys are optional:
|
||||
|
||||
- **Worker-auth key (Optional)**: The controller and worker share the worker-auth KMS key to authenticate a worker to the controller.
|
||||
If a worker uses PKI authentication, this key is unnecessary.
|
||||
- **BSR key (Optional)**: Session recording requires the BSR KMS key.
|
||||
Boundary uses the BSR key for encrypting data and checking the integrity of recordings.
|
||||
If you do not add a BSR key to your controller configuration, you receive an error when you try to enable session recording.
|
||||
|
||||
There are other optional KMS keys that you can configure for different encryption scenarios.
|
||||
These scenarios include Boundary worker PKI auth encryption and Boundary worker or controller configuration encryption.
|
||||
Refer to [Data encryption in Boundary](/boundary/docs/secure/encryption/data-encryption) for more information.
|
||||
|
||||
<Note>
|
||||
There are two types of Boundary workers, distinguished by the method by which they authenticate with the Boundary controllers.
|
||||
One worker uses a PKI exchange to authenticate with the controllers. The other uses a KMS key for authentication by both the worker and the controller.
|
||||
You use the Worker-auth key listed above to enable KMS worker authentication.
|
||||
</Note>
|
||||
|
||||
HashiCorp strongly recommends that you use either Vault Transit or your cloud provider's key management system.
|
||||
Refer to the [Vault Transit](/vault/docs/secrets/transit) documentation or your cloud provider's key management documentation for more information.
|
||||
|
||||
After you create the keys in Vault or the key management system of your choice, you can prepare the PostgreSQL database.
|
||||
|
||||
## Prepare the database
|
||||
|
||||
Boundary manages its state and configuration in a Relational Database Management System (RDBMS), PostgreSQL.
|
||||
You should create, set up, and make the PostgreSQL database accessible to the Boundary controller nodes before you configure the nodes.
|
||||
|
||||
Refer to the [Database recommendations](/boundary/docs/architecture/system-requirements#database-recommendations) documentation for examples of cloud managed PostgreSQL databases.
|
||||
|
||||
## Create the controller configuration
|
||||
|
||||
Once you have configured the following, you can create the controller configuration:
|
||||
|
||||
- At least three virtual machines with Boundary installed on them
|
||||
- At least one TLS certificate and key to distribute to the virtual machines for TLS communication
|
||||
- KMS keys to use for at least root and recovery operations
|
||||
- A PostgreSQL database to manage configuration and state
|
||||
|
||||
You must complete the following controller configuration for each of the Boundary controller nodes.
|
||||
|
||||
### Base controller configuration
|
||||
|
||||
The core required values for a Boundary controller configuration include the following:
|
||||
|
||||
- `listener` blocks for `api`, `cluster`, and `ops`
|
||||
- A `kms` block
|
||||
- `disable_mlock`
|
||||
- A `controller` block
|
||||
|
||||
When you install Boundary from the HashiCorp Linux Repository, it installs some example configuration files under `/etc/boundary.d/`.
|
||||
Run the following commands to rename the example configuration files:
|
||||
|
||||
1. `sudo mv boundary.hcl boundary.hcl.old`
|
||||
1. `sudo mv controller.hcl controller.hcl.old`
|
||||
1. `sudo mv worker.hcl worker.hcl.old`
|
||||
|
||||
HashiCorp recommends that you use either the `env://` or `file://` notation in the configuration files to securely provide secret configuration components to the Boundary controller binaries.
|
||||
The following controller configuration example uses `env://` to declare the PostgreSQL connect strings as well as secure the AWS KMS configuration items.
|
||||
|
||||
When you install the Boundary binary using a package manager, it includes a unit file that configures an environment file at `/etc/boundary.d/boundary.env`.
|
||||
You can use this file to set the sensitive values used to configure the Boundary controllers and workers.
|
||||
The following is an example of a configuration using this environment file:
|
||||
|
||||
<CodeBlockConfig lineNumbers filename="/etc/boundary.d/boundary.env">
|
||||
|
||||
```shell-session
|
||||
POSTGRESQL_CONNECTION_STRING=postgresql://boundary:boundary@postgres.yourdomain.com:5432/boundary
|
||||
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
|
||||
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
<Note>
|
||||
|
||||
In the example above, the proper IAM roles and permissions for the given `AWS_ACCESS_KEY` and `AWS_SECRET_ACCESS_KEY` must be in place so that Boundary can use them to access the different KMS keys.
|
||||
|
||||
</Note>
|
||||
|
||||
Next, populate the `controller.hcl` file with any relevant configuration information.
|
||||
The following example configuration file is a good starting point for a production Boundary controller installation.
|
||||
It defines the three `listener` blocks, two unique `kms` blocks that are specific to AWS (as an example), the `disable_mlock` value, and the `controller` block.
|
||||
|
||||
<CodeBlockConfig lineNumbers filename="/etc/boundary.d/controller.hcl">
|
||||
|
||||
```hcl
|
||||
# disable memory from being swapped to disk
|
||||
disable_mlock = true
|
||||
|
||||
# API listener configuration block
|
||||
listener "tcp" {
|
||||
# Should be the address of the NIC that the controller server will be reached on
|
||||
# Use 0.0.0.0 to listen on all interfaces
|
||||
address = "0.0.0.0:9200"
|
||||
# The purpose of this listener block
|
||||
purpose = "api"
|
||||
|
||||
# TLS Configuration
|
||||
tls_disable = false
|
||||
tls_cert_file = "/etc/boundary.d/tls/boundary-cert.pem"
|
||||
tls_key_file = "/etc/boundary.d/tls/boundary-key.pem"
|
||||
|
||||
# Uncomment to enable CORS for the Admin UI. Be sure to set the allowed origin(s)
|
||||
# to appropriate values.
|
||||
#cors_enabled = true
|
||||
#cors_allowed_origins = ["https://yourcorp.yourdomain.com", "serve://boundary"]
|
||||
}
|
||||
|
||||
# Data-plane listener configuration block (used for worker coordination)
|
||||
listener "tcp" {
|
||||
# Should be the IP of the NIC that the worker will connect on
|
||||
address = "0.0.0.0:9201"
|
||||
# The purpose of this listener
|
||||
purpose = "cluster"
|
||||
}
|
||||
|
||||
# Ops listener for operations like health checks for load balancers
|
||||
listener "tcp" {
|
||||
# Should be the address of the interface where your external systems'
|
||||
# (eg: Load-Balancer and metrics collectors) will connect on.
|
||||
address = "0.0.0.0:9203"
|
||||
# The purpose of this listener block
|
||||
purpose = "ops"
|
||||
|
||||
tls_disable = false
|
||||
tls_cert_file = "/etc/boundary.d/tls/boundary-cert.pem"
|
||||
tls_key_file = "/etc/boundary.d/tls/boundary-key.pem"
|
||||
}
|
||||
|
||||
# Controller configuration block
|
||||
controller {
|
||||
# This name attr must be unique across all controller instances if running in HA mode
|
||||
name = "boundary-controller-1"
|
||||
description = "Boundary controller number one"
|
||||
|
||||
# This is the public hostname or IP where the workers can reach the
|
||||
# controller. This should typically be a load balancer address
|
||||
public_cluster_addr = "example-cluster-lb.example.com"
|
||||
|
||||
# Enterprise license file, can also be the raw value or env:// value
|
||||
license = "file:///path/to/license/file.hclic"
|
||||
|
||||
# After receiving a shutdown signal, Boundary will wait 10s before initiating the shutdown process.
|
||||
graceful_shutdown_wait_duration = "10s"
|
||||
|
||||
# Database URL for postgres. This is set in boundary.env and
|
||||
#consumed via the “env://” notation.
|
||||
database {
|
||||
url = "env://POSTGRESQL_CONNECTION_STRING"
|
||||
}
|
||||
}
|
||||
|
||||
# Events (logging) configuration. This
|
||||
# configures logging for ALL events to both
|
||||
# stderr and a file at /var/log/boundary/controller.log
|
||||
events {
|
||||
audit_enabled = true
|
||||
sysevents_enabled = true
|
||||
observations_enable = true
|
||||
sink "stderr" {
|
||||
name = "all-events"
|
||||
description = "All events sent to stderr"
|
||||
event_types = ["*"]
|
||||
format = "cloudevents-json"
|
||||
}
|
||||
sink {
|
||||
name = "file-sink"
|
||||
description = "All events sent to a file"
|
||||
event_types = ["*"]
|
||||
format = "cloudevents-json"
|
||||
file {
|
||||
path = "/var/log/boundary"
|
||||
file_name = "controller.log"
|
||||
}
|
||||
audit_config {
|
||||
audit_filter_overrides {
|
||||
sensitive = "redact"
|
||||
secret = "redact"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
# Root KMS Key (managed by AWS KMS in this example)
|
||||
# Keep in mind that sensitive values are provided via ENV VARS
|
||||
# in this example, such as access_key and secret_key
|
||||
kms "awskms" {
|
||||
purpose = "root"
|
||||
region = "us-east-1"
|
||||
kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey"
|
||||
endpoint = "https://vpce-0e1bb1852241f8cc6-pzi0do8n.kms.us-east-1.vpce.amazonaws.com"
|
||||
}
|
||||
|
||||
# Recovery KMS Key
|
||||
kms "awskms" {
|
||||
purpose = "recovery"
|
||||
region = "us-east-1"
|
||||
kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey2"
|
||||
endpoint = "https://vpce-0e1bb1852241f8cc6-pzi0do8n.kms.us-east-1.vpce.amazonaws.com"
|
||||
}
|
||||
|
||||
# Worker-Auth KMS Key (optional, only needed if you use
|
||||
# KMS authenticated workers)
|
||||
kms "awskms" {
|
||||
purpose = "worker-auth"
|
||||
region = "us-east-1"
|
||||
kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey3"
|
||||
endpoint = "https://vpce-0e1bb1852241f8cc6-pzi0do8n.kms.us-east-1.vpce.amazonaws.com"
|
||||
}
|
||||
|
||||
# BSR KMS Key (optional, only needed if you use the
|
||||
# session recording feature)
|
||||
kms "awskms" {
|
||||
purpose = "bsr"
|
||||
region = "us-east-1"
|
||||
kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey4"
|
||||
endpoint = "https://vpce-0e1bb1852241f8cc6-pzi0do8n.kms.us-east-1.vpce.amazonaws.com"
|
||||
}
|
||||
```
|
||||
</CodeBlockConfig>
|
||||
|
||||
Refer to the list below for explanations of the parameters used in the example above:
|
||||
|
||||
- `disable mlock (bool: false)` - Disables the server from executing the `mlock` syscall, which prevents memory swap to the disk.
|
||||
Preventing memory swap is fine for local development and testing.
|
||||
However, HashiCorp does not recommend using it for production unless the systems running Boundary use encrypted swap or do not use swap at all.
|
||||
Boundary only supports memory locking on UNIX-like systems that support `mlock()` syscall like Linux and FreeBSD.
|
||||
|
||||
On Linux, to give the Boundary executable the ability to use `mlock` syscall without running the process as root, run the following command:
|
||||
|
||||
`sudo setcap cap_ipc_lock=+ep $(readlink -f $(which boundary))`
|
||||
|
||||
If you use a Linux distribution with a modern version of systemd, you can add the following directive to the **"[Service]"** configuration section:
|
||||
|
||||
`LimitMEMLOCK=infinity`
|
||||
|
||||
- `listener` - Configures the listeners on which Boundary serves traffic (API cluster and proxy).
|
||||
- `controller` - Configures the controller.
|
||||
If present, `boundary server` starts a controller subprocess.
|
||||
- `events` - Configures event-specific parameters.
|
||||
|
||||
The example events configuration above is exhaustive and writes all events to both `stderr` and a file.
|
||||
This configuration may or may not work for your organization's logging solution.
|
||||
|
||||
- `kms` - Configures KMS blocks for [various purposes](/boundary/docs/secure/encryption/data-encryption).
|
||||
|
||||
Refer to the links below for configuration information for the different cloud KMS blocks:
|
||||
|
||||
- [AWS](/boundary/docs/configuration/kms/awskms)
|
||||
- [Azure](/boundary/docs/configuration/kms/azurekeyvault)
|
||||
- [GCP](/boundary/docs/configuration/kms/gcpckms)
|
||||
- [OCI](/boundary/docs/configuration/kms/ocikms)
|
||||
- [AliCloud](/boundary/docs/configuration/kms/alicloudkms)
|
||||
- [Vault Transit](/boundary/docs/configuration/kms/transit)
|
||||
|
||||
Refer to the documentation for additional [top-level configuration options](/boundary/docs/configuration) and additional [controller-specific options](/boundary/docs/configuration/controller).
|
||||
|
||||
## Initialize the database
|
||||
|
||||
Before you can start Boundary, you must initialize the database from one Boundary controller.
|
||||
Initialization is a one-time operation that executes the required database migrations for the Boundary cluster to operate.
|
||||
|
||||
```shell-session
|
||||
boundary database init -config /etc/boundary.d/controller.hcl
|
||||
```
|
||||
|
||||
Unless you configure it not to, Boundary automatically generates a number of resources to make getting started easier. It automatically generates default scopes, auth methods, user, account, and targets. These
|
||||
resources, however, are not required. You can add the following flags to skip creating these initial resources:
|
||||
|
||||
```shell-session
|
||||
boundary database init \
|
||||
-skip-auth-method-creation \
|
||||
-skip-host-resources-creation \
|
||||
-skip-scopes-creation \
|
||||
-skip-target-creation \
|
||||
-config /etc/boundary.d/controller.hcl
|
||||
```
|
||||
|
||||
Use the following command to view the help for additional initialization options:
|
||||
|
||||
```shell-session
|
||||
boundary database init -h
|
||||
```
|
||||
|
||||
## Start the Boundary service
|
||||
|
||||
When the configuration files are in place on each Boundary controller, you can proceed to enable and start the binary on each of the Boundary controller nodes using `systemd`.
|
||||
Run the following commands to start the service:
|
||||
|
||||
1. `sudo systemctl enable boundary`
|
||||
1. `sudo systemctl start boundary`
|
||||
|
||||
## Authenticate and manage resources
|
||||
|
||||
Upon logging in to Boundary for the first time, HashiCorp recommends creating an admin user for the global and project level scopes to manage Boundary.
|
||||
Creating an admin user allows you to configure targets within those scopes and manage them.
|
||||
|
||||
HashiCorp recommends that you use the [KMS recovery workflow](/boundary/docs/deploy/self-managed/initialize#log-in-with-recovery-kms) to log in to Boundary for the first time.
|
||||
Refer to [Creating your first login account](/boundary/docs/deploy/self-managed/initialize#create-your-first-login-account) to learn about setting up your first auth method, user, account, and role to log in to Boundary going forward without the recovery KMS workflow.
|
||||
|
||||
## Next steps
|
||||
|
||||
After you configure the controller, you should:
|
||||
|
||||
1. [Deploy workers](/boundary/docs/deploy/self-managed/deploy-workers)
|
||||
1. [Initialize Boundary](/boundary/docs/deploy/self-managed/initialize)
|
||||
1. [Install the Boundary Clients](/boundary/docs/deploy/self-managed/install-clients)
|
||||
@@ -0,0 +1,278 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Deploy workers
|
||||
description: >-
|
||||
Configure Boundary workers for a self-managed deployment, including environment files and KMS keys. Set up ingress, intermediary, and egress roles for multi-hop.
|
||||
---
|
||||
|
||||
# Deploy workers
|
||||
|
||||
Before you deploy workers, you should have completed the following steps:
|
||||
|
||||
- Installed Boundary on at least three [controller nodes](/boundary/docs/deploy/self-managed/configure-controllers).
|
||||
- Prepared or have three existing network boundaries:
|
||||
- Public/DMZ network
|
||||
- Intermediary network
|
||||
- Private network
|
||||
- Prepared three virtual machines for Boundary workers, one in each network boundary with the Boundary binary installed on it.
|
||||
|
||||
In the following configuration files, there are common configuration components as well as some unique components depending on the role the Boundary worker performs.
|
||||
There are three files, one for each worker in a unique network boundary.
|
||||
Additionally, Boundary Enterprise supports a [multi-hop configuration](/boundary/docs/workers/multi-hop) in which the Boundary workers can serve one of three purposes: an ingress worker, an ingress/egress worker, or an egress worker.
|
||||
|
||||
## Prepare the environment files
|
||||
|
||||
HashiCorp recommends using either the `env://` or `file://` notation within the configuration files, to securely provide secret configuration components to the Boundary worker binaries.
|
||||
The following configuration example uses `env://` to secure AWS KMS configuration items.
|
||||
|
||||
When you install the Boundary binary using a package manager, it includes a unit file which configures an environment file at `/etc/boundar.d/boundary.env`.
|
||||
You can use this file to set the sensitive values that are used to configure the Boundary workers.
|
||||
The following file is an example of how this environment file could be configured:
|
||||
|
||||
<CodeBlockConfig lineNumbers filename="/etc/boundary.d/boundary.env">
|
||||
|
||||
```shell-session
|
||||
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
|
||||
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
In the example above, the proper IAM roles and permissions for the given `AWS_ACCESS_KEY` and `AWS_SECRET_ACCESS_KEY` must be in place so that Boundary can use them to access the different KMS keys.
|
||||
|
||||
## Prepare the worker KMS keys
|
||||
|
||||
The worker-auth storage KMS key is used by a Worker for the encrypted storage of authentication keys.
|
||||
This is recommended Workers using controller-led or worker-led methods. If it is not specified, the authentication keys are not encrypted on disk.
|
||||
Optionally, if you deploy KMS authentication-driven Boundary workers, an additional KMS key must be generated to authenticate the Boundary worker with the controller.
|
||||
|
||||
HashiCorp strongly recommends using the Key Management System (KMS) of the cloud provider where you deploy your Boundary workers.
|
||||
Keep in mind that Boundary workers must have the correct level of permissions for interacting with the cloud provider's KMS.
|
||||
Refer to your cloud provider's documentation, for more information.
|
||||
|
||||
## Create the worker configurations
|
||||
|
||||
After you create the requisite key or keys in the cloud provider of your choice, you can begin configuring the workers.
|
||||
|
||||
The following configuration examples all employ the worker-led authorization flow.
|
||||
For more information on configuring KMS authentication for Boundary workers, refer to the [KMS authentication configuration documenation](/boundary/docs/workers/registration#kms-configuration).
|
||||
|
||||
If you use Boundary Enterprise, you can configure multiple workers to act in three different roles: ingress, intermediary, and egress.
|
||||
For Community Edition, workers only serve one role, acting as both the point of ingress and egress.
|
||||
Select your Boundary edition, and complete the following steps to configure workers.
|
||||
|
||||
<Tabs>
|
||||
<Tab heading="Enterprise">
|
||||
|
||||
For Boundary Enterprise, you can configure ingress, intermediary, and egress workers to take advantage of [multi-hop worker capabilities](/boundary/docs/workers#multi-hop-sessions).
|
||||
|
||||
Note that "ingress," "intermediary," and "egress" are general ways to describe how the respective worker interacts with resources.
|
||||
A worker can serve more than one of those roles at a time.
|
||||
Refer to [Multi-hop sessions](/boundary/docs/workers/multi-hop) for more information.
|
||||
|
||||
Complete the steps below to configure workers for Boundary Enterprise.
|
||||
|
||||
### Ingress worker configuration
|
||||
|
||||
@include '/workers/ingress-worker-config.mdx'
|
||||
|
||||
### Intermediate worker configuration
|
||||
|
||||
@include '/workers/intermediate-worker-config.mdx'
|
||||
|
||||
### Egress worker configuration
|
||||
|
||||
@include '/workers/egress-worker-config.mdx'
|
||||
|
||||
</Tab>
|
||||
<Tab heading="Community Edition">
|
||||
|
||||
For the Community Edition of Boundary, you must configure a worker server that communicates with the controller and is responsible for storage-related tasks.
|
||||
|
||||
Boundary Community Edition only supports egress workers. To configure workers for multi-hop sessions, check the Boundary Enterprise configuration.
|
||||
|
||||
Complete the following steps to configure the worker.
|
||||
|
||||
### Worker configuration
|
||||
|
||||
@include '/workers/single-worker-config.mdx'
|
||||
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Start the Boundary service
|
||||
|
||||
When the configuration files are in place on each Boundary controller, you can proceed to enable and start the binary on each of the Boundary worker nodes using `systemd`.
|
||||
Run the following commands to start the service:
|
||||
|
||||
1. `sudo systemctl enable boundary`
|
||||
1. `sudo systemctl start boundary`
|
||||
|
||||
## Adopt the workers (optional)
|
||||
|
||||
If you use the workers as outlined above, you must adopt the Boundary workers.
|
||||
Complete the following steps to adopt the workers:
|
||||
|
||||
<Tabs>
|
||||
|
||||
<Tab heading="Admin UI">
|
||||
|
||||
Complete the following steps to adopt the worker using the UI:
|
||||
|
||||
1. Log in to Boundary as the admin user.
|
||||
|
||||
1. Select **Workers** in the navigation pane.
|
||||
|
||||
1. Click **New**.
|
||||
|
||||
1. (Optional) You can use the workers page to construct the contents of the `worker.hcl` file, if you did not [create the configuration file](/boundary/docs/deploy/self-managed/deploy-workers#create-the-worker-configurations) as part of the installation process above.
|
||||
Provide the following details, and Boundary constructs the worker configuration file for you:
|
||||
- Boundary Cluster ID
|
||||
- Worker Public Address
|
||||
- Config file path
|
||||
- Worker Tags
|
||||
|
||||
1. Scroll to the bottom of the **New Worker** page, and paste the **Worker Auth Registration Request** key.
|
||||
Boundary provides you with the **Worker Auth Registration Request** key in the CLI output when you start the worker.
|
||||
You can also locate this value in the `auth_request_token` file.
|
||||
|
||||
1. Click **Register Worker**.
|
||||
|
||||
1. Click **Done**.
|
||||
|
||||
The new worker appears on the **Workers** page.
|
||||
|
||||
1. Repeat the registration process for any other workers, such as the intermediate and egress workers.
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab heading="CLI">
|
||||
|
||||
Complete the following steps to adopt the worker using the CLI:
|
||||
|
||||
1. Use the following command to ensure that the `BOUNDARY_ADDR` is set as an environment variable:
|
||||
|
||||
```hcl
|
||||
$ export BOUNDARY_ADDR="https://c3a7a20a-f663-40f3-a8e3-1b2f69b3625.boundary.hashicorp.cloud"
|
||||
```
|
||||
|
||||
1. Log into the CLI as the admin user, providing the Auth Method ID, admin login name, and admin password when prompted.
|
||||
|
||||
```hcl
|
||||
$ boundary authenticate password \
|
||||
-auth-method-id=ampw_KfLAjMS2CG \
|
||||
-login-name=admin
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
<CodeBlockConfig hideClipboard>
|
||||
|
||||
```hcl
|
||||
$ boundary authenticate password \
|
||||
-auth-method-id=ampw_KfLAjMS2CG \
|
||||
-login-name=admin
|
||||
Please enter the password (it will be hidden):
|
||||
|
||||
Authentication information:
|
||||
Account ID: acctpw_r6crEm0FgM
|
||||
Auth Method ID: ampw_KfLAjMS2CG
|
||||
Expiration Time: Mon, 27 Jun 2022 22:03:28 MDT
|
||||
User ID: u_ysJd0LXX9T
|
||||
|
||||
The token was successfully stored in the chosen keyring and is not displayed here.
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
1. Next, use the following command to export the **Worker Auth Request Token** value as an environment variable:
|
||||
|
||||
```shell-session
|
||||
$ export WORKER_TOKEN=<Worker Auth Registration Request Value>
|
||||
```
|
||||
|
||||
Boundary provides you with the **Worker Auth Registration Request** key in the CLI output when you start the worker.
|
||||
You can also locate this value in the `auth_request_token` file.
|
||||
|
||||
The token is used to issue a create worker request that authorizes the worker to Boundary and makes it available.
|
||||
Currently worker creation is only supported for workers with an authorization token (worker-led and controller-led).
|
||||
|
||||
1. Create a new worker using the worker-led registration method with the following command:
|
||||
|
||||
```shell-session
|
||||
$ boundary workers create worker-led -worker-generated-auth-token=$WORKER_TOKEN
|
||||
|
||||
Worker information:
|
||||
Active Connection Count: 0
|
||||
Created Time: Fri, 03 Jan 2025 13:52:04 MST
|
||||
ID: w_zLGjAbYx1h
|
||||
Local Storage State: unknown
|
||||
Type: pki
|
||||
Updated Time: Fri, 03 Jan 2025 13:52:04 MST
|
||||
Version: 1
|
||||
|
||||
Scope:
|
||||
ID: global
|
||||
Name: global
|
||||
Type: global
|
||||
|
||||
Authorized Actions:
|
||||
no-op
|
||||
read
|
||||
update
|
||||
delete
|
||||
add-worker-tags
|
||||
set-worker-tags
|
||||
remove-worker-tags
|
||||
```
|
||||
|
||||
Confirm the worker registration and view its details by executing the following command and supplying the new worker's id:
|
||||
|
||||
```shell-session
|
||||
$ boundary workers read -id w_zLGjAbYx1h
|
||||
|
||||
Worker information:
|
||||
Active Connection Count: 0
|
||||
Address: 127.0.0.1:9202
|
||||
Created Time: Fri, 03 Jan 2025 13:52:04 MST
|
||||
ID: w_zLGjAbYx1h
|
||||
Last Status Time: 2025-01-03 20:58:41.346537 +0000 UTC
|
||||
Local Storage State: not configured
|
||||
Release Version: Boundary v0.18.1+ent
|
||||
Type: pki
|
||||
Updated Time: Fri, 03 Jan 2025 13:58:41 MST
|
||||
Version: 1
|
||||
|
||||
Scope:
|
||||
ID: global
|
||||
Name: global
|
||||
Type: global
|
||||
|
||||
Tags:
|
||||
Configuration:
|
||||
type: ["worker1" "upstream"]
|
||||
Canonical:
|
||||
type: ["upstream" "worker1"]
|
||||
|
||||
Authorized Actions:
|
||||
add-worker-tags
|
||||
set-worker-tags
|
||||
remove-worker-tags
|
||||
no-op
|
||||
read
|
||||
update
|
||||
delete
|
||||
```
|
||||
|
||||
1. Repeat the registration process for any other workers, such as the intermediate and egress workers.
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Next steps
|
||||
|
||||
After you configure workers, you should:
|
||||
|
||||
1. [Initialize Boundary](/boundary/docs/deploy/self-managed/initialize)
|
||||
1. [Install the Boundary Clients](/boundary/docs/deploy/self-managed/install-clients)
|
||||
@@ -0,0 +1,51 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Deploy Boundary in a self-managed environment
|
||||
description: >-
|
||||
Discover resources for deploying a self-managed version of Boundary Enterprise or Boundary Community Edition.
|
||||
---
|
||||
|
||||
# Deploy Boundary in a self-managed environment
|
||||
|
||||
To deploy a self-managed Boundary environment you should:
|
||||
|
||||
1. Install the Boundary binary
|
||||
1. Deploy and configure Boundary controllers and workers
|
||||
1. Install end-user clients
|
||||
|
||||
This guide outlines the required steps to manually install and configure a
|
||||
single self-managed HashiCorp Boundary cluster as defined in the Recommended
|
||||
architecture topic.
|
||||
It assumes you install Boundary on virtual machines (VMs) or bare-metal servers
|
||||
running a Debian or Red Hat-based Linux distribution.
|
||||
|
||||
To deploy HCP Boundary instead, refer to the [Deploy and log in](/boundary/docs/hcp/get-started/deploy-and-login) in the HCP Boundary Get started documentation.
|
||||
|
||||
This document includes general guidance as well as specific recommendations for
|
||||
popular cloud infrastructure platforms. These recommendations have also been
|
||||
encoded into official Terraform reference architectures for
|
||||
[AWS](https://github.com/hashicorp/boundary-reference-architecture/tree/main/deployment/aws),
|
||||
[Azure](https://github.com/hashicorp/boundary-reference-architecture/tree/main/deployment/azure),
|
||||
and
|
||||
[GCP](https://github.com/hashicorp/boundary-reference-architecture/tree/main/deployment/gcp).
|
||||
|
||||
## More information
|
||||
|
||||
Before you begin, you may want to review the following information about Boundary's architecture and system requirements:
|
||||
|
||||
- [System requirements](/boundary/docs/architecture/system-requirements)
|
||||
- [Recommended architecture](/boundary/docs/architecture/recommended-architecture)
|
||||
- [Fault tolerance](/boundary/docs/architecture/fault-tolerance)
|
||||
- [High availability](/boundary/docs/architecture/high-availability)
|
||||
|
||||
## Next steps
|
||||
|
||||
Refer to the following topics to deploy your self-managed environment:
|
||||
|
||||
1. [Install Boundary](/boundary/docs/deploy/self-managed/install)
|
||||
1. [Configure controllers](/boundary/docs/deploy/self-managed/configure-controllers)
|
||||
1. [Deploy workers](/boundary/docs/deploy/self-managed/deploy-workers)
|
||||
1. [Initialize Boundary](/boundary/docs/deploy/self-managed/initialize)
|
||||
1. [Install Boundary clients](/boundary/docs/deploy/self-managed/install-clients)
|
||||
|
||||
To configure Boundary resources using Terraform, refer to [Terraform patterns](/boundary/docs/deploy/terraform-patterns).
|
||||
@@ -0,0 +1,468 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Initialize Boundary
|
||||
description: >-
|
||||
Initialize new Boundary self-managed installations. Log in with the recovery KMS to create initial scope, auth method, login account, user, and role resources.
|
||||
---
|
||||
|
||||
# Initialize Boundary
|
||||
|
||||
This document describes how to access Boundary for the first time and create the necessary resources to log in as a
|
||||
user.
|
||||
|
||||
You can also initialize and manage Boundary using Terraform. Refer to the [Terraform patterns](/boundary/docs/deploy/terraform-patterns) page to learn more.
|
||||
|
||||
## Requirements
|
||||
|
||||
Before you initialize Boundary, you should have [initialized a database](/boundary/docs/deploy/self-managed/configure-controllers#initialize-the-database).
|
||||
|
||||
## Log in with recovery KMS
|
||||
|
||||
To access a new Boundary instance for the first time, you must use the recovery KMS defined in the
|
||||
controller configuration file. The following example represents a configuration file that uses hard-coded AEAD keys:
|
||||
|
||||
<Note>
|
||||
|
||||
In a production environment, HashiCorp recommends that you use a cloud provider's KMS such as [AWS KMS](/boundary/docs/configuration/kms/awskms)
|
||||
to manage the keys Boundary uses to encrypt sensitive information.
|
||||
|
||||
</Note>
|
||||
|
||||
```hcl
|
||||
<truncated>
|
||||
kms "aead" {
|
||||
purpose = "root"
|
||||
aead_type = "aes-gcm"
|
||||
key = "sP1fnF5Xz85RrXyELHFeZg9Ad2qt4Z4bgNHVGtD6ung="
|
||||
key_id = "global_root"
|
||||
}
|
||||
|
||||
kms "aead" {
|
||||
purpose = "worker-auth"
|
||||
aead_type = "aes-gcm"
|
||||
key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
|
||||
key_id = "global_worker-auth"
|
||||
}
|
||||
|
||||
kms "aead" {
|
||||
purpose = "recovery"
|
||||
aead_type = "aes-gcm"
|
||||
key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
|
||||
key_id = "global_recovery"
|
||||
}
|
||||
<truncated>
|
||||
```
|
||||
|
||||
The KMS with the `recovery` purpose is used to "recover" Boundary, allowing you to authenticate to Boundary and manage
|
||||
it as a super user. It also allows you to authenticate from the CLI or from Terraform to manage Boundary
|
||||
without any generated resources.
|
||||
|
||||
To authenticate to Boundary using the recovery KMS workflow:
|
||||
|
||||
<Tabs>
|
||||
<Tab heading="CLI">
|
||||
|
||||
|
||||
To use the recovery workflow on the CLI, you must pass the `-recovery-config <path_to_kms_recovery_config>` flag or set the environment
|
||||
variable for `BOUNDARY_RECOVERY_CONFIG` for every command ran. Authentication takes place for every command
|
||||
ran when using the recovery workflow. The `boundary authenticate` command does not apply when you use the recovery KMS.
|
||||
|
||||
```shell-session
|
||||
$ cat << EOF > /tmp/recovery.hcl
|
||||
kms "aead" {
|
||||
purpose = "recovery"
|
||||
aead_type = "aes-gcm"
|
||||
key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
|
||||
key_id = "global_recovery"
|
||||
}
|
||||
EOF
|
||||
|
||||
# Example command
|
||||
$ boundary users create <truncated> -recovery-config /tmp/recovery.hcl
|
||||
...
|
||||
```
|
||||
|
||||
</Tab>
|
||||
<Tab heading="Terraform">
|
||||
|
||||
|
||||
To configure your provider to use the recovery KMS workflow, provide the KMS block as the value for
|
||||
`recovery_kms_hcl`:
|
||||
|
||||
```hcl
|
||||
provider "boundary" {
|
||||
addr = "https://boundary.mycorp.com:9200"
|
||||
recovery_kms_hcl = <<EOT
|
||||
kms "aead" {
|
||||
purpose = "recovery"
|
||||
aead_type = "aes-gcm"
|
||||
key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
|
||||
key_id = "global_recovery"
|
||||
}
|
||||
EOT
|
||||
}
|
||||
```
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Create your first login account
|
||||
|
||||
This section covers how to configure your first auth method, user, account, and role to log in to Boundary without
|
||||
the recovery KMS workflow. In this example, we are going to make an admin user for the global and project level
|
||||
scopes we create. This will allow our user to configure targets within those scopes and manage them.
|
||||
|
||||
### Create org and project scopes
|
||||
|
||||
First, create an org and project scope and skip creating an administrator and admin role for each scope. We are going to
|
||||
specify a role for managing these scopes by selected users in a later step.
|
||||
|
||||
<Tabs>
|
||||
<Tab heading="CLI">
|
||||
|
||||
|
||||
```shell-session
|
||||
$ boundary scopes create -name 'org' -scope-id 'global' \
|
||||
-recovery-config /tmp/recovery.hcl \
|
||||
-skip-admin-role-creation \
|
||||
-skip-default-role-creation
|
||||
<truncated>
|
||||
|
||||
$ boundary scopes create -name 'project' -scope-id <org_scope_id_from_last_step> \
|
||||
-recovery-config /tmp/recovery.hcl \
|
||||
-skip-admin-role-creation \
|
||||
-skip-default-role-creation
|
||||
<truncated>
|
||||
```
|
||||
|
||||
</Tab>
|
||||
<Tab heading="Terraform">
|
||||
|
||||
|
||||
```hcl
|
||||
resource "boundary_scope" "org" {
|
||||
scope_id = "global"
|
||||
name = "organization"
|
||||
description = "Organization scope"
|
||||
|
||||
auto_create_admin_role = false
|
||||
auto_create_default_role = false
|
||||
}
|
||||
|
||||
resource "boundary_scope" "project" {
|
||||
name = "project"
|
||||
description = "My first project"
|
||||
scope_id = boundary_scope.org.id
|
||||
auto_create_admin_role = false
|
||||
auto_create_default_role = false
|
||||
}
|
||||
```
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
|
||||
### Create an auth method
|
||||
|
||||
Create an auth method in the organization scope.
|
||||
|
||||
<Tabs>
|
||||
<Tab heading="CLI">
|
||||
|
||||
|
||||
```shell-session
|
||||
$ boundary auth-methods create password \
|
||||
-recovery-config /tmp/recovery.hcl \
|
||||
-scope-id <org_scope_id> \
|
||||
-name 'my_method' \
|
||||
-description 'My password auth method'
|
||||
```
|
||||
|
||||
</Tab>
|
||||
<Tab heading="Terraform">
|
||||
|
||||
|
||||
```hcl
|
||||
resource "boundary_auth_method" "password" {
|
||||
name = "my_password_auth_method"
|
||||
description = "Password auth method"
|
||||
type = "password"
|
||||
scope_id = boundary_scope.org.id
|
||||
}
|
||||
```
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
|
||||
### Create a login account
|
||||
|
||||
Create a login account for the auth method.
|
||||
|
||||
<Tabs>
|
||||
<Tab heading="CLI">
|
||||
|
||||
|
||||
```shell-session
|
||||
$ boundary accounts create password \
|
||||
-recovery-config /tmp/recovery.hcl \
|
||||
-login-name "myuser" \
|
||||
-auth-method-id <auth_method_id_from_last_step>
|
||||
```
|
||||
|
||||
</Tab>
|
||||
<Tab heading="Terraform">
|
||||
|
||||
|
||||
```hcl
|
||||
resource "boundary_account" "myuser" {
|
||||
name = "myuser"
|
||||
description = "User account for my user"
|
||||
type = "password"
|
||||
login_name = "myuser"
|
||||
password = "foofoofoo"
|
||||
auth_method_id = boundary_auth_method.password.id
|
||||
}
|
||||
```
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
|
||||
### Create a user
|
||||
|
||||
Create a user and associate the user with the login account created in the previous step.
|
||||
This user will also be the principal in the role we create in the following step.
|
||||
|
||||
<Tabs>
|
||||
<Tab heading="CLI">
|
||||
|
||||
|
||||
```shell-session
|
||||
$ boundary users create -scope-id <org_scope_id> \
|
||||
-recovery-config /tmp/recovery.hcl \
|
||||
-name "myuser" \
|
||||
-description "My user!"
|
||||
|
||||
$ boundary users add-accounts \
|
||||
-recovery-config /tmp/recovery.hcl \
|
||||
-id <myuser_user_id> \
|
||||
-account <myuser_account_id>
|
||||
```
|
||||
|
||||
</Tab>
|
||||
<Tab heading="Terraform">
|
||||
|
||||
|
||||
```hcl
|
||||
resource "boundary_user" "myuser" {
|
||||
name = "myuser"
|
||||
description = "My user!"
|
||||
account_ids = [boundary_account.myuser.id]
|
||||
scope_id = boundary_scope.org.id
|
||||
}
|
||||
```
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
|
||||
### Create roles to manage scopes
|
||||
|
||||
The following section describes the four baseline roles you must create to manage resources within the org and project
|
||||
scopes that you created. These roles are similar to the roles Boundary automatically created for you if you did not skip generation using the `-skip-initial-login-role-creation` flag when you ran `boundary database init`. Declaring roles explicitly
|
||||
allows you to manage them independently and fully within Terraform or via the CLI. In doing so, you can precisely define their access.
|
||||
|
||||
The following example creates 4 roles:
|
||||
|
||||
1. To allow anonymous (unauthenticated) users the ability to list scopes and auth methods in the global scope.
|
||||
1. To allow anonymous (unauthenticated) users the ability to list scopes and auth methods in the organization scope.
|
||||
1. To allow `myuser` user administration grants at the org scope.
|
||||
1. To allow `myuser` user administration grants at the project scope.
|
||||
|
||||
#### Anonymous listing role for global scope
|
||||
|
||||
<Tabs>
|
||||
<Tab heading="CLI">
|
||||
|
||||
|
||||
Assumes recovery key export from above steps is still set:
|
||||
|
||||
```shell-session
|
||||
# Create global anonymous listing role
|
||||
$ boundary roles create -name 'global_anon_listing' \
|
||||
-recovery-config /tmp/recovery.hcl \
|
||||
-scope-id 'global'
|
||||
|
||||
$ boundary roles add-grants -id <global_anon_listing_id> \
|
||||
-recovery-config /tmp/recovery.hcl \
|
||||
-grant 'ids=*;type=auth-method;actions=list,authenticate' \
|
||||
-grant 'ids=*;type=scope;actions=list,no-op' \
|
||||
-grant 'ids={{.Account.Id}};actions=read,change-password'
|
||||
|
||||
$ boundary roles add-principals -id <global_anon_listing_id> \
|
||||
-recovery-config /tmp/recovery.hcl \
|
||||
-principal 'u_anon'
|
||||
```
|
||||
|
||||
</Tab>
|
||||
<Tab heading="Terraform">
|
||||
|
||||
|
||||
```hcl
|
||||
resource "boundary_role" "global_anon_listing" {
|
||||
scope_id = "global"
|
||||
grant_strings = [
|
||||
"ids=*;type=auth-method;actions=list,authenticate",
|
||||
"ids=*;type=scope;actions=list,no-op",
|
||||
"ids={{.Account.Id}};actions=read,change-password"
|
||||
]
|
||||
principal_ids = ["u_anon"]
|
||||
}
|
||||
```
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
|
||||
#### Anonymous listing role for org scope
|
||||
|
||||
<Tabs>
|
||||
<Tab heading="CLI">
|
||||
|
||||
|
||||
Assumes recovery key export from above steps is still set:
|
||||
|
||||
```shell-session
|
||||
$ boundary roles create -name 'org_anon_listing' \
|
||||
-recovery-config /tmp/recovery.hcl \
|
||||
-scope-id <org_scope_id>
|
||||
|
||||
$ boundary roles add-grants -id <org_anon_listing_id> \
|
||||
-recovery-config /tmp/recovery.hcl \
|
||||
-grant 'ids=*;type=auth-method;actions=list,authenticate' \
|
||||
-grant 'type=scope;actions=list' \
|
||||
-grant 'ids={{.Account.Id}};actions=read,change-password'
|
||||
|
||||
$ boundary roles add-principals -id <org_anon_listing_id> \
|
||||
-recovery-config /tmp/recovery.hcl \
|
||||
-principal 'u_anon'
|
||||
```
|
||||
|
||||
</Tab>
|
||||
<Tab heading="Terraform">
|
||||
|
||||
|
||||
```hcl
|
||||
resource "boundary_role" "org_anon_listing" {
|
||||
scope_id = boundary_scope.org.id
|
||||
grant_strings = [
|
||||
"ids=*;type=auth-method;actions=list,authenticate",
|
||||
"type=scope;actions=list",
|
||||
"ids={{.Account.Id}};actions=read,change-password"
|
||||
]
|
||||
principal_ids = ["u_anon"]
|
||||
}
|
||||
```
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
|
||||
#### Org admin role for myuser
|
||||
|
||||
<Tabs>
|
||||
<Tab heading="CLI">
|
||||
|
||||
|
||||
Assumes recovery key export from above steps is still set:
|
||||
|
||||
```shell-session
|
||||
$ boundary roles create -name 'org_admin' \
|
||||
-recovery-config /tmp/recovery.hcl \
|
||||
-scope-id 'global'
|
||||
|
||||
$ boundary roles set-grant-scopes \
|
||||
-id <org_admin_id> \
|
||||
-grant-scope-id <org_scope_id>
|
||||
|
||||
$ boundary roles add-grants -id <org_admin_id> \
|
||||
-recovery-config /tmp/recovery.hcl \
|
||||
-grant 'ids=*;type=*;actions=*'
|
||||
|
||||
$ boundary roles add-principals -id <org_admin_id> \
|
||||
-recovery-config /tmp/recovery.hcl \
|
||||
-principal <myuser_user_id>
|
||||
```
|
||||
|
||||
</Tab>
|
||||
<Tab heading="Terraform">
|
||||
|
||||
|
||||
```hcl
|
||||
resource "boundary_role" "org_admin" {
|
||||
scope_id = "global"
|
||||
grant_scope_ids = [boundary_scope.org.id]
|
||||
grant_strings = [
|
||||
"ids=*;type=*;actions=*"
|
||||
]
|
||||
principal_ids = [boundary_user.myuser.id]
|
||||
}
|
||||
```
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
|
||||
#### Project admin for myuser
|
||||
|
||||
<Tabs>
|
||||
<Tab heading="CLI">
|
||||
|
||||
|
||||
Assumes recovery key export from above steps is still set:
|
||||
|
||||
```shell-session
|
||||
$ boundary roles create -name 'project_admin' \
|
||||
-recovery-config /tmp/recovery.hcl \
|
||||
-scope-id <org_scope_id> \
|
||||
-grant-scope-id <project_scope_id>
|
||||
|
||||
$ boundary roles add-grants -id <project_admin_id> \
|
||||
-recovery-config /tmp/recovery.hcl \
|
||||
-grant 'ids=*;type=*;actions=*'
|
||||
|
||||
$ boundary roles add-principals -id <project_admin_id> \
|
||||
-recovery-config /tmp/recovery.hcl \
|
||||
-principal <myuser_user_id>
|
||||
```
|
||||
|
||||
</Tab>
|
||||
<Tab heading="Terraform">
|
||||
|
||||
|
||||
```hcl
|
||||
resource "boundary_role" "project_admin" {
|
||||
scope_id = boundary_scope.org.id
|
||||
grant_scope_ids = [boundary_scope.project.id]
|
||||
grant_strings = [
|
||||
"ids=*;type=*;actions=*"
|
||||
]
|
||||
principal_ids = [boundary_user.myuser.id]
|
||||
}
|
||||
```
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
|
||||
### Log in as your new user
|
||||
|
||||
```shell-session
|
||||
boundary authenticate password \
|
||||
-auth-method-id <auth_method_id>
|
||||
```
|
||||
|
||||
## Next steps
|
||||
|
||||
After you initialize Boundary, you should [Install the Boundary Clients](/boundary/docs/deploy/self-managed/install-clients).
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Install Boundary clients
|
||||
description: >-
|
||||
Install the Boundary CLI, Boundary Desktop Client app, or Boundary installer for Boundary Enterprise or Community Edition on Windows, MacOS, or Linux.
|
||||
---
|
||||
|
||||
# Install Boundary clients
|
||||
|
||||
Boundary end users access infrastructure targets using the Boundary Desktop Client app or the Boundary CLI. Enterprise or HCP Boundary users can use transparent sessions to proxy traffic through the Boundary Client Agent <sup>HCP/ENT</sup>.
|
||||
|
||||
This guide outlines the required steps to manually install and configure a Boundary client depending on which distribution of Boundary end users access.
|
||||
|
||||
To learn about installing the Boundary binary when you deploy Boundary controllers or workers, refer to the [Install Boundary](/boundary/docs/deploy/self-managed/install) page.
|
||||
|
||||
Select your Boundary distribution, and complete the steps to install the
|
||||
correct clients:
|
||||
|
||||
<Tabs>
|
||||
<Tab heading="Enterprise">
|
||||
|
||||
@include 'alerts/enterprise-only.mdx'
|
||||
|
||||
The Boundary installer bundles together the following components:
|
||||
|
||||
- Boundary binary (CLI)
|
||||
- Boundary Desktop Client app
|
||||
- Boundary Client Agent <sup>HCP/ENT</sup>
|
||||
|
||||
Download the appropriate Boundary installer for your Windows, MacOS, or Linux environment from the [Install Boundary](/boundary/install#installer) downloads page or the [releases](https://releases.hashicorp.com/boundary-installer) page. You can also download the components individually, but compatibility is not guaranteed. Refer to the [Supported versions policy](/boundary/docs/enterprise/supported-versions#control-plane-and-client-cli-compatibility) to learn more.
|
||||
|
||||
<Warning>
|
||||
|
||||
Before you launch the Boundary installer, ensure that you have uninstalled all previous versions of the Boundary binary and Boundary Desktop Client app.
|
||||
|
||||
</Warning>
|
||||
|
||||
To learn more about installing the Boundary CLI and Boundary Desktop Client app, refer to the [Get started with HCP Boundary](/boundary/tutorials/get-started-hcp) tutorials.
|
||||
|
||||
</Tab>
|
||||
<Tab heading="Community Edition">
|
||||
|
||||
We recommend the following components for end users:
|
||||
|
||||
- Boundary binary (CLI)
|
||||
- Boundary Desktop Client app
|
||||
|
||||
Download these components for your Windows, MacOS, or Linux environment from the [Install Boundary](/boundary/install) downloads page or the [HashiCorp releases](https://releases.hashicorp.com/) page.
|
||||
|
||||
<Warning>
|
||||
|
||||
Client compatibility is not guaranteed. You should always ensure that your client is compatible with the version of the Boundary control plane you connect to. Refer to the [Supported versions policy](/boundary/docs/enterprise/supported-versions#control-plane-and-client-cli-compatibility) to learn more.
|
||||
|
||||
</Warning>
|
||||
|
||||
To learn more about installing the Boundary CLI and Boundary Desktop Client app, refer to the [Get started with self-managed Boundary](/boundary/tutorials/get-started-community) tutorials.
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
@@ -0,0 +1,194 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Install Boundary
|
||||
description: >-
|
||||
Deploy a self-managed version of Boundary Enterprise or Community Edition on Ubuntu/Debian, CentOS/RHEL, or Amazon Linux by installing the binary file.
|
||||
---
|
||||
|
||||
# Install Boundary
|
||||
|
||||
Pre-built Boundary packages are available from the [HashiCorp Linux
|
||||
Repository](https://www.hashicorp.com/blog/announcing-the-hashicorp-linux-repository).
|
||||
In addition to installing the Boundary binary, the official package also
|
||||
provides a systemd service unit, and a local `boundary` user account under which
|
||||
the service runs.
|
||||
|
||||
<Note>
|
||||
|
||||
You must complete the following steps for each Boundary controller and worker
|
||||
node that you want to deploy. The binary operates as either a worker or
|
||||
controller, depending on the configuration that you generate for the
|
||||
Boundary binary.
|
||||
|
||||
</Note>
|
||||
|
||||
The steps vary by Linux distribution.
|
||||
|
||||
Select your distribution of Boundary, and complete the steps to install the
|
||||
binary:
|
||||
|
||||
<Tabs>
|
||||
<Tab heading="Enterprise">
|
||||
|
||||
<Tabs>
|
||||
<Tab heading="Ubuntu/Debian">
|
||||
|
||||
1. Use the following command to add the HashiCorp GPC key as a trusted
|
||||
package-signing key:
|
||||
|
||||
```shell-session
|
||||
$ curl -fsSL https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
|
||||
```
|
||||
1. Add the official HashiCorp Linux repository:
|
||||
|
||||
```shell-session
|
||||
$ echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
|
||||
```
|
||||
|
||||
1. Update the package index:
|
||||
|
||||
```shell-session
|
||||
$ sudo apt update
|
||||
```
|
||||
|
||||
1. Install Boundary Enterprise:
|
||||
|
||||
```shell-session
|
||||
$ sudo apt install boundary-enterprise
|
||||
```
|
||||
|
||||
</Tab>
|
||||
<Tab heading="CentOS/RHEL">
|
||||
|
||||
1. Use the following command to install `yum-config-manager` to manage your
|
||||
repositories:
|
||||
|
||||
```shell-session
|
||||
$ sudo yum install -y yum-utils
|
||||
```
|
||||
|
||||
2. Add the official HashiCorp Linux repository:
|
||||
|
||||
```shell-session
|
||||
$ sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo
|
||||
```
|
||||
|
||||
3. Install Boundary Enterprise:
|
||||
|
||||
```shell-session
|
||||
$ sudo yum -y install boundary-enterprise
|
||||
```
|
||||
|
||||
</Tab>
|
||||
<Tab heading="Amazon Linux">
|
||||
|
||||
1. Use the following command to install `yum-config-manager` to manage your
|
||||
repositories:
|
||||
|
||||
```shell-session
|
||||
$ sudo yum install -y yum-utils shadow-utils
|
||||
```
|
||||
|
||||
2. Add the official HashiCorp Linux repository:
|
||||
|
||||
```shell-session
|
||||
$ sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/AmazonLinux/hashicorp.repo
|
||||
```
|
||||
|
||||
3. Install Boundary Enterprise:
|
||||
|
||||
```shell-session
|
||||
$ sudo yum -y install boundary-enterprise
|
||||
```
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
</Tab>
|
||||
<Tab heading="Community Edition">
|
||||
<Tabs>
|
||||
<Tab heading="Ubuntu/Debian">
|
||||
|
||||
1. Use the following command to add the HashiCorp GPC key as a trusted
|
||||
package-signing key:
|
||||
|
||||
```shell-session
|
||||
$ curl -fsSL https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
|
||||
```
|
||||
1. Add the official HashiCorp Linux repository:
|
||||
|
||||
```shell-session
|
||||
$ echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
|
||||
```
|
||||
|
||||
1. Update the package index:
|
||||
|
||||
```shell-session
|
||||
$ sudo apt update
|
||||
```
|
||||
|
||||
1. Install Boundary Community Edition:
|
||||
|
||||
```shell-session
|
||||
$ sudo apt install boundary
|
||||
```
|
||||
|
||||
</Tab>
|
||||
<Tab heading="CentOS/RHEL">
|
||||
|
||||
1. Use the following command to install `yum-config-manager` to manage your
|
||||
repositories:
|
||||
|
||||
```shell-session
|
||||
$ sudo yum install -y yum-utils
|
||||
```
|
||||
|
||||
2. Add the official HashiCorp Linux repository:
|
||||
|
||||
```shell-session
|
||||
$ sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo
|
||||
```
|
||||
|
||||
3. Install Boundary Community Edition:
|
||||
|
||||
```shell-session
|
||||
$ sudo yum -y install boundary
|
||||
```
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab heading="Amazon Linux">
|
||||
|
||||
1. Use the following command to install `yum-config-manager` to manage your
|
||||
repositories:
|
||||
|
||||
```shell-session
|
||||
$ sudo yum install -y yum-utils shadow-utils
|
||||
```
|
||||
|
||||
2. Add the official HashiCorp Linux repository:
|
||||
|
||||
```shell-session
|
||||
$ sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/AmazonLinux/hashicorp.repo
|
||||
```
|
||||
|
||||
3. Install Boundary Community Edition:
|
||||
|
||||
```shell-session
|
||||
$ sudo yum -y install boundary
|
||||
```
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
You should install the binary on the controller and worker instances you configure to run in your Boundary environments.
|
||||
|
||||
## Next steps
|
||||
|
||||
After you install the binary, you should:
|
||||
|
||||
1. [Configure controllers](/boundary/docs/deploy/self-managed/configure-controllers)
|
||||
1. [Deploy workers](/boundary/docs/deploy/self-managed/deploy-workers)
|
||||
1. [Initialize Boundary](/boundary/docs/deploy/self-managed/initialize)
|
||||
1. [Install the Boundary Clients](/boundary/docs/deploy/self-managed/install-clients)
|
||||
@@ -0,0 +1,90 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: systemd Installation
|
||||
description: |-
|
||||
How to install Boundary under systemd on Linux
|
||||
---
|
||||
|
||||
# Install Boundary under systemd
|
||||
|
||||
This section covers how to install Boundary under the [systemd](https://systemd.io/) init system on modern Linux distributions. In this section, we'll cover an example of breaking out the controller and worker servers onto separate instances, though you can opt to run both on a single server.
|
||||
|
||||
## Filesystem configuration
|
||||
|
||||
`TYPE` below can be either `worker` or `controller` if you want to run them independently, e.g. for high availability. If you want to run combined nodes, modify as desired.
|
||||
|
||||
1. `/etc/boundary.d/boundary-${TYPE}.hcl`: Configuration file for the boundary service.
|
||||
|
||||
2. `/usr/local/bin/boundary`: The Boundary binary, which can be built from the [source](https://github.com/hashicorp/boundary) or downloaded from our [release page](/boundary/downloads).
|
||||
|
||||
3. `/etc/systemd/system/boundary-${TYPE}.service`: Systemd unit file for the Boundary service.
|
||||
|
||||
## User and group configuration
|
||||
|
||||
We recommend running Boundary as a non-root user and using this user to manage the Boundary process running under systemd. The example init files here do exactly that. Our example install script below creates a user and group on Ubuntu or Debian-like systems.
|
||||
|
||||
## systemd unit file
|
||||
|
||||
```
|
||||
[Unit]
|
||||
Description=${NAME} ${TYPE}
|
||||
|
||||
[Service]
|
||||
ExecStart=/usr/local/bin/${NAME} server -config /etc/${NAME}-${TYPE}.hcl
|
||||
User=boundary
|
||||
Group=boundary
|
||||
LimitMEMLOCK=infinity
|
||||
Capabilities=CAP_IPC_LOCK+ep
|
||||
CapabilityBoundingSet=CAP_SYSLOG CAP_IPC_LOCK
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
## systemd all-in-one installation script
|
||||
|
||||
Here's a simple install script that creates the `boundary` group and user, installs the
|
||||
systemd unit file, and enables it at startup:
|
||||
|
||||
```
|
||||
#!/bin/bash
|
||||
# Installs the boundary as a service for systemd on linux
|
||||
# Usage: ./install.sh <worker|controller>
|
||||
|
||||
TYPE=$1
|
||||
NAME=boundary
|
||||
|
||||
sudo cat << EOF > /etc/systemd/system/${NAME}-${TYPE}.service
|
||||
[Unit]
|
||||
Description=${NAME} ${TYPE}
|
||||
|
||||
[Service]
|
||||
ExecStart=/usr/local/bin/${NAME} server -config /etc/${NAME}-${TYPE}.hcl
|
||||
User=boundary
|
||||
Group=boundary
|
||||
LimitMEMLOCK=infinity
|
||||
Capabilities=CAP_IPC_LOCK+ep
|
||||
CapabilityBoundingSet=CAP_SYSLOG CAP_IPC_LOCK
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
EOF
|
||||
|
||||
# Add the boundary system user and group to ensure we have a no-login
|
||||
# user capable of owning and running Boundary
|
||||
sudo adduser --system --group boundary || true
|
||||
sudo chown boundary:boundary /etc/${NAME}-${TYPE}.hcl
|
||||
sudo chown boundary:boundary /usr/local/bin/boundary
|
||||
|
||||
# Make sure to initialize the DB before starting the service. This will result in
|
||||
# a database already initialized warning if another controller or worker has done this
|
||||
# already, making it a lazy, best effort initialization
|
||||
if [ "${TYPE}" = "controller" ]; then
|
||||
sudo /usr/local/bin/boundary database init -config /etc/${NAME}-${TYPE}.hcl || true
|
||||
fi
|
||||
|
||||
sudo chmod 664 /etc/systemd/system/${NAME}-${TYPE}.service
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable ${NAME}-${TYPE}
|
||||
sudo systemctl start ${NAME}-${TYPE}
|
||||
```
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Terraform patterns for Boundary
|
||||
description: >-
|
||||
Configure the Terraform Boundary provider so that you can use Terraform patterns to install and manage Boundary resources.
|
||||
---
|
||||
|
||||
# Terraform patterns for Boundary
|
||||
|
||||
HashiCorp recommends using Terraform to deploy and maintain your Boundary environment.
|
||||
|
||||
This following topics outline MVP (Minimum Viable Product) patterns to deploy and maintain Boundary using Terraform.
|
||||
|
||||
## Requirements
|
||||
|
||||
This document assumes the reader has:
|
||||
|
||||
- An understanding of [Terraform](/terraform/docs) fundamentals.
|
||||
- An existing Boundary installation. Refer to [Deploy Boundary in a self-managed environment](/boundary/docs/deploy/self-managed) to learn about deploying Boundary.
|
||||
|
||||
## Terraform provider configuration
|
||||
|
||||
To use Terraform to manage your Boundary environment, you must first configure the Terraform Boundary provider.
|
||||
|
||||
The following code block provides an example of provider configuration using the userpass authentication method.
|
||||
You can use any of the available Boundary authentication methods by specifying the appropriate `auth_method_id`.
|
||||
|
||||
```hcl
|
||||
terraform {
|
||||
required_providers {
|
||||
# Declare the provider
|
||||
boundary = {
|
||||
source = "hashicorp/boundary"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
# Configure the provider
|
||||
# This example assumes that you have stored your Boundary cluster address and credentials in Terraform variables
|
||||
|
||||
provider "boundary" {
|
||||
addr = var.boundary_addr
|
||||
auth_method_login_name = var.boundary_login_name
|
||||
auth_method_password = var.boundary_password
|
||||
}
|
||||
```
|
||||
## More information
|
||||
|
||||
Refer to the [Boundary provider documentation](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs/) for more information on the available authentication methods.
|
||||
|
||||
## Next steps
|
||||
|
||||
The following pages provide examples and patterns for configuring Boundary resources with Terraform.
|
||||
|
||||
If you are configuring Boundary resources for the first time, you may want to start by creating a scope.
|
||||
You create scopes to partition resources and then assign ownership of those resources to users and groups.
|
||||
|
||||
- [Scopes](/boundary/docs/deploy/terraform-patterns/terraform-scopes)
|
||||
- [Users and auth methods](/boundary/docs/deploy/terraform-patterns/terraform-users-and-auth-methods)
|
||||
- [Groups and role-based-access-control (RBAC)](/boundary/docs/deploy/terraform-patterns/terraform-groups-and-rbac)
|
||||
- [Hosts and host management](/boundary/docs/deploy/terraform-patterns/terraform-hosts-and-host-management)
|
||||
- [Credentials and credential stores](/boundary/docs/deploy/terraform-patterns/terraform-credentials-and-credential-stores)
|
||||
- [Session recording](/boundary/docs/deploy/terraform-patterns/terraform-session-recording)
|
||||
- [Targets](/boundary/docs/deploy/terraform-patterns/terraform-targets)
|
||||
+199
@@ -0,0 +1,199 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Terraform patterns for credentials and credential stores
|
||||
description: >-
|
||||
Use Terraform patterns to create and manage Boundary credentials and credential stores. Learn how to create static or Vault credential stores, add credentials.
|
||||
---
|
||||
|
||||
# Terraform patterns for credentials and credential stores
|
||||
|
||||
Boundary supports multiple types of static credentials and Vault dynamic credentials. A credential store stores credentials for hosts. Static credential stores can hold username/passwords, JSON tokens, SSH key pairs, and SSH certificates.
|
||||
|
||||
## Requirements
|
||||
|
||||
This document assumes the reader has:
|
||||
|
||||
- An understanding of [Terraform](/terraform/docs) fundamentals.
|
||||
- An existing Boundary installation. Refer to [Deploy Boundary in a self-managed environment](/boundary/docs/deploy/self-managed) to learn about deploying Boundary.
|
||||
- Configured the [Terraform Boundary provider](/boundary/docs/deploy/terraform-patterns/#terraform-provider-configuration).
|
||||
- Configured [hosts](/boundary/docs/deploy/terraform-patterns/terraform-hosts-and-host-management) for any credential store you plan to create.
|
||||
|
||||
## Static credential store configuration
|
||||
|
||||
This example creates both a static credential store and a Vault credential store.
|
||||
|
||||
```hcl
|
||||
# Create a static credential store
|
||||
resource "boundary_credential_store_static" "example" {
|
||||
name = "example_static_credential_store"
|
||||
description = "My first static credential store"
|
||||
scope_id = boundary_scope.project.id
|
||||
}
|
||||
|
||||
# Create a Vault credential store
|
||||
resource "boundary_credential_store_vault" "example" {
|
||||
name = "vault_store"
|
||||
description = "My first Vault credential store"
|
||||
|
||||
# change to your Vault address
|
||||
address = "http://127.0.0.1:8200"
|
||||
|
||||
# Use a token that has rights to access the secrets in Vault that
|
||||
# Boundary should use
|
||||
token = var.vault_token
|
||||
scope_id = boundary_scope.project.id
|
||||
}
|
||||
```
|
||||
|
||||
After you create a credential store, you can create one or more credentials in that store.
|
||||
|
||||
### Add static credentials configuration
|
||||
|
||||
This example creates static credentials that Boundary manages. The credentials are for a user named Carlos.
|
||||
|
||||
```hcl
|
||||
# Create a username/password combination
|
||||
resource "boundary_credential_username_password" "carlos" {
|
||||
name = "example_username_password"
|
||||
description = "My first username password credential"
|
||||
credential_store_id = boundary_credential_store_static.example.id
|
||||
username = "Carlos"
|
||||
password = "Carlos-password"
|
||||
}
|
||||
|
||||
# Create an ssh private key
|
||||
resource "boundary_credential_ssh_private_key" "carlos_ssh" {
|
||||
name = "example_ssh_private_key"
|
||||
description = "My first ssh private key credential"
|
||||
credential_store_id = boundary_credential_store_static.example.id
|
||||
username = "carlos"
|
||||
|
||||
# You can also load the private_key from a file using the Terraform file() function.
|
||||
private_key = var.carlos_ssh_key
|
||||
|
||||
# change to the passphrase of the private key, if required
|
||||
private_key_passphrase = "optional-passphrase"
|
||||
}
|
||||
|
||||
# Create a JSON credential
|
||||
resource "boundary_credential_json" "example" {
|
||||
name = "example_json"
|
||||
description = "My first json credential"
|
||||
credential_store_id = boundary_credential_store_static.example.id
|
||||
|
||||
# This points to the actual json file. You can also load this from a variable.
|
||||
object = file("~/object.json")
|
||||
}
|
||||
```
|
||||
|
||||
## Vault credential store configuration
|
||||
|
||||
For Vault credential stores, you can then create a credential library which distributes credentials of a specific access level from a Vault path.
|
||||
|
||||
This example creates a credential library that reads secrets from a Vault path called `my/secret/foo`.
|
||||
|
||||
```hcl
|
||||
|
||||
resource "boundary_credential_library_vault" "foo" {
|
||||
name = "foo"
|
||||
description = "My first Vault credential library"
|
||||
credential_store_id = boundary_credential_store_vault.example.id
|
||||
|
||||
# Defines a valid Vault secret path
|
||||
path = "my/secret/foo"
|
||||
http_method = "GET"
|
||||
}
|
||||
```
|
||||
|
||||
### Translate key names from Vault configuration
|
||||
|
||||
If you need to translate the key names from Vault into values expected by
|
||||
Boundary, use this pattern.
|
||||
|
||||
```hcl
|
||||
resource "boundary_credential_library_vault" "baz" {
|
||||
name = "baz"
|
||||
description = "vault username password credential with mapping overrides"
|
||||
credential_store_id = boundary_credential_store_vault.example.id
|
||||
|
||||
# Defines the vault path that contains the secret you need
|
||||
path = "my/secret/baz"
|
||||
http_method = "GET"
|
||||
credential_type = "username_password"
|
||||
|
||||
# This maps the username and password field names in Vault to their names in Boundary
|
||||
credential_mapping_overrides = {
|
||||
password_attribute = "alternative_password_label"
|
||||
username_attribute = "alternative_username_label"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Use SSH certificates as credentials configuration
|
||||
|
||||
To use SSH certificates as credentials, you use the `boundary_credential_vault_ssh_certificate` resource as shown in this example.
|
||||
|
||||
```hcl
|
||||
resource "boundary_credential_library_vault_ssh_certificate" "example" {
|
||||
name = "foo"
|
||||
description = "My first Vault SSH certificate credential library"
|
||||
credential_store_id = boundary_credential_store_vault.foo.id
|
||||
|
||||
# Declares the vault path that generates certificates
|
||||
path = "ssh/sign/foo"
|
||||
|
||||
# Defines the username
|
||||
username = "foo"
|
||||
}
|
||||
```
|
||||
### Declare additional certificate attributes and extensions configuration
|
||||
|
||||
This example declares additional certificate attributes and extensions. Note that you can enable extensions by declaring their names and setting their values to empty strings.
|
||||
|
||||
```hcl
|
||||
resource "boundary_credential_library_vault_ssh_certificate" "example" {
|
||||
name = "baz"
|
||||
description = "vault "
|
||||
credential_store_id = boundary_credential_store_vault.foo.id
|
||||
path = "ssh/issue/foo" # change to the Vault endpoint and role
|
||||
username = "foo"
|
||||
|
||||
# Defines additional optional certificate attributes
|
||||
key_type = "rsa"
|
||||
key_bits = 4096
|
||||
|
||||
extensions = {
|
||||
permit-pty = ""
|
||||
permit-X11-forwarding = ""
|
||||
}
|
||||
|
||||
critical_options = {
|
||||
force-command = "/bin/some_script"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## More information
|
||||
|
||||
For more information about the Boundary resources mentioned in this topic, refer to the domain model documentation:
|
||||
|
||||
- [Credential stores](/boundary/docs/domain-model/credential-stores)
|
||||
- [Credentials](/boundary/docs/domain-model/credentials)
|
||||
- [Credential libraries](/boundary/docs/domain-model/credential-libraries)
|
||||
|
||||
For more information about managing the following resources using Terraform, refer to the Boundary provider documentation:
|
||||
|
||||
- Credentials
|
||||
- [JSON](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs/resources/credential_json/)
|
||||
- [SSH private keys](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs/resources/credential_ssh_private_key/)
|
||||
- [Username/passwords](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs/resources/credential_username_password/)
|
||||
- Credential libraries
|
||||
- [Vault](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs/resources/credential_library_vault/)
|
||||
- [Vault SSH certificates](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs/resources/credential_library_vault_ssh_certificate/)
|
||||
- Credential stores
|
||||
- [Static](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs/resources/credential_store_static/)
|
||||
- [Vault](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs/resources/credential_store_vault/)
|
||||
|
||||
## Next steps
|
||||
|
||||
Once you have configured credentials and credential stores, you may want to enable [session recording](/boundary/docs/deploy/terraform-patterns/terraform-session-recording) for auditing purposes or configure [targets](/boundary/docs/deploy/terraform-patterns/terraform-targets) for your users to connect to.
|
||||
@@ -0,0 +1,100 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Terraform patterns for groups and RBAC
|
||||
description: >-
|
||||
Use Terraform patterns to create and manage Boundary groups and role-based access control (RBAC). Learn how to add users to managed groups and assign roles.
|
||||
---
|
||||
|
||||
# Terraform patterns for groups and RBAC
|
||||
|
||||
The following pattern demonstrates how to aggregate users into groups.
|
||||
|
||||
Security best-practices recommend that you use Role-Based Access Control (RBAC) when you make authorization decisions. RBAC is a methodology in which you create a role that defines the actions that a user is allowed to take, and then assign one or more users to that role.
|
||||
|
||||
In Boundary, you can assign users directly to a role, but a better pattern is to put users with equivalent access into groups. You can then assign groups to roles that grant least-privileges to your Boundary environment.
|
||||
|
||||
## Requirements
|
||||
|
||||
This document assumes the reader has:
|
||||
|
||||
- An understanding of [Terraform](/terraform/docs) fundamentals.
|
||||
- An existing Boundary installation. Refer to [Deploy Boundary in a self-managed environment](/boundary/docs/deploy/self-managed) to learn about deploying Boundary.
|
||||
- Configured the [Terraform Boundary provider](/boundary/docs/deploy/terraform-patterns/#terraform-provider-configuration).
|
||||
- Created Boundary [users and auth methods](/boundary/docs/deploy/terraform-patterns/terraform-users-and-auth-methods) to assign to the group you plan to create.
|
||||
|
||||
## Group configuration
|
||||
|
||||
This example adds users to the `Accounting` group.
|
||||
|
||||
```hcl
|
||||
# Add Jeff and Susmitha to the Accounting group
|
||||
resource "boundary_group" "Accounting" {
|
||||
name = "Accounting"
|
||||
description = "The Accounting Department"
|
||||
member_ids = [boundary_user.susmitha,id, boundary_user.jeff.id]
|
||||
scope_id = boundary_scope.project.id
|
||||
}
|
||||
```
|
||||
|
||||
You are not required to populate groups manually, and can instead take advantage of the pre-existing groups provided by an identity provider.
|
||||
|
||||
## Managed group configuration
|
||||
|
||||
This example creates a managed group that is automatically populated based on an LDAP group called `Engineering`.
|
||||
|
||||
```hcl
|
||||
resource "boundary_managed_group_ldap" "Engineering" {
|
||||
name = "Engineering"
|
||||
description = "Engineering Managed LDAP Group"
|
||||
auth_method_id = boundary_auth_method_ldap.forumsys_ldap.id
|
||||
group_names = ["Engineering"]
|
||||
}
|
||||
```
|
||||
|
||||
HashiCorp recommends using managed groups whenever possible because it abstracts the management of group membership and simplifies Boundary administration.
|
||||
|
||||
## Role configuration
|
||||
|
||||
After you have created a group, you must assign one or more roles to that group to enable the group members to do useful work in Boundary.
|
||||
|
||||
This pattern creates a role called `readonly` that include a grant
|
||||
that allows the user read-only access to all Boundary resources. This example also associates the `Accounting` static group and the `Engineering` managed group with that role.
|
||||
|
||||
```hcp
|
||||
resource "boundary_role" "readonly" {
|
||||
name = "readonly"
|
||||
description = "A readonly role"
|
||||
|
||||
# Assign Accounting and Engineering to this role
|
||||
principal_ids = [boundary_group.accounting.id, boundary_managed_group_ldap.Engineering.id]
|
||||
|
||||
# This is the grant string provides read-only access to all objects in the current scope.
|
||||
grant_strings = ["ids=*;type=*;actions=read"]
|
||||
scope_id = boundary_scope.project.id
|
||||
}
|
||||
```
|
||||
|
||||
## More information
|
||||
|
||||
For more information about the Boundary resources mentioned in this topic, refer to the domain model documentation:
|
||||
|
||||
- [Roles](/boundary/docs/domain-model/roles)
|
||||
- [Groups](/boundary/docs/domain-model/groups)
|
||||
- [Managed groups](/boundary/docs/domain-model/managed-groups)
|
||||
- [Grants](/boundary/docs/rbac#grant-strings)
|
||||
|
||||
For more information about managing the following resources using Terraform, refer to the Boundary provider documentation:
|
||||
|
||||
- Accounts
|
||||
- [Password accounts](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs/resources/account_password/)
|
||||
- [LDAP accounts](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs/resources/account_ldap/)
|
||||
- [OIDC accounts](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs/resources/account_oidc/)
|
||||
- [Users](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs/resources/user/)
|
||||
- [Groups](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs/resources/group/)
|
||||
- [LDAP managed groups](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs/resources/managed_group_ldap/)
|
||||
- [Roles](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs/resources/role/)
|
||||
|
||||
## Next steps
|
||||
|
||||
You may want to create [hosts and host sets](/boundary/docs/deploy/terraform-patterns/terraform-hosts-and-host-management) so that you can configure targets for your users to connect to.
|
||||
Targets require an address or host, and credentials to connect to that host.
|
||||
+154
@@ -0,0 +1,154 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Terraform patterns for hosts and host management
|
||||
description: >-
|
||||
Use Terraform patterns to create and manage Boundary hosts and host catalogs. Learn how to add static or plugin-based hosts to static or dynamic host catalogs.
|
||||
---
|
||||
|
||||
# Terraform patterns for hosts and host management
|
||||
|
||||
Before you can access a system, you must create a target. Targets require an address or host, and credentials to connect to that host.
|
||||
|
||||
You can define target addresses directly to simplify access, but HashiCorp does not recommend that pattern at scale.
|
||||
Instead, HashiCorp recommends adding hosts to a host set, and then attaching the host set to a target.
|
||||
|
||||
## Requirements
|
||||
|
||||
This document assumes the reader has:
|
||||
|
||||
- An understanding of [Terraform](/terraform/docs) fundamentals.
|
||||
- An existing Boundary installation. Refer to [Deploy Boundary in a self-managed environment](/boundary/docs/deploy/self-managed) to learn about deploying Boundary.
|
||||
- Configured the [Terraform Boundary provider](/boundary/docs/deploy/terraform-patterns/#terraform-provider-configuration).
|
||||
|
||||
## Static host catalog configuration
|
||||
|
||||
The following example shows how to create a Boundary static host catalog and add a known host to that catalog.
|
||||
|
||||
```hcl
|
||||
# Create the host catalog
|
||||
resource "boundary_host_catalog_static" "example" {
|
||||
name = "My static catalog"
|
||||
description = "My static host catalog"
|
||||
scope_id = boundary_scope.project.id
|
||||
}
|
||||
|
||||
# Create the static host
|
||||
resource "boundary_host" "example" {
|
||||
type = "static"
|
||||
name = "example_host"
|
||||
description = "My first host"
|
||||
address = "10.0.0.1"
|
||||
|
||||
# Associate the host with the static host catalog
|
||||
host_catalog_id = boundary_host_catalog.static.id
|
||||
}
|
||||
```
|
||||
|
||||
Static host catalogs increase your administrative burden and should only be used when necessary.
|
||||
|
||||
## Dynamic host catalog configuration
|
||||
|
||||
When you use cloud providers like Amazon Web Services (AWS) and Microsoft Azure, a better pattern is to use a plugin-based host catalog that automatically discovers hosts based on the filtering criteria for a given cloud.
|
||||
|
||||
This example creates a dynamic host catalog that auto-discovers AWS hosts in `us-east-1`.
|
||||
|
||||
```hcl
|
||||
resource "boundary_host_catalog_plugin" "aws_example" {
|
||||
name = "My AWS catalog"
|
||||
description = "My AWS dynamic host catalog"
|
||||
scope_id = boundary_scope.project.id
|
||||
|
||||
# Delare the cloud plugin to use and the region to search for hosts
|
||||
plugin_name = "aws"
|
||||
attributes_json = jsonencode({ "region" = "us-east-1" })
|
||||
|
||||
# Define the cloud credentials to use for searching
|
||||
secrets_json = jsonencode({
|
||||
"access_key_id" = "aws_access_key_id_value",
|
||||
"secret_access_key" = "aws_secret_access_key_value"
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
## Azure host catalog configuration
|
||||
|
||||
This host catalog example discovers hosts in Azure. Notice that it is very similar to the AWS example.
|
||||
|
||||
```hcl
|
||||
resource "boundary_host_catalog_plugin" "azure_example" {
|
||||
name = "My Azure catalog"
|
||||
description = "My Azure dynamic host catalog"
|
||||
scope_id = boundary_scope.project.id
|
||||
plugin_name = "azure"
|
||||
|
||||
# HashiCorp recommends providing Azure secrets using a file() or environment variables
|
||||
|
||||
# The attributes below must be generated in Azure by creating an Entra ID application
|
||||
attributes_json = jsonencode({
|
||||
"disable_credential_rotation" = "true",
|
||||
"tenant_id" = "ARM_TENANT_ID",
|
||||
"subscription_id" = "ARM_SUBSCRIPTION_ID",
|
||||
"client_id" = "ARM_CLIENT_ID"
|
||||
})
|
||||
|
||||
# The secrets below must be generated in Azure by creating an Entra ID application
|
||||
secrets_json = jsonencode({
|
||||
"secret_value" = "ARM_CLIENT_SECRET"
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
## Add static hosts to hosts sets configuration
|
||||
|
||||
This example adds static hosts to static host sets.
|
||||
|
||||
```hcl
|
||||
resource "boundary_host_set_static" "web" {
|
||||
host_catalog_id = boundary_host_catalog_static.example.id
|
||||
host_ids = [
|
||||
# This is the static Boundary host created in the example above.
|
||||
boundary_host_static.example.id
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Add plugin-based hosts to host sets configuration
|
||||
|
||||
Hosts discovered using a plugin-based host catalog should be added to a `boundary_host_set_plugin` host set.
|
||||
|
||||
This example demonstrates how to add hosts from the AWS host catalog to a host set using tags as a filtering criteria. In this example, the filter looks for tags named `service-type` that have a value of `web`.
|
||||
|
||||
```hcl
|
||||
resource "boundary_host_set_plugin" "web" {
|
||||
name = "My web host set plugin"
|
||||
|
||||
# This is the AWS host catalog that was created above
|
||||
host_catalog_id = boundary_host_catalog_plugin.aws_example.id
|
||||
|
||||
# This is the filter that looks for specific tags using AWS filtering syntax
|
||||
attributes_json = jsonencode({ "filters" = ["tag:service-type=web"] })
|
||||
}
|
||||
```
|
||||
|
||||
## More information
|
||||
|
||||
For more information about the Boundary resources mentioned in this topic, refer to the domain model documentation:
|
||||
|
||||
- [Targets](/boundary/docs/domain-model/targets)
|
||||
- [Hosts](/boundary/docs/domain-model/hosts)
|
||||
- [Host sets](/boundary/docs/domain-model/host-sets)
|
||||
- [Host catalogs](/boundary/docs/domain-model/host-catalogs)
|
||||
|
||||
For more information about managing the following resources using Terraform, refer to the Boundary provider documentation:
|
||||
|
||||
- [Static hosts](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs/resources/host_static/)
|
||||
- [Static host catalogs](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs/resources/host_catalog_static/)
|
||||
- [Static host sets](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs/resources/host_set_static/)
|
||||
- [Plugin-based host catalogs](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs/resources/host_catalog_plugin/)
|
||||
- [Plugin-based host sets](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs/resources/host_set_plugin/)
|
||||
|
||||
Refer to [Filtering and listing resources](/boundary/docs/filtering) for more information about Boundary's filter syntax and best practices.
|
||||
|
||||
## Next steps
|
||||
|
||||
Once you have configured hosts, you may want to configure [credentials and credential stores](/boundary/docs/deploy/terraform-patterns/terraform-credentials-and-credential-stores) for your hosts and users.
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Terraform patterns for scopes
|
||||
description: >-
|
||||
Use Terraform patterns to create and manage Boundary scopes. Learn how to configure global, org-level, and project-level scopes using the Boundary provider.
|
||||
---
|
||||
|
||||
# Terraform patterns for scopes
|
||||
|
||||
You can use the following patterns to create org-level and project-level scopes.
|
||||
|
||||
## Requirements
|
||||
|
||||
This document assumes the reader has:
|
||||
|
||||
- An understanding of [Terraform](/terraform/docs) fundamentals.
|
||||
- An existing Boundary installation. Refer to [Deploy Boundary in a self-managed environment](/boundary/docs/deploy/self-managed) to learn about deploying Boundary.
|
||||
- Configured the [Terraform Boundary provider](/boundary/docs/deploy/terraform-patterns/#terraform-provider-configuration).
|
||||
|
||||
## Scopes configuration
|
||||
|
||||
The `scope_id` parameter determines what kind of scope to create according to these rules:
|
||||
|
||||
- If `scope_id` is the global scope, an org-level scope is created.
|
||||
- If `scope_id` is an org-level scope, a project-level scope is created.
|
||||
- If `scope_id` is a project-level scope, a nested project-level scope is created.
|
||||
|
||||
```hcl
|
||||
resource "boundary_scope" "project" {
|
||||
name = "Basic Boundary Demo"
|
||||
description = "First Ever Boundary Demo"
|
||||
|
||||
# This parameter is the parent scope. It can be either the global scope, an
|
||||
# org-level scope, or a project-level scope.
|
||||
scope_id = var.se_org_scope
|
||||
|
||||
# Using the auto_create_x_role flags can help you get set up faster
|
||||
# becasue you won't have to explicitly define these roles.
|
||||
auto_create_admin_role = true
|
||||
auto_create_default_role = true
|
||||
}
|
||||
```
|
||||
|
||||
## More information
|
||||
|
||||
For more information about the Boundary resources mentioned in this topic, refer to the domain model documentation:
|
||||
|
||||
- [Scopes](/boundary/docs/domain-model/scopes)
|
||||
- [Org-level scopes](/boundary/docs/domain-model/scopes#organizations)
|
||||
- [Project-level scopes](/boundary/docs/domain-model/scopes#projects)
|
||||
|
||||
For more information about managing the following resources using Terraform, refer to the Boundary provider documentation:
|
||||
|
||||
- [Scopes](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs/resources/scope/)
|
||||
|
||||
## Next steps
|
||||
|
||||
You use scopes to partition resources and assign them to users.
|
||||
Once you have created scopes, you may want to create [users and auth methods](/boundary/docs/deploy/terraform-patterns/terraform-users-and-auth-methods).
|
||||
@@ -0,0 +1,88 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Terraform patterns for session recording
|
||||
description: >-
|
||||
Use Terraform patterns to enable session recording for auditing user sessions in Boundary. Learn how to configure storage policies and storage buckets.
|
||||
---
|
||||
|
||||
# Terraform patterns for session recording
|
||||
|
||||
<EnterpriseAlert product="boundary">This feature requires <a href="https://www.hashicorp.com/products/boundary">HCP Boundary or Boundary Enterprise</a></EnterpriseAlert>
|
||||
|
||||
Session recording requires that you create a storage policy for your current scope and then allocate an AWS S3 bucket to store the recordings. This example does not demonstrate creating the S3 bucket or the associated IAM policies. Refer to the [create storage buckets](/boundary/docs/session-recording/configuration/create-storage-bucket) documentation to learn how to configure AWS.
|
||||
|
||||
## Requirements
|
||||
|
||||
This document assumes the reader has:
|
||||
|
||||
- An understanding of [Terraform](/terraform/docs) fundamentals.
|
||||
- An existing Boundary installation. Refer to [Deploy Boundary in a self-managed environment](/boundary/docs/deploy/self-managed) to learn about deploying Boundary.
|
||||
- Configured the [Terraform Boundary provider](/boundary/docs/deploy/terraform-patterns/#terraform-provider-configuration).
|
||||
- Created a [scope](/boundary/docs/deploy/terraform-patterns/terraform-scopes) for any storage policy you plan to create.
|
||||
- A licensed version of HCP Boundary or Boundary Enterprise.
|
||||
|
||||
## Storage policy configuration
|
||||
|
||||
This example creates a Boundary storage policy for a project scope.
|
||||
|
||||
```hcl
|
||||
# Create the storage policy. This policy is effective for the attached scope
|
||||
resource "boundary_policy_storage" "example" {
|
||||
|
||||
# The policy applies to all recordings in this scope
|
||||
scope_id = boundary_scope.project.id
|
||||
|
||||
name = "soc2-policy"
|
||||
description = "SOC 2 compliant storage policy for session recordings"
|
||||
|
||||
# These define your retention parameters
|
||||
retain_for_days = 2557
|
||||
retain_for_overridable = false
|
||||
|
||||
delete_after_days = 2657
|
||||
delete_after_overridable = true
|
||||
}
|
||||
```
|
||||
|
||||
## Storage bucket configuration
|
||||
|
||||
This example creates the Boundary storage bucket and attaches it to the S3 bucket.
|
||||
|
||||
```hcl
|
||||
resource "boundary_storage_bucket" "aws_bucket" {
|
||||
name = "My aws storage bucket with dynamic credentials"
|
||||
description = "My first storage bucket"
|
||||
scope_id = boundary_scop.project.id
|
||||
plugin_name = "aws"
|
||||
|
||||
# This must match the name of the AWS S3 bucket that stores the recordings
|
||||
bucket_name = "mybucket1"
|
||||
|
||||
# The role_arn value must be the same arn used as the instance profile
|
||||
# attached to your Boundary Worker ec2 instance
|
||||
# https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html
|
||||
attributes_json = jsonencode({
|
||||
"region" = "us-east-1"
|
||||
"role_arn" = "arn:aws:iam::123456789012:role/S3Access"
|
||||
"disable_credential_rotation" = true
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
You have configured the prerequisites for session recording. The last task is to enable recording on a Boundary target.
|
||||
|
||||
## More information
|
||||
|
||||
For more information about the Boundary resources mentioned in this topic, refer to the domain model documentation:
|
||||
|
||||
- [Session recordings](/boundary/docs/domain-model/session-recordings)
|
||||
- [Storage buckets](/boundary/docs/domain-model/storage-buckets)
|
||||
|
||||
For more information about managing the following resources using Terraform, refer to the Boundary provider documentation:
|
||||
|
||||
- [Storage buckets](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs/resources/storage_bucket/)
|
||||
- [Storage policies](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs/resources/policy_storage/)
|
||||
|
||||
## Next steps
|
||||
|
||||
Once you have configured the prerequisites for session recording, you can enable recording on a Boundary [target](/boundary/docs/deploy/terraform-patterns/terraform-targets).
|
||||
@@ -0,0 +1,125 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Terraform patterns for targets
|
||||
description: >-
|
||||
Use Terraform patterns to create and manage Boundary targets. Learn how to configure SSH and TCP targets, inject passwords, and enable session recording.
|
||||
---
|
||||
|
||||
# Terraform patterns for targets
|
||||
|
||||
Once you have defined a host, a host catalog, and a credential store, you
|
||||
can create [targets](/boundary/docs/domain-model/targets).
|
||||
|
||||
## Requirements
|
||||
|
||||
This document assumes the reader has:
|
||||
|
||||
- An understanding of [Terraform](/terraform/docs) fundamentals.
|
||||
- An existing Boundary installation. Refer to [Deploy Boundary in a self-managed environment](/boundary/docs/deploy/self-managed) to learn about deploying Boundary.
|
||||
- Configured the [Terraform Boundary provider](/boundary/docs/deploy/terraform-patterns/#terraform-provider-configuration).
|
||||
- Defined a host, [host catalog](/boundary/docs/deploy/terraform-patterns/terraform-hosts-and-host-management), and [credential store](/boundary/docs/deploy/terraform-patterns/terraform-credentials-and-credential-stores).
|
||||
- (Optional) Configured a storage policy and storage bucket for any targets you want to enable for [session recording](/boundary/docs/deploy/terraform-patterns/terraform-session-recording).
|
||||
|
||||
## Target configuration
|
||||
|
||||
This example creates a target with an injected username and password.
|
||||
|
||||
<Note>
|
||||
|
||||
[Credential injection](/boundary/docs/concepts/credential-management#credential-injection) and SSH target types are only supported for HCP Boundary and Boundary Enterprise. You can configure [credential brokering](/boundary/docs/concepts/credential-management#credential-brokering) instead using `brokered_credential_source_ids`.
|
||||
|
||||
</Note>
|
||||
|
||||
```hcl
|
||||
resource "boundary_target" "ssh_foo" {
|
||||
name = "ssh_foo"
|
||||
description = "SSH target"
|
||||
scope_id = boundary_scope.project.id
|
||||
|
||||
# Declare the target type and connection port
|
||||
type = "ssh"
|
||||
default_port = "22"
|
||||
|
||||
# Declare the host set
|
||||
host_source_ids = [
|
||||
boundary_host_set.foo.id
|
||||
]
|
||||
|
||||
# Declare the injected credentials
|
||||
injected_application_credential_source_ids = [
|
||||
boundary_credential_library_vault.example.id
|
||||
]
|
||||
|
||||
# Enable session recording
|
||||
enable_session_recording = true
|
||||
storage_bucket_id = boundary_storage_bucket.aws_bucket.id
|
||||
}
|
||||
|
||||
```
|
||||
## Session recording configuration
|
||||
|
||||
This example enables session recording, but uses brokered credentials instead.
|
||||
|
||||
```hcl
|
||||
resource "boundary_target" "ssh_foo" {
|
||||
name = "ssh_foo"
|
||||
description = "SSH target"
|
||||
scope_id = boundary_scope.project.id
|
||||
|
||||
# Declare the target type and connection port
|
||||
type = "ssh"
|
||||
default_port = "22"
|
||||
|
||||
# Declare the host set
|
||||
host_source_ids = [
|
||||
boundary_host_set.foo.id
|
||||
]
|
||||
|
||||
# Declare the brokered credentials
|
||||
# This uses a static credential library created earlier
|
||||
brokered_application_credential_source_ids = [
|
||||
boundary_credential_library.example.id
|
||||
]
|
||||
|
||||
# Enable session recording.
|
||||
enable_session_recording = true
|
||||
storage_bucket_id = boundary_storage_bucket.aws_bucket.id
|
||||
}
|
||||
```
|
||||
|
||||
## TCP target configuration
|
||||
|
||||
This example creates a `tcp` target that connects to Windows servers using RDP.
|
||||
|
||||
```hcl
|
||||
resource "boundary_target" "rdp_foo" {
|
||||
name = "rdp_foo"
|
||||
description = "RDP target"
|
||||
scope_id = boundary_scope.project.id
|
||||
|
||||
# Declare the target type and connection port
|
||||
type = "tcp"
|
||||
default_port = "3389"
|
||||
|
||||
# Declare the host set. This assumes that this host set contains Windows hosts
|
||||
host_source_ids = [
|
||||
boundary_host_set.foo.id
|
||||
]
|
||||
|
||||
# The credentials we will use to connect. RDP requires the use of brokered credentials
|
||||
# This uses a static credential library created earlier
|
||||
brokered_application_credential_source_ids = [
|
||||
boundary_credential_library.example.id
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## More information
|
||||
|
||||
For more information about the Boundary resources mentioned in this topic, refer to the domain model documentation:
|
||||
|
||||
- [Targets](/boundary/docs/domain-model/targets)
|
||||
|
||||
For more information about managing the following resources using Terraform, refer to the Boundary provider documentation:
|
||||
|
||||
- [Targets](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs/resources/target/)
|
||||
@@ -0,0 +1,106 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Terraform patterns for users and auth methods
|
||||
description: >-
|
||||
Use Terraform patterns to create and manage Boundary users and auth methods. Learn how to configure password and LDAP auth methods, add accounts, create users.
|
||||
---
|
||||
|
||||
# Terraform patterns for users and auth methods
|
||||
|
||||
Boundary supports password, OIDC, and LDAP auth methods.
|
||||
|
||||
## Requirements
|
||||
|
||||
This document assumes the reader has:
|
||||
|
||||
- An understanding of [Terraform](/terraform/docs) fundamentals.
|
||||
- An existing Boundary installation. Refer to [Deploy Boundary in a self-managed environment](/boundary/docs/deploy/self-managed) to learn about deploying Boundary.
|
||||
- Configured the [Terraform Boundary provider](/boundary/docs/deploy/terraform-patterns/#terraform-provider-configuration).
|
||||
- Created a [scope](/boundary/docs/deploy/terraform-patterns/terraform-scopes) to add the users and auth methods to.
|
||||
|
||||
## Auth method configuration
|
||||
|
||||
Below is an example of creating a password auth method. Terraform creates the auth method in the scope that is specified by the `scope_id` option.
|
||||
|
||||
```hcl
|
||||
resource "boundary_auth_method" "password" {
|
||||
scope_id = boundary_scope.org.id
|
||||
type = "password"
|
||||
}
|
||||
```
|
||||
|
||||
### LDAP auth method configuration
|
||||
|
||||
The next example demonstrates how to create an LDAP auth method.
|
||||
|
||||
```hcl
|
||||
resource "boundary_auth_method_ldap" "forumsys_ldap" {
|
||||
name = "forumsys public LDAP"
|
||||
scope_id = "global" # add the new auth method to the global scope
|
||||
urls = ["ldap://ldap.forumsys.com"] # the addr of the LDAP server
|
||||
user_dn = "dc=example,dc=com" # the basedn for users
|
||||
user_attr = "uid" # the user attribute
|
||||
group_dn = "dc=example,dc=com" # the basedn for groups
|
||||
bind_dn = "cn=read-only-admin,dc=example,dc=com" # the dn to use when binding
|
||||
bind_password = "password" # passwd to use when binding
|
||||
state = "active-public" # make sure the new auth-method is available to everyone
|
||||
enable_groups = true # this turns-on the discovery of a user's groups
|
||||
discover_dn = true # this turns-on the discovery of an authenticating user's dn
|
||||
}
|
||||
```
|
||||
|
||||
## Account and user configuration
|
||||
|
||||
After you create an auth method, you need to add accounts to it and create users to represent the accounts. Users and accounts are different constructs. A user is a "parent" object associated to one or more accounts created using a supported auth method.
|
||||
|
||||
This example creates 2 accounts using the password auth method and associated users.
|
||||
|
||||
```hcl
|
||||
# Create a user named "Jeff"
|
||||
resource "boundary_account_password" "jeff" {
|
||||
auth_method_id = boundary_auth_method.password.id
|
||||
type = "password"
|
||||
login_name = "jeff"
|
||||
password = "$uper$ecure"
|
||||
}
|
||||
|
||||
# Associate the Jeff account with a user alias
|
||||
resource "boundary_user" "jeff" {
|
||||
name = "jeff"
|
||||
description = "Jeff's user resource"
|
||||
account_ids = [boundary_account_password.jeff.id]
|
||||
scope_id = boundary_scope.org.id
|
||||
}
|
||||
|
||||
#Create a user named Susmitha
|
||||
resource "boundary_account_password" "susmitha" {
|
||||
auth_method_id = boundary_auth_method.password.id
|
||||
type = "password"
|
||||
login_name = "susmitha"
|
||||
password = "more$super$ecure"
|
||||
}
|
||||
|
||||
# And this associates the account with a user alias
|
||||
resource "boundary_user" "susmitha" {
|
||||
name = "susmitha"
|
||||
description = "Susmitha's user resource"
|
||||
account_ids = [boundary_account_password.susmitha.id]
|
||||
scope_id = boundary_scope.org.id
|
||||
}
|
||||
```
|
||||
|
||||
## More information
|
||||
|
||||
For more information about the Boundary resources mentioned in this topic, refer to the domain model documentation:
|
||||
- [Auth methods](/boundary/docs/domain-model/auth-methods)
|
||||
- [Users](/boundary/docs/domain-model/users)
|
||||
- [Accounts](/boundary/docs/domain-model/accounts)
|
||||
|
||||
For more information about managing the following resources using Terraform, refer to the Boundary provider documentation:
|
||||
- [LDAP accounts](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs/resources/account_ldap/)
|
||||
- [OIDC accounts](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs/resources/account_oidc/)
|
||||
- [Password accounts](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs/resources/account_password/)
|
||||
|
||||
## Next steps
|
||||
|
||||
Once you have created users and auth methods, you may want to create [groups for your users or configure RBAC](/boundary/docs/deploy/terraform-patterns/terraform-groups-and-rbac) to define the actions a user is allowed to take.
|
||||
Reference in new issue
Block a user