-
Notifications
You must be signed in to change notification settings - Fork 0
/
.terraform-docs
149 lines (94 loc) · 9.57 KB
/
.terraform-docs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
content: |-
{{ .Header }}
## Features
This module aims to implement **ALL** combinations of `aws_security_group` and `aws_security_group_rule` arguments supported by AWS and latest stable version of Terraform.
What's more, this module was designed after the [terraform-aws-modules/terraform-aws-security-group](https://github.com/terraform-aws-modules/terraform-aws-security-group#features) module and aims to have feature parody. Please see the [Acknowledgments](https://github.com/aidanmelen/terraform-aws-security-group-v2/blob/main/README.md#acknowledgments) section for more information.
### Rule Aliases
**Manage Rules**:
<details><summary>Click to show</summary>
```hcl
{{ include "alias_managed_rules.tf" }}
```
</details>
**Common Rules:**
<details><summary>Click to show</summary>
```hcl
{{ include "alias_common_rules.tf" }}
```
</details>
## Examples
Create a Security Group with the following rules:
- Ingress `https-443-tcp` managed rules (ipv4 and ipv6)
- Egress `all-all-to-public` common rule
```hcl
{{ include "examples/basic/.main.tf.docs" }}
```
</details>
Please see the full examples for more information:
- [Basic Example](https://github.com/aidanmelen/terraform-aws-security-group-v2/tree/main/examples/basic)
- [Complete Example](https://github.com/aidanmelen/terraform-aws-security-group-v2/tree/main/examples/complete)
- [Customer Rules Example](https://github.com/aidanmelen/terraform-aws-security-group-v2/tree/main/examples/customer)
- [Managed Rules Example](https://github.com/aidanmelen/terraform-aws-security-group-v2/tree/main/examples/managed)
- [Common Rules Example](https://github.com/aidanmelen/terraform-aws-security-group-v2/tree/main/examples/common)
- [Matrix Rules Example](https://github.com/aidanmelen/terraform-aws-security-group-v2/tree/main/examples/matrix)
- [Computed Rules Example](https://github.com/aidanmelen/terraform-aws-security-group-v2/tree/main/examples/computed)
- [Name Prefix Example](https://github.com/aidanmelen/terraform-aws-security-group-v2/tree/main/examples/name_prefix)
- [Rules Only Example](https://github.com/aidanmelen/terraform-aws-security-group-v2/tree/main/examples/rules_only)
- [Unpack Example](https://github.com/aidanmelen/terraform-aws-security-group-v2/tree/main/examples/unpack)
- [Source Security Group IDs Example](https://github.com/aidanmelen/terraform-aws-security-group-v2/tree/main/examples/source_security_group_ids)
## Key Concepts
| Terminology | Description |
|---|---|
| **AWS Security Group Rule** | The Security Group (SG) rule resource (ingress/egress). |
| **Customer Rule** | A module rule where the customer explicitly declares all of the SG rule arguments. <br/><br/>These rules are analogous to [AWS customer policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#customer-managed-policies) for IAM. |
| **Managed Rule** | A module rule alias for a managed/[predefined](https://github.com/terraform-aws-modules/terraform-aws-security-group#security-group-with-predefined-rules) group of `from_port`, `to_port`, and `protocol` arguments. <br/><br/> E.g. `https-443-tcp`/`https-tcp`, `postgresql-tcp`, `ssh-tcp`, and `all-all`. Please see [alias_managed_rules.tf](https://github.com/aidanmelen/terraform-aws-security-group-v2/tree/main/alias_managed_rules.tf) for the complete list of managed rules. <br/><br/>These rules are analogous to [AWS managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#aws-managed-policies) for IAM. |
| **Common Rule** | A module rule alias for a common scenario where all SG rule arguments except for `type` are known and managed by the rule. <br/><br/>E.g. `https-443-tcp-public`/`https-tcp-from-public`, and `all-all-to-public`, `all-all-from-self` just to name a few. Please see [alias_common_rules.tf](https://github.com/aidanmelen/terraform-aws-security-group-v2/tree/main/alias_common_rules.tf) for the complete list of common rules. |
| **Matrix Rules** | A map of module rule(s) and source(s)/destination(s) representing the multi-dimensional matrix rules to be applied. <br/><br/>These rules act like a [multi-dimension matrix in Github Actions](https://docs.github.com/en/actions/using-jobs/using-a-matrix-for-your-jobs#example-using-a-multi-dimension-matrix).|
| **Computed Rule** | A special module rule that works with [unknown values](https://github.com/hashicorp/terraform/issues/30937) such as: `aws_vpc.vpc.cidr_blocks`, `aws_security_group.sg.id`, etc. All types of module rules are supported. |
| **Packed Rules** | The arguments for a single `aws_security_group_rule` resource are considered "packed" when the resulting EC2 API creates many security group rules. |
| **Unpacked Rules** | The arguments for a single `aws_security_group_rule` resource are considered "unpacked" when the resulting EC2 API creates exactly one security group rule. |
## Rule Argument Precedence
This module uses the [`try` function](https://developer.hashicorp.com/terraform/language/functions/try) to implement argument precedence.
| Argument | Precedence (most -> least) |
|---|---|
| **description** | `rule.description` -> `rule_alias.description` -> `var.default_rule_description` |
| **from_port** | `rule.from_port (customer)` -> `rule_alias.from_port (managed/common)` |
| **to_port** | `rule.to_port (customer)` -> `rule_alias.to_port (managed/common)` |
| **protocol** | `rule.protocol (customer)` -> `rule_alias.protocol (managed/common)` |
| **cidr_blocks** | `rule.cidr_blocks` -> `rule_alias.cidr_blocks (common)` |
| **ipv6_cidr_blocks** | `rule.ipv6_cidr_blocks` -> `rule_alias.ipv6_cidr_blocks (common)` |
| **prefix_list_ids** | `rule.prefix_list_ids` -> `rule_alias.prefix_list_ids (common)` |
| **source_security_group_id** | `rule.source_security_group_id` -> `rule_alias.source_security_group_id (common)` |
| **self** | `rule.self` -> `rule_alias.self (common)` |
## Tests
Run Terratest using the [Makefile](https://github.com/aidanmelen/terraform-aws-security-group-v2/tree/main/Makefile) targets:
1. `make setup`
2. `make tests`
### Results
```
{{ include "test/.terratest.docs" }}
```
## Makefile Targets
```
{{ include ".makefile.docs" }}
```
{{ .Requirements }}
{{ .Modules }}
{{ .Resources }}
{{ .Inputs }}
{{ .Outputs }}
## Acknowledgments
This modules aims to improve on the venerable [terraform-aws-modules/terraform-aws-security-group](https://github.com/terraform-aws-modules/terraform-aws-security-group) module authored by [Anton Babenko](https://github.com/antonbabenko). It does so by:
- Reduce the amount of code with [`for` expressions](https://www.terraform.io/language/expressions/for). The core functionality found in the [main.tf](https://github.com/aidanmelen/terraform-aws-security-group-v2/blob/main/main.tf) is ~100 lines.
- Follow DRY principals by using [Conditionally Omitted Arguments](https://www.hashicorp.com/blog/terraform-0-12-conditional-operator-improvements#conditionally-omitted-arguments) AKA nullables.
- Prevent Service interruptions by [unpacking](https://github.com/aidanmelen/terraform-aws-security-group-v2/tree/main/examples/unpack) packed arguments provided by the user.
- A simplified interface for matrix functionality that works with all module rule types and computed rules.
- Dynamically create customer, managed and common security group rule resources with [`for_each` meta-arguments](https://www.terraform.io/language/meta-arguments/for_each). `for_each` has two advantages over `count`:
1. Resources created with `for_each` are identified by a list of string values instead of by index with `count`.
2. If an element is removed from the middle of the list, every security group rule after that element would see its values change, resulting in more remote object changes than intended. Using `for_each` gives the same flexibility without the extra churn. Please see [When to Use for_each Instead of count](https://www.terraform.io/language/meta-arguments/count#when-to-use-for_each-instead-of-count) for more information.
- Computed security group rule resources must use `count` due to the [Limitations on values used in `for_each`](https://www.terraform.io/language/meta-arguments/for_each#limitations-on-values-used-in-for_each). However, this implementation uses the `length` function to dynamically set the `count` which is an improvement from the `number_of_computed_` variables used by the [terraform-aws-security-group](https://github.com/terraform-aws-modules/terraform-aws-security-group#note-about-value-of-count-cannot-be-computed) module. Please see [#30937](https://github.com/hashicorp/terraform/issues/30937) for more information on unknown values.
- Encourage the security best practice of restrictive rules by making users **opt-in** to common rules like `all-all-to-public`. This approach is consistent with the implementation of the `aws_security_group_rule` resource as described in the [NOTE on Egress rules](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/security_group#basic-usage). Moreover, please see [no-public-egress-sgr](https://aquasecurity.github.io/tfsec/v0.61.3/checks/aws/vpc/no-public-egress-sgr/) for more information.
- Improve security by making it easy for users to declare granular customer, managed, common, matrix, and computed security group rules.
- Test examples with [Terratest](https://terratest.gruntwork.io/).
## License
Apache 2 Licensed. See [LICENSE](https://github.com/aidanmelen/terraform-kubernetes-confluent-platform/blob/main/LICENSE) for full details.