Reorganize repo layout and pin provider 0.3.0-beta.4

- Move sources into components/ (sidecar plumbing), workloads/
  (patroni, webdemo), clusters/ (patroni-demo, new starter), support/,
  and docs/, from the flat top-level layout.
- Add clusters/starter: minimal API+worker peer-VIP/service-VIP demo.
- Pin phala-network/phala 0.3.0-beta.4 (official-Go-SDK build) in both
  clusters; refresh .terraform.lock.hcl.
- Update publish.yml path filters for the new components/workloads
  directory layout.

Verified on real cloud (patroni-demo, 8 CVMs): in-place env/compose
updates with no slot replacement, mesh data path (webdemo LB via
Consul+Envoy), and Patroni HA leader/replica.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: h4x3rotab

.dockerignore

@@ -3,16 +3,16 @@
 .local
 snapshots
 
-cluster-example/.terraform
-cluster-example/terraform.tfstate*
-cluster-example/terraform.tfvars
-cluster-example/*.backup
-cluster-example/*.bak
+clusters/*/.terraform
+clusters/*/terraform.tfstate*
+clusters/*/terraform.tfvars
+clusters/*/*.backup
+clusters/*/*.bak
 
-admission-broker/admission-broker
-admission-client/admission-client
-bootstrap-secrets/bootstrap-secrets
-mesh-conn/mesh-conn
-signaling/signaling
-signaling/icetest
-webdemo/webdemo
+components/admission-broker/admission-broker
+components/admission-client/admission-client
+components/bootstrap-secrets/bootstrap-secrets
+components/mesh-conn/mesh-conn
+components/signaling/signaling
+components/signaling/icetest
+workloads/webdemo/webdemo

.github/workflows/publish.yml

@@ -15,8 +15,8 @@ name: Publish service-mesh images
 #
 # `mesh-sidecar` is the consolidated platform-plumbing image. Its build
 # context is the repository root so its Dockerfile
-# can pull the Go sources from sibling subdirs. The other three images
-# build from their own subdirs.
+# can pull Go sources from component subdirs. The other three images
+# build from their workload/component subdirs.
 #
 # Verifying a published image (consumer side):
 #
@@ -28,25 +28,25 @@ on:
   push:
     branches: [main]
     paths:
-      - 'bootstrap-secrets/**'
-      - 'admission-broker/**'
-      - 'admission-client/**'
-      - 'mesh-conn/**'
-      - 'mesh-sidecar/**'
-      - 'patroni/**'
-      - 'webdemo/**'
-      - 'signaling/**'
+      - 'components/bootstrap-secrets/**'
+      - 'components/admission-broker/**'
+      - 'components/admission-client/**'
+      - 'components/mesh-conn/**'
+      - 'components/mesh-sidecar/**'
+      - 'components/signaling/**'
+      - 'workloads/patroni/**'
+      - 'workloads/webdemo/**'
       - '.github/workflows/publish.yml'
   pull_request:
     paths:
-      - 'bootstrap-secrets/**'
-      - 'admission-broker/**'
-      - 'admission-client/**'
-      - 'mesh-conn/**'
-      - 'mesh-sidecar/**'
-      - 'patroni/**'
-      - 'webdemo/**'
-      - 'signaling/**'
+      - 'components/bootstrap-secrets/**'
+      - 'components/admission-broker/**'
+      - 'components/admission-client/**'
+      - 'components/mesh-conn/**'
+      - 'components/mesh-sidecar/**'
+      - 'components/signaling/**'
+      - 'workloads/patroni/**'
+      - 'workloads/webdemo/**'
       - '.github/workflows/publish.yml'
   workflow_dispatch:
 
@@ -69,18 +69,16 @@ jobs:
       matrix:
         include:
           # `mesh-sidecar` builds with the parent dir as context so
-          # its Dockerfile can pull bootstrap-secrets/, mesh-conn/,
-          # admission-broker/, and admission-client/ Go sources from
-          # siblings.
+          # its Dockerfile can pull Go sources from components/.
           - name: mesh-sidecar
             context: .
-            dockerfile: mesh-sidecar/Dockerfile
+            dockerfile: components/mesh-sidecar/Dockerfile
           - name: patroni
-            context: ./patroni
+            context: ./workloads/patroni
           - name: webdemo
-            context: ./webdemo
+            context: ./workloads/webdemo
           - name: signaling
-            context: ./signaling
+            context: ./components/signaling
 
     steps:
       - uses: actions/checkout@v4
@@ -115,7 +113,7 @@ jobs:
           context: ${{ matrix.context }}
           # Most images use the default Dockerfile in the context.
           # `mesh-sidecar` overrides this to point at
-          # mesh-sidecar/Dockerfile while keeping the parent context.
+          # components/mesh-sidecar/Dockerfile while keeping the parent context.
           file: ${{ matrix.dockerfile || format('{0}/Dockerfile', matrix.context) }}
           platforms: linux/amd64
           push: ${{ github.event_name != 'pull_request' }}

.gitignore

@@ -8,17 +8,20 @@ snapshots/
 .env
 
 # Compiled Go binaries
-admission-broker/admission-broker
-admission-client/admission-client
-bootstrap-secrets/bootstrap-secrets
-mesh-conn/mesh-conn
-signaling/signaling
-signaling/icetest
-webdemo/webdemo
+components/admission-broker/admission-broker
+components/admission-client/admission-client
+components/bootstrap-secrets/bootstrap-secrets
+components/mesh-conn/mesh-conn
+components/signaling/signaling
+components/signaling/icetest
+workloads/webdemo/webdemo
 
 # Terraform local state. Keep .terraform.lock.hcl tracked.
-cluster-example/.terraform/
-cluster-example/terraform.tfstate*
-cluster-example/terraform.tfvars
-cluster-example/*.backup
-cluster-example/*.bak
+clusters/*/.terraform/
+clusters/*/terraform.tfstate*
+clusters/*/terraform.tfvars
+clusters/*/*.backup
+clusters/*/*.bak
+
+# Legacy local state after moving the demo cluster to clusters/patroni-demo.
+cluster-example/

CONTRIBUTING.md

@@ -16,30 +16,32 @@ Install:
 Validate the Terraform example:
 
 ```bash
-terraform -chdir=cluster-example init -upgrade
-terraform -chdir=cluster-example validate
+terraform -chdir=clusters/patroni-demo init -upgrade
+terraform -chdir=clusters/patroni-demo validate
+terraform -chdir=clusters/starter init -upgrade
+terraform -chdir=clusters/starter validate
 ```
 
 Run local Go tests:
 
 ```bash
-(cd admission-broker && go test ./...)
-(cd signaling && go test ./...)
-(cd webdemo && go test ./...)
+(cd components/admission-broker && go test ./...)
+(cd components/signaling && go test ./...)
+(cd workloads/webdemo && go test ./...)
 ```
 
 Run Go 1.24 module tests through Docker when needed:
 
 ```bash
-docker run --rm -v "$PWD:/src" -w /src/admission-client golang:1.24 go test ./...
-docker run --rm -v "$PWD:/src" -w /src/bootstrap-secrets golang:1.24 go test ./...
-docker run --rm -v "$PWD:/src" -w /src/mesh-conn golang:1.24 go test ./...
+docker run --rm -v "$PWD:/src" -w /src/components/admission-client golang:1.24 go test ./...
+docker run --rm -v "$PWD:/src" -w /src/components/bootstrap-secrets golang:1.24 go test ./...
+docker run --rm -v "$PWD:/src" -w /src/components/mesh-conn golang:1.24 go test ./...
 ```
 
 Build the main sidecar image:
 
 ```bash
-docker build -t service-mesh-mesh-sidecar-check -f mesh-sidecar/Dockerfile .
+docker build -t service-mesh-mesh-sidecar-check -f components/mesh-sidecar/Dockerfile .
 ```
 
 ## Pull Request Expectations

README.md

@@ -22,7 +22,7 @@ The default deployment is a public web backend plus a private HA
 PostgreSQL service. Every workload CVM must pass attestation admission
 before it receives Consul and Envoy credentials.
 
-![Default demo architecture](assets/demo-architecture.svg)
+![Default demo architecture](docs/assets/demo-architecture.svg)
 
 Applications use stable names such as `webdemo`, `postgres-master`, and
 `postgres-replica`; they do not need to know which CVM is currently
@@ -38,7 +38,7 @@ You need:
 
 ```bash
 git clone https://github.com/Dstack-TEE/service-mesh.git
-cd service-mesh/cluster-example
+cd service-mesh/clusters/patroni-demo
 cp terraform.tfvars.example terraform.tfvars
 export PHALA_CLOUD_API_KEY=phak_...
 terraform init -upgrade
@@ -106,7 +106,7 @@ mesh path. The database is private; it exposes `postgres-master` and
 
 ## Demo Inputs
 
-`cluster-example/terraform.tfvars.example` contains the default demo
+`clusters/patroni-demo/terraform.tfvars.example` contains the default demo
 values. Edit the copied `terraform.tfvars` when you want to change
 replica counts, cluster name, bootstrap endpoint, or image tags.
 
@@ -119,6 +119,39 @@ Public gateway URLs are derived from the Phala Terraform provider's
 `gateway_base_domain` attribute, so this template does not require a
 hardcoded gateway suffix.
 
+## Starter Template
+
+Use `clusters/starter` when you want the smallest custom mesh to copy:
+one public API workload group and one private worker workload group.
+It deliberately has no database and no Patroni role tags.
+
+```bash
+cd service-mesh/clusters/starter
+cp terraform.tfvars.example terraform.tfvars
+export PHALA_CLOUD_API_KEY=phak_...
+terraform init -upgrade
+terraform apply
+
+API=$(terraform output -raw api_url)
+curl "$API/hello"
+curl "$API/worker"
+```
+
+`/hello` returns the API instance identity. `/worker` makes the API call
+`http://worker:9090/hello` through the private mesh.
+
+## Repository Layout
+
+- `clusters/patroni-demo`: full demo cluster, including its Terraform
+  definition and compose files.
+- `clusters/starter`: minimal API + worker cluster template.
+- `components`: reusable platform components built into the sidecar or
+  support images.
+- `workloads`: demo workload images used by the Patroni demo.
+- `support`: helper services that are useful during bootstrap or local
+  operation but are not a cluster definition.
+- `docs`: architecture, operations, and design notes.
+
 ## Default Demo Topology
 
 This section describes the shipped demo only: a public web backend plus
@@ -181,15 +214,15 @@ flowchart LR
   coord -. admits .-> api2
 ```
 
-Declare workload groups, producer backends, and callable routes in
-`cluster-example/cluster.tf`:
+The starter cluster in `clusters/starter/cluster.tf` is a small version
+of this shape:
 
 ```hcl
 locals {
   workload_groups = {
     api = {
       replicas = 2
-      compose  = "${path.module}/../compose/api.yaml"
+      compose  = "${path.module}/compose/api.yaml"
       images   = { API_IMAGE = var.api_image }
       secrets  = {}
       backends = {
@@ -207,7 +240,7 @@ locals {
 
     worker = {
       replicas = 5
-      compose  = "${path.module}/../compose/job-worker.yaml"
+      compose  = "${path.module}/compose/worker.yaml"
       images   = { WORKER_IMAGE = var.worker_image }
       secrets  = {}
       backends = {
@@ -233,7 +266,7 @@ starts an egress Envoy on every workload CVM so calls work even when the
 caller does not host the target backend.
 
 Run each application container in its own group's compose file beside
-the existing `sidecar` service. For example, `compose/api.yaml` would
+the existing `sidecar` service. For example, `clusters/starter/compose/api.yaml` would
 contain:
 
 ```yaml
@@ -251,7 +284,7 @@ services:
         condition: service_healthy
 ```
 
-`compose/job-worker.yaml` would have the same sidecar and a `worker`
+`clusters/starter/compose/worker.yaml` would have the same sidecar and a `worker`
 service that binds `127.0.0.1:9090`.
 
 After deployment, code in either workload group can call:
@@ -274,7 +307,7 @@ For a backend port listed in `workload_groups`, avoid binding `0.0.0.0:<port>`.
 That also captures the local mesh address for the same port. Bind
 `127.0.0.1:<port>` for mesh traffic; if the same service is public
 through the Phala gateway, also bind the host interface address. The
-demo [`webdemo`](webdemo/main.go) shows that dual-bind pattern.
+demo [`webdemo`](workloads/webdemo/main.go) shows that dual-bind pattern.
 
 ## Service Definition Reference
 
@@ -335,7 +368,7 @@ identity `spiffe://<cluster>/api`.
 The shipped backend-plus-database demo uses
 `registration.owner = "workload"` for Postgres because runtime metadata
 belongs to Patroni. The sidecar still creates a Connect-aware stub so
-Envoy can start, but `patroni/entrypoint.sh` updates dynamic metadata
+Envoy can start, but `workloads/patroni/entrypoint.sh` updates dynamic metadata
 such as role tags and health checks. `postgres-master` and
 `postgres-replica` are two routes to one Patroni/Postgres backend:
 
@@ -344,7 +377,7 @@ locals {
   workload_groups = {
     postgres = {
       replicas = var.postgres_replicas
-      compose  = "${path.module}/../compose/postgres.yaml"
+      compose  = "${path.module}/compose/postgres.yaml"
       backends = {
         postgres = {
           port         = 5432
@@ -367,7 +400,7 @@ locals {
 
 Both routes share `backend = "postgres"` and select the same parent
 service, `var.cluster_name`. Patroni uses Consul for leader election,
-and `patroni/entrypoint.sh` runs the role-watcher that publishes the
+and `workloads/patroni/entrypoint.sh` runs the role-watcher that publishes the
 current `master` or `replica` tag. The Consul resolver for each route
 selects the matching tag, so clients keep dialing
 `postgres-master:5432` and `postgres-replica:5432` across failovers.
@@ -416,31 +449,33 @@ design.
 Validate Terraform:
 
 ```bash
-terraform -chdir=cluster-example init -upgrade
-terraform -chdir=cluster-example validate
+terraform -chdir=clusters/patroni-demo init -upgrade
+terraform -chdir=clusters/patroni-demo validate
+terraform -chdir=clusters/starter init -upgrade
+terraform -chdir=clusters/starter validate
 ```
 
 Run local Go tests:
 
 ```bash
-(cd admission-broker && go test ./...)
-(cd signaling && go test ./...)
-(cd webdemo && go test ./...)
+(cd components/admission-broker && go test ./...)
+(cd components/signaling && go test ./...)
+(cd workloads/webdemo && go test ./...)
 ```
 
 Some modules use Go 1.24. Run them through Docker if your host Go is
 older:
 
 ```bash
-docker run --rm -v "$PWD:/src" -w /src/admission-client golang:1.24 go test ./...
-docker run --rm -v "$PWD:/src" -w /src/bootstrap-secrets golang:1.24 go test ./...
-docker run --rm -v "$PWD:/src" -w /src/mesh-conn golang:1.24 go test ./...
+docker run --rm -v "$PWD:/src" -w /src/components/admission-client golang:1.24 go test ./...
+docker run --rm -v "$PWD:/src" -w /src/components/bootstrap-secrets golang:1.24 go test ./...
+docker run --rm -v "$PWD:/src" -w /src/components/mesh-conn golang:1.24 go test ./...
 ```
 
 Build the sidecar image:
 
 ```bash
-docker build -t service-mesh-mesh-sidecar-check -f mesh-sidecar/Dockerfile .
+docker build -t service-mesh-mesh-sidecar-check -f components/mesh-sidecar/Dockerfile .
 ```
 
 ## More Docs