Run a Workload on GCP

Step-by-step guide to deploy a Docker application as a dstack CVM on GCP with Intel TDX.

Run a Workload on GCP

Deploy a Docker application as a dstack CVM on GCP with Intel TDX. This page covers the full workflow — from configuration to verification — including how to choose between managed and self-hosted KMS endpoints.

---

Prerequisites

• A GCP project with Confidential VM quota enabled
  • Intel TDX Confidential VMs are available in select zones (for example us-central1-a)
• gcloud CLI installed and authenticated
  gcloud auth login
  gcloud config set project YOUR_PROJECT_ID
  
• Linux host for deployment (recommended)
• Docker installed
• gsutil available in PATH
• mtools (mcopy) and dosfstools (mkfs.fat) installed
• dstack-cloud CLI installed
  curl -fsSL -o ~/.local/bin/dstack-cloud \
    https://raw.githubusercontent.com/Phala-Network/meta-dstack-cloud/main/scripts/bin/dstack-cloud
  chmod +x ~/.local/bin/dstack-cloud
  

Why Linux + mtools + dosfstools? dstack-cloud deploy builds a shared FAT image and needs these tools in local environment.

---

Step 1: Configure dstack-cloud

Edit global config:

dstack-cloud config-edit

dstack-cloud uses JSON config (~/.config/dstack-cloud/config.json). Example:

{
  "services": {
    "kms_urls": ["https://kms.tdxlab.dstack.org:12001"],
    "gateway_urls": ["https://gateway.tdxlab.dstack.org:12002"],
    "pccs_url": ""
  },
  "image_search_paths": ["/path/to/images"],
  "gcp": {
    "project": "YOUR_PROJECT_ID",
    "zone": "us-central1-a",
    "bucket": "gs://YOUR_BUCKET_NAME"
  }
}

Create bucket if needed:

gcloud storage buckets create gs://YOUR_BUCKET_NAME --project YOUR_PROJECT_ID --location us-central1

KMS Options

Option	Description	When to Use
Phala Official KMS	Use managed KMS endpoints in services.kms_urls	Quick start, testing
Self-hosted KMS	Use your own KMS endpoint in services.kms_urls	Production, compliance, full control

For Self-hosted KMS, point services.kms_urls to your deployed KMS URL (see Run a dstack-kms CVM on GCP for how to set one up).

If you run with key provider tpm/none (no external KMS), remove .env in project and remove env_file from app.json.

---

Step 2: Pull the OS Image

For dstack-cloud-0.6.0, download both archives:

dstack-cloud pull https://github.com/Phala-Network/meta-dstack-cloud/releases/download/v0.6.0-test/dstack-cloud-0.6.0.tar.gz
dstack-cloud pull https://github.com/Phala-Network/meta-dstack-cloud/releases/download/v0.6.0-test/dstack-cloud-0.6.0-uki.tar.gz

Verify boot image file exists:

ls -lh /path/to/images/dstack-cloud-0.6.0/disk.raw

If disk.raw is missing, VM may boot-loop with UEFI Failed to load image.

---

Step 3: Create a Project

dstack-cloud new my-gcp-app --os-image dstack-cloud-0.6.0 --instance-name dstack-my-app
cd my-gcp-app

---

Step 4: Configure Project (app.json)

Update key fields in app.json:

• gcp_config.project
• gcp_config.zone
• gcp_config.bucket
• gcp_config.instance_name

Choose key provider mode:

• External KMS mode (recommended): "key_provider": "kms"
• No external KMS mode: "key_provider": "tpm" (or none)

Gateway options:

• If you use dstack gateway URL routing, keep gateway_enabled: true
• If you access service directly via VM public IP + opened port, set gateway_enabled: false

---

Step 5: Define Your Application

Edit docker-compose.yaml:

services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"

---

Step 6: (Optional) Add Environment Variables

If your app needs secrets/config, create .env:

API_KEY=your-api-key
DATABASE_URL=postgres://user:pass@host:5432/db

In KMS mode, env values are encrypted client-side and only decrypted inside CVM after attestation.

---

Step 7: Deploy

dstack-cloud deploy --delete

dstack-cloud will:

1. Prepare shared config files
2. Upload image artifacts to GCS
3. Create a GCP TDX Confidential VM
4. Start VM and run compose workload

First deployment usually takes several minutes.

---

Step 8: Open Firewall

Open app port(s):

dstack-cloud fw allow 8080

List firewall rules:

dstack-cloud fw list

---

Step 9: Verify

Check status:

dstack-cloud status

View logs:

dstack-cloud logs --follow

Access app:

• Direct VM mode (gateway_enabled=false):
  curl http://<EXTERNAL_IP>:8080
  
• Gateway mode (gateway_enabled=true): use URL printed in dstack-cloud status.

---

Managing Your Deployment

dstack-cloud logs
dstack-cloud stop
dstack-cloud start
dstack-cloud remove

---

Common Issues

Issue	Solution
Boot image 'dstack-cloud-0.6.0' not found locally	Ensure disk.raw exists under <image_search_paths>/dstack-cloud-0.6.0/
VM RUNNING but serial log shows UEFI load failures	Wrong boot image source; use official -uki.tar.gz image containing disk.raw
gsutil not found	Install Google Cloud SDK / ensure PATH
mcopy not found	Install mtools
mkfs.fat not found	Install dosfstools
.env found but KMS is not enabled	Remove .env and remove env_file from app.json, or set key provider back to kms
App not reachable immediately	Wait for compose startup to complete; check dstack-cloud logs

---

Next Steps

• Run a dstack-kms CVM on GCP
• Attestation Integration
• Run a Workload on AWS Nitro