You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
###Contributing Guidelines for Hashicorp Boundary and Vault Stack
1
+
# Contributing Guidelines for HashiCorp Boundary and Vault Stack
2
2
3
-
Thank you for considering contributing to the Hashicorp Boundary and Vault Stack project! Contributions help improve the project and are highly appreciated. To ensure smooth collaboration, please follow the guidelines below.
3
+
Thank you for considering contributing to the HashiCorp Boundary and Vault Stack project! Your contributions are invaluable to the project's improvement. To ensure smooth collaboration, please follow the guidelines outlined below.
4
4
5
5
## Table of Contents
6
6
-[Getting Started](#getting-started)
7
7
-[Types of Contributions](#types-of-contributions)
3. **Set up your environment**: Ensure you have the necessary dependencies installed as outlined in the [documentation](./artifacts/wiki.md).
30
+
3. **Set Up Your Environment**: Ensure you have the necessary dependencies installed as outlined in the [documentation](./artifacts/wiki.md).
32
31
33
-
4. **Read the documentation**: Familiarize yourself with the project by thoroughly reading the [documentation](./artifacts/wiki.md) and reviewing the [diagram of the automation workflow](https://linktw.in/PloXtt).
32
+
4. **Review the Documentation**: Familiarize yourself with the project by thoroughly reading the [documentation](./artifacts/wiki.md) and reviewing the [automation workflow diagram](https://linktw.in/PloXtt).
34
33
35
34
## Types of Contributions
36
35
37
36
### Reporting Issues
38
37
39
38
If you encounter any bugs, errors, or have suggestions for improvements:
40
39
41
-
- **Search existing issues**: Before submitting a new issue, please check if it has already been reported.
42
-
- **Create a new issue**: If it’s a new issue, create one and provide detailed information such as steps to reproduce, expected and actual results, and any relevant screenshots or logs.
43
-
- **Link to related tasks**: If your issue is related to any of the [TODOs](#https://github.com/Shayan-Ghani/boundary-vault-stack/tree/main/#to-do), please reference the corresponding task.
40
+
- **Search Existing Issues**: Before submitting a new issue, check if it has already been reported.
41
+
- **Create a New Issue**: If it’s a new issue, provide detailed information such as steps to reproduce, expected vs. actual results, and any relevant screenshots or logs.
42
+
- **Link to Related Tasks**: If your issue relates to any of the [TODOs](https://github.com/Shayan-Ghani/boundary-vault-stack/tree/main/#to-do), reference the corresponding task.
43
+
44
+
### Commit Messages
45
+
46
+
**Use Conventional Commits**: The project follows [semantic versioning](https://semver.org/) to ensure proper releases. Start your commits with a prefix such as `fix:`, `feat:`, `chore:`, or `doc:`.
47
+
48
+
- **Imperative Mood**: Write commit messages as commands (e.g., "Add Vagrantfile for VM provisioning").
49
+
- **Be Concise but Descriptive**: Provide enough detail to understand the change.
50
+
- **Commit Message Conventions**: Use `doc:`for any changes related to documentation.
44
51
45
52
### Submitting Pull Requests
46
53
47
54
When submitting pull requests (PRs):
48
55
49
-
1. **Create a branch**: Create a new branch for your feature or bug fix. Avoid working directly on the `main` branch.
56
+
1. **Create a Branch**: Create a new branch for your feature or bug fix. Avoid working directly on the `main` branch.
50
57
```bash
51
58
git checkout -b feature/your-feature-name
52
59
```
53
60
54
-
2. **Make atomic commits**: Ensure each commit is focused and addresses a single change by Conforming to the Commit Messages section.
61
+
2. **Make Atomic Commits**: Ensure each commit is focused and addresses a single change, following the Commit Messages section.
55
62
56
-
3. **Follow the code style guidelines**: Ensure your code adheres to the project's code style and best practices.
63
+
3. **Follow Best Practices**: Ensure your code adheres to the project's best practices.
57
64
58
-
4. **Test your changes**: Run tests and ensure your changes do not break the existing code.
65
+
4. **Test Your Changes**: Run tests and ensure your changes do not break existing code.
59
66
60
-
5. **Update documentation**: If your change requires documentation updates, ensure these are included in your PR.
67
+
5. **Update Documentation**: If your change requires documentation updates, include them in your PR. Use the `documentation` label and provide additional context in the PR description.
61
68
62
69
6. **Submit the PR**: Push your branch to GitHub and open a pull request against the `main` branch. Link the PR to the corresponding issue(s).
63
70
64
71
### Code Style and Best Practices
65
72
66
-
- **Use meaningful variable and function names**.
67
-
- **Keep functions small and focused**: Each function should perform a single task.
68
-
- **DRY (Don’t Repeat Yourself)**: Reuse code where possible.
69
-
- **Comment your code**: Provide comments where the code is not self-explanatory.
70
-
- **Follow best practices**: For Terraform, Ansible, and Shell Scripting, refer to the [Guidelines for Specific Tasks](#guidelines-for-specific-tasks).
71
-
72
-
### Commit Messages
73
-
74
-
- **Use imperative mood**: Write commit messages as if you are commanding the code to do something (e.g., "Add Vagrantfile for VM provisioning").
75
-
- **Be concise but descriptive**: Provide enough detail to understand the change.
76
-
77
-
#### Conventions
78
-
- start your commit with `doc:` in case of any change in wiki.
79
-
- start your commit with `closes #issue_number :` if your commit closes an issue.
80
-
73
+
- **Use Meaningful Names**: Choose descriptive names for variables and tasks.
74
+
- **Keep Tasks Small and Focused**: Each function should perform a single task.
- **Comment Your Code**: Add comments where the code is not self-explanatory.
77
+
- **Adhere to Best Practices**: Refer to the [Guidelines for Specific Tasks](#guidelines-for-specific-tasks) for Terraform, Ansible, and Shell Scripting.
81
78
82
79
## Guidelines for Specific Tasks
83
80
84
81
### Terraform
85
82
86
-
- **State management**: Ensure you properly configure remote state management, especially when working on the tasks related to the remote backend.
87
-
- **Output values**: Enhance output values to make them more informative and useful.
83
+
- **State Management**: Configure remote state management properly, especially when working with remote backends.
84
+
- **Output Values**: Make output values informative and useful.
85
+
- **Avoid Unnecessary Loops**: Minimize the use of `foreach` and loops for variables, and avoid hardcoding values.
88
86
89
87
### Ansible
90
88
91
-
- **Environment variables**: Use the `environment` attribute for declaring environment variables in roles.
92
-
- **Role organization**: Keep roles modular and reusable.
89
+
- **Role Organization**: Keep roles modular and reusable.
90
+
- **Handlers and Utilities**: Use [handlers](./ansible/handlers/) and [utilities](./ansible/utils/) for frequently repeated tasks.
93
91
94
92
### Shell Scripting
95
93
96
-
- **Logging**: Implement a consistent logging mechanism across all shell scripts. Use a custom logger function as outlined in the TODOs.
97
-
- **Error handling**: Ensure scripts handle errors gracefully and provide informative messages.
94
+
- **Logging**: Implement consistent logging across all shell scripts. Use a custom logger function as outlined in the TODOs.
95
+
- **Error Handling**: Ensure scripts handle errors gracefully and provide informative messages.
98
96
99
97
### CI/CD
100
98
101
99
- **GitHub Actions**: Contribute to the existing CI/CD pipeline by implementing automated testing, linting, and security scans for pull requests.
102
100
103
-
### Testing
104
-
105
-
- **Implement Ansible Molecule test cases**: For Ansible roles, write Molecule test scenarios to ensure your roles work as expected.
106
-
- **Automated testing**: Contribute to the CI/CD pipeline by writing GitHub Actions workflows that automate testing.
107
-
108
101
## Communication
109
102
110
-
- **Stay updated**: Regularly check for updates on the project and communicate with the maintainers for any significant contributions.
111
-
- **Respectful collaboration**: Follow a code of conduct that fosters a respectful and inclusive environment.
103
+
- **Stay Updated**: Regularly check for project updates and communicate with maintainers about significant contributions.
104
+
- **Respectful Collaboration**: Follow the code of conduct to maintain a respectful and inclusive environment.
112
105
113
106
## License
114
107
115
108
By contributing to this project, you agree that your contributions will be licensed under the project's [license](./LICENSE).
116
109
117
110
---
118
111
119
-
Thank you foryour interestin contributing to the Hashicorp Boundary and Vault Stack! We look forward to your contributions.
112
+
Thank you foryour interestin contributing to the HashiCorp Boundary and Vault Stack! We look forward to your contributions.
Deploy Self-Hosted HCP Vault and Boundary using End-To-End automation.
3
-
4
-
## What This Project Offers
5
-
By providing a comprehensive and hands-on experience in Infrastructure as Code (IaC) and Configuration Management along with creating vital deliverables such as documentation and diagrams, this project simulates a real-world infrastructure development that emphasizes End-to-End automation, enabling DevOps Engineers to collaborate and deliver a reliable and production-ready stack to the end-users.
6
-
7
-
## How To Use
8
-
**First, make sure you have [READ THE DOCUMENTATION](./artifacts/wiki.md) for instructions on how the stack and Hashicorp Boundary/Vault work.**
9
-
10
-
**See a thorough [diagram of the automation workflow big picture](https://linktw.in/nWgoiO).**
1
+
# HashiCorp Boundary and Vault Stack
11
2
3
+
Deploy a Self-Hosted HCP Vault and Boundary stack using end-to-end automation.
12
4
5
+
## What This Project Offers
13
6
14
-
1. To begin with, create your own `tfvars` based on the sample provided in [boundary](./boundary/terraform/terraform.tfvars.sample) and [vault](./vault/terraform/terraform.tfvars.sample) or simply remove the leading .sample extension to apply the sample values.
7
+
This project provides a comprehensive, hands-on experience in Infrastructure as Code (IaC) and Configuration Management. It simulates a real-world infrastructure environment with a focus on end-to-end automation, enabling DevOps engineers to collaboratively deliver a reliable, production-ready stack. Key deliverables include detailed documentation and diagrams.
15
8
16
-
2. Initialize the process by running `start.sh` script in your desired environment:
17
-
```bash
18
-
#run in dev:
19
-
./start.sh -e development
20
-
```
9
+
## How to Use
21
10
22
-
*If you need further assistance on the exit/return code and configurations, check out [ wiki ](./artifacts/wiki.md).*
11
+
1.**Read the Documentation**: Before getting started, ensure you have thoroughly reviewed the [project documentation](./artifacts/wiki.md) and the [automation workflow diagram](https://linktw.in/nWgoiO).
23
12
24
-
3. You'll be prompted to Enter the vault-password to decrypt ansible-vault encrypted files (e.g inventory.ini).
13
+
2.**Configure Variables**: Create your own `tfvars` file based on the samples provided in the [Boundary](./boundary/terraform/terraform.tfvars.sample) and [Vault](./vault/terraform/terraform.tfvars.sample) directories. Alternatively, you can remove the `.sample` extension from the provided sample files to use the default values.
25
14
26
-
**The `ansible-vault-pass` is `BVSTACK`. This is for the sake of simplicity and sample, make sure you use a strong password for your ansible vault encrypted files.**
15
+
3.**Run the Start Script**: Begin the setup by running the `start.sh` script in your desired environment:
16
+
```bash
17
+
# Run in development:
18
+
./start.sh -e development
19
+
```
27
20
28
-
## TO-DO
29
-
> Terraform ....
21
+
For further assistance on exit/return codes and configurations, refer to the [documentation](./artifacts/wiki.md).
30
22
31
-
> NOTE
32
-
> Implement all of the provisioners inside provision Directory and Ansible Role
23
+
4. **Enter Vault Password**: You will be prompted to enter the Vault password to decrypt Ansible Vault-encrypted files (e.g., `inventory.ini`).
33
24
34
-
-[ ] Add a **Vagrantfile** to provision a VM using the **Vagrant** provider of your choice based on [ specs ](./provision/specs.txt) with `Terraform`.
25
+
**Note**: The default `ansible-vault-pass` is `BVSTACK`. This is provided forsimplicityinthe sample; ensure you use a strong password for your Ansible Vault-encrypted files.
35
26
36
-
-[ ] Using `Terraform`**AWS** provider provision an **EC2** instance based on [ specs ](./provision/specs.txt) + additional required configuration.
27
+
## To-Do List
37
28
38
-
-[ ] Using `Terraform`**Azure** provider provision an Azure VMs instace based on [ specs ](./provision/specs.txt) + additional required configuration.
29
+
### Terraform
39
30
40
-
-[ ] Using `Terraform`**Vsphere** provider, provision a vm on an ESXI server based on [ specs ](./provision/specs.txt).
31
+
- [ ] Add a **Vagrantfile** to provision a VM using the **Vagrant** provider of your choice, based on the [specifications](./provision/specs.txt).
32
+
- [ ] Provision an **EC2** instance using the **AWS** provider based on the [specifications](./provision/specs.txt) and additional required configurations.
33
+
- [ ] Provision an **Azure** VM using the **Azure** provider based on the [specifications](./provision/specs.txt) and additional required configurations.
34
+
- [ ] Provision a VM on an ESXi server using the **vSphere** provider based on the [specifications](./provision/specs.txt).
35
+
- [ ] Add a remote backend option for Boundary and Vault.
- [ ] Enhance Terraform output values for both Boundary and Vault.
38
+
- [ ] Implement Policy as Code (PaC) to validate Terraform policies.
41
39
40
+
### Packer
42
41
43
-
-[ ] Add `Terraform` Remote Backend option for Boundary and Vault.
44
-
-[ ] Add other Vault auth methods using `Terraform`.
45
-
-[ ] Enchance `Terraform Output` values for both Boundary and Vault
46
-
-[ ] Implement `Policy as Code (PaC)` to validate `Terraform` policies.
42
+
- [ ] Add a Packer custom image template for VMware vSphere using the [specifications](./provision/specs.txt).
47
43
48
-
> Packer ...
44
+
### Ansible
49
45
50
-
-[ ] Add Packer custom image template for VMware Vsphere using [ specs ](./provision/specs.txt).
46
+
- [ ] Install and configure Terraform on the **control node** using the `prepare_env` role.
47
+
- [ ] Install and configure Docker on **target (managed) nodes** using the `prepare_env` role.
48
+
- [ ] Template `tfvars` files to handle specific variables for both Boundary and Vault Terraform providers.
49
+
- [ ] Create a well-organized Ansible template for Vault and Boundary configurations.
50
+
- [ ] Update environment variable declarations in Ansible roles to use the `environment` attribute instead of inline definitions in the `shell` module.
51
+
- [ ] Add proper configurations to serve the stack as a reverse proxy in the `serve` directory (tool optional).
52
+
- [ ] Update `boundary.yml` to use environment variables instead of hardcoding, then manage the export of these variables with Ansible.
53
+
- [ ] Convert Docker Compose files to corresponding Ansible modules using the `community.docker.docker_container` collection as an optional deployment method.
54
+
- [ ] Implement Ansible Molecule scenarios to test different aspects of your roles.
55
+
- [ ] Choose which provider to provision based on a user-defined or environment variable when handling provisions with Ansible.
51
56
52
-
> Ansible ...
57
+
### CI/CD
53
58
54
-
-[ ] Install and configure `Terraform` on the **control node** (`prepare_env` role).
55
-
-[ ] Install and configure `Docker` on **target (managed) node(s)** (`prepare_env` role).
56
-
-[ ] Optionally, install boundary and vault on **admins** node(s) Based on `STACK_BIN=true/false` Environment variable.
57
-
-[ ] Template `tfvars` file to handle specific variables for both boundary and vault terraform providers.
58
-
-[ ] Create a well-organized `Ansible` template for Vault and boundary configurations.
59
-
-[ ] Update environment variable declaration through `Ansible` roles to use `environment` attribute instead of inline definition in `shell` module.
60
-
-[ ] Add proper configurations to serve the stack as a reverse proxy in the `serve` directory(the tool is optional).
61
-
-[ ] Update `boundary.yml` to use ENV variables instead of hardcoding then handle the export of the env variables with `Ansible`.
62
-
-[ ] Using `Ansible``community.docker.docker_container` collection, convert docker-compose files to the corresponding `Ansible` module as an optional deployment method.
63
-
-[ ] Implement Ansible `Molecule` case scenarios to test different aspects of your roles.
64
-
-[ ] When handling Provisions with `Ansible`, Choose which Provider to provision Based on a User-Defined or Environment variable.
59
+
- [ ] Implement automated testing using GitHub Actions for pull requests.
65
60
66
-
> CI/CD ....
61
+
### Shell Scripting
67
62
68
-
-[ ] Implement automated testing using GitHub actions for pull requests.
63
+
- [ ] Write a custom logger functionand implement it throughout all shell scripts for better error handling and logging (in the `log` directory).
64
+
- [ ] Use `case` statements instead of `if`forargument handlingin`init.sh`.
65
+
- [ ] Update `start.sh` to prompt for the Ansible Vault password once and use it for all operations.
66
+
- [ ] Replace sleep commands in`start.sh` with the appropriate Ansible `wait_for` modules.
67
+
- [ ] Remove the Vault root token in the `cleanup` script.
69
68
70
-
> Shell Scripting ...
69
+
## Contribution
71
70
72
-
-[ ] Write a `Custom Logger` function and use it throughout all shell scripts for better error handling and logging (`log` directory).
73
-
-[ ] Use `case` instead of if for argument handling in `init.sh`.
74
-
-[ ] Make `start.sh` ask for the ansible-vault password once and use it for all.
75
-
-[ ] Update the sleep commands in the `start.sh` to use `Ansible` wait_for modules instead.
76
-
-[ ] Remove vault root token in `cleanup`.
71
+
All contributions are welcome! Please read the [Contributing Guidelines](./CONTRIBUTING.md) for more information.
77
72
78
-
## Contribution
79
-
all types of contribution is welcomed, read [`Contribution.md`](./Contributing.md) for more information.
0 commit comments