phala_app Resource

Reference for the phala_app resource — deploy and manage Phala Cloud apps with Docker Compose, environment variables, replicas, and CVM lifecycle.

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.

​

Related

• CVM Power Control
• Data Sources
• Examples