Merge pull request #91 from sourcefuse/feature/doc

Documentation Added
sourcefuse · Apr 12, 2024 · a5b5915 · a5b5915
2 parents 3c3c3f2 + f05f411
commit a5b5915
Show file tree

Hide file tree

Showing 60 changed files with 3,471 additions and 281 deletions.
diff --git a/.github/workflows/terraform-docs.yaml b/.github/workflows/terraform-docs.yaml
@@ -0,0 +1,25 @@
+---
+name: Terraform-Documentation
+
+on:              # yamllint disable-line rule:truthy
+  pull_request:
+    branches:
+      - main
+
+
+jobs:
+  docs:
+    runs-on: [self-hosted, linux, codebuild]
+    name: terraform-doc
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.ref }}
+
+      - name: Render terraform docs inside the README.md and push changes back to PR branch
+        uses: terraform-docs/[email protected]
+        with:
+          find-dir: .
+          output-file: README.md
+          output-method: inject
+          git-push: 'true'
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -21,7 +21,6 @@ repos:
   - repo: https://github.com/antonbabenko/pre-commit-terraform
     rev: v1.77.1
     hooks:
-      - id: terraform_validate
       - id: terraform_tflint
       - id: terraform_fmt
         args:

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,154 @@
+# Contributing to AWS ARC EKS
+
+Thank you for considering contributing to AWS ARC EKS! We appreciate your time and effort.
+To ensure a smooth collaboration, please take a moment to review the following guidelines.
+
+## How to Contribute
+
+1. Fork the repository to your own GitHub account.
+2. Clone the repository to your local machine.
+   ```bash
+   git clone https://github.com/<your_organization>/<your_terraform_module>.git
+   ```
+3. Create a new branch for your feature / bugfix.
+   ```bash
+   git checkout -b feature/branch_name
+   ```
+4. Make your changes and commit them.
+   ```bash
+   git commit -m "Your descriptive commit message"
+   ```
+5. Push to your forked repository.
+   ```bash
+   git push origin feature/branch_name
+   ```
+6. Open a pull request in the original repository with a clear title and description.
+   If your pull request addresses an issue, please reference the issue number in the pull request description.
+
+### Git commits
+
+while Contributing or doing git commit please specify the breaking change in your commit message whether its major,minor or patch
+
+For Example
+
+```sh
+git commit -m "your commit message #major"
+```
+By specifying this , it will bump the version and if you don't specify this in your commit message then by default it will consider patch and will bump that accordingly
+
+# Terraform Code Collaboration Guidelines
+
+## File Naming Conventions
+
+1. **Variables File (variables.tf):**
+    - All variable names should be in snake_case.
+    - Each variable declaration must contain:
+        - Description: A brief explanation of the variable's purpose.
+        - Type: The data type of the variable.
+
+    Example:
+    ```hcl
+    variable "example_variable" {
+      description = "This is an example variable."
+      type        = string
+    }
+    ```
+
+2. **Outputs File (outputs.tf):**
+    - All output names should be in snake_case.
+    - Each output declaration must contain:
+        - Description: A brief explanation of the output's purpose.
+        - Value: The value that will be exposed as the output.
+
+    Example:
+    ```hcl
+    output "example_output" {
+      description = "This is an example output."
+      value       = module.example_module.example_attribute
+    }
+    ```
+
+## Resource and Module Naming
+
+1. **Terraform Resources/Modules:**
+    - Resource and module names should be in snake_case.
+    - Choose descriptive names that reflect the purpose of the resource or module.
+
+    Example:
+    ```hcl
+    resource "aws_instance" "web_server" {
+      // ...
+    }
+
+    module "networking" {
+      // ...
+    }
+    ```
+
+## General Guidelines
+
+1. **Consistent Formatting:**
+    - Follow consistent code formatting to enhance readability.
+    - Use indentation and line breaks appropriately.
+
+2. **Comments:**
+    - Add comments to explain complex logic, decisions, or any non-trivial code.
+    - Keep comments up-to-date with the code.
+
+3. **Module Documentation:**
+    - Include a README.md file within each module directory, explaining its purpose, inputs, and outputs.
+    - Use inline documentation within the code for complex modules.
+
+4. **Avoid Hardcoding:**
+    - Minimize hardcoded values; prefer using variables and references for increased flexibility.
+
+5. **Sensitive Information:**
+    - Do not hardcode sensitive information (e.g., passwords, API keys). Use appropriate methods for securing sensitive data.
+
+6. **Error Handling:**
+    - Implement proper error handling and consider the impact of potential failures.
+
+## Version Control
+
+1. **Commit Messages:**
+    - Use descriptive and concise commit messages that explain the purpose of the changes.
+
+2. **Branching:**
+    - Follow a branching strategy (e.g., feature branches) for better collaboration.
+
+## Pre-commit Hooks
+
+1. **Install `pre-commit`:**
+    - Install `pre-commit` hooks to automatically check and enforce code formatting, linting, and other pre-defined rules before each commit.
+
+    Example:
+    ```bash
+    brew install pre-commit (for mac users)
+    ```
+    ```bash
+    pre-commit run -a
+    ```
+
+    This ensures that your code adheres to the defined standards before being committed, reducing the likelihood of introducing issues into the repository.
+
+## Code Style
+
+Please follow the Terraform language conventions and formatting guidelines. Consider using an editor with Terraform support or a linter to ensure adherence to the style.
+
+## Testing
+
+!!! This section is a work-in-progress, as we are starting to adopt testing using Terratest. !!!
+
+Before submitting a pull request, ensure that your changes pass all tests. If applicable, add new tests to cover your changes.
+
+## Documentation
+
+Keep the module documentation up-to-date.
+
+## Security and Compliance Checks
+
+GitHub Actions are in place to perform security and compliance checks. Please make sure your changes pass these checks before submitting a pull request.
+
+## Licensing
+
+By contributing, you agree that your contributions will be licensed under the project's [LICENSE](LICENSE).
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2020-2023] [SourceFuse Technologies]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
@@ -1,5 +1,106 @@
-# ARC EKS SAAS 
+# SourceFuse ARC EKS SAAS Reference Architecture
 
-[![Quality gate](https://sonarcloud.io/api/project_badges/quality_gate?project=sourcefuse_terraform-aws-arc-eks-saas&token=753087a003438b8bb11e624ea44302d9044d428e)](https://sonarcloud.io/summary/new_code?id=sourcefuse_terraform-aws-arc-eks-saas)
 
-[![snyk](https://github.com/sourcefuse/terraform-aws-arc-eks-saas/actions/workflows/synk.yaml/badge.svg)](https://github.com/sourcefuse/terraform-aws-arc-eks-saas/actions/workflows/synk.yaml)
+<p align="left">
+<a href="https://sonarcloud.io/summary/new_code?id=sourcefuse_terraform-aws-arc-eks-saas" target="_blank">
+<img alt="Quality Gate Status" src="https://sonarcloud.io/api/project_badges/measure?project=sourcefuse_terraform-aws-arc-eks-saas&metric=alert_status&token=753087a003438b8bb11e624ea44302d9044d428e">
+</a>
+<a href="https://app.snyk.io/org/ashishkaushik/reporting?context[page]=issues-detail&project_target=%255B%2522sourcefuse%252Fterraform-aws-arc-eks-saas%2522%255D&project_origin=%255B%2522github%2522%255D&issue_status=%255B%2522Open%2522%255D&issue_by=Severity&table_issues_detail_cols=SCORE%257CCVE%257CCWE%257CPROJECT%257CEXPLOIT%2520MATURITY%257CAUTO%2520FIXABLE%257CINTRODUCED%257CSNYK%2520PRODUCT&v=1">
+<img alt="Synk" src="https://github.com/sourcefuse/terraform-aws-arc-eks-saas/actions/workflows/synk.yaml/badge.svg">
+</a>
+<a href="./LICENSE">
+<img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License" />
+</a>
+
+</p>
+
+
+# Overview
+
+SourceFuse Reference Architecture to implement a sample EKS Multi-Tenant SaaS Solution. This solution will use AWS Codepipeline to deploy all the control plane infrastructure component of Networking, Compute, Database, Monitoring & Logging and Security alongwith the control plane application using helm chart. This solution will also setup tenant codebuild projects which is responsible for onboarding of new silo/pooled tenant. Each tenant will have it's own infrastructure and application helm chart Which will be managed using gitops tool like ArgoCD and Argo Workflow. This solution will also have strict IAM policy and Kubernetes Authorization Policy for tenants to avoid cross namespace access.
+
+## Requirements
+
+1. AWS Account 
+2. Terraform CLI
+3. AWS CLI
+
+
+## Pre-Requisitie
+
+> :warning: Please ensure you are logged into AWS Account as an IAM user with Administrator privileges, not the root account user.
+
+1. If you don't have registered domain in Route53 then [register domain in Route53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/domain-register.html).
+2. Generate Public Certificate for the domain using [AWS ACM](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-request-public.html). (please ensure to give both wildcard and root domain in Fully qualified domain name while generating ACM, e.g. if domain name is xyz.com then use both xyz.com & *.xyz.com in ACM)
+3. SES account should be setup in production mode and domain identity should be verified. [Generate smtp credentials](https://docs.aws.amazon.com/ses/latest/dg/smtp-credentials.html) and store them in ssm parameter store. (using parameter name - /{namespace}/ses_access_key & /{namespace}/ses_secret_access_key where **namespace** is project name)
+4. [Generate http credentials](https://docs.aws.amazon.com/codecommit/latest/userguide/setting-up-gc.html#setting-up-gc-iam) for your IAM user and store them in ssm parameter. (using parameter name - /{namespace}/https_connection_user & /{namespace}/https_connection_password where **namespace** is project name)
+5. Create a [codepipeline connection for github](https://docs.aws.amazon.com/codepipeline/latest/userguide/connections-github.html). Please make sure to update the connection name in **tfvars** file of terraform/core-infra-pipeline folder.
+6. If you want to use client-vpn to access opensearch dashboard then enable it using variable defined in **.tfvars** file of client-vpn folder.
+
+
+## Setting up the environment
+
+First clone the Github repository. Update the variables like **namespace**,**environment**,**region**,**domain_name** etc. in the respective **tfvars** file of terraform folder. Also, make sure to update the variables in the script files of terraform/tenant-codebuilds folder.
+
+Once the required variables are updated, We will setup terraform codepipeline which will deploy all control plane infrastructure components. We have multiple option to do that - 
+
+1. Using Github Actions :: 
+
+> **_NOTE:_** We are using slef hosted github runners to execute workflow action. please follow [this](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners) document to setup runners.
+
+* First create an [IAM role for github workflow actions](https://aws.amazon.com/blogs/security/use-iam-roles-to-connect-github-actions-to-actions-in-aws/) and update the role name and other required variables like environment etc. in workflow yaml files.
+* Add **AWS_ACCOUNT_ID** in [github repository secret](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions).
+* Next, Make sure to update the environment variable in *scripts/update-backend-config.sh* file.
+* Execute the workflow of *apply-bootstrap.yaml* & *apply-pipeline.yaml* by updating the github events in these files. Currently these workflows will be executed when pull request will be merged to main branch so change the invocation of these workflow files according to you. 
+
+
+> **_NOTE:_** If you want to run other workflows, which are terraform plans, make sure to update the workflow files. Terraform bootstrap is one time activity so once bootstrap workflow is executed, please disable that to run again.
+
+
+2. Using Local ::
+
+AWS CLI version2 & Terraform CLI version 1.7 must be installed on your machine. If not installed, then follow the documentation to install [aws cli](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) & [terraform cli](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli).
+
+* Configure your terminal with aws.
+* Go to the terraform/bootstrap folder and run the floowing command to deploy it - 
+
+    ```
+    terraform init
+    terraform plan --var-file={env}.tfvars
+    terraform apply --var-file={env}.tfvars
+    ```
+* Now, Go to the terraform/core-infra-pipeline and update the *config.{env}.hcl* with bucket and dynamodb table name, created in above step. 
+* Run the Followign command to create terraform codepipeline - 
+
+    ```
+    terraform init --backend-config=config.{env}.hcl
+    terraform plan --var-file={env}.tfvars
+    terraform apply --var-file={env}.tfvars
+    ```
+> **_NOTE:_** All Terraform module README files are present in respective folder.
+
+
+once the codepipeline is created, it will be triggered when code will be merged to main branch as current release branch set to main in terraform pipeline folder (you can change it). When Codepipeline is executed successfully then register the following entry in route53 hosted zone of the domain, using Load Balancer DNS address.
+
+| Record Entry          | Description                     |
+|-----------------------|---------------------------------|
+| {domain-name}         | control-plane application URL.  |
+| argocd.{domain-name}  | ArgoCD URL                      |
+| argo.{domain-name}    | Argo Workflow URL               |
+| grafana.{domain-name} | Grafana Dashboard URL           |
+
+> **_NOTE:_** All authentication password will be saved in SSM Paramater store.
+
+
+
+## Authors
+
+This project is authored by below people
+
+- SourceFuse ARC Team
+
+
+## License
+
+Distributed under the MIT License. See [LICENSE](LICENSE) for more information.
+
diff --git a/modules/aws-managed-grafana/README.md b/modules/aws-managed-grafana/README.md
@@ -45,4 +45,42 @@ No resources.
 | <a name="output_grafana_workspace_endpoint"></a> [grafana\_workspace\_endpoint](#output\_grafana\_workspace\_endpoint) | Amazon Managed Grafana Workspace endpoint |
 | <a name="output_grafana_workspace_iam_role_arn"></a> [grafana\_workspace\_iam\_role\_arn](#output\_grafana\_workspace\_iam\_role\_arn) | Amazon Managed Grafana Workspace's IAM Role ARN |
 | <a name="output_grafana_workspace_id"></a> [grafana\_workspace\_id](#output\_grafana\_workspace\_id) | Amazon Managed Grafana Workspace ID |
-<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
+<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
+<!-- BEGIN_TF_DOCS -->
+## Requirements
+
+No requirements.
+
+## Providers
+
+No providers.
+
+## Modules
+
+| Name | Source | Version |
+|------|--------|---------|
+| <a name="module_managed_grafana"></a> [managed\_grafana](#module\_managed\_grafana) | terraform-aws-modules/managed-service-grafana/aws | 1.10.0 |
+
+## Resources
+
+No resources.
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| <a name="input_grafana_version"></a> [grafana\_version](#input\_grafana\_version) | AWS Managed grafana version | `string` | n/a | yes |
+| <a name="input_region"></a> [region](#input\_region) | AWS Region | `string` | n/a | yes |
+| <a name="input_workspace_api_keys_keyname"></a> [workspace\_api\_keys\_keyname](#input\_workspace\_api\_keys\_keyname) | Workspace api key base key name | `string` | n/a | yes |
+| <a name="input_workspace_api_keys_keyrole"></a> [workspace\_api\_keys\_keyrole](#input\_workspace\_api\_keys\_keyrole) | Workspace api key base key role like ADMIN, VIEWER, EDITOR etc | `string` | n/a | yes |
+| <a name="input_workspace_api_keys_ttl"></a> [workspace\_api\_keys\_ttl](#input\_workspace\_api\_keys\_ttl) | Workspace api key base key  time to live in seconds . Specifies the time in seconds until the API key expires. Keys can be valid for up to 30 days | `number` | n/a | yes |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| <a name="output_grafana_workspace_endpoint"></a> [grafana\_workspace\_endpoint](#output\_grafana\_workspace\_endpoint) | Amazon Managed Grafana Workspace endpoint |
+| <a name="output_grafana_workspace_iam_role_arn"></a> [grafana\_workspace\_iam\_role\_arn](#output\_grafana\_workspace\_iam\_role\_arn) | Amazon Managed Grafana Workspace's IAM Role ARN |
+| <a name="output_grafana_workspace_id"></a> [grafana\_workspace\_id](#output\_grafana\_workspace\_id) | Amazon Managed Grafana Workspace ID |
+| <a name="output_granafa_workspace_api_key"></a> [granafa\_workspace\_api\_key](#output\_granafa\_workspace\_api\_key) | n/a |
+<!-- END_TF_DOCS -->