cRud resourceHouseRead()

In addition to the workflow of the Read operation, we will look into an interesting aspect of Terraform which is easy to miss out as it is not written anywhere in the code.

• TL;DR

  • To read data, we use .get() function. To update data, we use .set().

    • When performing a read operation, Terraform runs a sanity check and compares the 'state that is applied via Terraform' against the 'actual state of the resources on the Cloud' (lines 28-38).

      • So this read function includes .set() even though it is a "read" operation.

  • The argument d is the Terraform's knowledge of the latest state that was executed via terraform apply. The variable responseData is the state data fetched from the Cloud service via API call (the http request). Terraform then compares d against responseData and updates d to inform itself of the most up-to-date actual cloud state.

• From this function on, there will be repeating lines of logic in the HTTP request flow. The repeat lines will be skipped.

• The source code: main.go

main.go

func resourceHouseRead(ctx context.Context, d *schema.ResourceData, m interface{}) diag.Diagnostics {
	var diags diag.Diagnostics

	config := m.(*Config)

	homeUUID := d.Id()

	// Construct the HTTP Request
	url := config.Endpoint+"/u/"+config.UserUuid+"/homes/"+homeUUID
	req, err := http.NewRequest("GET", url, nil)
	if err != nil {
		return diag.FromErr(err)
	}

	// Set Headers
	req.Header.Set("Authorization", "Bearer "+config.Token)
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Accept", "application/json")
	
	// Send HTTP request
	client := http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		return diag.FromErr(err)
	}
	defer resp.Body.Close()

	var responseData map[string]interface{}

	if resp.StatusCode == http.StatusOK {
		// parse response JSON
		if err := json.NewDecoder(resp.Body).Decode(&responseData);  err != nil {
			return diag.FromErr(err)
		}
		d.Set("name",responseData["name"].(string))
		d.Set("description",responseData["description"].(string))
		d.Set("domain_name",responseData["domain_name"].(string))
		d.Set("content_version",responseData["content_version"].(float64))
	} else if resp.StatusCode != http.StatusNotFound {
		d.SetId("")
	} else if resp.StatusCode != http.StatusOK {
		return diag.FromErr(fmt.Errorf("failed to read home resource, status_code: %d, status: %s, body %s", resp.StatusCode, resp.Status, responseData))
	}

	return diags
}

• Line 6: the ID from the schema.ResourceData object d is stored in the variable homeUUID.

• Line 10: Construct the HTTP request.

  • For this operation, we use the GET method as we want to "read" the existing data. The object d contains the local state information on the resources we created with the resourceHouseCreate() function.

• Lines 30-43: Parse response JSON & update resourceData d

  • One interesting thing to note here is that, in Terraform, the CRUD (Create, Read, Update, Delete) functions in a custom provider are not explicitly called anywhere in our Terraform codes (.tf files) or the Terraform configuration. Instead, Terraform's engine calls them under the hood based on the blue prints we declare in terraform files (.tf, .tfvars and such).

    • Lines 32-33: if the status code is healthy (http.StatusOK, line 30), the function will first run the error check and store it in the diag object.

    • Lines 35-38: We are talking about the "Read" operation in CRUD, but there are .set() functions in it. Did you ever question why this is necessary when what we only need to do is to read? It may make more sense for you to read the Multiverse of Madness section below first.

      • These lines update the object d which is an argument (*schema.ResourceData) passed into the function signature (line 1). Let's clarify which is which:

        • d *schema.ResourceData : this is the in-memory state within Terraform. The local state Terraform manages, and it's state 2 in the below classification.

        • responseData (line 28): this is the state 3, the actual state over there on the cloud (TerraTowns). If you think about it, it's also logical because we are creating an HTTP request and store the response from the cloud service to this variable. What else would we interact through the API with, if not with the remote "Cloud"? (Any idea 👀 ??)

      • In summary, Terraform is updating the object d, its most-up-to-date knowledge about the resources it manages, and running the sanity check to make sure its knowledge is aligned with the actual situation on the cloud service.

    • Lines 39-42: Error handling for status 404 and if the status is sick (not 200).

• The read operation is now complete and Terraform is aware of what the state is (the state 2 updated based on state 3).

Multiverse of Madness: multiple States

In Terraform, the concept of the "state" is extremely important. It is everything, everywhere all at once. So let's dive in.

• State: this is the state of the resources in your cloud infrastructure.

  • Examples: In the context of Andrews' Terraform Bootcamp, the state would be the state of our S3 buckets on AWS where we store all the data necessary to spin up our terra houses.

    • ❓ So the question is, will you provision a VPC? How many buckets have you provisioned? How many buckets are currently running on AWS? How many RDS database instances are currently running on AWS?

    • These are all states.

Speaking of the state of resources, we can categorise varying levels of states into specific groups because states have different characteristics depending on where they are in the process of provisioning. Generally speaking, there are three types of states:

• 1) the state you desire

• 2) the state that is actually provisioned (via Terraform)

• 3) the actual state in place (on cloud service)

I'll elaborate the above three states:

• 1) This is the design of the infrastructure you wish to apply and provision. It might be only in your head, or maybe you declared them in your .tf files. You can generally think of it as the idea of a state before terraform apply.

• 2) The state of the infrastructure that has been executed (provisioned) on the cloud via Terraform upon terraform apply. Given that you are running Terraform locally on your local machine, the data of the running state reside in your RAM (this is also called in-memory).

• 3) The state of the resources provisioned on the cloud service of your choice. This includes all kinds of state - not just running resources, but also resources that were stopped or terminated.

• 🚨 IMPORTANT!: Did you knotice?

  • Generally speaking, the state 3 is often the result of the state 2. However, it is possible that discrepancies occur between the state 2 and state 3. The typical reasons include:

    • You manually deleted some resources on AWS console after running terraform apply.

    • There were some errors between the terraform code and the AWS resource provisioning rules so some resources failed to be created or destroyed.

      • S3 buckets are good examples. A bucket should be empty before destroying. If it contains files, terraform will fail to destroy it. If you run terraform destroy, though, it still can destroy everything else in the infrastructure. So it successfully completes the destroy command AND reports you that the destroy was successful. But if you go to the S3 console and check, the bucket is still there (hey! 👀).