Terraform Provider

The Qovery Terraform provider manages Qovery resources from Terraform: organization settings, cloud credentials, clusters, projects, environments, services (applications, containers, jobs, Helm charts, Terraform services and databases) and their variables. You describe the resources in HCL, review the changes with terraform plan, and apply them with terraform apply. This page covers the setup. The reference of every resource and data source is on the Terraform Registry.

Upgrading from an earlier version? Read the upgrade guide before you change the version constraint.

Requirements

Terraform. The provider is tested against Terraform 1.15. Earlier versions are expected to work but are not tested.
A Qovery API token.

Install the provider

Declare the provider and pin its major version, so that a future major release cannot introduce a breaking change without an explicit upgrade:

main.tf

terraform {
  required_providers {
    qovery = {
      source  = "qovery/qovery"
      version = "~> 1.0"
    }
  }
}

# Reads the API token from the QOVERY_API_TOKEN environment variable.
provider "qovery" {}

Run terraform init to download the provider.

Authentication

The provider authenticates with a Qovery API token. To create one, see API Token. The token carries a role: give it one that allows the changes your configuration makes. Pass the token in one of two ways:

Set the QOVERY_API_TOKEN environment variable. The provider reads it when the token argument is not set.
export QOVERY_API_TOKEN="<your-api-token>"

Set the token argument from a sensitive input variable:

variable "qovery_api_token" {
  type      = string
  sensitive = true
}

provider "qovery" {
  token = var.qovery_api_token
}

Do not write the token in your configuration files or commit it to version control.

Find resource IDs

Resources reference each other by ID. To use a resource that your configuration does not manage, such as an existing cluster, pass its ID to the configuration, usually as an input variable.

Console: IDs appear in the page URL, for example https://console.qovery.com/organization/<organization_id>/project/<project_id>/overview.
CLI: qovery organization list, qovery project list, qovery cluster list and qovery environment list print the ID of each resource. Run qovery context set first to select the organization and the project. See the CLI documentation.

Data sources look up an existing resource by its id, not by its name (qovery_organization_member uses the member’s email). Organization-level data sources, such as qovery_cluster, also require organization_id:

variable "organization_id" {
  type = string
}

variable "cluster_id" {
  type = string
}

data "qovery_cluster" "main" {
  id              = var.cluster_id
  organization_id = var.organization_id
}

output "cluster_name" {
  value = data.qovery_cluster.main.name
}

To bring a resource created from the Console or the API under Terraform, declare it in the configuration and add an import block. The Registry page of each resource gives its import ID. The Terraform exporter generates the configuration of a whole environment.

How the provider tracks changes

The configuration is the source of truth. terraform plan refreshes every resource from the Qovery API, so a change made from the Console or the API shows up as a difference, and the next terraform apply reverts it to the configured value. The API never returns secrets, such as secret values, passwords and secret keys: Terraform keeps them as configured, so a change made to them outside Terraform does not show up in the plan. Removing an attribute from the configuration plans its default value or its removal. A few attributes keep their current value when you remove them, because the Qovery API gives Terraform no way to reset them, for example deployment_stage_id and advanced_settings_json. The Managing changes guide explains the rules and lists these exceptions. Change the resources that Terraform manages in the configuration, not in the Console.

Deploy an environment

Creating or changing a service with Terraform updates its configuration in Qovery but does not deploy it. The qovery_deployment resource deploys, stops or restarts an environment on terraform apply. You can also deploy from the Console. Qovery stores no deployment object, so a deployment started from the Console does not show up in terraform plan.

Destroying a qovery_deployment, or removing it from the configuration, deletes its environment and all the services in it. Only declare it for an environment that the same configuration creates or has imported.

Next steps

Basic Application

Deploy an application from a git repository

Application with Database

Connect an application to a database

Linking Services Together

Connect services to each other

Multi-Environment Setup

Create development, staging and production environments

Airbyte Deployment

Deploy a Helm chart with a database and a proxy

Advanced Patterns

Modules, workspaces and remote state

Terraform Exporter

Generate the configuration of an existing environment

Terraform Registry

Reference of every resource and data source

GitHub Repository

Provider source code and issues

Getting Started

Examples

Terraform Provider

Requirements

Install the provider

Authentication

Find resource IDs

How the provider tracks changes

Deploy an environment

Next steps

Basic Application

Application with Database

Linking Services Together

Multi-Environment Setup

Airbyte Deployment

Advanced Patterns

Terraform Exporter

Terraform Registry

GitHub Repository

​Requirements

​Install the provider

​Authentication

​Find resource IDs

​How the provider tracks changes

​Deploy an environment

​Next steps

Basic Application

Application with Database

Linking Services Together

Multi-Environment Setup

Airbyte Deployment

Advanced Patterns

Terraform Exporter

Terraform Registry

GitHub Repository

Requirements

Install the provider

Authentication

Find resource IDs

How the provider tracks changes

Deploy an environment

Next steps