WIP: tutorial up to task 5 -- input vars

README.md

@@ -3,7 +3,7 @@
 Lab with Terraform and any Cloud
 
 Lab template for a Cloud provisioning/orchestration exercise with Terraform
-(TF) and AWS. Originally written by Marcel Graf (HEIG-VD).
+(TF) and AWS.
 
 ## Pedagogical objectives ##
 
@@ -25,6 +25,13 @@ conventions about the *command line prompt*:
   * `lcl`: your local machine
   * `ins`: your VM instance
 
+TF CLI commands' output follow a diff-style convention of prefixing lines with
+special marks to explain what is (or would be) going on:
+  * `+`: something is added
+  * `-`: something is removed/destroyed
+  * `-/+`: a resource is destroyed and recreated
+  * `~`: something is modified in place
+
 
 ### Task #1: install Terraform CLI and AWS CLI ###
 
@@ -116,7 +123,6 @@ that Terraform can guarantee to make the same selections by default when you run
 Terraform has been successfully initialized!
 ...
 ```
-Take note of what the file` .terraform.lock.hcl` is used for.
 
 Have a look inside the newly created sub-directory
 `~/terraform/AWS/.terraform/`, you'll find the required `aws` provider module
@@ -312,5 +318,116 @@ lcl$ terraform show | grep instance_state
     instance_state                       = "running"
 ```
 
-Modify the resource's `ami` in `main.tf` (here we use the second one found
-from the [catalog query done above](#AMI-query))
+Replace the resource's `ami` in `main.tf` with the second one found from the
+[catalog query done above](#AMI-query) (or another one available with your
+account). Before applying our new plan, let's see what TF thinks of it:
+
+``` shell
+lcl$ terraform plan -out=change-AMI.tfplan
+aws_instance.app_server: Refreshing state... [id=i-0155ba9d77ee0a854]
+
+Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
+-/+ destroy and then create replacement
+
+Terraform will perform the following actions:
+
+  # aws_instance.app_server must be replaced
+-/+ resource "aws_instance" "app_server" {
+      ~ ami                                  = "ami-0fa37863afb290840" -> "ami-0e2512bd9da751ea8" # forces replacement
+
+...
+
+Plan: 1 to add, 0 to change, 1 to destroy.
+
+Saved the plan to: change-AMI.tfplan
+
+To perform exactly these actions, run the following command to apply:
+    terraform apply "change-AMI.tfplan"
+```
+
+:bulb: Remarks:
+  * The change we want to apply is destructive!
+  * We saved our plan. :question: Why? It is not really necessary in a simple
+    scenario like ours, however a more complex IaC workflow might require plan
+    artifacts to be programmatically validated and versioned.
+
+Apply the saved plan:
+``` shell
+lcl$ terraform apply change-AMI.tfplan
+aws_instance.app_server: Destroying... [id=i-0155ba9d77ee0a854]
+...
+aws_instance.app_server: Destruction complete after 33s
+aws_instance.app_server: Creating...
+...
+aws_instance.app_server: Creation complete after 48s [id=i-0470db35749548101]
+```
+
+:bulb: What? Not asking for confirmation? Indeed, a saved plan is intended for
+automated workflows! Moreover, a saved plan will come handy for rolling back a
+broken infrastructure to the last working setup.
+
+:question: What if we did not save our plan, and called a plain apply command?
+Would the result be the same?
+
+
+### Task #5: input variables ###
+
+**Goal:** make a TF plan more flexible via input variables.
+
+Our original plan has all its content hard-coded. Let's make it more flexible
+with some input variables stored in a separate `variables.tf` file inside your
+TF sandbox:
+
+``` hcl
+variable "instance_name" {
+  description = "Value of the Name tag for the EC2 instance"
+  type        = string
+  default     = "AnotherAppServerInstance"
+}
+```
+
+Then modify the `main.tf` as follows:
+
+``` hcl
+resource "aws_instance" "app_server" {
+  ami           = "ami-0e2512bd9da751ea8"
+  instance_type = "t2.micro"
+
+  tags = {
+-   Name = "ExampleAppServerInstance"
++   Name = var.instance_name
+  }
+}
+```
+
+Apply the change:
+``` shell
+lcl$ terraform apply -auto-approve
+aws_instance.app_server: Refreshing state... [id=i-0470db35749548101]
+...
+
+  ~ update in-place
+
+Terraform will perform the following actions:
+
+  # aws_instance.app_server will be updated in-place
+  ~ resource "aws_instance" "app_server" {
+        id                                   = "i-0470db35749548101"
+      ~ tags                                 = {
+          ~ "Name" = "ExampleAppServerInstance" -> "AnotherAppServerInstance"
+        }
+      ~ tags_all                             = {
+          ~ "Name" = "ExampleAppServerInstance" -> "AnotherAppServerInstance"
+        }
+...
+    }
+
+Plan: 0 to add, 1 to change, 0 to destroy.
+...
+Apply complete! Resources: 0 added, 1 changed, 0 destroyed.
+```
+
+:bulb: Input variables can also be passed on the `apply` command line. **As an
+exercise**, find how to do that with another different value for
+`instance_name`. :question: Would that last change be persistent if we rerun a
+plain `terraform apply`?