Phala Cloud Documentation — Private AI on TEE

phala_app is the primary lifecycle resource in the Phala Cloud Terraform provider. It manages a single application identity (app_id) with shared Docker Compose configuration, shared environment variables, and one or more CVM replicas. This is the resource you use for every deployment.

Example Usage

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

  env = {
    APP_SECRET = "replace-me"
  }

  public_logs     = false
  public_sysinfo  = false
  public_tcbinfo  = false
  gateway_enabled = true

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

  wait_for_ready       = true
  wait_timeout_seconds = 900
}

Required Attributes

Attribute	Type	Description
`name`	String	Application name. Force-new — changing this destroys and recreates the resource.
`docker_compose`	String	Docker Compose YAML content defining your services.
`size`	String	Instance type slug (e.g. `tdx.small`, `tdx.medium`). Discover valid values with `data.phala_sizes`.

Optional Attributes

Placement and Identity

Attribute	Type	Description
`region`	String	Preferred region slug (e.g. `US-WEST-1`). Force-new. Discover values with `data.phala_regions`.
`image`	String	OS image slug. Updatable in-place. Use exact slugs from `data.phala_images`.
`node_id`	Number	Pin placement to a specific worker node. Force-new. Discover nodes with `data.phala_nodes`.
`kms`	String	KMS type for provisioning: `phala` (default), `ethereum`, or `base`. Force-new.
`custom_app_id`	String	Custom app ID for deterministic identity flow (PHALA KMS). Force-new.
`nonce`	Number	Nonce paired with `custom_app_id` for deterministic identity. Force-new.
`listed`	Boolean	Whether the app is publicly listed. Force-new.

Infrastructure

Attribute	Type	Description
`disk_size`	Number	Disk size in GB. Can only grow — shrink attempts are rejected by the provider.
`replicas`	Number	Desired replica count. All replicas share the same compose, env, and settings.
`storage_fs`	String	Filesystem for the data disk: `zfs` (default) or `ext4`. `ext4` has lower I/O overhead; only `zfs` detects a modified block on the encrypted disk. Immutable after create — changing forces replacement.
`ssh_authorized_keys`	List of String	SSH public keys injected at launch. Force-new — runtime mutation is not supported.
`pre_launch_script`	String	Optional script content run before the CVM starts.

Compose Runtime Settings

These attributes control compose-level runtime behavior. Changing any of them triggers a compose update and CVM restart.

Attribute	Type	Default	Description
`public_logs`	Boolean	`false`	Expose container logs publicly.
`public_sysinfo`	Boolean	`false`	Expose system info publicly.
`public_tcbinfo`	Boolean	`false`	Expose TCB attestation info publicly.
`gateway_enabled`	Boolean	—	Enable public gateway routing.
`secure_time`	Boolean	—	Enable secure time mode.

Compose Settings, Init Scripts, Annotations and Launch Token

These attributes are in the provider’s unreleased changes (after 0.3.0-beta.4). No released provider version has them yet.

The provider sends every compose change of one apply as a single PATCH /cvms/{id} merge patch. Only changed keys are sent, and compose keys the provider does not manage stay as they are. The provider keeps these settings as configured in state and does not read them back from Phala Cloud.

Attribute	Type	Description
`port_policy`	Object	Which guest ports the gateway forwards: `restrict_mode` (Boolean) and `ports` (list of `{ port, pp }`, where `pp` sends the PROXY protocol header).
`swap_size`	String	Guest swap size, for example `2G`.
`storage_discard`	Boolean	Pass discard (TRIM) through to the data disk.
`snapshotter`	String	`overlayfs` or `stargz`. Only with `runner = "nerdctl-compose"`.
`event_log_version`	Number	Event log format, `1` or `2`. Every verifier that checks the app must support the version you pick.
`requirements`	Object	Guest requirements: `health_check`, `health_status_file`, `platforms`, `tdx_measure_acpi_tables`, `ephemeral_data_disk` and `gpu_policy`. Only the keys you set are written. `gpu_policy` needs a feature flag and is force-new.
`init_scripts`	Set of String	Platform init scripts every CVM of the app runs on boot: `docker_cleanup` and `env_merge` (feature-flagged). See Init scripts.
`confirm_data_wipe`	Boolean	Confirms an update that turns on `docker_cleanup` or `requirements.ephemeral_data_disk`, which erase data on every boot. Not needed on create.
`runner`	String	`docker-compose` (default), `nerdctl-compose` or `bash`. The other runners need a feature flag. Force-new.
`bash_script`	String	Script the `bash` runner runs; set `docker_compose = ""` with it. Force-new.
`annotations`	Map of String	Host-side settings for the app’s CVMs, behind a feature flag. Not measured, so attestation does not cover them. See Annotations.
`launch_token`	String (Sensitive)	App launch token, at least 32 bytes. Stored in state. Phala Cloud and the node operator can read it. See Launch Token.
`generate_launch_token`	Boolean	Have Phala Cloud generate the launch token when `launch_token` is not set. The generated token is stored in state.

Changing port_policy, swap_size, storage_discard, snapshotter, event_log_version, requirements (except gpu_policy) or init_scripts updates the app in place and restarts its running CVMs. annotations are applied to the bootstrap CVM at create. A change replaces the whole map on the app’s existing CVMs, without a restart or a compose change. CVMs added later, such as phala_app_instance slots, start without them. Removing the attribute clears them. Changing launch_token sets the new token on the app first, then updates each CVM’s requirements.launch_token_hash. A CVM that restarts in between fails to boot until its compose is updated. Removing it removes the hash from every CVM, then clears the token.

Environment Variables

The provider offers two modes for managing environment variables. You must pick one — they cannot be combined in the same resource. Auto-encryption mode (recommended):

resource "phala_app" "web" {
  # ...
  env = {
    DATABASE_URL = "postgres://..."
    API_SECRET   = "s3cr3t"
  }
}

Attribute	Type	Description
`env`	Map of String, Sensitive	Plaintext env vars. The provider auto-derives `env_keys` and encrypts values before sending to the API.

Even in auto-encryption mode, plaintext values are stored in your Terraform state file. If you cannot tolerate plaintext in state storage, use manual encrypted mode instead.

Manual encrypted mode:

resource "phala_app" "web" {
  # ...
  encrypted_env = var.pre_encrypted_hex_blob
  env_keys      = ["DATABASE_URL", "API_SECRET"]
}

Attribute	Type	Description
`encrypted_env`	String, Sensitive	Hex-encoded encrypted env payload. Must be valid hex.
`env_keys`	List of String	Allowed environment variable keys for the encrypted payload.

On-chain KMS fields (advanced):

Attribute	Type	Description
`env_compose_hash`	String	Compose hash for phase-2 env update flow with contract-owned KMS.
`env_transaction_hash`	String	On-chain transaction hash for phase-2 env update flow.

Wait Behavior

Attribute	Type	Description
`wait_for_ready`	Boolean	Wait until the app reports running replicas before Terraform returns.
`wait_timeout_seconds`	Number	Timeout in seconds for the readiness wait.

Setting wait_for_ready = true is recommended for production workflows. Without it, Terraform returns immediately after the API call, and subsequent resources that depend on the endpoint may see incomplete values.

Read-Only (Computed) Attributes

Attribute	Type	Description
`app_id`	String	The Phala app identifier.
`id`	String	Terraform resource ID (same as `app_id`).
`primary_cvm_id`	String	Primary CVM identifier, used for patch operations and as input to `phala_cvm_power`.
`cvm_ids`	List of String	All CVM identifiers attached to this app.
`endpoint`	String	Primary public endpoint URL.
`status`	String	Current CVM status from the API.

Lifecycle Behavior

Force-New Fields

Changing any of these attributes destroys the existing resource and creates a new one:

name
region
listed
ssh_authorized_keys
storage_fs
kms
custom_app_id
nonce
node_id
runner, bash_script and requirements.gpu_policy (unreleased, see above)

In-Place Updates

These attributes can be updated without replacement:

size (CPU/RAM changes)
disk_size (grow only)
image (OS image swap via API patch)
docker_compose
pre_launch_script
replicas
env / encrypted_env
Compose runtime settings (public_logs, public_sysinfo, public_tcbinfo, gateway_enabled, secure_time)
Unreleased: the compose settings, init_scripts, annotations and launch_token described above

Replica Scaling

Set replicas to scale your app horizontally. All replicas share the same compose file, environment, and settings. The provider manages replica creation and deletion to match your desired count.

resource "phala_app" "api" {
  name     = "api-service"
  size     = "tdx.medium"
  region   = "US-WEST-1"
  replicas = 3

  docker_compose = <<-YAML
    services:
      api:
        image: myregistry/api:latest
        ports:
          - "8080:8080"
  YAML
}

Create Flow

The provider follows Phala’s two-step API: first POST /cvms/provision to allocate resources, then POST /cvms to commit the deployment. This happens automatically during terraform apply.

​Example Usage

​Required Attributes

​Optional Attributes

​Placement and Identity

​Infrastructure

​Compose Runtime Settings

​Compose Settings, Init Scripts, Annotations and Launch Token

​Environment Variables

​Wait Behavior

​Read-Only (Computed) Attributes

​Lifecycle Behavior

​Force-New Fields

​In-Place Updates

​Replica Scaling

​Create Flow

​Related

Example Usage

Required Attributes

Optional Attributes

Placement and Identity

Infrastructure

Compose Runtime Settings

Compose Settings, Init Scripts, Annotations and Launch Token

Environment Variables

Wait Behavior

Read-Only (Computed) Attributes

Lifecycle Behavior

Force-New Fields

In-Place Updates

Replica Scaling

Create Flow

Related