Skip to content

Commit 7e4a415

Browse files
author
manikanta-sadurla
committed
Merge pull request #2 from sourcefuse/feature/fix-workflow
updated workflow
1 parent d2f4b86 commit 7e4a415

File tree

1 file changed

+237
-0
lines changed
  • docs/arc-iac-docs/modules/terraform-aws-arc-sns

1 file changed

+237
-0
lines changed

‎docs/arc-iac-docs/modules/terraform-aws-arc-sns/README.md‎

Lines changed: 237 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,237 @@
1+
![Module Structure](./static/banner.png)
2+
# AWS SNS Terraform Module
3+
4+
# [terraform-aws-arc-sns](https://github.com/sourcefuse/terraform-aws-arc-sns)
5+
6+
<a href="https://github.com/sourcefuse/terraform-aws-arc-sns/releases/latest"><img src="https://img.shields.io/github/release/sourcefuse/terraform-aws-arc-sns.svg?style=for-the-badge" alt="Latest Release"/></a> <a href="https://github.com/sourcefuse/terraform-aws-arc-sns/commits"><img src="https://img.shields.io/github/last-commit/sourcefuse/terraform-aws-arc-sns.svg?style=for-the-badge" alt="Last Updated"/></a> ![Terraform](https://img.shields.io/badge/terraform-%235835CC.svg?style=for-the-badge&logo=terraform&logoColor=white) ![GitHub Actions](https://img.shields.io/badge/github%20actions-%232671E5.svg?style=for-the-badge&logo=githubactions&logoColor=white)
7+
8+
[![Quality gate](https://sonarcloud.io/api/project_badges/quality_gate?project=sourcefuse_terraform-aws-arc-sns&token=0becb68af7fd9c5aa57e380d1b53c84558fa4037)](https://sonarcloud.io/summary/new_code?id=sourcefuse_terraform-aws-arc-sns)
9+
10+
11+
## Overview
12+
13+
The ARC Terraform module provides an easy and consistent way to create and manage Amazon SNS topics on AWS. This module supports defining topics, subscriptions, and policies, making it simple to connect services like S3, Lambda, and SQS. By using this module, you can quickly set up reliable messaging and notification workflows while following AWS best practices.
14+
15+
### Prerequisites
16+
Before using this module, ensure you have the following:
17+
18+
- AWS credentials configured.
19+
- Terraform installed.
20+
- A working knowledge of Terraform.
21+
22+
## Getting Started
23+
24+
1. **Define the Module**
25+
26+
Initially, it's essential to define a Terraform module, which is organized as a distinct directory encompassing Terraform configuration files. Within this module directory, input variables and output values must be defined in the variables.tf and outputs.tf files, respectively. The following illustrates an example directory structure:
27+
28+
29+
30+
```plaintext
31+
sns/
32+
|-- main.tf
33+
|-- variables.tf
34+
|-- outputs.tf
35+
```
36+
37+
38+
2. **Define Input Variables**
39+
40+
Inside the `variables.tf` or in `*.tfvars` file, you should define values for the variables that the module requires.
41+
42+
3. **Use the Module in Your Main Configuration**
43+
In your main Terraform configuration file (e.g., main.tf), you can use the module. Specify the source of the module, and version, For Example
44+
45+
```hcl
46+
module "sns" {
47+
source = "sourcefuse/arc-sns/aws"
48+
version = "0.0.1"
49+
50+
name = var.topic_name
51+
display_name = var.display_name
52+
53+
tags = module.tags.tags
54+
}
55+
```
56+
57+
4. **Output Values**
58+
59+
Inside the `outputs.tf` file of the module, you can define output values that can be referenced in the main configuration. For example:
60+
61+
```hcl
62+
output "topic_arn" {
63+
description = "ARN of the created SNS topic"
64+
value = module.basic_sns_topic.topic_arn
65+
}
66+
67+
output "topic_name" {
68+
description = "Name of the created SNS topic"
69+
value = module.basic_sns_topic.topic_name
70+
}
71+
72+
```
73+
74+
5. **.tfvars**
75+
76+
Inside the `.tfvars` file of the module, you can provide desired values that can be referenced in the main configuration.
77+
78+
79+
## First Time Usage
80+
***uncomment the backend block in [main.tf](./examples/endpoint//main.tf)***
81+
```shell
82+
terraform init -backend-config=config.dev.hcl
83+
```
84+
***If testing locally, `terraform init` should be fine***
85+
86+
Create a `dev` workspace
87+
```shell
88+
terraform workspace new dev
89+
```
90+
91+
Plan Terraform
92+
```shell
93+
terraform plan -var-file dev.tfvars
94+
```
95+
96+
Apply Terraform
97+
```shell
98+
terraform apply -var-file dev.tfvars
99+
```
100+
101+
## Production Setup
102+
```shell
103+
terraform init -backend-config=config.prod.hcl
104+
```
105+
106+
Create a `prod` workspace
107+
```shell
108+
terraform workspace new prod
109+
```
110+
111+
Plan Terraform
112+
```shell
113+
terraform plan -var-file prod.tfvars
114+
```
115+
116+
Apply Terraform
117+
```shell
118+
terraform apply -var-file prod.tfvars
119+
```
120+
121+
<!-- BEGIN_TF_DOCS -->
122+
## Requirements
123+
124+
| Name | Version |
125+
|------|---------|
126+
| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.5.0 |
127+
| <a name="requirement_aws"></a> [aws](#requirement\_aws) | ~> 5.0 |
128+
129+
## Providers
130+
131+
| Name | Version |
132+
|------|---------|
133+
| <a name="provider_aws"></a> [aws](#provider\_aws) | 4.67.0 |
134+
135+
## Modules
136+
137+
No modules.
138+
139+
## Resources
140+
141+
| Name | Type |
142+
|------|------|
143+
| [aws_lambda_permission.external_lambda](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/lambda_permission) | resource |
144+
| [aws_lambda_permission.sns_invoke](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/lambda_permission) | resource |
145+
| [aws_sns_topic.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/sns_topic) | resource |
146+
| [aws_sns_topic_subscription.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/sns_topic_subscription) | resource |
147+
148+
## Inputs
149+
150+
| Name | Description | Type | Default | Required |
151+
|------|-------------|------|---------|:--------:|
152+
| <a name="input_application_feedback"></a> [application\_feedback](#input\_application\_feedback) | Map of IAM role ARNs and sample rate for success and failure feedback | <pre>object({<br/> failure_role_arn = optional(string)<br/> success_role_arn = optional(string)<br/> success_sample_rate = optional(number)<br/> })</pre> | `{}` | no |
153+
| <a name="input_archive_policy"></a> [archive\_policy](#input\_archive\_policy) | The message archive policy for FIFO topics | `string` | `null` | no |
154+
| <a name="input_content_based_deduplication"></a> [content\_based\_deduplication](#input\_content\_based\_deduplication) | Enables content-based deduplication for FIFO topics | `bool` | `false` | no |
155+
| <a name="input_create_subscription"></a> [create\_subscription](#input\_create\_subscription) | Whether to create SNS subscriptions | `bool` | `true` | no |
156+
| <a name="input_create_topic"></a> [create\_topic](#input\_create\_topic) | Whether to create the SNS topic | `bool` | `true` | no |
157+
| <a name="input_delivery_policy"></a> [delivery\_policy](#input\_delivery\_policy) | The SNS delivery policy | `string` | `null` | no |
158+
| <a name="input_display_name"></a> [display\_name](#input\_display\_name) | Display name for the SNS topic | `string` | `null` | no |
159+
| <a name="input_fifo_throughput_scope"></a> [fifo\_throughput\_scope](#input\_fifo\_throughput\_scope) | Enables higher throughput for FIFO topics by adjusting the scope of deduplication. Valid values: Topic, MessageGroup | `string` | `null` | no |
160+
| <a name="input_fifo_topic"></a> [fifo\_topic](#input\_fifo\_topic) | Boolean indicating whether or not to create a FIFO (first-in-first-out) topic | `bool` | `false` | no |
161+
| <a name="input_firehose_feedback"></a> [firehose\_feedback](#input\_firehose\_feedback) | Map of IAM role ARNs and sample rate for success and failure feedback | <pre>object({<br/> failure_role_arn = optional(string)<br/> success_role_arn = optional(string)<br/> success_sample_rate = optional(number)<br/> })</pre> | `{}` | no |
162+
| <a name="input_http_feedback"></a> [http\_feedback](#input\_http\_feedback) | Map of IAM role ARNs and sample rate for success and failure feedback | <pre>object({<br/> failure_role_arn = optional(string)<br/> success_role_arn = optional(string)<br/> success_sample_rate = optional(number)<br/> })</pre> | `{}` | no |
163+
| <a name="input_kms_master_key_id"></a> [kms\_master\_key\_id](#input\_kms\_master\_key\_id) | The ID of an AWS-managed customer master key (CMK) for Amazon SNS or a custom CMK | `string` | `null` | no |
164+
| <a name="input_lambda_feedback"></a> [lambda\_feedback](#input\_lambda\_feedback) | Map of IAM role ARNs and sample rate for success and failure feedback | <pre>object({<br/> failure_role_arn = optional(string)<br/> success_role_arn = optional(string)<br/> success_sample_rate = optional(number)<br/> })</pre> | `{}` | no |
165+
| <a name="input_lambda_permissions"></a> [lambda\_permissions](#input\_lambda\_permissions) | Map of Lambda function ARNs that should be granted permission to be invoked by this SNS topic | `map(string)` | `{}` | no |
166+
| <a name="input_name"></a> [name](#input\_name) | Name of the SNS topic | `string` | n/a | yes |
167+
| <a name="input_policy"></a> [policy](#input\_policy) | The fully-formed AWS policy as JSON | `string` | `null` | no |
168+
| <a name="input_signature_version"></a> [signature\_version](#input\_signature\_version) | The signature version corresponds to the hashing algorithm used while creating the signature of the notifications | `number` | `null` | no |
169+
| <a name="input_sqs_feedback"></a> [sqs\_feedback](#input\_sqs\_feedback) | Map of IAM role ARNs and sample rate for success and failure feedback | <pre>object({<br/> failure_role_arn = optional(string)<br/> success_role_arn = optional(string)<br/> success_sample_rate = optional(number)<br/> })</pre> | `{}` | no |
170+
| <a name="input_subscriptions"></a> [subscriptions](#input\_subscriptions) | A map of subscription configurations | <pre>map(object({<br/> protocol = string<br/> endpoint = string<br/> confirmation_timeout_in_minutes = optional(number, 1)<br/> endpoint_auto_confirms = optional(bool, false)<br/> raw_message_delivery = optional(bool, false)<br/> filter_policy = optional(string)<br/> filter_policy_scope = optional(string)<br/> delivery_policy = optional(string)<br/> redrive_policy = optional(string)<br/> }))</pre> | `{}` | no |
171+
| <a name="input_tags"></a> [tags](#input\_tags) | A map of tags to assign to the resource | `map(string)` | `{}` | no |
172+
| <a name="input_tracing_config"></a> [tracing\_config](#input\_tracing\_config) | Tracing mode of an Amazon SNS topic | `string` | `null` | no |
173+
| <a name="input_use_name_prefix"></a> [use\_name\_prefix](#input\_use\_name\_prefix) | Determines whether name is used as a prefix | `bool` | `false` | no |
174+
175+
## Outputs
176+
177+
| Name | Description |
178+
|------|-------------|
179+
| <a name="output_subscriptions"></a> [subscriptions](#output\_subscriptions) | Map of subscriptions created and their attributes |
180+
| <a name="output_topic_arn"></a> [topic\_arn](#output\_topic\_arn) | The ARN of the SNS topic |
181+
| <a name="output_topic_display_name"></a> [topic\_display\_name](#output\_topic\_display\_name) | The display name of the SNS topic |
182+
| <a name="output_topic_id"></a> [topic\_id](#output\_topic\_id) | The ID of the SNS topic |
183+
| <a name="output_topic_name"></a> [topic\_name](#output\_topic\_name) | The name of the SNS topic |
184+
| <a name="output_topic_owner"></a> [topic\_owner](#output\_topic\_owner) | The AWS Account ID of the SNS topic owner |
185+
<!-- END_TF_DOCS -->
186+
187+
## Versioning
188+
This project uses a `.version` file at the root of the repo which the pipeline reads from and does a git tag.
189+
190+
When you intend to commit to `main`, you will need to increment this version. Once the project is merged,
191+
the pipeline will kick off and tag the latest git commit.
192+
193+
## Development
194+
195+
### Prerequisites
196+
197+
- [terraform](https://learn.hashicorp.com/terraform/getting-started/install#installing-terraform)
198+
- [terraform-docs](https://github.com/segmentio/terraform-docs)
199+
- [pre-commit](https://pre-commit.com/#install)
200+
- [golang](https://golang.org/doc/install#install)
201+
- [golint](https://github.com/golang/lint#installation)
202+
203+
### Configurations
204+
205+
- Configure pre-commit hooks
206+
```sh
207+
pre-commit install
208+
```
209+
210+
### Versioning
211+
212+
while Contributing or doing git commit please specify the breaking change in your commit message whether its major,minor or patch
213+
214+
For Example
215+
216+
```sh
217+
git commit -m "your commit message #major"
218+
```
219+
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
220+
221+
### Tests
222+
- Tests are available in `test` directory
223+
- Configure the dependencies
224+
```sh
225+
cd test/
226+
go mod init github.com/sourcefuse/terraform-aws-refarch-<module_name>
227+
go get github.com/gruntwork-io/terratest/modules/terraform
228+
```
229+
- Now execute the test
230+
```sh
231+
go test -timeout 30m
232+
```
233+
234+
## Authors
235+
236+
This project is authored by:
237+
- SourceFuse ARC Team

0 commit comments

Comments
 (0)