terraform-provider-env0

README

terraform-provider-env0

Terraform provider to interact with env0

Available in the Terraform Registry

The full list of supported resources is available here.

Example usage

terraform {
  required_providers {
    env0 = {
      source = "env0/env0"
      version = "0.0.2"
    }
  }
}

provider "env0" {}

data "env0_project" "default_project" {
  name = "Default Organization Project"
}

resource "env0_template" "example" {
  name        = "example"
  description = "Example template"
  repository  = "https://github.com/env0/templates"
  path        = "aws/hello-world"
  project_ids = [data.env0_project.default_project.id]
}

resource "env0_configuration_variable" "in_a_template" {
  name        = "VARIABLE_NAME"
  value       = "some value"
  template_id = env0_template.tested1.id
}

Authentication

First, generate an api_key and api_secret from the organization settings page. See here.

These can be provided by one of two methods. First method consists of setting ENV0_API_KEY and ENV0_API_SECRET environment variables, and just declaring the provider with no parameters:

provider "env0" {}

The second method would be to specify these fields as parameters to the provider:

variable "env0_api_key" {}
variable "env0_api_secret" {}

provider "env0" {
    api_key = var.env0_api_key
    api_secret = var.env0_api_secret
}

Dev setup

To build locally, you can use the ./build.sh script. The rest of the steps below are relevant if you would like to use the provider outside of the test harness (the test harness performs the steps described here).

To use local binary version, you'll need to create a local terraform provider repository. The simplest way to do so would be to create a folder on your disk. Under that folder, copy the built provider binary to terraform-registry.env0.com/env0/env0/6.6.6/linux_amd64/terraform-provider-env0 (note to replace linux_amd64 if using a different platform). Then, create a terraform.rc file (location doesn't matter). The content of said file should look like so:

provider_installation {
  filesystem_mirror {
    path    = "<absolute path to local repository folder>"
    include = ["terraform-registry.env0.com/*/*"]
  }
  direct {}
}

Finally, set an environment variable TF_CLI_CONFIG_FILE to point to the terraform.rc file created. After that, terraform init should be able to locate the provider on disk. To define this variable only when running terraform once, you can, in bash shell:

TF_CLI_CONFIG_FILE=<terraform.rc path> terraform init

Testing

Harness

If you have ENV0_API_KEY and ENV0_API_SECRET environment variables defined, after building the provider locally, just run go run tests/harness.go to run all the tests. Make sure to run from the project root folder.

Use go run tests/harness.go 003_configuration_variable to run a specific test. The last argument can also be specified as a full path, e.g., tests/003_configuration_variable/.

Each test perform the following steps:

• terraform init
• terraform apply -auto-approve -var second_run=0
• terraform apply -auto-approve -var second_run=1
• terraform outputs -json - and verifies expected outputs from expected_outputs.json
• terraform destroy

The harness has two convineint modes to help while developing: If an environment variable DESTROY_MODE exists and it's value is NO_DESTROY, the harness will avoid calling terraform destroy, allowing the developer to inspect the resources created, through the dashboard, for example. Afterwards, when cleanup is required, just set DESTROY_MODE to DESTROY_ONLY and only terraform destroy will run.

Unit Testing

How to run tests

Run from root directory:

go test ./...

How to use mocks

1. Make sure to add this line in files that include the interface you'd wish to mock:

//go:generate mockgen -destination=<file>_mock.go -package=<package> . <interface>

1. Run from root directory:

go generate ./...

Documentation

• Docs are generated using github.com/hashicorp/terraform-plugin-docs
• Run ./generate-docs to generate docs
• Must be run manually before releasing a version

Release

• To release a version to the Terraform Public Registry, create a Release+tag that matches semver (d.d.d)
• Docs must be generated manually and committed to the repo before release.
• Binaries will be automatically generated by .github/workflows/release.yml
• The Registry will automatically pick up on the new version.