Terraform Provider

Deploy confidential apps on Phala Cloud with Terraform — install, configure, and deploy your first CVM in minutes.

The Terraform Provider is currently in beta. The resource schema may change between releases.

The Phala Cloud Terraform provider lets you manage confidential virtual machines (CVMs) using standard Terraform workflows. It follows an app-first model where phala_app is the primary resource, managing one application identity with shared Docker Compose configuration, shared environment variables, and one or more CVM replicas.

If you have used providers like DigitalOcean or AWS, the patterns here will feel familiar: catalog data sources for discovery, declarative compute resources, explicit power control, and SSH key management.

Installation

The provider is published on the Terraform Registry under phala-network/phala. Add it to your required_providers block:

terraform {
  required_version = ">= 1.5.0"

  required_providers {
    phala = {
      source  = "phala-network/phala"
      version = "0.2.0-beta.1"
    }
  }
}

provider "phala" {}

Run terraform init to download the provider binary. Terraform handles the rest automatically.

Authentication

The provider authenticates with a Phala Cloud API key. You can get one from the dashboard:

1. Sign in at cloud.phala.com.
2. Go to Settings then API Keys.
3. Create a key and export it in your shell:

export PHALA_CLOUD_API_KEY="phak_xxx"

The provider reads PHALA_CLOUD_API_KEY automatically. You can also set it explicitly in the provider block, though environment variables are recommended for security.

Provider Configuration

Attribute	Type	Description
api_key	String, Sensitive	Phala Cloud API key. Falls back to PHALA_CLOUD_API_KEY env var.
api_prefix	String	API base URL. Falls back to PHALA_CLOUD_API_PREFIX. Most users do not need this.
api_version	String	API version sent in X-Phala-Version header.
timeout_seconds	Number	HTTP timeout in seconds.

# Explicit configuration (usually not needed)
provider "phala" {
  api_key         = var.phala_api_key
  timeout_seconds = 60
}

Quick Start

This deploys a single nginx CVM and outputs the app ID and public endpoint. The values below (tdx.medium, US-WEST-1, 40 GB disk) are tested defaults that work out of the box.

terraform {
  required_version = ">= 1.5.0"

  required_providers {
    phala = {
      source  = "phala-network/phala"
      version = "0.2.0-beta.1"
    }
  }
}

provider "phala" {}

resource "phala_app" "hello" {
  name      = "hello-phala"
  size      = "tdx.medium"
  region    = "US-WEST-1"
  image     = "dstack-dev-0.5.7-9b6a5239"
  disk_size = 40
  replicas  = 1

  docker_compose = <<-YAML
    services:
      web:
        image: nginx:stable
        ports:
          - "80:80"
  YAML

  wait_for_ready       = true
  wait_timeout_seconds = 900
}

output "app_id" {
  value = phala_app.hello.app_id
}

output "endpoint" {
  value = phala_app.hello.endpoint
}

Run the standard Terraform workflow:

terraform init
terraform apply -auto-approve
terraform output

When it completes, Terraform prints the app_id and a public endpoint URL. Your app also appears in the Phala Cloud dashboard in a running state.

To tear down:

terraform destroy -auto-approve

What’s in the Provider

The provider includes three resources and seven data sources:

Resources:

• phala_app — the primary lifecycle resource for deploying apps with CVM replicas
• phala_cvm_power — start/stop power control for existing CVMs
• phala_ssh_key — manage account-level SSH keys

Data Sources:

• phala_account — current user and workspace info
• phala_workspace — active workspace metadata
• phala_sizes — available instance types
• phala_regions — available deployment regions
• phala_images — available OS images
• phala_nodes — worker nodes for placement pinning
• phala_attestation — TEE attestation data for a CVM

Common Workflow

A typical deployment follows this pattern:

1. Use data sources (phala_sizes, phala_regions, phala_images) to discover valid slugs.
2. Define a phala_app with your Docker Compose file and desired replica count.
3. Wait for readiness, then consume app_id, cvm_ids, and endpoint as outputs.
4. Optionally use phala_cvm_power for explicit start/stop control after deployment.

Related

• App Resource Reference
• Data Sources
• Examples
• Changelog