From f93957e366457a56e7dd9a00f9fa4e0d8354e49d Mon Sep 17 00:00:00 2001
From: Chikara Takahashi <chtakahashi10@gmail.com>
Date: Tue, 30 Jan 2024 14:36:04 -0500
Subject: [PATCH] docs: continuing to add to naming and style guide

---
 docs/infrasec/terraform/naming.md      | 25 +++++++++++++++++++++++++
 docs/infrasec/terraform/style-guide.md | 19 ++++++++++++++++++-
 2 files changed, 43 insertions(+), 1 deletion(-)

diff --git a/docs/infrasec/terraform/naming.md b/docs/infrasec/terraform/naming.md
index e70e1694..7bddaf84 100644
--- a/docs/infrasec/terraform/naming.md
+++ b/docs/infrasec/terraform/naming.md
@@ -1,5 +1,30 @@
 # Naming conventions for Terraform
 
+## Resource naming
+- Always use underscores in resource names, consistent with the resource type.
+- Always use dashes in arguments, values, and places where values will be exposed to a human or read in the AWS console. This is also important because some AWS resources have restrictions on allowed characters in description values, and the error messages that these cause can be opaque.
+- Use descriptive singular nouns for resource names.
+  - Do not repeat the resource type in the resource name
+  - Within reason, do not use environment names in resource names either. Exceptions might include if you are working in one terraform directory that provisions the entirety of the AWS account and you have no choice :)
+```hcl
+#
+# Good example
+#
+resource "aws_instance" "jenkins" {
+  tags = {
+    ...
+    "environment" = "staging"
+    ...
+  }
+}
+
+#
+# Bad example
+#
+resource "aws_instance" "jenkins_ec2_instance_staging" {
+  ...
+}
+```
 Please refer to the following sheet for various naming conventions, including of terraform modules.
 
 [Infrasec Naming Conventions](../aws/naming.md)
diff --git a/docs/infrasec/terraform/style-guide.md b/docs/infrasec/terraform/style-guide.md
index 3b23147e..abe1eed9 100644
--- a/docs/infrasec/terraform/style-guide.md
+++ b/docs/infrasec/terraform/style-guide.md
@@ -23,7 +23,7 @@ where:
 
 As the complexity of the logic in `main.tf` grows, it should be broken up into smaller, well-named files.
 These subdivisions should be made along *service-based* and *purpose-based* lines:
-- A **service-based** file houses configuration for a specific AWS service. e.g. if you use SSM Parameter Store, you might have a file called `ssm.tf` that contains every parameter you provision.
+- A **service-based** file houses configuration for a specific AWS service. e.g. if you use SSM Parameter Store, you might have a file called `ssm.tf` that contains every parameter you provision. (please redact your values!)
 - A **purpose-based** file houses configuration for a set of resources that work together to serve a single purpose and whose resources are derived from multiple AWS services. e.g. when provisioning a lambda, we want to provision resources from AWS Lambda, AWS Cloudwatch Triggers, AWS IAM to name a few. These may be contained in a file that is either named `lambda.tf` or `lambda-<lambda-name-or-use>.tf`.
 
 ### Meta-Arguments
@@ -54,4 +54,21 @@ resource "aws_instance" "foo" {
     ...
   }
 }
+```
+
+Keep in mind that the use of meta-arguments is not considered best practice. If you wish to enforce any semblance of order of operations in terraform, I recommend you consider the [dependency graph](https://developer.hashicorp.com/terraform/internals/graph). More on that in the [dependency graph](!NEEDS_LINK_TO_DOCUMENT) section 
+
+### Variables
+`variables.tf` should be organized in alphabetical order (`tfsort` is a potential tool to help do this automatically). Use descriptions and type declarations. Try to name your variables with proper nouns and explicit/obvious meaning interpretations.
+```hcl
+variable "ec2_desired_count" {
+  description = "number of EC2 tasks to run ..."
+  type        = number
+  default     = 2
+}
+
+variables "image_tag" {
+  description = "the image tag to use for ..."
+  type        = string
+}
 ```
\ No newline at end of file