Configure OIDC

.github/workflows/deploy.yml

@@ -17,7 +17,7 @@ jobs:
           fetch-depth: 0
       - uses: taiki-e/install-action@v2
         with:
-          tool: [email protected],[email protected],[email protected]
+          tool: [email protected],[email protected],[email protected],[email protected]
       - name: Build Book
         run: |
           mdbook build

book.toml

@@ -11,7 +11,11 @@ title = "Terraform Cloud Path to Production Guide"
 command = "mdbook-admonish"
 assets_version = "2.0.2" # do not edit: managed by `mdbook-admonish install`
 
+[preprocessor.mermaid]
+command = "mdbook-mermaid"
+
 [output]
 
 [output.html]
 additional-css = ["./mdbook-admonish.css"]
+additional-js = ["mermaid.min.js", "mermaid-init.js"]

mermaid-init.js

@@ -0,0 +1 @@
+mermaid.initialize({startOnLoad:true});

src/SUMMARY.md

@@ -7,3 +7,8 @@
   - [Create Terraform Cloud Resources](tfcloud-setup/tfcloud-resources.md)
   - [Migrate Local State to Terraform Cloud](tfcloud-setup/tfcloud-state-migration.md)
   - [VCS Workflow Integration](tfcloud-setup/vcs-workflow-integration.md)
+- [Initial Pipeline](initial-pipeline/README.md)
+  - [Create common variables for AWS Projects](initial-pipeline/create-common-variables-for-aws-projects.md)
+  - [Create a Module for Managing Terraform Cloud Workspaces](initial-pipeline/create-a-module-for-managing-terraform-cloud-aws-based-workspaces.md)
+  - [Create GitHub Repo and Terraform Cloud Project](initial-pipeline/create-github-repo-and-terraform-cloud-project.md)
+  - [Configure OIDC Provider](initial-pipeline/create-oidc-provider.md)

src/initial-pipeline/README.md

@@ -0,0 +1,16 @@
+# Initial Pipeline
+
+This chapter will help you to configure a simple path to production pipeline in Terraform Cloud. The pipeline will deploy the following environments:
+
+```mermaid
+graph LR;
+Pre-Dev-->Dev;
+Dev-->Test;
+Test-->Prod;
+```
+
+By the end of this chapter you will have:
+
+* A GitHub repository containing Terraform code to manage an AWS VPC and some subnets.
+* A Terraform Cloud project and several workspaces linked to the above GitHub repository; each workspace will control each of the above path to production stages
+* OIDC authentication configured so that Terraform Cloud uses temporary credentials for interacting with AWS APIs

src/initial-pipeline/create-a-module-for-managing-terraform-cloud-aws-based-workspaces.md

@@ -0,0 +1,31 @@
+# Create a Module for Managing Terraform Cloud AWS-based Workspaces
+
+As we'll be creating a number of Terraform Cloud workspaces in this section, it makes sense to create a [Terraform module](https://developer.hashicorp.com/terraform/language/modules) to ensure those workspaces are created in a consistent manner. Our module will follow the [standard module structure](https://developer.hashicorp.com/terraform/language/modules/develop/structure), which defines the layout of modules and their position in the filesystem relative to other code.
+
+To start with, we'll need to declare a number of variables that will be passed to the module. Copy and paste the following into `modules/tfcloud_aws_workspace/variables.tf`:
+
+```hcl
+{{#include terraform/modules/tfcloud_aws_workspace/variables.tf}}
+```
+
+Next, we'll have the module manage some Terraform Cloud resources. Copy and paste the following into `modules/tfcloud_aws_workspace/main.tf`:
+
+```hcl
+{{#include terraform/modules/tfcloud_aws_workspace/main.tf}}
+```
+
+As you can see, the module is relatively simple; it simply creates a Terraform Cloud Workspace and some workspace-specific variables. As this guide is opinionated, we know that we'll be asking Terraform Cloud to create resources in an AWS account and we'd like it to use an OIDC provider in order to avoid using static authentication credentials. The workspace-specific variables help support that authentication flow:
+
+* `region` - as we've configured our workspaces to be region-specific, as per Hashicorp's [examples](https://developer.hashicorp.com/terraform/cloud-docs/workspaces/creating#workspace-naming), and the AWS provider needs to know what region to operate in, we store this as a Terraform variable.
+
+* `TFC_AWS_PLAN_ROLE_ARN` and `TFC_AWS_APPLY_ROLE_ARN` environment variables. These are part of the OIDC authentication flow; Terraform Cloud will assume these roles when running plan and apply operations respectively. We will create these roles shortly.
+
+The OIDC setup is described in detail in [Terraform Cloud's documentation](https://developer.hashicorp.com/terraform/cloud-docs/workspaces/dynamic-provider-credentials/aws-configuration).
+
+Finally, we'll want to output the workspaces that the module creates as these will be used when configuring GitHub Pull Request checks a little later on. Copy and paste the following into `modules/tfcloud_aws_workspace/outputs.tf`:
+
+```hcl
+{{#include terraform/modules/tfcloud_aws_workspace/outputs.tf}}
+```
+
+With the module in place, the next section will make use of it to actually create our example pipeline.

src/initial-pipeline/create-common-variables-for-aws-projects.md

@@ -0,0 +1,13 @@
+# Create Common Variables for AWS Projects
+
+In order for Terraform Cloud to be able to authenticate with AWS using short-lived credentials, we need to configure an OIDC connection. As all AWS projects will use this same authentication method, it makes sense to make the necessary information available via a shared variable set. Copy and paste the following into `aws_common_variables.tf`:
+
+```hcl
+{{#include terraform/aws_common_variables.tf}}
+```
+
+```admonish
+* The values given to the various `oidc_*` locals are the defaults required if using Terraform Cloud; they only need to be changed if you have a local installation of Terraform Enterprise.
+
+* AWS has good documentation on [obtaining the thumbprint for an OIDC provider](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc_verify-thumbprint.html).
+```

src/initial-pipeline/create-github-repo-and-terraform-cloud-project.md

@@ -0,0 +1,20 @@
+# Create GitHub Repo and Terraform Cloud Project
+
+Copy and paste the following into a new file, `tfcloud_pipeline_project.tf` in the `tfcloud-mgmt` repo.
+
+```hcl
+{{#include terraform/tfcloud_pipeline_project.tf}}
+```
+
+Adjust the `aws_account_id` values to match your AWS account setup. Whilst the pre-requisites only strictly need us to have a single AWS account, it's strongly recommended to maintain separate accounts for your different path to production environments. AWS has some [guidance](https://docs.aws.amazon.com/whitepapers/latest/organizing-your-aws-environment/core-concepts.html) on this topic if you wish to explore it further but the main reasons for account separation are:
+
+* Minimises the "blast radius" of changes; if your production account is the only one that contains production resources, then a change to your dev account can't possibly affect your production service.
+* Some AWS services, most notably IAM and Route53 are global in nature. For example, a change to an IAM role in an account shared between environments will affect all environments at the same time.
+
+One option to avoid some of the IAM-related problems that can arise from having a shared account is to prefix or suffix the role name such that unique roles are created in each workspace. This is alluded to above, and more clearly shown in the next section when we create the roles necessary for OIDC authentication.
+
+The code above creates 4 workspaces, each one representing a separate stage in the path to production.
+
+Commit and push your changes to a branch, and raise a PR. The resulting Terraform Cloud plan should show 35 resources will be created. Go ahead and merge the PR, then apply the changes.
+
+If you take a look at the new `tfcloud-pipeline` project in the Terraform Cloud UI, you'll see that it has the expected 4 workspaces configured and that each of them had a plan triggered by the initial commit to the new `tfcloud-pipeline` GitHub repo. Again, as expected at this stage, all of those runs failed due to a lack of Terraform code in the repository. The next section will bootstrap the OIDC authentication between Terraform Cloud and your AWS account so that Terraform Cloud can plan and apply changes successfully.