|
| 1 | +## Terraform Modules Developer Guidelines |
| 2 | + |
| 3 | +### Installation |
| 4 | +It is recommended to use tfenv or tfswitch. This makes managing and switching between Terraform versions quick and easy. |
| 5 | + |
| 6 | +***TFenv*** |
| 7 | + |
| 8 | +```brew install tfenv``` |
| 9 | +To get up and running with TFenv refer to the Usage section of the README |
| 10 | + |
| 11 | +***TFSwitch*** |
| 12 | + |
| 13 | +```brew install warrensbox/tap/tfswitch``` |
| 14 | +To get up and running with TFSwitch refer to the documentation |
| 15 | + |
| 16 | +***Indentation*** |
| 17 | + |
| 18 | +Use two spaces, no tabs. |
| 19 | + |
| 20 | +```hcl |
| 21 | +resource "aws_instance" "example" { |
| 22 | + ami = "abc123" |
| 23 | +
|
| 24 | + network_interface { |
| 25 | + # ... |
| 26 | + } |
| 27 | +} |
| 28 | +``` |
| 29 | + |
| 30 | +***Comments*** |
| 31 | + |
| 32 | +Our best practice is to add a comment for every resource declared. This comment should explain what the resource is doing and how it interconnects with other resources. Hashicorp recommends using # for single-line comments. |
| 33 | + |
| 34 | +Here is an example of a resource with its comment: |
| 35 | + |
| 36 | +```hcl |
| 37 | +# Create the Lacework application within Azure Active Directory to grant |
| 38 | +# access to Azure Storage, Azure Key Vault, AAD Graph API, and Microsoft Graph |
| 39 | +resource "azuread_application" "default" { |
| 40 | + ... |
| 41 | +} |
| 42 | +``` |
| 43 | + |
| 44 | + |
| 45 | +***Input Variables*** |
| 46 | + |
| 47 | +Always document user-facing variables, even if your variable names are self-descriptive like api_key or account, they could be easily misinterpreted. Always add a description field with a brief explanation. |
| 48 | + |
| 49 | +A couple of examples: |
| 50 | + |
| 51 | + |
| 52 | +```hcl |
| 53 | +variable "account" { |
| 54 | + type = string |
| 55 | + description = "Lacework account subdomain of URL (i.e. <ACCOUNT>.lacework.net)" |
| 56 | +} |
| 57 | +``` |
| 58 | + |
| 59 | +```hcl |
| 60 | +variable "api_key" { |
| 61 | + type = string |
| 62 | + description = "A Lacework API access key" |
| 63 | +} |
| 64 | +``` |
| 65 | +Additionally, any required variables like api keys, or required tagging should not have default values, and should require the user to input those either manually each run, or optimally using a terraform.tfvars file |
| 66 | + |
| 67 | +***Recommended Project File Organization*** |
| 68 | + |
| 69 | +A few best practices for organizing Terraform projects: |
| 70 | + |
| 71 | +* `main.tf` - Store the main structure of your terraform code in this file |
| 72 | +* `variables.tf` - All variables for your project |
| 73 | +* `output.tf` - All outputs in this file |
| 74 | +* `tfvars.example` - An example terraform.tfvars file for easy cp for users (note: *.tfvars are typically |
| 75 | +ignored by .gitignore |
| 76 | +* `.gitignore` - Critical to ensure that any sensitive information used in tfvars are not checked in to git |
| 77 | + |
| 78 | + |
| 79 | +***Version Support / Documentation*** |
| 80 | + |
| 81 | +Hashicorp release frequent patch and minor updates as needed, as well as new major releases of Terraform each year. Although Hashicorp provide solid documentation on how to upgrade between major releases of Terraform, Lacework must contend with the fact that Lacework customers do not all upgrade in a timely manor. For this reason Tech Alliances Team must continue to update documentation with supported versions of Terraform, as well as update CI pipelines to test changes across each supported version. |
| 82 | + |
| 83 | +***Standard Versioning for Code Snippets*** |
| 84 | +All customer facing code snippets should adhere to the standard of using pessimistic version constraint to minor releases. |
| 85 | + |
| 86 | +```hcl |
| 87 | +module "aws_config" { |
| 88 | + source = "lacework/config/aws" |
| 89 | + version = "~> 0.1" |
| 90 | +} |
| 91 | +``` |
| 92 | +```hcl |
| 93 | +module "aws_cloudtrail" { |
| 94 | + source = "lacework/cloudtrail/aws" |
| 95 | + version = "~> 0.1" |
| 96 | +
|
| 97 | + bucket_force_destroy = true |
| 98 | + use_existing_iam_role = true |
| 99 | + iam_role_name = module.aws_config.iam_role_name |
| 100 | + iam_role_arn = module.aws_config.iam_role_arn |
| 101 | + iam_role_external_id = module.aws_config.external_id |
| 102 | +} |
| 103 | +``` |
| 104 | + |
| 105 | +The example above will work for version 0.1.9 as well as 0.4.0, but will not pull in any major releases such as 1.0.0. |
| 106 | + |
| 107 | +For more information visit [Semantic Versioning 2.0.0](https://semver.org/) |
| 108 | + |
| 109 | +## Commit message standard |
| 110 | + |
| 111 | +The format is: |
| 112 | + |
| 113 | +``` |
| 114 | +type(scope): subject |
| 115 | +BODY |
| 116 | +FOOTER |
| 117 | +``` |
| 118 | +Each commit message consists of a header, body, and footer. The header is mandatory, the scope is optional, the type and subject are mandatory. |
| 119 | +When writing a commit message try and limit each line of the commit to a max of 100 hundred characters, so it can be read easily. |
| 120 | + |
| 121 | +### Type |
| 122 | + |
| 123 | +| Type | Description | |
| 124 | +| ----- | ----------- | |
| 125 | +| feat: | A new feature you're adding | |
| 126 | +| fix: |A bug fix| |
| 127 | +| style: | Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) | |
| 128 | +| refactor: | A code change that neither fixes a bug nor adds a feature | |
| 129 | +| test: | Everything related to testing | |
| 130 | +| docs: | Everything related to documentation | |
| 131 | +| chore: | Regular code maintenance | |
| 132 | +| build: | Changes that affect the build | |
| 133 | +| ci: | Changes to our CI configuration files and scripts | |
| 134 | +| perf: | A code change that improves performance | |
| 135 | +| metric: | A change that provides better insights about the adoption of features and code statistics | |
| 136 | + |
| 137 | +### Scope |
| 138 | +The optional scope refers to the section that this commit belongs to, for example, changing a specific component or service, a directive, pipes, etc. |
| 139 | +Think about it as an indicator that will let the developers know at first glance what section of your code you are changing. |
| 140 | + |
| 141 | +A few good examples are: |
| 142 | + |
| 143 | +feat(client): |
| 144 | +docs(cli): |
| 145 | +chore(tests): |
| 146 | +ci(directive): |
| 147 | + |
| 148 | +### Subject |
| 149 | +The subject should contain a short description of the change, and written in present-tense, for example, use “add” and not “added”, or “change” and not “changed”. |
| 150 | +I like to fill this sentence below to understand what should I put as my description of my change: |
| 151 | + |
| 152 | +If applied, this commit will ________________________________________. |
| 153 | + |
| 154 | +### Body |
| 155 | +The body should contain a longer description of the change, try not to repeat the subject and keep it in the present tense as above. |
| 156 | +Put as much context as you think it is needed, don’t be shy and explain your thought process, limitations, ideas for new features or fixes, etc. |
| 157 | + |
| 158 | +### Footer |
| 159 | +The footer is used to reference issues, pull requests or breaking changes, for example, “Fixes ticket #123”. |
| 160 | + |
| 161 | +## Signing commits |
| 162 | +Signed commits are required for any contribution to this project. Please see Github's documentation on configuring signed commits, [tell git about your signing key](https://docs.github.com/en/github/authenticating-to-github/managing-commit-signature-verification/telling-git-about-your-signing-key) and [signing commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits) |
0 commit comments