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:
+ +Workflows
+Vault
+Vault workflow involves setting up authentication methods, secret engines, and policies. The key + components include:
+-
+
- Auth Methods: How users and applications authenticate to Vault. +
- Secret Engines: Where secrets are stored, such as key-value pairs, + database credentials, or + encryption keys. +
- Policies: Rules that define what actions an authenticated user or + service can perform within + Vault. +
Boundary
+Boundary workflow involves managing sessions, targets, and credentials. The key components include: +
+-
+
- Sessions: Establish secure, just-in-time access to resources. +
- Targets: The infrastructure resources that users need access to, such + as servers or + databases. + +
- Credential Stores: Where dynamic or static credentials are retrieved + for access to targets. + +
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
+ +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:
+-
+
- 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.
+