Awesome
<a href="https://env0.com"> <img src=".github/env0_logo.svg" alt="env0 logo" title="env0" align="right" height="40" /> </a>Terraform Provider for env0
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
-
Generate an
api_key
andapi_secret
from the Organization Settings page. See here. -
These can be provided by one of two methods:
- Set
ENV0_API_KEY
andENV0_API_SECRET
environment variables, and just declaring the provider with no parameters:
provider "env0" {}
- 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 }
- Set
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:
github_installation_id
for Githubbitbucket_client_key
for Bitbucketgitlab_project_id
+token_id
for Gitlabtoken_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, replacearm64
withamd64
) - Copy the built binary -
cp ./terraform-provider-env0 ~/.terraform.d/plugins/terraform.env0.com/local/env0/6.6.6/darwin_arm64
(Replacedarwin
withlinux
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
andENV0_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 fromexpected_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
- Make sure
GOPATH
is in yourPATH
go env GOPATH
echo $PATH
export PATH=$PATH:$(go env GOPATH) # if not
- Install mockgen
go install go.uber.org/mock/mockgen@v0.3.0
- 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>
- 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:
- Validate that all status checks are ✅ on
main
branch (specifically that docs generation is complete) - Pull from remote first -
git pull origin main
- Create and push a tag locally, in semver format -
git tag v0.0.9 && git push origin --tags
- New release with binaries will be automatically generated by the GitHub action defined in
.github/workflows/release.yml
. It needs to be approved. - The Registry will automatically pick up on the new version.