Terraform

If you’ve been living under a rock or happen to be a newcomer in the DevOps/Site Reliability Engineering space, Hashicorp’s Terraform enables provisioning and managing cloud infrastructure. It’s essentially a glorified diffing tool for any cloud resource that, as long as a Terraform Provider exists, can ensure the state of your infrastructure is as expected when written in Hashicorp Config Language (HCL).

As a forewarning before digging deeper, it has been common to hear some Linuxy sysadmin-looking neckbeards in-passing talking about infrastructure as code, better known as IaC, being the bee’s knees and how they keep managing to give Dave a good ribbing after causing the Great Network failure of ‘22 after performing a Git force push…

Terraform could be your new life.

It’s a good one.

I digress…

The great thing about Terraform is that it provides for your infrastructure:

  • Automated creation of new resources
  • Showing the difference between current and expected resources on terraform plan
  • The ability to reconcile the current state with the written expectation on terraform apply
  • And when used with Git, an auditable history of changes

Plenty of Terraform Providers exist for cloud providers, for example, Azure, AWS, Digital Ocean and more! But while Terraform can manage Cloud Resources, it has been built so that, as long as you can interact with an API (create, read, update or delete) to adjust the state of a given “Thing”, it can be managed by Terraform.

Providers

Hashicorp has maintained a wonderfully extensible Terraform Plugin Software Development Kit (SDK) for creating Providers for many, many years and has recently journeyed into what it would look like to build an idiomatically Go, more streamlined, strongly typed framework with documentation generation for creating providers. If you want to dig into the weeds to understand the difference between the Plugin SDKv2 and the Plugin Framework, check out Hashicorp’s article on the “Plugin Framework Benefits”.

Objectives

At my place of employment, we have been using FusionAuth as our 3rd-party auth provider and a community-maintained Terraform Provider, which I have committed and pushed many a PR to. While it works, there are several rough edges that would be nice to round out, plus I wanted to gain an appreciation of where Hashicorp is heading with the new framework.

My main objectives when starting this project are:

  • Consistency - Ensuring that the project has a similar consistent pattern of solving common problems.
  • DX/UX - Ensure it provides a much better developer and user experience due to automatic documentation generation or better error suggestions.
  • Testability - Ensuring that the project has proper acceptance tests that show when the API of FusionAuth or the Go-Client has broken the Terraform Provider.

Starting Out

Hashicorp kindly provides many good resources for creating your first Terraform Provider. The first thing I read through was Hashicorp’s documentation on Plugin Development. I then cloned the Terraform Provider Scaffolding Framework repo and proceeded to get myself versed in the repo’s layout.

Interestingly, the Provider implementation is stored in an internal folder, meaning external developers can’t import the Provider code. Not a bad thing, but it helps to force developers to use the Terraform Provider as a gRPC binary plugin assuming they don’t want to copy+paste code.

Delving into internal/provider/provider.go I started to build out my FusionAuth Provider config - enabling the configuration of a Host Name and API Token.

After an initial skeleton, I backtracked to the docs and found a helpful walkthrough article on framework-based Providers. The info gleaned here helped with initial provider configuration - using envvars and pulling data out from the config struct was pertinent to success. So that was neat to find.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

func (p *FusionAuthProvider) Configure(ctx context.Context, req provider.ConfigureRequest, resp *provider.ConfigureResponse) {
	// Check environment variables
	apiToken := os.Getenv(envApiToken)
	endpoint := os.Getenv(envEndpoint)
	tenant := os.Getenv(envTenant)

	var data FusionAuthProviderModel

	// Read configuration data into model
	resp.Diagnostics.Append(req.Config.Get(ctx, &data)...)

	if resp.Diagnostics.HasError() {
		return
	}

	// Configuration values are now available.
	if data.ApiToken.String() != "" {
		apiToken = data.ApiToken.String()
	}
	if apiToken == "" {
		resp.Diagnostics.AddError(
			"Missing API Token Configuration",
			"While configuring the provider, the API token was not found in "+
				"the "+envApiToken+" environment variable or provider "+
				"configuration block api_token attribute.",
		)
	}

	if data.Endpoint.String() != "" {
		endpoint = data.Endpoint.String()
	}
	if endpoint == "" {
		resp.Diagnostics.AddError(
			"Missing Endpoint Configuration",
			"While configuring the provider, the API endpoint was not found in "+
				"the "+envEndpoint+" environment variable or provider "+
				"configuration block endpoint attribute.",
		)
	}

	if data.Tenant.String() != "" {
		tenant = data.Tenant.String()
	}

	baseURL, err := url.Parse(endpoint)
	if err != nil {
		resp.Diagnostics.AddError(
			"Unable to parse FusionAuth API Endpoint",
			"While configuring the provider, the API endpoint '"+endpoint+"'was unable "+
				"to be parsed as a URL.",
		)
	}

	// Finalized validating config, return errors
	if resp.Diagnostics.HasError() {
		return
	}

	// client configuration for data sources and resources
	httpClient := &http.Client{
		Timeout: time.Second * 10,
	}
	client := FusionAuthClient{
		API:    fusionauth.NewClient(httpClient, baseURL, apiToken),
		Tenant: tenant,
	}

	// Bind in the client data
	resp.DataSourceData = client
	resp.ResourceData = client
}

Refer: https://github.com/matthewhartstonge/terraform-provider-fusionauth/blob/95cb893c5bb5e778a1af18592d0719e4492e732f/internal/provider/provider.go#L83-L153

Interestingly, I don’t know if I’m meant to be plugging in a struct to resp.DataSourceData and resp.ResourceData as the “client” as that bit wasn’t clear, but no doubt I’ll find this out pretty quick when I crack back into this when building out my first Terraform FusionAuth Resource.

Anywho, that’s where I got to for my first night.

Follow along

Feel free to follow along with my development at GitHub or chat via my socials:

Addendum

  • Time to Code: 3h
  • Time to Blog: 2h
  • Realising I can plumb thumbnails into my blogs and backporting: 1h