Getting Started
After the server is properly provisioned and configured, you'll have Vault and Boundary up and running. For the sake of education, the stack will be initialized with minimum resources for both services, including KV and Transit engine Vault and a series of auth-methods, host catalog, credential stores, etc. Boundary. As the contributions increase, the resources will be enriched accordingly, covering more arbitrary resources and features in the format of Infrastructure as Code (IaC).
To grasp what's going on under the hood, you can reach out to the section you wish to explore in this documentation.
About Hashicorp Vault and Boundary
According to Hashicorp documentation:
Boundary is an identity-aware proxy that simplifies and secures least-privileged access to cloud infrastructure. It enables SSO, just-in-time access, dynamic credentials, and session management.
Vault is an identity-based secrets and encryption management system. A secret is anything that you want to tightly control access to, such as API encryption keys, passwords, and certificates. Vault provides encryption services that are gated by authentication and authorization methods. Using Vault’s UI, CLI, or HTTP API, access to secrets and other sensitive data can be securely stored, managed, tightly controlled (restricted), and audited.
Learn more:
Workflow
After the environment is prepared, Ansible deploys Vault using Docker Compose. The Vault server is first initialized by the vault-init service, which runs the `init.sh` script and calls the `init_vault_setup` function. This process unseals Vault, creates the necessary secret engines, policies, tokens, and other basic configurations. Once the deployment is complete, the Transit-token and secrets.txt file, containing all the essential tokens and keys, are generated and stored in the `secrets/secrets.txt` file on the controller machine. Next, the Terraform role is applied to configure Vault, utilizing the generated tokens and variables. Following this, the deployment shifts focus to Boundary. To enable Boundary to use Vault's Transit Engine for Encryption as a Service (EaaS), the Transit token (already stored in `secrets.txt`) is passed to the Boundary role. Once the Boundary database (PostgreSQL) is up and running, it is initialized using the db-init service. Finally, Boundary is deployed with the initial credentials saved in secrets/boundary-init-creds.txt. Terraform resources are then applied using the Vault Transit recovery key and Transit token. To use the stack, you need to install the Boundary and Vault clients (ensure the server and client versions match). Once installed, you can start using BVSTACK. You can checkout the boundary UI at http://192.168.1.15:9200 and Vault at http://192.168.1.15:8200 .
Vault
Vault workflow involves setting up authentication methods, secret engines, and policies. The key components of Vault server setup include:
Boundary
Boundary workflow involves managing sessions, targets, and credentials. The key components of Boundary server setup include:
Configurations
Environment Variables
Environment variables need to be configured for both Vault and Boundary. Here's an example:
STACK_ENV (mandatory)
This variable determines in which mode/environment the stack is deployed.
default : development
STACK_INIT (mandatory)
When first running the stack, vault-init and boundary-init services are in charge of initiating the basic configurations for Boundary and `vault`. This variable determines whether these services should be executed or not. So if it's not your first time running the stack successfully, set to false.
default : true
SSH_INJECTION (optional)
SSH injection variable enables Boundary vault credential store. only works on paid plan!!
default : false
STACK_SERVER (optional)
If set to false, vagrant and virtualbox won't be used to spin up BVSTACK. Instead you must create both Controller, BVSTACK and Client machines manually using your prefered method; ensure to address them in the inventory file accordingly.
default : true
Return/Exit Codes
In this project, several scripts use return/exit codes to indicate the result of operations. Understanding these codes is essential for diagnosing issues and ensuring proper execution of the scripts. Below is a detailed explanation of each return/exit code used in the project.
Exit Code 1: Service Not Installed
Description: This exit code indicates that the required service is not installed on the system.
Possible Causes:
- The service was not installed during the setup process.
- The installation process was interrupted or failed.
Resolution:
- Verify and ensure that the installation was successful by running the prepare_env role.
Resolution:
$ scripts/init.sh vault
# Output: Terraform not installed
# Exit code: 1
Exit Code 2: Terraform Init Failed
Description: This exit code indicates that the `terraform init` command failed.
Possible Causes:
- The Terraform configuration files are missing or corrupted.
- There is a network issue preventing Terraform from accessing necessary modules or providers.
- Incorrect permissions to the directory where Terraform is being initialized.
- Wrong terraform directory path.
Resolution:
- Ensure that all required Terraform configuration files are present and correctly configured.
- Refer to the Terraform Documentation for more details.
- Check network connectivity and permissions.
Resolution:
$ scripts/init.sh vault
# Output: Terraform init failed
# Exit code: 2
Exit Code 3: Configuration is Invalid
Description: This exit code indicates that `terraform validate` was not successfully executed.
Possible Causes:
- The configuration file has syntax errors.
- Required configuration parameters are missing or incorrect.
Resolution:
- Validate the configuration file against the expected schema.
- Ensure all required parameters are correctly specified.
Resolution:
$ scripts/init.sh vault
# Output: Configuration is invalid
# Exit code: 3
Exit Code 4: Arguments and Options are Invalid.
Description: This exit code indicates that the arguments or options passed to the script are invalid.
Possible Causes:
- Incorrect or missing arguments/options.
- The script was invoked with unsupported options.
Resolution:
- Refer to the script usage documentation to ensure all required arguments and options are correctly specified.
- Use the `--help` option with the script to view the correct usage.
Resolution:
$ ./start.sh --environment development
# Output: Invalid option: --environment
# Exit code: 4
Bear In Mind
Keep the following in mind when working with the Boundary-Vault stack:
- Since Boundary Terraform uses Vault recovery transit key you must export the transit-token as VAULT_TOKEN (secrets/secrets.txt) before planning/applying the code. Otherwise, you should use auth-method credentials to communicate with the boundary api.
- If you have issues with DockerHub make sure you change the image registry in deployments and `prepare_env` role.
- If the target node(s) get restarted, the vault gets sealed and boundary container will be in restarting mode.
- In case the vault container gets restarted, it will be sealed and you'll have an error on your boundary container, there manage to get them working together again.
- You can additionally add session recording and other paid plan features.
- Vault is initialized with 1 shared-key to simplify the process, consider increasing the number of keys and threshold for better security.
Still Having Issues
For further assistance, feel free to open up a new issue on the GitHub Issues page.