Skip to content

Commit 2aca1da

Browse files
author
mayank0202
committed
added contribution file and added module usage guide
1 parent b58e9ad commit 2aca1da

File tree

3 files changed

+280
-0
lines changed

3 files changed

+280
-0
lines changed

‎.github/workflows/update-docs.yml

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,3 +36,15 @@ jobs:
3636
user-name: ${{ github.actor }}
3737
target-branch: main
3838
commit-message: ${{ github.event.head_commit.message }}
39+
- name: Pushes Module Usage Guide
40+
uses: dmnemec/copy_file_to_another_repo_action@main
41+
env:
42+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
43+
API_TOKEN_GITHUB: ${{ secrets.ARC_DOCS_API_TOKEN_GITHUB }}
44+
with:
45+
source_file: 'docs/module-usage-guide/README.md'
46+
destination_repo: 'sourcefuse/arc-docs'
47+
destination_folder: 'docs/arc-iac-docs/modules/terraform-aws-arc-ecs/docs/module-usage-guide'
48+
user_email: 'github-actions@github.com'
49+
user_name: ${{ github.actor }}
50+
commit_message: ${{ github.event.head_commit.message }}

‎CONTRIBUTING.md

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# Contributing to AWS ARC ECS
2+
3+
Thank you for considering contributing to AWS ARC ECS! We appreciate your time and effort.
4+
To ensure a smooth collaboration, please take a moment to review the following guidelines.
5+
6+
## How to Contribute
7+
8+
1. Fork the repository to your own GitHub account.
9+
2. Clone the repository to your local machine.
10+
```bash
11+
git clone https://github.com/<your_organization>/<your_terraform_module>.git
12+
```
13+
3. Create a new branch for your feature / bugfix.
14+
```bash
15+
git checkout -b feature/branch_name
16+
```
17+
4. Make your changes and commit them.
18+
```bash
19+
git commit -m "Your descriptive commit message"
20+
```
21+
5. Push to your forked repository.
22+
```bash
23+
git push origin feature/branch_name
24+
```
25+
6. Open a pull request in the original repository with a clear title and description.
26+
If your pull request addresses an issue, please reference the issue number in the pull request description.
27+
28+
### Git commits
29+
30+
while Contributing or doing git commit please specify the breaking change in your commit message whether its major,minor or patch
31+
32+
For Example
33+
34+
```sh
35+
git commit -m "your commit message #major"
36+
```
37+
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
38+
39+
# Terraform Code Collaboration Guidelines
40+
41+
## File Naming Conventions
42+
43+
1. **Variables File (variables.tf):**
44+
- All variable names should be in snake_case.
45+
- Each variable declaration must contain:
46+
- Description: A brief explanation of the variable's purpose.
47+
- Type: The data type of the variable.
48+
49+
Example:
50+
```hcl
51+
variable "example_variable" {
52+
description = "This is an example variable."
53+
type = string
54+
}
55+
```
56+
57+
2. **Outputs File (outputs.tf):**
58+
- All output names should be in snake_case.
59+
- Each output declaration must contain:
60+
- Description: A brief explanation of the output's purpose.
61+
- Value: The value that will be exposed as the output.
62+
63+
Example:
64+
```hcl
65+
output "example_output" {
66+
description = "This is an example output."
67+
value = module.example_module.example_attribute
68+
}
69+
```
70+
71+
## Resource and Module Naming
72+
73+
1. **Terraform Resources/Modules:**
74+
- Resource and module names should be in snake_case.
75+
- Choose descriptive names that reflect the purpose of the resource or module.
76+
77+
Example:
78+
```hcl
79+
resource "aws_instance" "web_server" {
80+
// ...
81+
}
82+
83+
module "networking" {
84+
// ...
85+
}
86+
```
87+
88+
## General Guidelines
89+
90+
1. **Consistent Formatting:**
91+
- Follow consistent code formatting to enhance readability.
92+
- Use indentation and line breaks appropriately.
93+
94+
2. **Comments:**
95+
- Add comments to explain complex logic, decisions, or any non-trivial code.
96+
- Keep comments up-to-date with the code.
97+
98+
3. **Module Documentation:**
99+
- Include a README.md file within each module directory, explaining its purpose, inputs, and outputs.
100+
- Use inline documentation within the code for complex modules.
101+
102+
4. **Avoid Hardcoding:**
103+
- Minimize hardcoded values; prefer using variables and references for increased flexibility.
104+
105+
5. **Sensitive Information:**
106+
- Do not hardcode sensitive information (e.g., passwords, API keys). Use appropriate methods for securing sensitive data.
107+
108+
6. **Error Handling:**
109+
- Implement proper error handling and consider the impact of potential failures.
110+
111+
## Version Control
112+
113+
1. **Commit Messages:**
114+
- Use descriptive and concise commit messages that explain the purpose of the changes.
115+
116+
2. **Branching:**
117+
- Follow a branching strategy (e.g., feature branches) for better collaboration.
118+
119+
## Code Style
120+
121+
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.
122+
123+
## Testing
124+
125+
!!! This section is a work-in-progress, as we are starting to adopt testing using Terratest. !!!
126+
127+
Before submitting a pull request, ensure that your changes pass all tests. If applicable, add new tests to cover your changes.
128+
129+
## Documentation
130+
131+
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.
132+
133+
## Security and Compliance Checks
134+
135+
GitHub Actions are in place to perform security and compliance checks. Please make sure your changes pass these checks before submitting a pull request.
136+
137+
## Licensing
138+
139+
By contributing, you agree that your contributions will be licensed under the project's [LICENSE](LICENSE).

‎docs/module-usage-guide/README.md

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# Terraform AWS ARC EKS Module Usage Guide
2+
3+
## Introduction
4+
5+
### Purpose of the Document
6+
7+
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.
8+
9+
### Module Overview
10+
11+
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.
12+
13+
![Module Structure](./static/ecs_module_hla.png)
14+
15+
### Prerequisites
16+
17+
Before using this module, ensure you have the following:
18+
19+
- AWS credentials configured.
20+
- Terraform installed.
21+
- A working knowledge of AWS VPC, ECS and Terraform concepts.
22+
23+
## Getting Started
24+
25+
### Module Source
26+
27+
To use the module in your Terraform configuration, include the following source block:
28+
29+
```hcl
30+
module "arc-ecs" {
31+
source = "sourcefuse/arc-ecs/aws"
32+
version = "1.5.0"
33+
# insert the 6 required variables here
34+
}
35+
```
36+
37+
Refer to the [Terraform Registry](https://registry.terraform.io/modules/sourcefuse/arc-ecs/aws/latest) for the latest version.
38+
39+
### Integration with Existing Terraform Configurations
40+
41+
Integrate the module with your existing Terraform mono repo configuration, follow the steps below:
42+
43+
1. Create a new folder in `terraform/` named `ecs`.
44+
2. Create the required files, see the [examples](https://github.com/sourcefuse/terraform-aws-arc-ecs/tree/main/example) to base off of.
45+
3. Configure with your backend
46+
- Create the environment backend configuration file: `config.<environment>.hcl`
47+
- **region**: Where the backend resides
48+
- **key**: `<working_directory>/terraform.tfstate`
49+
- **bucket**: Bucket name where the terraform state will reside
50+
- **dynamodb_table**: Lock table so there are not duplicate tfplans in the mix
51+
- **encrypt**: Encrypt all traffic to and from the backend
52+
53+
### Required AWS Permissions
54+
55+
Ensure that the AWS credentials used to execute Terraform have the necessary permissions to create, list and modify:
56+
57+
- ECS cluster
58+
- Application load balancer
59+
- ACM
60+
- SSM Parameters
61+
- Cloudwatch Log groups
62+
- IAM roles and policies
63+
64+
## Module Configuration
65+
66+
### Input Variables
67+
68+
For a list of input variables, see the README [Inputs](https://github.com/sourcefuse/terraform-aws-arc-ecs?tab=readme-ov-file#inputs) section.
69+
70+
### Output Values
71+
72+
For a list of outputs, see the README [Outputs](https://github.com/sourcefuse/terraform-aws-arc-ecs?tab=readme-ov-file#outputs) section.
73+
74+
## Module Usage
75+
76+
### Basic Usage
77+
78+
For basic usage, see the [example](https://github.com/sourcefuse/terraform-aws-arc-ecs/tree/main/example) folder.
79+
80+
This example will create:
81+
82+
- An ECS Cluster with Fargate launch type.
83+
- Application Load Balancer with default port 80 to 443 redirect.
84+
- 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.
85+
- Task Execution IAM Role: Used by downstream services for task execution.
86+
- ACM Certificate: Generates a certificate specific to the ALB.
87+
- Tags/SSM Params: The module tags resources and outputs SSM params for ECS services to reference when deploying into the cluster
88+
89+
### Tips and Recommendations
90+
91+
- 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.
92+
93+
## Troubleshooting
94+
95+
### Reporting Issues
96+
97+
If you encounter a bug or issue, please report it on the [GitHub repository](https://github.com/sourcefuse/terraform-aws-arc-ecs/issues).
98+
99+
## Security Considerations
100+
101+
### AWS VPC
102+
103+
Understand the security considerations related to ECS clusters on AWS when using this module.
104+
105+
### Best Practices for AWS EKS
106+
107+
Follow best practices to ensure secure EKS configurations:
108+
109+
- [ECS security on AWS](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/security.html)
110+
111+
## Contributing and Community Support
112+
113+
### Contributing Guidelines
114+
115+
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.
116+
117+
### Reporting Bugs and Issues
118+
119+
If you find a bug or issue, report it on the [GitHub repository](https://github.com/sourcefuse/terraform-aws-arc-ecs/issues).
120+
121+
## License
122+
123+
### License Information
124+
125+
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.
126+
127+
### Open Source Contribution
128+
129+
Contribute to open source by using and enhancing this module. Your contributions are welcome!

0 commit comments

Comments
 (0)