Terraform Provider for env0

• Documentation
• Usage Examples

Quick Start

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

provider "env0" {}

data "env0_project" "default_project" {
  name = "My First Project"
}

resource "env0_template" "example" {
  name        = "example"
  description = "Example template"
  repository  = "https://github.com/env0/templates"
  path        = "aws/hello-world"
}

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

Authentication

1. Generate an api_key and api_secret from the Organization Settings page. See here.

2. These can be provided by one of two methods:

   1. Set ENV0_API_KEY and ENV0_API_SECRET environment variables, and just declaring the provider with no parameters:

      provider "env0" {}

   2. 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
   }

How to get VCS credentials for Creating a template or a VCS environment

To create an env0_template or a VCS env0_environment resources a user must provision the corresponding credentials:

1. github_installation_id for Github
2. bitbucket_client_key for Bitbucket
3. gitlab_project_id + token_id for Gitlab
4. token_id for Azure DevOps

To get those credentials in the provider you must first create a "master" environment via the env0 app, then just fetch the corresponding env0_environment data source and use the relevant credentials:

data "env0_environment" "master_environment" {
  id = "exampleId"
}

resource "env0_template" "example" {
  name        = "example AzureDevOps"
  description = "Example AzureDevOps template"
  repository  = "https://dev.azure.com/example-org/AWS/_git/example"
  path        = "hello-world"
  token_id    = data.env0_environment.master_environment.token_id
}

Development Setup

Supported Go Version: 1.21

Build

• Use the ./build.sh script.
• The output binary is called terraform-provider-env0

Run local version of the provider

• Build - ./build.sh
• Create the plugins folder - mkdir -p ~/.terraform.d/plugins/terraform.env0.com/local/env0/6.6.6/darwin_arm64 (for Intel processor, replace arm64 with amd64)
• Copy the built binary - cp ./terraform-provider-env0 ~/.terraform.d/plugins/terraform.env0.com/local/env0/6.6.6/darwin_arm64 (Replace darwin with linux on Linux)
• Require the local provider in your main.tf -

terraform {
  required_providers {
    env0 = {
      version = "6.6.6"
      source  = "terraform.env0.com/local/env0"
    }
  }
}

Installing pre-commit hooks

For consistent coding style, install pre-commit hooks.

go install golang.org/x/tools/...@latest
go install honnef.co/go/tools/cmd/staticcheck@latest
pre-commit install
pre-commit install --hook-type pre-push

Testing

Integration tests

• The integration tests run against the real env0 API
• Have ENV0_API_KEY and ENV0_API_SECRET environment variables defined.
• Also set ENV0_API_ENDPOINT if you want to run against a non-prod environment.
• Run go run tests/harness.go (from the project root folder) to run all the tests.
• Use go run tests/harness.go 003_configuration_variable to run a specific test.

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 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.

Integration Test Prerequisites

• An env0 organization
• An API Key
• A Github.com integrated template name Github Integrated Template for https://github.com/env0/templates
• A Gitlab.com integrated template name Gitlab Integrated Template for https://gitlab.com/env0/gitlab-vcs-integration-tests

Unit Testing

How to run tests

Run from root directory:

go test -v ./...

Running a single provider test

export TEST_PATTERN="TestUnitConfigurationVariableResource/Create" && go test -v ./env0

How to use mocks

1. Make sure GOPATH is in your PATH

go env GOPATH
echo $PATH
export PATH=$PATH:$(go env GOPATH)  # if not

2. Install mockgen

go install go.uber.org/mock/[email protected]

3. 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>

4. Run from root directory:

go generate ./...

Documentation

• Docs are generated using github.com/hashicorp/terraform-plugin-docs
• Run ./generate-docs.sh to generate docs
• Must be run manually before releasing a version
• Please add an example to examples/<resources or data-sources>/env0_<name> dir and make sure it is added to the docs.

Release

To release a version to the Terraform Public Registry:

1. Validate that all status checks are ✅ on main branch (specifically that docs generation is complete)
2. Pull from remote first - git pull origin main
3. Create and push a tag locally, in semver format - git tag v0.0.9 && git push origin --tags
4. New release with binaries will be automatically generated by the GitHub action defined in .github/workflows/release.yml. It needs to be approved.
5. The Registry will automatically pick up on the new version.