Adding initial draft of new module (#2)

* initial commit * remove configs * move to modules folder * move to modules folder * Move providers block to main.tf * mid clean up * Remove logic from workspace submodule * Clean up outputs and versions from workspaces module * chore: general clean-up * chore: working config and project workspaces * chore: fix file trigger for config workspace * chore: move config module to root * chore: README * chore: interim commit * Initial commit * Updating comments * Adding support for custom project folders * Updating some comments * Updating comment in modules/variables/main.tf Co-authored-by: Erik Osterman <erik@cloudposse.com> * Making a few recommended updates * Updating examples & fixing a few things * Adding new example configs & renaming fixtures * Update examples/complete/config/ue2-dev.yaml Co-authored-by: Erik Osterman <erik@cloudposse.com> * Update examples/complete/config/ue2-dev.yaml Co-authored-by: Erik Osterman <erik@cloudposse.com> * Updating README * Renaming example configs * Update examples/complete/config/gbl-root.yaml Co-authored-by: Erik Osterman <erik@cloudposse.com> * Formatting updates * Adding references to docs * More README updates * More README updates * More README updates * Updating example environment name * Making auto_apply and filename_trigger configurable via YAML config at the project level * Update examples/complete/config/ue2-testing.yaml Co-authored-by: Erik Osterman <erik@cloudposse.com> * Update README.yaml Co-authored-by: Erik Osterman <erik@cloudposse.com> * Update README.yaml Co-authored-by: Erik Osterman <erik@cloudposse.com> * Update README.yaml Co-authored-by: Erik Osterman <erik@cloudposse.com> * Update README.yaml Co-authored-by: Erik Osterman <erik@cloudposse.com> * Updating README * Update README.yaml Co-authored-by: Erik Osterman <erik@cloudposse.com> * Update README.yaml Co-authored-by: Erik Osterman <erik@cloudposse.com> * Update README.yaml Co-authored-by: Erik Osterman <erik@cloudposse.com> * Update README.yaml Co-authored-by: Erik Osterman <erik@cloudposse.com> * Update README.yaml Co-authored-by: Erik Osterman <erik@cloudposse.com> * Update README.yaml Co-authored-by: Erik Osterman <erik@cloudposse.com> * Update README.yaml Co-authored-by: Erik Osterman <erik@cloudposse.com> * Update README.yaml Co-authored-by: Erik Osterman <erik@cloudposse.com> * Documentation updates! * Fixing config example indentation * Update README.yaml Co-authored-by: Andriy Knysh <aknysh@users.noreply.github.com> * Update README.yaml Co-authored-by: Andriy Knysh <aknysh@users.noreply.github.com> * Updating example variable descriptions & defaults * Updating descriptions & Terraform format * Adding missing descriptions to project variables * Update modules/project/variables.tf Co-authored-by: Andriy Knysh <aknysh@users.noreply.github.com> * Update modules/project/variables.tf Co-authored-by: Andriy Knysh <aknysh@users.noreply.github.com> * Adding type to workspace 'name' variable * Fixing types * Updating descriptions * Additional description updates * Update variables.tf Co-authored-by: Andriy Knysh <aknysh@users.noreply.github.com> * Updating documentation and Github workflows * Fixing format Co-authored-by: Hugo Samayoa <htplbc@gmail.com> Co-authored-by: John C. Bland II <johncblandii@gmail.com> Co-authored-by: Dan Meyers <danjbh@users.noreply.github.com> Co-authored-by: Erik Osterman <erik@cloudposse.com> Co-authored-by: Andriy Knysh <aknysh@users.noreply.github.com>
cloudposse-archives · Nov 4, 2020 · c856676 · c856676
1 parent 7c90b02
commit c856676
Show file tree

Hide file tree

Showing 33 changed files with 873 additions and 148 deletions.
diff --git a/.github/workflows/auto-release.yml b/.github/workflows/auto-release.yml
@@ -3,17 +3,17 @@ name: auto-release
 on:
   push:
     branches:
-      - master
+    - master
 
 jobs:
   semver:
     runs-on: ubuntu-latest
     steps:
-      # Drafts your next Release notes as Pull Requests are merged into "master"
-      - uses: release-drafter/release-drafter@v5
-        with:
-          publish: true
-          prerelease: false
-          config-name: auto-release.yml
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    # Drafts your next Release notes as Pull Requests are merged into "master"
+    - uses: release-drafter/release-drafter@v5
+      with:
+        publish: true
+        prerelease: false
+        config-name: auto-release.yml
+      env:
+        GITHUB_TOKEN: ${{ secrets.PUBLIC_REPO_ACCESS_TOKEN }}
diff --git a/.gitignore b/.gitignore
@@ -17,3 +17,4 @@
 # Crash log files
 crash.log
 test.log
+.DS_Store
diff --git a/README.md b/README.md
diff --git a/README.yaml b/README.yaml
@@ -5,7 +5,7 @@
 #
 
 # Name of this project
-name: terraform-example-module
+name: terraform-tfe-cloud-infrastructure-automation
 
 # Logo for this project
 #logo: docs/logo.png
@@ -20,65 +20,119 @@ copyrights:
     year: "2020"
 
 # Canonical GitHub repo
-github_repo: cloudposse/terraform-example-module
+github_repo: cloudposse/terraform-tfe-cloud-infrastructure-automation
 
 # Badges to display
 badges:
   - name: "Latest Release"
-    image: "https://img.shields.io/github/release/cloudposse/terraform-example-module.svg"
-    url: "https://github.com/cloudposse/terraform-example-module/releases/latest"
+    image: "https://img.shields.io/github/release/cloudposse/terraform-tfe-cloud-infrastructure-automation.svg"
+    url: "https://github.com/cloudposse/terraform-tfe-cloud-infrastructure-automation/releases/latest"
   - name: "Slack Community"
     image: "https://slack.cloudposse.com/badge.svg"
     url: "https://slack.cloudposse.com"
   - name: "Discourse Forum"
     image: "https://img.shields.io/discourse/https/ask.sweetops.com/posts.svg"
     url: "https://ask.sweetops.com/"
 
-# List any related terraform modules that this module may be used with or that this module depends on.
 related:
-  - name: "terraform-null-label"
-    description: "Terraform module designed to generate consistent names and tags for resources. Use terraform-null-label to implement a strict naming convention."
-    url: "https://github.com/cloudposse/terraform-null-label"
+  - name: "terraform-kubernetes-tfc-cloud-agent"
+    description: "Installs the Terraform Cloud Agent on an existing Kubernetes cluster."
+    url: "https://github.com/cloudposse/terraform-kubernetes-tfc-cloud-agent"
 
 # List any resources helpful for someone to get started. For example, link to the hashicorp documentation or AWS documentation.
 references:
-  - name: "Terraform Standard Module Structure"
-    description: "HashiCorp's standard module structure is a file and directory layout we recommend for reusable modules distributed in separate repositories."
-    url: "https://www.terraform.io/docs/modules/index.html#standard-module-structure"
-  - name: "Terraform Module Requirements"
-    description: "HashiCorp's guidance on all the requirements for publishing a module. Meeting the requirements for publishing a module is extremely easy."
-    url: "https://www.terraform.io/docs/registry/modules/publish.html#requirements"
-  - name: "Terraform `random_integer` Resource"
-    description: "The resource random_integer generates random values from a given range, described by the min and max attributes of a given resource."
-    url: "https://registry.terraform.io/providers/hashicorp/random/latest/docs/resources/integer"
   - name: "Terraform Version Pinning"
     description: "The required_version setting can be used to constrain which versions of the Terraform CLI can be used with your configuration"
     url: "https://www.terraform.io/docs/configuration/terraform.html#specifying-a-required-terraform-version"
+  - name: "Terraform Cloud"
+    description: "Terraform Cloud is an application that helps teams use Terraform together."
+    url: "https://app.terraform.io/signup/account"
+  - name: "Terraform Enterprise/Cloud Documentation"
+    description: ""
+    url: "https://registry.terraform.io/providers/hashicorp/tfe/latest/docs"
 
 # Short description of this project
 description: |-
-  This is `terraform-example-module` project provides all the scaffolding for a typical well-built Cloud Posse module. It's a template repository you can
-  use when creating new repositories.
+  Terraform module to provision workspaces & configurations in Terraform Cloud via YAML configuration.
+
+  NOTE: Requires [Terraform Cloud or Terraform Enterprise](https://www.hashicorp.com/products/terraform/pricing).
 
 # Introduction to the project
 #introduction: |-
 #  This is an introduction.
 
 # How to use this module. Should be an easy example to copy and paste.
 usage: |-
-  Here's how to invoke this example module in your projects
+  Here's how to invoke this example module in your projects:
 
   ```hcl
+  provider "tfe" {
+    version  = ">= 0.21.0"
+  }
+
   module "example" {
-    source = "https://github.com/cloudposse/terraform-example-module.git?ref=master"
-    example = "Hello world!"
+    source = "https://github.com/cloudposse/terraform-tfe-cloud-infrastructure-automation.git?ref=master"
+
+    # Directory containing all YAML configurations
+    config_file_path = "config"
+    organization     = var.organization
+
+    vcs_repo = {
+      branch             = "main"
+      ingress_submodules = true
+      # We recommend exporting the `FOOBAR` environment variable instead of passing a variable
+      oauth_token_id     = var.oauth_token_id
+    }
   }
   ```
 
 # Example usage
 examples: |-
   Here is an example of using this module:
-  - [`examples/complete`](https://github.com/cloudposse/terraform-example-module/) - complete example of using this module
+  - [`examples/complete`](https://github.com/cloudposse/terraform-tfe-cloud-infrastructure-automation/) - complete example of using this module
+
+  We use YAML for the configuration files in order to separate configuration settings from business logic. It's also a portable format that can be used across multiple tools. Our convention is to name files by `$env-$stage.yaml` (e.g. `ue2-testing.yaml`), so for example an `$env` could be `ue2` (for `us-east-2`) and the `$stage` might be `testing`. Workspace names are derived from the `$env-$stage-$project`, which looks like  `ue2-testing-eks`.
+  
+  ```yaml
+  # Projects are all the top-level root modules
+  projects:
+    # Globals are exported as TF_VAR_... environment variables in every workspace
+    globals:
+      # Used to determine the name of the workspace (e.g. the 'testing' in 'ue2-testing')
+      stage: testing
+      # Used to determine the name of the workspace (e.g. the 'ue2' in 'ue2-testing')
+      environment: ue2
+
+    # The configuration file format is designed to be used across multiple tools.
+    # All terraform projects should be listed under this section.
+    terraform:
+      # List one or more Terraform projects here
+      first-project:
+        # Controls whether or not this workspace should be created
+        # NOTE: If set to 'false', you cannot reference this workspace via `triggers` in another workspace!
+        workspace_enabled: true
+        # Override the version of Terraform for this workspace (defaults to the latest in Terraform Cloud/Enterprise)
+        terraform_version: 0.13.4
+        # Controls the `auto_apply` setting within this workspace
+        auto_apply: true
+        # Optional filename trigger to match (default is *.tf)
+        filename_trigger: "*.*"
+        # Add extra 'Run Triggers' to this workspace, beyond the parent workspace, which is created by default
+        # These triggers mean this project workspace will be automatically planned if any of these workspaces are applied.
+        triggers:
+          - uw2-testing-example2
+          - gbl-root-example1
+        # Set the Terraform input variable values for this project. Complex types like maps and lists are supported.
+        vars:
+          my_input_var: "Hello world! This is a value that needs to be passed to my `first-project` Terraform project."
+      # Every project should be uniquely named and correspond to a folder in the `projects/` directory
+      second-project:
+        workspace_enabled: true
+        # Specify a custom project folder (defalts to the project name if not specified)
+        custom_project_folder: my-custom-project-folder
+        vars:
+          my_input_var: "Hello world! This is another example!"
+  ```
 
 # How to get started quickly
 #quickstart: |-
@@ -93,3 +147,5 @@ include:
 contributors:
   - name: "Erik Osterman"
     github: "osterman"
+  - name: "Dan Meyers"
+    github: "danjbh"
diff --git a/docs/terraform.md b/docs/terraform.md
@@ -3,41 +3,50 @@
 
 | Name | Version |
 |------|---------|
-| terraform | >= 0.12.0, < 0.14.0 |
-| local | ~> 1.2 |
-| random | ~> 2.2 |
+| terraform | >= 0.13.0 |
+| local | >= 1.4 |
+| random | >= 2.2 |
+| tfe | >= 0.21.0 |
 
 ## Providers
 
 | Name | Version |
 |------|---------|
-| random | ~> 2.2 |
+| tfe | >= 0.21.0 |
 
 ## Inputs
 
 | Name | Description | Type | Default | Required |
 |------|-------------|------|---------|:--------:|
 | additional\_tag\_map | Additional tags for appending to tags\_as\_list\_of\_maps. Not added to `tags`. | `map(string)` | `{}` | no |
 | attributes | Additional attributes (e.g. `1`) | `list(string)` | `[]` | no |
+| config\_auto\_apply | Controls Terraform Cloud workspace auto-apply feature | `bool` | `true` | no |
+| config\_file\_path | Relative path to YAML config files | `string` | `null` | no |
+| config\_file\_pattern | File pattern used to locate configuration files | `string` | `"*.yaml"` | no |
 | context | Single object for setting entire context at once.<br>See description of individual variables for details.<br>Leave string and numeric variables as `null` to use default value.<br>Individual variable settings (non-null) override settings in context object,<br>except for attributes, tags, and additional\_tag\_map, which are merged. | <pre>object({<br>    enabled             = bool<br>    namespace           = string<br>    environment         = string<br>    stage               = string<br>    name                = string<br>    delimiter           = string<br>    attributes          = list(string)<br>    tags                = map(string)<br>    additional_tag_map  = map(string)<br>    regex_replace_chars = string<br>    label_order         = list(string)<br>    id_length_limit     = number<br>  })</pre> | <pre>{<br>  "additional_tag_map": {},<br>  "attributes": [],<br>  "delimiter": null,<br>  "enabled": true,<br>  "environment": null,<br>  "id_length_limit": null,<br>  "label_order": [],<br>  "name": null,<br>  "namespace": null,<br>  "regex_replace_chars": null,<br>  "stage": null,<br>  "tags": {}<br>}</pre> | no |
 | delimiter | Delimiter to be used between `namespace`, `environment`, `stage`, `name` and `attributes`.<br>Defaults to `-` (hyphen). Set to `""` to use no delimiter at all. | `string` | `null` | no |
 | enabled | Set to false to prevent the module from creating any resources | `bool` | `null` | no |
 | environment | Environment, e.g. 'uw2', 'us-west-2', OR 'prod', 'staging', 'dev', 'UAT' | `string` | `null` | no |
-| example | Example variable | `string` | `"hello world"` | no |
 | id\_length\_limit | Limit `id` to this many characters.<br>Set to `0` for unlimited length.<br>Set to `null` for default, which is `0`.<br>Does not affect `id_full`. | `number` | `null` | no |
 | label\_order | The naming order of the id output and Name tag.<br>Defaults to ["namespace", "environment", "stage", "name", "attributes"].<br>You can omit any of the 5 elements, but at least one must be present. | `list(string)` | `null` | no |
 | name | Solution name, e.g. 'app' or 'jenkins' | `string` | `null` | no |
 | namespace | Namespace, which could be your organization name or abbreviation, e.g. 'eg' or 'cp' | `string` | `null` | no |
+| organization | Name of the organization. | `string` | n/a | yes |
+| projects\_path | Project directory path relative to the repository root | `string` | `"projects"` | no |
 | regex\_replace\_chars | Regex to replace chars with empty string in `namespace`, `environment`, `stage` and `name`.<br>If not set, `"/[^a-zA-Z0-9-]/"` is used to remove all characters other than hyphens, letters and digits. | `string` | `null` | no |
 | stage | Stage, e.g. 'prod', 'staging', 'dev', OR 'source', 'build', 'test', 'deploy', 'release' | `string` | `null` | no |
 | tags | Additional tags (e.g. `map('BusinessUnit','XYZ')` | `map(string)` | `{}` | no |
+| terraform\_version | The version of Terraform to use for this workspace. Defaults to the latest available version. | `string` | `null` | no |
+| tfc\_project\_path | Name of the working directory where the top-level Terraform Cloud project resides (e.g. within `projects_path`). | `string` | `"tfc"` | no |
+| top\_level\_workspace | Name of the top-level configuration workspace in Terraform Cloud | `string` | `"tfc-config"` | no |
+| vcs\_repo | The VCS repository to configure. | `map(string)` | `{}` | no |
 
 ## Outputs
 
 | Name | Description |
 |------|-------------|
-| example | Example output |
-| id | ID of the created example |
-| random | Stable random number for this example |
+| environment\_workspaces | A list of environment workspaces & their configurations. |
+| global\_workspace | Configuration information for the global workspace. |
+| project\_workspaces | A list of project workspaces & their configurations. |
 
 <!-- markdownlint-restore -->
diff --git a/examples/complete/config/gbl-root.yaml b/examples/complete/config/gbl-root.yaml
@@ -0,0 +1,11 @@
+projects:
+  globals:
+    stage: testing
+    environment: gbl
+
+  terraform:
+    example1:
+      workspace_enabled: true
+      custom_project_folder: example1-custom
+      vars:
+        my_input_var: "Hello world! This is example1!"
diff --git a/examples/complete/config/ue2-testing.yaml b/examples/complete/config/ue2-testing.yaml
@@ -0,0 +1,17 @@
+projects:
+  globals:
+    stage: testing
+    environment: ue2
+
+  terraform:
+    example2:
+      workspace_enabled: true
+      terraform_version: 0.13.4
+      auto_apply: true
+      # Optional filename trigger to match (default is *.tf)
+      filename_trigger: "*.*"
+      triggers:
+        - uw2-testing-example2
+        - gbl-root-example1
+      vars:
+        my_input_var: "Hello world! This is example2. This project uses a different version of Terraform and contains custom triggers!"
diff --git a/examples/complete/config/uw2-testing.yaml b/examples/complete/config/uw2-testing.yaml
@@ -0,0 +1,16 @@
+projects:
+  globals:
+    stage: testing
+    environment: uw2
+
+  terraform:
+    example2:
+      workspace_enabled: true
+      vars:
+        my_input_var: "Hello world! This is example1. It's disabled!"
+    example3:
+      workspace_enabled: true
+      triggers:
+        - gbl-root-example1
+      vars:
+        my_input_var: "Hello world! This is example2. This project contains a custom trigger!"
diff --git a/examples/complete/fixtures.tfvars b/examples/complete/fixtures.tfvars
@@ -0,0 +1,21 @@
+region = "us-east-2"
+
+namespace = "eg"
+
+environment = "ue2"
+
+stage = "test"
+
+name = "example"
+
+branch = "master"
+
+identifier = "void"
+
+ingress_submodules = true
+
+oauth_token_id = "abc123"
+
+organization = "cpco-test-automation"
+
+tfe_hostname = "app.terraform.io"
diff --git a/examples/complete/fixtures.us-east-2.tfvars b/examples/complete/fixtures.us-east-2.tfvars
diff --git a/examples/complete/main.tf b/examples/complete/main.tf
@@ -1,7 +1,20 @@
+# Configure the Terraform Enterprise Provider
+provider "tfe" {
+  hostname = var.tfe_hostname
+  token    = var.tfe_token
+  version  = ">= 0.21.0"
+}
+
 module "example" {
-  source = "../.."
+  source = "../../"
 
-  example = var.example
+  config_file_path = "config"
+  organization     = var.organization
 
-  context = module.this.context
+  vcs_repo = {
+    branch             = var.branch
+    identifier         = var.identifier
+    ingress_submodules = var.ingress_submodules
+    oauth_token_id     = var.oauth_token_id
+  }
 }
diff --git a/examples/complete/outputs.tf b/examples/complete/outputs.tf
@@ -1,14 +1,5 @@
-output "id" {
-  description = "ID of the created example"
-  value       = module.example.id
-}
-
 output "example" {
-  description = "Output \"example\" from example module"
-  value       = module.example.example
+  description = "Outputs for the example module"
+  value       = module.example
 }
 
-output "random" {
-  description = "Output \"random\" from example module"
-  value       = module.example.random
-}
diff --git a/examples/complete/projects/example1/main.tf b/examples/complete/projects/example1/main.tf
@@ -0,0 +1,8 @@
+variable "my_input_var" {
+  type    = string
+  default = ""
+}
+
+output "dummy_output" {
+  value = var.my_input_var
+}
diff --git a/examples/complete/projects/example2/main.tf b/examples/complete/projects/example2/main.tf
@@ -0,0 +1,8 @@
+variable "my_input_var" {
+  type    = string
+  default = ""
+}
+
+output "dummy_output" {
+  value = var.my_input_var
+}
diff --git a/examples/complete/projects/example3/main.tf b/examples/complete/projects/example3/main.tf
@@ -0,0 +1,8 @@
+variable "my_input_var" {
+  type    = string
+  default = ""
+}
+
+output "dummy_output" {
+  value = var.my_input_var
+}