Fix up a number of issues in chapter 1

src/tfcloud-setup/pre-requisites.md

@@ -86,14 +86,6 @@ echo 'github_admin_token = "github_pat_*****..."' >> credentials.auto.tfvars
 The GitHub PAT above has **very** high privileges across **all** repositories. As such, it is crucial that this PAT isn't leaked or re-used for other purposes.
 ```
 
-## Terraform Cloud and GitHub Related Settings
-
-Copy and paste the following into a new file, `locals.tf`, and adjust the values to match your desired Terraform Cloud and GitHub organization names:
-
-```hcl
-{{#include terraform/locals.tf}}
-```
-
 ## AWS Credentials
 
 Follow [AWS' instructions](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) for creating an access key for your own IAM user account. We will only need these to bootstrap connectivity between Terraform Cloud and AWS; after that then we'll use an IAM role to provide temporary security credentials.

src/tfcloud-setup/terraform-local.md

@@ -2,16 +2,26 @@
 
 At this early stage, all we want to do is ensure that `terraform`, when run locally, can initialize itself and run successfully but not manage any resources.
 
+Copy and paste the following Terraform code into a new file, `variables.tf`, which declares the input variables we set up earlier in `credentials.auto.tfvars`
+
+```hcl
+{{#include terraform/variables.tf}}
+```
+
 Copy and paste the following Terraform code into a new file, `terraform.tf`, which will configure the [Terraform Enterprise provider](https://github.com/hashicorp/terraform-provider-tfe), [AWS provider](https://github.com/hashicorp/terraform-provider-aws), and [GitHub provider](https://github.com/integrations/terraform-provider-github). Terraform will use local state files to keep track of any resources that it is managing.
 
 ```hcl
 {{#include terraform/terraform.tf}}
 ```
 
-Copy and paste the following Terraform code into a new file, `variables.tf`, which declares the input variables we set up earlier in `credentials.auto.tfvars`
+```admonish
+The format of the `required_version` argument ensures that only versions of Terraform that match the specified major and minor versions can be used to manage our resources. Terraform Cloud defaults to using the latest version of Terraform for all plan and apply operations, but major releases can contain breaking changes so by pinning the version we can avoid upstream releases breaking our pipelines.
+```
+
+Copy and paste the following into a new file, `locals.tf`, and adjust the values to match your desired Terraform Cloud and GitHub organization names:
 
 ```hcl
-{{#include terraform/variables.tf}}
+{{#include terraform/locals.tf}}
 ```
 
 Initialize Terraform:
@@ -22,15 +32,12 @@ $ terraform init
 Initializing the backend...
 
 Initializing provider plugins...
-- Finding hashicorp/aws versions matching "~> 5.19.0"...
-- Finding hashicorp/tfe versions matching "~> 0.48.0"...
-- Finding integrations/github versions matching "~> 5.38.0"...
-- Installing hashicorp/aws v5.19.0...
-- Installed hashicorp/aws v5.19.0 (signed by HashiCorp)
-- Installing hashicorp/tfe v0.48.0...
-- Installed hashicorp/tfe v0.48.0 (signed by HashiCorp)
-- Installing integrations/github v5.38.0...
-- Installed integrations/github v5.38.0 (signed by a HashiCorp partner, key ID 38027F80D7FD5FB2)
+- Finding integrations/github versions matching "~> 5.39.0"...
+- Finding hashicorp/tfe versions matching "~> 0.49.2"...
+- Installing integrations/github v5.39.0...
+- Installed integrations/github v5.39.0 (signed by a HashiCorp partner, key ID 38027F80D7FD5FB2)
+- Installing hashicorp/tfe v0.49.2...
+- Installed hashicorp/tfe v0.49.2 (signed by HashiCorp)
 
 Partner and community providers are signed by their developers.
 If you'd like to know more about provider signing, you can read about it here:
@@ -42,6 +49,14 @@ so that Terraform can guarantee to make the same selections by default when
 you run "terraform init" in the future.
 
 Terraform has been successfully initialized!
+
+You may now begin working with Terraform. Try running "terraform plan" to see
+any changes that are required for your infrastructure. All Terraform commands
+should now work.
+
+If you ever set or change modules or backend configuration for Terraform,
+rerun this command to reinitialize your working directory. If you forget, other
+commands will detect it and remind you to do so if necessary.
 ```
 
 At this point, a `terraform plan` should succeed but show no resources need to change, somewhat obviously due to us not having asked it to manage any just yet:

src/tfcloud-setup/terraform/terraform.tf

@@ -2,17 +2,15 @@ terraform {
   required_providers {
     tfe = {
       source  = "hashicorp/tfe"
-      version = "~> 0.48.0"
+      version = "~> 0.49.2"
     }
     github = {
       source  = "integrations/github"
-      version = "~> 5.38.0"
-    }
-    aws = {
-      source  = "hashicorp/aws"
-      version = "~> 5.19.0"
+      version = "~> 5.39.0"
     }
   }
+
+  required_version = "~> 1.6.0"
 }
 
 provider "tfe" {
@@ -22,7 +20,3 @@ provider "tfe" {
 provider "github" {
   token = var.github_admin_token
 }
-
-provider "aws" {
-  region = "us-east-1"
-}

src/tfcloud-setup/terraform/tfcloud_mgmt_project.tf

@@ -1,5 +1,9 @@
+locals {
+  tfcloud_mgmt_project_name = "tfcloud-mgmt"
+}
+
 resource "github_repository" "tfcloud_mgmt" {
-  name               = "tfcloud-mgmt"
+  name               = local.tfcloud_mgmt_project_name
   auto_init          = true
   gitignore_template = "Terraform"
   license_template   = "mit"
@@ -29,16 +33,17 @@ resource "github_branch_protection" "tfcloud_mgmt" {
 
 resource "tfe_project" "tfcloud_mgmt" {
   organization = tfe_organization.example.id
-  name         = "tfcloud-mgmt"
+  name         = local.tfcloud_mgmt_project_name
 }
 
 resource "tfe_workspace" "tfcloud_mgmt_prod" {
-  name         = "tfcloud-mgmt-prod"
-  organization = tfe_organization.example.id
-  project_id   = tfe_project.tfcloud_mgmt.id
+  name              = "${local.tfcloud_mgmt_project_name}-prod"
+  organization      = tfe_organization.example.id
+  project_id        = tfe_project.tfcloud_mgmt.id
+  terraform_version = "~> 1.6.0"
 
   tag_names = [
-    "tfcloud-mgmt",
+    local.tfcloud_mgmt_project_name,
     "prod"
   ]
 

src/tfcloud-setup/terraform/tfcloud_variables.tf

@@ -1,4 +1,3 @@
-
 resource "tfe_variable_set" "tfcloud_common_credentials" {
   organization = tfe_organization.example.id
   name         = "tfcloud-common-credentials"

src/tfcloud-setup/tfcloud-resources.md

@@ -2,7 +2,7 @@
 
 We'd like Terraform to deploy the Terraform Cloud organization, a project within that organization, and a workspace within that project. Further, by linking the GitHub repository with the workspace, we can demonstrate Terraform Cloud's ability to automatically plan and apply changes made by commits to that repository.
 
-To start with, copy and paste the following into `organization.tf` to create the Terraform Cloud Organization, replacing the placeholder values with ones that will work for you. This will also create an OAuth client so that Terraform can watch for and react to commits to GitHub repositories.
+To start with, copy and paste the following into `main.tf` to create the Terraform Cloud Organization and an OAuth client so that Terraform Cloud can watch for and react to commits to GitHub repositories.
 
 ```hcl
 {{#include terraform/main.tf}}
@@ -32,4 +32,8 @@ Apply complete! Resources: 14 added, 0 changed, 0 destroyed.
 
 Congratulations! You now have a Terraform Cloud organization, project and workspace configured. You also have a GitHub repository that is linked up to that workspace.
 
+```admonish
+Because we initialized a new GitHub repository and then immediately created a workspace linked to it, if you visit the Terraform Cloud UI then you'll notice that a `terraform plan` has already been triggered and failed because there's no Terraform code in that repository yet. We'll sort that out in just a moment.
+```
+
 Notice that in your current working directory there is a file called `terraform.tfstate` which holds the state of your Terraform Cloud configuration as far as your local `terraform` considers it. Alas, Terraform Cloud itself knows nothing of this state of affairs. Next we'll perform a state migration which is how we get your local copy of the state into Terraform Cloud.