Introduction
Like many software projects, frameworks, plugins they start off because the author could not find a solution that really fitted their needs and submitting pull requests to existing projects would not have changed the direction of such projects to the needs of the author. This is one of those kind of projects and it is offered against a number of alternative solutions that are available as Gradle plugins.
The aim with the group of plugins is making the integration of Terraform into the build automation pipeline as smooth as possible. This combination of Gradle with Terraform makes for an extremely powerful orchestration platform in the DevOps.
The plugin brings with it a number of subgoals:
-
Simplicity to use defaults - convention over configuration
-
Maximum flexibility if you need it.
-
No need to install
terraform
or relevant tools - let Gradle take care of it for you.
This is an incubating project. Until is 1.0 released one day, interfaces and DSL may change between 0.x releases.
|
These documentation pages assume that you have at least a basic working knowledge of Terraform. |
Terraform + Gradle - A mindset change
Integrating these two products delivers a pwerful combination, but also presents a number of operational ways that challenges people that is used to using terraform
standalone or in scripts.
Using Terraform with Gradle means that the former no longer needs to be installed. Just specify the version and Gradle will boostrap the correct version. If the version is already in cache (~/gradle/native-binaries/
), Gradle will just reuse it.
Caching of plugins
Gradle will cache Terraform plugins using the Terraform caching mechanism, but share it between project by using the Gradle user home caching directories. It is possible to override this a have the caching use a per-project basis or purely rely on global Terrafom settings.
Bootstrapping
These plugins are available from the plugin portal. Add the appropriate plugin identifiers to your build.gradle
file depending on the type of functionality you require.
plugins {
id 'org.ysb33r.terraform.base' version '0.1.3' (1)
id 'org.ysb33r.terraform' version '0.1.3' (2)
id 'org.ysb33r.terraform.rc' version '0.1.3' (3)
id 'org.ysb33r.terraform.wrapper' version '0.1.3' (4)
}
1 | Base plugin provides terraform extension. |
2 | Conventions for terraform including source sets and tasks created by convention. |
3 | This plugin is normally not applied directly, but deals specifically with Terraform configuration |
4 | This plugin is usually only applied at the root project and dealks with the creation of terraformw wrappers. |
You need at least Gradle 4.7 to use these plugins. |
Base plugin
The base plugin provides:
-
A project extension named
terraform
. -
Various Terraform task types which tend to map the
terraform
command closely. Fot instance for theinit
command, the appropriate task type is calledTerraformInit
. -
Ability to download and use
terraform
executables.
When the base plugin is applied to the root project it will automatically apply the terraformrc
plugin.
Terraform plugin
The Terraform conventions plugin provides:
-
terraformSourceSets
as a project extension. -
The default Terraform source set called
main
with default directorysrc/tf/main
. -
A number of tasks including
terraformInit
,terraformPlan
andterraformApply
which acts upon the default source set.
Applying the Terraform plugin will apply the base plugin.
Terraform RC plugin
The terraformrc
plugin provies an extension called terraformrc
which deals with the creation of a configuration file specificaly for use by Terraform within the project.
Terraform Wrapper plugin
Provides the terraformWrapper
and cacheTerraformBinaries
tasks.
Quick start
The minimalist project is
plugins {
id 'org.ysb33r.terraform' version '{revnumber}'
}
Now add a init.tf
file to src/tf/main
and add some Terraform content to it.
$ ./gradlew terraformInit (1) $ ./gradlew terraformApply (2) $ git add src/tf/main/terraform.tfstate (3)
1 | Initialise your Terraform project environment. |
2 | Apply your changes |
3 | Add your newly created .tfstate file to source control. If your Terraform context uses remote state storage, then this last step is not required. |
Platform installation support
These plugins can automatically download, cache and render Terraform for the following platforms:
-
Linux 32 & 64-bit.
-
Mac 64-bit.
-
Windows 32 & 64-bit.
-
FreeBSD 32 & 64-bit.
-
Solaris 64-bit.
Should you need to run Gradle on a platform not listed above, but which Terraform supports and on which Gradle can run, you will need to configure the Terraform executable via the path
or search
methods. You can also raise an issue to ask for the support or you can submit a PR with the solution.
Source Sets
When the org.ysb33r.terraform
plugin is applied, it adds the terraformSourceSets
extension which contain the main
source set. Associated with this source set is the default folder of src/tf/main
and a number of tasks including:
-
terraformInit
-
terraformPlan
-
terraformApply
If additional source sets are needed they can be added by convention i.e.
terraformSourceSets {
development (1)
staging {
srcDir = 'staging' (2)
}
}
1 | Creates a Terraform source set named 'development' with default directory src/tf/development |
2 | Creates a Terraform source set named 'release` and set the directory to staging . |
Tasks for additional source sets follow the terraform<SourceSetName><TerraformCommand>
format. For instance in the above example the initialisation task for the development
source set will be called terraformDevelopmentInit
.