Skip to main content

​
Introduction

Terraform Native Service enables you to deploy and manage Terraform or OpenTofu infrastructure code directly within Qovery. This service type allows you to provision cloud resources, configure external services, and manage infrastructure as code (IaC) using the same environment structure as your applications. Terraform executes within Kubernetes pods on your cluster, with automatic state management, variable injection, and integrated deployment workflows.

​
Creating a Terraform Service

1

Open Environment Overview

Navigate to the environment where you want to deploy your Terraform infrastructure.
2

Create New Service

Click New Service and select Terraform from the service type options.
3

Configure Service Name

Provide a service name that identifies this Terraform service (e.g., aws-infrastructure, cloudflare-config).
4

Select Git Repository

Choose the Git repository containing your Terraform code. This repository must include your .tf configuration files.Specify the branch and root path if your Terraform code is in a subdirectory.
5

Select Engine

Choose the execution engine:
  • Terraform - Official HashiCorp Terraform
  • OpenTofu - Open-source Terraform fork
6

Select Terraform Version

Choose the Terraform version to use for execution. Supported versions depend on your selected engine.
7

State Management (Default)

By default, Terraform state is managed inside the Kubernetes cluster. State files are stored securely within the cluster and managed automatically by Qovery.This default configuration requires no additional setup.
8

Execution Timeout (Default)

The default timeout is set to 1 hour. This can be customized if your Terraform operations require more time.
9

Cloud Credentials (Default Behavior)

By default, Terraform uses cluster credentials when provisioning resources on the same cloud provider as your cluster.If you need to use custom credentials (e.g., a different AWS account, GCP project, or Azure subscription), you will configure them in the Environment Variables step.
10

Compute Resources (Default)

Terraform execution uses the following default compute resources:
  • CPU: 500,000 millicores (500 mCPU or 0.5 vCPU)
  • Memory: 512 MB
  • Storage: 1 GB
These resources can be updated later in the Service Settings if your Terraform operations require more capacity.
11

Configure Terraform Variables

Qovery provides comprehensive variable management for Terraform, automatically detecting variables from your code and allowing flexible configuration.Automatic Variable DetectionQovery automatically loads variables from:
  • main.tf
  • variables.tf
Variables detected by Qovery will appear prefixed with tf_var_.Example:If your variables.tf contains:
variable "bucket_name" {
  type = string
}

variable "environment" {
  type = string
  default = "production"
}
Qovery will create:
  • tf_var_bucket_name
  • tf_var_environment
Importing TFVAR FilesYou can import .tfvars files to configure multiple variables at once:
  1. Click Import TFVAR
  2. Select the TFVAR file(s) to import
  3. Choose which TFVAR files to apply
  4. Reorder the TFVAR files as needed
The last TFVAR file applied wins. If multiple TFVAR files define the same variable, the value from the last file in the order takes precedence.
Manual Variable OverrideYou can manually override any variable value in two ways:
  1. Direct Value Entry - Enter a value directly: 
    tf_var_bucket_name = "my-custom-bucket"
  2. Reference Environment Variable - Reference another environment variable: 
    tf_var_bucket_name = ${MY_BUCKET_NAME}
Variables Not in main.tf or variables.tfIf you have variables defined in other .tf files that are not in main.tf or variables.tf, Qovery will not automatically detect them. You can create these variables manually using the tf_var_ prefix:
tf_var_my_custom_variable = "value"
Configure Terraform Variables
12

Configure Environment Variables

Add standard environment variables that will be available during Terraform execution. This is where you configure custom cloud provider credentials, provider-specific settings, and other configuration.Common use cases:Custom Cloud CredentialsOverride the default cluster credentials with your own:AWS:
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
AWS_DEFAULT_REGION=us-east-1
GCP:
GOOGLE_CREDENTIALS={"type":"service_account",...}
GOOGLE_PROJECT=my-project-id
GOOGLE_REGION=us-central1
Azure:
ARM_CLIENT_ID=...
ARM_CLIENT_SECRET=...
ARM_SUBSCRIPTION_ID=...
ARM_TENANT_ID=...
Provider ConfigurationAdd provider-specific environment variables:Cloudflare:
CLOUDFLARE_API_TOKEN=...
CLOUDFLARE_ZONE_ID=...
Datadog:
DATADOG_API_KEY=...
DATADOG_APP_KEY=...
Use Qovery Secrets for sensitive credentials to ensure they are encrypted and never exposed in logs.
Terraform Environment VariablesYou can also set Terraform-specific environment variables:
TF_LOG=DEBUG
TF_WORKSPACE=production
13

Review and Create

Review your configuration and click Create to provision the Terraform service.Optionally, you can select Create & Run Plan to execute terraform plan immediately and preview the execution plan before applying changes.

​
Running Terraform

After creating your Terraform service, you can execute Terraform commands using the Action Toolbar.
Terraform Action Menu

​
Available Actions

The following Terraform operations are available from the service’s Action Toolbar:
Executes terraform plan to preview infrastructure changes without applying them.Use this to:
  • Review what Terraform will create, modify, or destroy
  • Validate your Terraform configuration
  • Check for drift between your code and actual infrastructure
Executes terraform plan followed by terraform apply to provision or update infrastructure.This is the standard deployment action that:
  • Generates an execution plan
  • Applies changes to your infrastructure
  • Updates the Terraform state
Executes terraform destroy to remove all resources managed by this Terraform service.
This action is irreversible and will delete all infrastructure resources defined in your Terraform code.
Releases a stuck Terraform state lock.Use this if:
  • A previous Terraform operation was interrupted
  • State is locked and preventing new operations
  • You see “state is locked” errors
Only use Force Unlock if you’re certain no other Terraform operation is running.
Migrates Terraform state between storage backends or updates state schema.This operation runs terraform init -migrate-state to:
  • Move state to a new backend
  • Upgrade state file format
  • Reconfigure state storage

​
Create & Run Plan

During service creation, you can select Create & Run Plan to immediately execute terraform plan after the service is created. This allows you to:
  • Preview infrastructure changes before deployment
  • Validate your Terraform configuration
  • Review the execution plan before committing to apply

​
Terraform Service Settings

After creating your Terraform service, you can update all configuration options in the Service Settings.

​
General Configuration

All parameters from the creation flow can be modified:
  • Change the Git repository source
  • Update the branch to deploy from
  • Modify the root path for Terraform code location
  • Switch between Terraform and OpenTofu
  • This change will take effect on the next deployment
  • Update the Terraform or OpenTofu version
  • Useful for testing new versions or maintaining compatibility
  • Modify state storage configuration
  • Update state backend settings if using custom backend
  • Adjust the execution timeout (default: 1 hour)
  • Increase for long-running Terraform operations
  • Decrease to fail faster for quick validations
  • Update CPU allocation (default: 500 mCPU)
  • Modify memory allocation (default: 512 MB)
  • Adjust storage allocation (default: 1 GB)
Increase these resources if your Terraform operations:
  • Manage a large number of resources
  • Require significant memory for state processing
  • Need more CPU for provider operations
  • Add or update cloud provider credentials
  • Configure Terraform input variables (TF_VAR_*)
  • Set provider-specific environment variables
  • Reference secrets for sensitive values

​
Terraform Arguments

The Terraform Arguments section allows you to specify additional CLI arguments for each Terraform command. These arguments override default behaviors and enable advanced customization.
Terraform Arguments Configuration
Terraform Arguments provide fine-grained control over Terraform execution. Use these to customize init, validate, plan, apply, and destroy operations.
Customize terraform init behavior.Common arguments:
  • -upgrade - Upgrade modules and providers to latest versions
  • -reconfigure - Reconfigure backend ignoring existing configuration
  • -backend-config=... - Override backend configuration
Example:
-upgrade -backend-config="bucket=my-state-bucket"
Customize terraform validate behavior.Common arguments:
  • -json - Output validation results in JSON format
  • -no-color - Disable colored output
Example:
-json -no-color
Customize terraform plan behavior.Common arguments:
  • -target=resource.name - Plan changes for specific resource only
  • -var="key=value" - Set a variable value
  • -var-file=filename - Load variables from file
  • -out=filename - Save plan to a file
  • -refresh=false - Skip state refresh
  • -parallelism=n - Limit concurrent operations
Example:
-target=aws_s3_bucket.main -parallelism=5
Customize terraform apply behavior.Common arguments:
  • -target=resource.name - Apply changes to specific resource only
  • -var="key=value" - Set a variable value
  • -var-file=filename - Load variables from file
  • -parallelism=n - Limit concurrent operations
  • -refresh=false - Skip state refresh
Example:
-parallelism=10 -refresh=false
Customize terraform destroy behavior.Common arguments:
  • -target=resource.name - Destroy specific resource only
  • -var="key=value" - Set a variable value
  • -parallelism=n - Limit concurrent operations
  • -refresh=false - Skip state refresh
Use destroy arguments carefully. Targeting specific resources can lead to incomplete cleanup or resource dependencies issues.
Example:
-target=aws_s3_bucket.temp -parallelism=2
Argument Format:
  • Separate multiple arguments with spaces
  • Quote values containing spaces: -var="name=my value"
  • Use multiple -var flags for multiple variables: -var="a=1" -var="b=2"
Example Full Configuration: 
Init: -upgrade
Plan: -parallelism=10 -var="environment=production"
Apply: -parallelism=10 -var="environment=production"
Destroy: -parallelism=5 -refresh=false

​
Next Steps

Environment Variables

Learn how to manage variables and secrets

Terraform Provider

Use Qovery Terraform Provider to manage Qovery resources

Lifecycle Jobs

Run scripts during deployment lifecycle

Deployment Overview

Understand deployment workflows