Skip to content

Commit 5435f62

Browse files
author
vijay-stephen
committed
Merge pull request #1 from sourcefuse/feature/terraform-fsx-module
Feature/terraform fsx module
1 parent 0481c94 commit 5435f62

File tree

1 file changed

+189
-0
lines changed
  • docs/arc-iac-docs/modules/terraform-aws-arc-fsx/docs/module-usage-guide

1 file changed

+189
-0
lines changed

‎docs/arc-iac-docs/modules/terraform-aws-arc-fsx/docs/module-usage-guide/README.md‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
# Terraform AWS ARC FSx 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 FSx module for deploying AWS FSx file systems.
8+
9+
### Module Overview
10+
11+
The Terraform AWS ARC FSx module provides a secure and modular foundation for deploying AWS FSx file systems on AWS. It supports all four FSx variants: Windows File Server, Lustre, NetApp ONTAP, and OpenZFS with comprehensive configuration options.
12+
13+
### Prerequisites
14+
15+
Before using this module, ensure you have the following:
16+
17+
- AWS credentials configured.
18+
- Terraform installed (>= 1.3).
19+
- A working knowledge of AWS VPC, FSx, and Terraform concepts.
20+
- Understanding of your specific FSx requirements (Windows AD, S3 integration, etc.).
21+
22+
## Getting Started
23+
24+
### Module Source
25+
26+
To use the module in your Terraform configuration, include the following source block:
27+
28+
```hcl
29+
module "arc-fsx" {
30+
source = "sourcefuse/arc-fsx/aws"
31+
version = "0.0.1"
32+
33+
# Required variables
34+
name = "my-fsx"
35+
environment = "prod"
36+
fsx_type = "windows" # windows, lustre, ontap, openzfs
37+
storage_capacity = 32
38+
subnet_ids = ["subnet-12345678"]
39+
vpc_id = "vpc-12345678"
40+
}
41+
```
42+
43+
### Integration with Existing Terraform Configurations
44+
45+
Integrate the module with your existing Terraform mono repo configuration, follow the steps below:
46+
47+
- Create a new folder in terraform/ named fsx.
48+
- Create the required files, see the examples to base off of.
49+
- Configure with your backend:
50+
- Create the environment backend configuration file: config.<environment>.hcl
51+
- region: Where the backend resides
52+
- key: <working_directory>/terraform.tfstate
53+
- bucket: Bucket name where the terraform state will reside
54+
- dynamodb_table: Lock table so there are not duplicate tfplans in the mix
55+
- encrypt: Encrypt all traffic to and from the backend
56+
57+
### Required AWS Permissions
58+
59+
Ensure that the AWS credentials used to execute Terraform have the necessary permissions to create, list and modify:
60+
61+
- FSx file systems (all types: Windows, Lustre, ONTAP, OpenZFS)
62+
- FSx backups and snapshots
63+
- FSx volumes and storage virtual machines
64+
- FSx data repository associations
65+
- EC2 security groups and network interfaces
66+
- IAM roles and policies (if using IAM integration)
67+
- KMS keys (if using encryption)
68+
- VPC subnets and network resources
69+
70+
## Module Configuration
71+
72+
### Input Variables
73+
74+
For a list of input variables, see the README [Inputs](../../README.md#inputs) section.
75+
76+
Key configuration objects:
77+
- `backup_configuration` - Backup settings and retention policies
78+
- `windows_configuration` - Active Directory and audit log settings
79+
- `lustre_configuration` - S3 integration and performance settings
80+
- `ontap_configuration` - Storage virtual machines and volume settings
81+
- `openzfs_configuration` - Snapshot and compression settings
82+
83+
### Output Values
84+
85+
For a list of outputs, see the README [Outputs](../../README.md#outputs) section.
86+
87+
Key outputs include:
88+
- `fsx_id` - FSx file system ID
89+
- `fsx_arn` - FSx file system ARN
90+
- `fsx_dns_name` - DNS name for mounting
91+
- `fsx_network_interface_ids` - Network interface IDs
92+
93+
## Module Usage
94+
95+
### Basic Usage
96+
97+
For basic usage, see the [examples](../../examples/) folder.
98+
99+
Available examples:
100+
- [Basic Windows](../../examples/basic-windows/) - Single-AZ Windows file server
101+
- [Windows Self-Managed AD](../../examples/windows-self-managed-ad/) - Windows with custom AD
102+
- [Lustre](../../examples/lustre/) - High-performance Lustre file system
103+
- [ONTAP Complete](../../examples/ontap-complete/) - NetApp ONTAP with full features
104+
- [ONTAP Multi-Protocol](../../examples/ontap-multi-protocol/) - ONTAP with NFS/SMB/iSCSI
105+
- [OpenZFS Complete](../../examples/openzfs-complete/) - OpenZFS with snapshots
106+
107+
This example will create:
108+
109+
- FSx file system of the specified type
110+
- Security group with protocol-specific rules
111+
- Optional backup configuration
112+
- Optional IAM roles and policies
113+
- Network interfaces in specified subnets
114+
115+
### Tips and Recommendations
116+
117+
- The module focuses on provisioning FSx file systems with security best practices. The convention-based approach enables downstream services to easily attach to the file systems.
118+
- Use `skip_final_backup = true` in `backup_configuration` to prevent backup creation during destruction
119+
- Configure security groups appropriately for your FSx type (SMB/445 for Windows, NFS/2049 for ONTAP/OpenZFS)
120+
- For Lustre with S3, ensure proper IAM permissions for data repository access
121+
- Consider Multi-AZ deployment for production Windows and ONTAP file systems
122+
123+
## Troubleshooting
124+
125+
### Common Issues
126+
127+
**Backup Creation During Destroy**: By default, FSx creates final backups when destroyed. To skip:
128+
```hcl
129+
backup_configuration = {
130+
skip_final_backup = true
131+
}
132+
```
133+
134+
**Security Group Access**: Ensure security groups allow the correct ports:
135+
- Windows: 445 (SMB), 135 (RPC), 137-139 (NetBIOS)
136+
- Lustre: 988, 1021-1023
137+
- ONTAP: 111, 635, 2049 (NFS), 445 (SMB)
138+
- OpenZFS: 111, 2049 (NFS)
139+
140+
**Active Directory Issues**: For Windows FSx, ensure:
141+
- AD is in the same VPC or connected via VPC peering/transit gateway
142+
- DNS resolution is working between FSx subnets and AD
143+
144+
### Reporting Issues
145+
146+
If you encounter a bug or issue, please report it on the [GitHub repository](https://github.com/sourcefuse/terraform-aws-arc-fsx).
147+
148+
## Security Considerations
149+
150+
### AWS VPC
151+
152+
Understand the security considerations related to FSx file systems on AWS when using this module:
153+
154+
- FSx file systems are deployed within your VPC for network isolation
155+
- Security groups control access to FSx endpoints
156+
- Network ACLs provide additional subnet-level security
157+
- Consider using VPC endpoints for S3 access with Lustre
158+
159+
### Best Practices for AWS FSx
160+
161+
Follow best practices to ensure secure FSx configurations:
162+
163+
- [AWS FSx Security Best Practices](https://docs.aws.amazon.com/fsx/latest/WindowsGuide/security.html)
164+
- Enable encryption at rest using KMS keys
165+
- Use least-privilege IAM policies
166+
- Implement proper backup and retention policies
167+
- Monitor access using CloudTrail and VPC Flow Logs
168+
- Use Multi-AZ deployments for high availability
169+
170+
## Contributing and Community Support
171+
172+
### Contributing Guidelines
173+
174+
Contribute to the module by following the guidelines outlined in the [CONTRIBUTING.md](../../CONTRIBUTING.md) file.
175+
176+
### Reporting Bugs and Issues
177+
178+
If you find a bug or issue, report it on the [GitHub repository](https://github.com/sourcefuse/terraform-aws-arc-fsx).
179+
180+
## License
181+
182+
### License Information
183+
184+
This module is licensed under the Apache 2.0 license. Refer to the [LICENSE](../../LICENSE) file for more details.
185+
186+
### Open Source Contribution
187+
188+
Contribute to open source by using and enhancing this module. Your contributions are welcome!
189+

0 commit comments

Comments
 (0)