Merge pull request #50 from sourcefuse/GH-49

added contribution file and added module usage guide

Author: mayank0202

.github/workflows/update-docs.yml

@@ -36,3 +36,15 @@ jobs:
           user-name: ${{ github.actor }}
           target-branch: main
           commit-message: ${{ github.event.head_commit.message }}
+      - name: Pushes Module Usage Guide
+        uses: dmnemec/copy_file_to_another_repo_action@main
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          API_TOKEN_GITHUB: ${{ secrets.ARC_DOCS_API_TOKEN_GITHUB }}
+        with:
+          source_file: 'docs/module-usage-guide/README.md'
+          destination_repo: 'sourcefuse/arc-docs'
+          destination_folder: 'docs/arc-iac-docs/modules/terraform-aws-arc-ecs/docs/module-usage-guide'
+          user_email: 'github-actions@github.com'
+          user_name: ${{ github.actor }}
+          commit_message: ${{ github.event.head_commit.message }}

CONTRIBUTING.md

@@ -0,0 +1,154 @@
+# Contributing to AWS ARC ECS
+
+Thank you for considering contributing to AWS ARC ECS! 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. If you add new features or change existing functionality, update the [README](README.md) and any relevant documentation files.
+
+## 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).

docs/module-usage-guide/README.md

@@ -0,0 +1,127 @@
+# Terraform AWS ARC ECS Module Usage Guide
+
+## Introduction
+
+### Purpose of the Document
+
+This document provides guidelines and instructions for users looking to implement the Terraform AWS ARC ECS module for setting up and running a production ready ECS cluster.
+
+### Module Overview
+
+The [Terraform AWS ARC ECS](https://github.com/sourcefuse/terraform-aws-arc-ecs) module provides a secure and modular foundation for deploying ECS clusters on AWS.
+
+### Prerequisites
+
+Before using this module, ensure you have the following:
+
+- AWS credentials configured.
+- Terraform installed.
+- A working knowledge of AWS VPC, ECS and Terraform concepts.
+
+## Getting Started
+
+### Module Source
+
+To use the module in your Terraform configuration, include the following source block:
+
+```hcl
+module "arc-ecs" {
+  source  = "sourcefuse/arc-ecs/aws"
+  version = "1.5.0"
+  # insert the 6 required variables here
+}
+```
+
+Refer to the [Terraform Registry](https://registry.terraform.io/modules/sourcefuse/arc-ecs/aws/latest) for the latest version.
+
+### Integration with Existing Terraform Configurations
+
+Integrate the module with your existing Terraform mono repo configuration, follow the steps below:
+
+1. Create a new folder in `terraform/` named `ecs`.
+2. Create the required files, see the [examples](https://github.com/sourcefuse/terraform-aws-arc-ecs/tree/main/example) to base off of.
+3. Configure with your backend
+  - Create the environment backend configuration file: `config.<environment>.hcl`
+    - **region**: Where the backend resides
+    - **key**: `<working_directory>/terraform.tfstate`
+    - **bucket**: Bucket name where the terraform state will reside
+    - **dynamodb_table**: Lock table so there are not duplicate tfplans in the mix
+    - **encrypt**: Encrypt all traffic to and from the backend
+
+### Required AWS Permissions
+
+Ensure that the AWS credentials used to execute Terraform have the necessary permissions to create, list and modify:
+
+- ECS cluster
+- Application load balancer
+- ACM
+- SSM Parameters
+- Cloudwatch Log groups
+- IAM roles and policies
+
+## Module Configuration
+
+### Input Variables
+
+For a list of input variables, see the README [Inputs](https://github.com/sourcefuse/terraform-aws-arc-ecs?tab=readme-ov-file#inputs) section.
+
+### Output Values
+
+For a list of outputs, see the README [Outputs](https://github.com/sourcefuse/terraform-aws-arc-ecs?tab=readme-ov-file#outputs) section.
+
+## Module Usage
+
+### Basic Usage
+
+For basic usage, see the [example](https://github.com/sourcefuse/terraform-aws-arc-ecs/tree/main/example) folder.
+
+This example will create:
+
+- An ECS Cluster with Fargate launch type.
+- Application Load Balancer with default port 80 to 443 redirect.
+- Health Check Service: A vanilla HTTP echo service serving as the default target group for the load balancer to      ensure core infrastructure, networking, security groups, etc. are configured correctly.
+- Task Execution IAM Role: Used by downstream services for task execution.
+- ACM Certificate: Generates a certificate specific to the ALB.
+- Tags/SSM Params: The module tags resources and outputs SSM params for ECS services to reference when deploying into the cluster
+
+### Tips and Recommendations
+
+- The module focuses on provisioning an ECS Cluster using Fargate launch type, an ALB with a default port redirect, a health check service, a task execution IAM role, and an ACM certificate for secure communication. The convention-based approach enables downstream services to easily attach to the ECS Fargate cluster. Adjust the configuration parameters as needed for your specific use case.
+
+## Troubleshooting
+
+### Reporting Issues
+
+If you encounter a bug or issue, please report it on the [GitHub repository](https://github.com/sourcefuse/terraform-aws-arc-ecs/issues).
+
+## Security Considerations
+
+### AWS VPC
+
+Understand the security considerations related to ECS clusters on AWS when using this module.
+
+### Best Practices for AWS ECS
+
+Follow best practices to ensure secure ECS configurations:
+
+- [ECS security on AWS](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/security.html)
+
+## Contributing and Community Support
+
+### Contributing Guidelines
+
+Contribute to the module by following the guidelines outlined in the [CONTRIBUTING.md](https://github.com/sourcefuse/terraform-aws-arc-ecs/blob/main/CONTRIBUTING.md) file.
+
+### Reporting Bugs and Issues
+
+If you find a bug or issue, report it on the [GitHub repository](https://github.com/sourcefuse/terraform-aws-arc-ecs/issues).
+
+## License
+
+### License Information
+
+This module is licensed under the Apache 2.0 license. Refer to the [LICENSE](https://github.com/sourcefuse/terraform-aws-arc-ecs/blob/main/LICENSE) file for more details.
+
+### Open Source Contribution
+
+Contribute to open source by using and enhancing this module. Your contributions are welcome!