|
| 1 | +--- |
| 2 | +description: 'Terraform Conventions and Guidelines' |
| 3 | +applyTo: '**/*.tf' |
| 4 | +--- |
| 5 | + |
| 6 | +# Terraform Conventions |
| 7 | + |
| 8 | +## General Instructions |
| 9 | + |
| 10 | +- Use Terraform to provision and manage infrastructure. |
| 11 | +- Use version control for your Terraform configurations. |
| 12 | + |
| 13 | +## Security |
| 14 | + |
| 15 | +- Always use the latest stable version of Terraform and its providers. |
| 16 | + - Regularly update your Terraform configurations to incorporate security patches and improvements. |
| 17 | +- Store sensitive information in a secure manner, such as using AWS Secrets Manager or SSM Parameter Store. |
| 18 | + - Regularly rotate credentials and secrets. |
| 19 | + - Automate the rotation of secrets, where possible. |
| 20 | +- Use AWS environment variables to reference values stored in AWS Secrets Manager or SSM Parameter Store. |
| 21 | + - This keeps sensitive values out of your Terraform state files. |
| 22 | +- Never commit sensitive information such as AWS credentials, API keys, passwords, certificates, or Terraform state to version control. |
| 23 | + - Use `.gitignore` to exclude files containing sensitive information from version control. |
| 24 | +- Always mark sensitive variables as `sensitive = true` in your Terraform configurations. |
| 25 | + - This prevents sensitive values from being displayed in the Terraform plan or apply output. |
| 26 | +- Use IAM roles and policies to control access to resources. |
| 27 | + - Follow the principle of least privilege when assigning permissions. |
| 28 | +- Use security groups and network ACLs to control network access to resources. |
| 29 | +- Deploy resources in private subnets whenever possible. |
| 30 | + - Use public subnets only for resources that require direct internet access, such as load balancers or NAT gateways. |
| 31 | +- Use encryption for sensitive data at rest and in transit. |
| 32 | + - Enable encryption for EBS volumes, S3 buckets, and RDS instances. |
| 33 | + - Use TLS for communication between services. |
| 34 | +- Regularly review and audit your Terraform configurations for security vulnerabilities. |
| 35 | + - Use tools like `trivy`, `tfsec`, or `checkov` to scan your Terraform configurations for security issues. |
| 36 | + |
| 37 | +## Modularity |
| 38 | + |
| 39 | +- Use separate projects for each major component of the infrastructure; this: |
| 40 | + - Reduces complexity |
| 41 | + - Makes it easier to manage and maintain configurations |
| 42 | + - Speeds up `plan` and `apply` operations |
| 43 | + - Allows for independent development and deployment of components |
| 44 | + - Reduces the risk of accidental changes to unrelated resources |
| 45 | +- Use modules to avoid duplication of configurations. |
| 46 | + - Use modules to encapsulate related resources and configurations. |
| 47 | + - Use modules to simplify complex configurations and improve readability. |
| 48 | + - Avoid circular dependencies between modules. |
| 49 | + - Avoid unnecessary layers of abstraction; use modules only when they add value. |
| 50 | + - Avoid using modules for single resources; only use them for groups of related resources. |
| 51 | + - Avoid excessive nesting of modules; keep the module hierarchy shallow. |
| 52 | +- Use `output` blocks to expose important information about your infrastructure. |
| 53 | + - Use outputs to provide information that is useful for other modules or for users of the configuration. |
| 54 | + - Avoid exposing sensitive information in outputs; mark outputs as `sensitive = true` if they contain sensitive data. |
| 55 | + |
| 56 | +## Maintainability |
| 57 | + |
| 58 | +- Prioritize readability, clarity, and maintainability. |
| 59 | +- Use comments to explain complex configurations and why certain design decisions were made. |
| 60 | +- Write concise, efficient, and idiomatic configs that are easy to understand. |
| 61 | +- Avoid using hard-coded values; use variables for configuration instead. |
| 62 | + - Set default values for variables, where appropriate. |
| 63 | +- Use data sources to retrieve information about existing resources instead of requiring manual configuration. |
| 64 | + - This reduces the risk of errors, ensures that configurations are always up-to-date, and allows configurations to adapt to different environments. |
| 65 | + - Avoid using data sources for resources that are created within the same configuration; use outputs instead. |
| 66 | + - Avoid, or remove, unnecessary data sources; they slow down `plan` and `apply` operations. |
| 67 | +- Use `locals` for values that are used multiple times to ensure consistency. |
| 68 | + |
| 69 | +## Style and Formatting |
| 70 | + |
| 71 | +- Follow Terraform best practices for resource naming and organization. |
| 72 | + - Use descriptive names for resources, variables, and outputs. |
| 73 | + - Use consistent naming conventions across all configurations. |
| 74 | +- Follow the **Terraform Style Guide** for formatting. |
| 75 | + - Use consistent indentation (2 spaces for each level). |
| 76 | +- Group related resources together in the same file. |
| 77 | + - Use a consistent naming convention for resource groups (e.g., `providers.tf`, `variables.tf`, `network.tf`, `ecs.tf`, `mariadb.tf`). |
| 78 | +- Place `depends_on` blocks at the very beginning of resource definitions to make dependency relationships clear. |
| 79 | + - Use `depends_on` only when necessary to avoid circular dependencies. |
| 80 | +- Place `for_each` and `count` blocks at the beginning of resource definitions to clarify the resource's instantiation logic. |
| 81 | + - Use `for_each` for collections and `count` for numeric iterations. |
| 82 | + - Place them after `depends_on` blocks, if they are present. |
| 83 | +- Place `lifecycle` blocks at the end of resource definitions. |
| 84 | +- Alphabetize providers, variables, data sources, resources, and outputs within each file for easier navigation. |
| 85 | +- Group related attributes together within blocks. |
| 86 | + - Place required attributes before optional ones, and comment each section accordingly. |
| 87 | + - Separate attribute sections with blank lines to improve readability. |
| 88 | + - Alphabetize attributes within each section for easier navigation. |
| 89 | +- Use blank lines to separate logical sections of your configurations. |
| 90 | +- Use `terraform fmt` to format your configurations automatically. |
| 91 | +- Use `terraform validate` to check for syntax errors and ensure configurations are valid. |
| 92 | +- Use `tflint` to check for style violations and ensure configurations follow best practices. |
| 93 | + - Run `tflint` regularly to catch style issues early in the development process. |
| 94 | + |
| 95 | +## Documentation |
| 96 | + |
| 97 | +- Always include `description` and `type` attributes for variables and outputs. |
| 98 | + - Use clear and concise descriptions to explain the purpose of each variable and output. |
| 99 | + - Use appropriate types for variables (e.g., `string`, `number`, `bool`, `list`, `map`). |
| 100 | +- Document your Terraform configurations using comments, where appropriate. |
| 101 | + - Use comments to explain the purpose of resources and variables. |
| 102 | + - Use comments to explain complex configurations or decisions. |
| 103 | + - Avoid redundant comments; comments should add value and clarity. |
| 104 | +- Include a `README.md` file in each project to provide an overview of the project and its structure. |
| 105 | + - Include instructions for setting up and using the configurations. |
| 106 | +- Use `terraform-docs` to generate documentation for your configurations automatically. |
| 107 | + |
| 108 | +## Testing |
| 109 | + |
| 110 | +- Write tests to validate the functionality of your Terraform configurations. |
| 111 | + - Use the `.tftest.hcl` extension for test files. |
| 112 | + - Write tests to cover both positive and negative scenarios. |
| 113 | + - Ensure tests are idempotent and can be run multiple times without side effects. |
0 commit comments