This is a walkthrough of my custom Terraform provider that creates/updates file content inside a GitHub repository. The official Terraform GitHub provider may only control the existence of certain resources (such as repositories) but does not implement content manipulation of repositories. You can find my custom Terraform provider here on GitHub. I wrote my custom provider using the go-github Go library for accessing the GitHub API. You will notice that the official GitHub provider also utilizes this library.
It's easier than it sounds
Before I begin, I recommend following the Writing Custom Providers guide to get started. Once that's up and running, elaborate on functionality and explore a new horizon of opportunities! I am grateful to HashiCorp's attention to detail involved in their documentation. In addition to being very thorough, you also have the entire collection of official Terraform providers openly accessible on GitHub. This is especially useful when attempting to follow best practices and discover how particular scenarios are achieved.
After exercising the tutorial, I became almost immediately aware of how I can approach my problem. However, it was a challenge to design these functions. I had to keep in mind how they will be interfacing with Terraform modules in a declarative fashion. In other words, it was tough to avoid writing the provider like any other shell script I have written in the past.
Room for improvement
My custom provider is far from complete. As of writing this, it only supports the creation of resources. I have not implemented terraform destroy, nor does it handle the updating of existing resources. However, it would not be too complicated to implement this logic. Much of the logic would be reused from the Create function. Given more time, some areas I would have liked to improve:
- Move the organization and GitHub token parameters from resource to provider-scope. Right now, all Terraform/environment variables are referenced via the resource. This means the organization and token need to be provided for each resource defined in .tf files, as opposed to the provider block. This is also a security concern as the GitHub token will be exposed in plaintext during terraform runs and in state files.
- Move OAuth2 client declaration to provider-scope. While the OAuth2 client is only being created once for the Create function, it would need to be generated upon update and destroy as well. Initializing the client during the provider construction would be a bit more efficient.
- Implement branch creation and pull requests. Currently, this provider allows for directly writing to files in an existing branch (even master, if it is not protected). An ideal approach would be to generate a pull request with a dynamic branch, awaiting an authorized approver's review before applying the merge.
Setup, usage details, and examples given here can be found in my repo.
Here's a high-level explanation of what's going on in the repository:
Main entry point for the Go code of the custom Terraform provider.
Contains the example usage of the demo_repo_content resource.
Root of the Terraform provider code.
Defines the manufacturing process of the demo_repo_content resource.
Let's go into more detail one-by-one. Please note that I will be using snippets in this blog article, but the full code is available on GitHub!
This will be a main Go package that contains the same boilerplate main as the official tutorial:
These 2 imports are necessary when creating a Terraform provider. The Provider constructor being called is defined in provider.go.
This Terraform module contains 1 example resource creating a README.md in the root of a GitHub repository.
Notice that I am not providing the GitHub token in the resource declaration. Because this is sensitive data, I'd much rather export it as an environment variable than having it present in my publicly accessible repository. 😬
We could also specify the provider block (for demo), but at the moment, there are no arguments to be passed at the provider-level.
Lastly, this is the mapping between the Terraform resource name (referenced in .tf files) and its implementation in Go (create, update, destroy, etc). This implementation is defined in resource_demo_repo_content.go:
Here is where all of the logic comes into play, expect a bit of verbosity.
The above snippet demonstrates what components are typically required for defining a Terraform resource. Terraform will be using this function to determine what actions to perform when we reference demo_repo_content in .tf modules.
Create, Read, Update, and Delete (CRUD) are all referencing Go functions within this file to be called when appropriate. Currently, only the Create function has been implemented, the others simply return nil and do nothing. While this does not break functionality when using terraform commands, it will certainly cause inconsistencies. For example, after running terraform destroy, Terraform will successfully destroy the resource(s) from its state file(s). However, according to Terraform's state, this will make the resource available to be created again, when in reality, it was never destroyed in the first place.
See the Schema definition that follows the CRUD references:
This is where we can plug in the resource's configuration parameters. For example, the organization and token can be included as arguments within the resource declaration in the .tf file, or by exporting the GITHUB_ORGANIZATION and GITHUB_TOKEN environment variables, respectively.
These get referenced in the Create function like so:
Next, we create an OAuth2 client to authenticate and perform actions against the GitHub API:
I have tried being meticulous with error-handling throughout my code as Terraform doesn't give the most helpful message when a provider fails ungracefully.
Here's where the magic happens. Using our OAuth2 client, acquire the repo and branch in question, and apply the file content:
With client.Git.GetRef we receive the branch reference (for its SHA) to make a new commit. Then, client.Repositories.UpdateFile performs the commit to that same branch to write the file. encodedContent is a byte-encoded version of the file_content argument passed into our Terraform resource configuration.
To keep things simple, these actions are all performed after running terraform apply and confirming the outcome. To set the state of this particular resource, a unique identifier must be set:
So long as the resource configuration remains the same, Terraform will not attempt to run Create again. To handle the other scenarios a resource's life cycle includes, we can implement the remaining CRUD functions.
Want to learn more Terraform? We'd be happy to hear from you.