From 5bb08918dc17c96b19b301d3baf3958b6f6ca0e9 Mon Sep 17 00:00:00 2001 From: David John Arnold Jr Date: Thu, 17 Apr 2025 13:37:34 -0700 Subject: [PATCH] updating readme (#22) * updating readme * Add initial README.md with project overview, structure, and usage instructions * Revise README.md for clarity and organization, enhancing descriptions of repository contents and usage instructions. --- README.md | 168 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 114 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index 454f6c3a..248d122a 100644 --- a/README.md +++ b/README.md @@ -1,55 +1,115 @@ -## How to setup and run terragrunt scripts for EKS related modules in a LAB account - -### Lab Account request and setup: - - Open a REMEDY ticket for creating an account in LAB environment, preferably with t3-admin role. - - LAB account url:https://pssvlab.tco.census.gov/PSS/ - - Make a note that the LAB account password is different from laptop password - - Once you have successful log proceed to next steps below - -### Access LAB jumphost (bromine): - Refer this page for additional help on sso credentials: https://github.e.it.census.gov/terraform/support/tree/master/docs/how-to/aws-sso - - 1. Goto LAB workspace:https://clients.amazonworkspaces.com/ - 2. Hit the web access login on the top right corner - 3. Enter the following registration code: FRosu+FMEXNZ and click Register - 4. Use your jbid and password (use lab password) - 5. Open reflection client and ssh connect to bromine.cto.census.gov - 6. On bromine, sso login to lab-gov as: - $ aws-sso-login.sh lab-gov - 7. On a browser goto auth-dev.census.gov - 8. Use PIV card option to login - 9. Copy the link from step 6 and paste it on the portal and authenticate - 10. Go back to bromine and doubleclick at an empty space, you should get successful login lab env - -### Environment Setup: - - Set your profile as a default profile by exporting AWS_PROFILE variable - $ export AWS_PROFILE="224384469011-lab-dev-gov.inf-admin-t3" - $ aws sts get-caller-identity - - Run any aws commands to make sure you are getting responses from the account your profile is set to: - $ aws s3 ls - -### Terraform/Terragrunt binaries and versions: - The following binaries used: - - Terraform version: v1.7.5 - - Terragrunt version: v0.55.21 - These versions can be found on bromine.cto.census.gov host at: - /app/terraform/bin/terr* folder - -### Run the Terragrunt script: - - Cd to specifc folder (example: cd eks) and Run terragrunt plan - $ terragrunt plan - - Verify the plan output and make sure there are no errors - - Run terragrunt apply - $ terragrunt apply - - Verify apply completes successfully and verify the resources on AWS Console. - -### Accessing the cluster: - $ aws eks --region us-gov-east-1 update-kubeconfig --name platform-eng-eks-test - $ kubectl config use-context arn:aws-us-gov:eks:us-gov-east-1:224384469011:cluster/platform-eng-eks-test - $ kubectl config get-contexts - -### Run few kubectl commands to verify you are accessing the cluster - $ kubectl cluster-info - $ kubectl get pods -A - $ kubectl get ns +# Platform Infrastructure with Terragrunt +This repository helps manage cloud infrastructure using Terragrunt. It is designed to make managing infrastructure easier and more organized. Terragrunt is used to handle infrastructure as code for different environments. + +## What's in This Repository + +- `/configs` - Files for setting up things like node groups and resource limits +- `/docs` - Guides and rules for how to set up and manage the infrastructure +- `/lab` - Settings for testing and development environments +- `/monitoring` - Tools for keeping an eye on the system +- `/tests` - Tests to make sure everything works as expected + +## Documentation + +You can find detailed guides in the `/docs` folder: + +- [Architecture](docs/ARCHITECTURE.md) - How the system is built +- [Documentation Standards](docs/DOCUMENTATION_STANDARDS.md) - How to write good documentation +- [Infrastructure Standards](docs/INFRASTRUCTURE_STANDARDS.md) - Rules for setting up infrastructure +- [Module Dependencies](docs/MODULE_DEPENDENCIES.md) - How different parts depend on each other +- [Module Standards](docs/MODULE_STANDARDS.md) - Rules for creating modules +- [Observability Standards](docs/OBSERVABILITY_STANDARDS.md) - How to monitor the system +- [Security Audit Checklist](docs/SECURITY_AUDIT_CHECKLIST.md) - Steps to check for security issues +- [Security Baseline](docs/SECURITY_BASELINE.md) - Basic security requirements +- [Testing Standards](docs/TESTING_STANDARDS.md) - Rules for testing +- [Version Control](docs/VERSION_CONTROL.md) - How to manage code versions + +## What You Need + +- Terraform v1.0.0 or newer +- Terragrunt v0.36.0 or newer +- AWS CLI set up with the right permissions +- Access to AWS resources + +## How to Get Started + +### Using the Makefile + +This repository has a Makefile with helpful commands: + +```bash +make help # See available commands +make init # Set up Terragrunt +make validate # Check if everything is set up correctly +make plan # Preview changes +make fmt # Format files +make check # Run all checks +make clean # Clean up temporary files +``` + +### Manual Terragrunt Commands + +Go to the folder with the Terragrunt configuration you want to use: + +```bash +cd lab/environment/component + +# Set up Terragrunt +terragrunt init + +# Preview changes +terragrunt plan + +# Apply changes +terragrunt apply + +# Remove resources +terragrunt destroy +``` + +### Running All Configurations + +Run commands for all Terragrunt configurations: + +```bash +# Set up everything +terragrunt run-all init + +# Preview all changes +terragrunt run-all plan + +# Apply all changes +terragrunt run-all apply +``` + +## Configuration + +Terragrunt configurations are organized like this: + +1. Main settings for each environment +2. Specific settings for different parts of the system +3. Overrides for special cases + +Check the environment folders for more details. + +## Testing + +The `/tests` folder has tools to check if everything works. To run tests: + +```bash +cd tests +./run_tests.sh +``` + +## How to Contribute + +1. Make a copy of this repository +2. Create a new branch for your changes +3. Make your updates +4. Run `make check` to ensure everything is correct +5. Submit a pull request + +## License + +Copyright © 2025 Your Organization. All rights reserved.