0
# AWS Hooks
1

2
AWS-specific hooks and utilities for handling AWS resource configurations and provider quirks. This module provides specialized transformation functions to ensure proper Terraform configuration generation for AWS resources.
3

4
## Capabilities
5

6
### Security Group Rule Transformation
7

8
Utility for ensuring AWS security group rules have all required attributes properly defined to avoid Terraform provider issues.
9

10
```python { .api }
11
def fill_in_optional_aws_security_group_rules_attrs(object_id: str, attrs: dict) -> dict:
12
    """
13
    Ensure AWS security group rules have all mandatory attributes defined.
14

15
    Parameters:
16
    - object_id: str - The resource object ID
17
    - attrs: dict - Resource attributes to transform
18

19
    Returns:
20
    dict - Modified attributes with all optional rule attributes set to None if missing
21

22
    This function processes 'ingress' and 'egress' rule blocks and ensures all
23
    optional attributes are explicitly set to None to prevent Terraform provider issues.
24
    """
25
```
26

27
### Security Group Hook Installation
28

29
Convenience function for installing the AWS security group attribute transformation hook.
30

31
```python { .api }
32
def install_aws_security_group_attributes_as_blocks_hook() -> None:
33
    """
34
    Install hook for AWS security group attribute handling.
35

36
    This installs a transformation hook that ensures all ingress and egress blocks
37
    have all mandatory attributes defined as None so they compile out as null.
38

39
    Addresses: https://github.com/terraform-providers/terraform-provider-aws/issues/8786
40
    """
41
```
42

43
## Constants
44

45
### Security Group Rule Attributes
46

47
```python { .api }
48
SECURITY_GROUP_RULE_OPTIONAL_ATTRS: tuple = (
49
    "cidr_blocks",
50
    "ipv6_cidr_blocks",
51
    "prefix_list_ids",
52
    "security_groups",
53
    "self",
54
    "description"
55
)
56
"""
57
Tuple of optional attribute names for AWS security group rules.
58
These attributes must be explicitly set to None if not provided
59
to avoid Terraform AWS provider validation issues.
60
"""
61
```
62

63
## Usage Examples
64

65
### Basic AWS Security Group Hook Usage
66

67
```python
68
from terraformpy import Resource
69
from terraformpy.hooks.aws import install_aws_security_group_attributes_as_blocks_hook
70

71
# Install the AWS security group hook globally
72
install_aws_security_group_attributes_as_blocks_hook()
73

74
# Create security group - hook will automatically ensure proper attribute handling
75
web_sg = Resource('aws_security_group', 'web',
76
    name='web-security-group',
77
    description='Security group for web server',
78
    vpc_id='${aws_vpc.main.id}',
79

80
    ingress=[
81
        {
82
            'from_port': 80,
83
            'to_port': 80,
84
            'protocol': 'tcp',
85
            'cidr_blocks': ['0.0.0.0/0']
86
            # Missing optional attributes will be automatically set to None
87
        },
88
        {
89
            'from_port': 443,
90
            'to_port': 443,
91
            'protocol': 'tcp',
92
            'security_groups': ['${aws_security_group.alb.id}']
93
            # Missing optional attributes will be automatically set to None
94
        }
95
    ],
96

97
    egress=[
98
        {
99
            'from_port': 0,
100
            'to_port': 0,
101
            'protocol': '-1',
102
            'cidr_blocks': ['0.0.0.0/0']
103
            # Missing optional attributes will be automatically set to None
104
        }
105
    ]
106
)
107
```
108

109
### Manual Hook Application
110

111
```python
112
from terraformpy import Resource
113
from terraformpy.hooks.aws import fill_in_optional_aws_security_group_rules_attrs
114

115
# Apply transformation manually to specific attributes
116
sg_attrs = {
117
    'name': 'my-security-group',
118
    'ingress': [
119
        {
120
            'from_port': 22,
121
            'to_port': 22,
122
            'protocol': 'tcp',
123
            'cidr_blocks': ['10.0.0.0/8']
124
            # Missing: ipv6_cidr_blocks, prefix_list_ids, security_groups, self, description
125
        }
126
    ]
127
}
128

129
# Transform attributes to ensure all optional fields are present
130
transformed_attrs = fill_in_optional_aws_security_group_rules_attrs('aws_security_group.ssh', sg_attrs)
131

132
# Create resource with transformed attributes
133
ssh_sg = Resource('aws_security_group', 'ssh', **transformed_attrs)
134
```
135

136
### Using with Resource Collections
137

138
```python
139
from terraformpy import ResourceCollection, Resource
140
from terraformpy.hooks.aws import install_aws_security_group_attributes_as_blocks_hook
141
import schematics
142

143
class WebTierSecurityGroups(ResourceCollection):
144
    vpc_id = schematics.StringType(required=True)
145
    allowed_cidrs = schematics.ListType(schematics.StringType(), default=['0.0.0.0/0'])
146

147
    def create_resources(self):
148
        # Install AWS hooks for this collection
149
        install_aws_security_group_attributes_as_blocks_hook()
150

151
        # ALB security group
152
        self.alb_sg = Resource('aws_security_group', 'alb',
153
            name='alb-security-group',
154
            vpc_id=self.vpc_id,
155
            ingress=[
156
                {
157
                    'from_port': 80,
158
                    'to_port': 80,
159
                    'protocol': 'tcp',
160
                    'cidr_blocks': self.allowed_cidrs
161
                },
162
                {
163
                    'from_port': 443,
164
                    'to_port': 443,
165
                    'protocol': 'tcp',
166
                    'cidr_blocks': self.allowed_cidrs
167
                }
168
            ]
169
        )
170

171
        # Web server security group
172
        self.web_sg = Resource('aws_security_group', 'web',
173
            name='web-security-group',
174
            vpc_id=self.vpc_id,
175
            ingress=[
176
                {
177
                    'from_port': 80,
178
                    'to_port': 80,
179
                    'protocol': 'tcp',
180
                    'security_groups': [self.alb_sg.id]
181
                }
182
            ]
183
        )
184

185
# Usage
186
web_security = WebTierSecurityGroups(
187
    vpc_id='${aws_vpc.main.id}',
188
    allowed_cidrs=['10.0.0.0/8', '172.16.0.0/12']
189
)
190
```
191

192
### Hook System Integration
193

194
```python
195
from terraformpy import Resource, TFObject
196
from terraformpy.hooks.aws import fill_in_optional_aws_security_group_rules_attrs
197

198
# Add hook directly to Resource class
199
Resource.add_hook('aws_security_group', fill_in_optional_aws_security_group_rules_attrs)
200

201
# Or add to the global TFObject system
202
TFObject.add_hook('aws_security_group', fill_in_optional_aws_security_group_rules_attrs)
203

204
# Now all aws_security_group resources will automatically use the hook
205
security_group = Resource('aws_security_group', 'example',
206
    name='example-sg',
207
    ingress=[{'from_port': 22, 'to_port': 22, 'protocol': 'tcp', 'cidr_blocks': ['0.0.0.0/0']}]
208
)
209
```
210

211
## Best Practices
212

213
### When to Use AWS Hooks
214

215
- **Always use** `install_aws_security_group_attributes_as_blocks_hook()` when working with AWS security groups
216
- **Use early** in your configuration - call once at the beginning of your script
217
- **Use in ResourceCollections** that create AWS security groups to ensure consistent behavior
218

219
### Troubleshooting AWS Provider Issues
220

221
The AWS hooks address common Terraform AWS provider validation errors:
222

223
```python
224
# Without hooks - may cause Terraform validation errors:
225
Resource('aws_security_group', 'broken',
226
    ingress=[{
227
        'from_port': 80,
228
        'to_port': 80,
229
        'protocol': 'tcp',
230
        'cidr_blocks': ['0.0.0.0/0']
231
        # Missing optional attributes may cause provider validation errors
232
    }]
233
)
234

235
# With hooks - guaranteed to work:
236
from terraformpy.hooks.aws import install_aws_security_group_attributes_as_blocks_hook
237
install_aws_security_group_attributes_as_blocks_hook()
238

239
Resource('aws_security_group', 'working',
240
    ingress=[{
241
        'from_port': 80,
242
        'to_port': 80,
243
        'protocol': 'tcp',
244
        'cidr_blocks': ['0.0.0.0/0']
245
        # Hook automatically adds missing attributes as None
246
    }]
247
)
248
```