TIMEWARP SKILL — deploy a generated app from its Aspire AppHost: the target matrix (Docker Compose, Kubernetes/Helm, Azure: AKS or Azure Container Apps), aspire publish / aspire deploy per target, operator-run dev deploy / dev deprovision / dev open / dev deploy migrate (never CI), a local kind recipe, production-safety rules, secrets and parameters, Postgres migrations per target, the ingress topology, and container-runtime neutrality. Invoke before deploying, before adding a publish target, or before touching publish-mode wiring in the AppHost. WHEN: deploy the app, dev deploy, dev deprovision, dev open, dev deploy migrate, open the deployed app, migrate the deployed database, tear down a deployment, kind cluster, aspire publish, aspire deploy, docker compose, Helm chart, Kubernetes, AKS, Azure, Azure Container Apps, ACA, Flexible Server, Key Vault purge, production secrets, run migrations in production, ingress controller, Podman.

Maintained in timewarp-architecture · Canonical file: SKILL.md

Install

With TimeWarp.Skills:

dnx TimeWarp.Skills -- add tw-deploy https://timewarp.software/

Add a harness target and skills sync (see the TimeWarp.Skills page). Or copy the SKILL.md into your agent's skills directory.

Deploy (Aspire publish targets)

The AppHost (source/container-apps/aspire/projects/aspire-app-host/program.cs) is the single source of truth for deployment. Every deployment artifact — docker-compose.yaml, .env, the Helm chart, the migration script — is generated by aspire publish / aspire deploy. There are no hand-written Dockerfiles, manifests, or charts, and there is no devops/ tree. The AppHost Design region holds the per-line reasoning; this skill is the operator's map.

Detection — when to invoke

Target matrix

One target per publish. Aspire assigns every compute resource to exactly one compute environment, so Compose, Kubernetes and Azure Container Apps are alternatives selected by configuration, never both in one model. Publish:Target is read in publish mode only; any other value throws. Run mode (dev run) always ignores it.

Publishing and deploying

aspire publish only writes files — no image build, no deploy, no container runtime needed. aspire deploy builds images through the detected container runtime and applies them.

# Compose (default target)
dev publish compose                         # publish to artifacts/aspire-output/compose + safety suite
aspire publish --apphost <apphost.csproj> --output-path out/compose
aspire deploy  --apphost <apphost.csproj>   # fills .env, builds images, brings the stack up

# Kubernetes (Helm chart)
dev publish kubernetes                      # publish to artifacts/aspire-output/kubernetes + safety suite + helm lint
aspire publish --apphost <apphost.csproj> --output-path out/k8s -- --Publish:Target=kubernetes
aspire deploy  --apphost <apphost.csproj> -- --Publish:Target=kubernetes   # helm upgrade --install, current kubectl context

# Azure Container Apps (Bicep) — publishing needs no Azure credentials
dev publish aca                             # publish to artifacts/aspire-output/aca + safety suite
aspire publish --apphost <apphost.csproj> --output-path out/aca -- --Publish:Target=aca
aspire deploy  --apphost <apphost.csproj> -- --Publish:Target=aca   # provisions + pushes images, az CLI credential

• Kubernetes prerequisites: Helm ≥ 4.2, a kubectl context pointing at the cluster, a container registry the cluster can pull from (registry-endpoint + registry-repository parameters), and an ingress controller already installed in the cluster.
• Generated output is never committed. dev publish writes under artifacts/ (git-ignored); CI uploads the output as a workflow artifact. Regenerate, do not hand-edit.
• dev publish <target> is the gate. It runs the target's production-safety suite in aspire-tests against the generated files. Run it after any change to publish-mode wiring.
• Deploying is a deliberate, operator-run action — never automated in CI. CI publishes and runs the production-safety suites only; it never runs aspire deploy, helm upgrade or docker compose up against a real environment. A deploy is run by an operator who has chosen the target, the context and the parameter values, with dev deploy (below).

Deploying: dev deploy, dev deploy migrate, dev open, dev deprovision

dev deploy / dev deprovision are thin, operator-run wrappers over aspire deploy / aspire destroy for one Publish:Target; dev deploy migrate and dev open are the two steps after a deploy (apply the migrations, reach the app), keyed on the same --target. No CI job, workflow step or dev workflow mode calls them, and none may. A merge never deploys.

dev deploy                                  # compose (the Publish:Target default): preflight, plan, prompt
dev deploy --target kubernetes              # Helm chart to the CURRENT kubectl context
dev deploy --target aca                     # Azure Container Apps in the az CLI's subscription (az login first)
dev deploy --target compose --yes           # no prompt: aspire deploy --non-interactive

dev deploy migrate --target kubernetes      # psql the published migration script into the deployed postgres
dev open --target kubernetes                # port-forward the ingress controller and open the browser

dev deprovision --target kubernetes         # preflight, then aspire destroy asks before deleting
dev deprovision --target kubernetes --yes   # aspire destroy --yes --non-interactive — deletes the deployment and its data
dev deprovision --target aca                # aspire destroy, then purge the soft-deleted Key Vault

• dev deploy runs aspire deploy --apphost <csproj> --environment Production -- --Publish:Target=<target> --Parameters:<name>=<value> …, forwarding the target's deploy parameters (below) after the preflight (below). It then asks for confirmation; --yes skips the prompt and adds --non-interactive. Without a terminal and without --yes it refuses. Aspire runs attached to the terminal, so a prompt it still shows (e.g. aca's location and resource group) works. For aca the preflight requires az login and prints the subscription and where it came from, in this order: the Azure__SubscriptionId environment variable, then the AppHost user secret Azure:SubscriptionId (read with dotnet user-secrets list --project <apphost>), then the one az account show reports. Only that last fallback is passed to aspire deploy as Azure__SubscriptionId, so the az CLI never overrides a subscription you pinned. A subscription Aspire remembered in its own deployment state is not checked; pin it in user secrets if az account may point elsewhere. Location and resource group come from Azure__Location / Azure__ResourceGroup, or Aspire's prompt.

• Deploy configuration is committed in the AppHost appsettings.json Parameters section. The kubernetes target needs k8s-namespace, helm-release-name, registry-endpoint and registry-repository (the AppHost parameters without a default in code); compose and aca need none. None of them is a secret. The template sets the three that identify the app — k8s-namespace, helm-release-name, registry-repository — to the app's kebab name (a DNS-1123 label: Contoso.Shop → contoso-shop), and registry-endpoint to localhost:5001, the kind recipe's registry, so a kind deploy needs no configuration:

  "Parameters": {
    "k8s-namespace": "contoso-shop",
    "helm-release-name": "contoso-shop",
    "registry-endpoint": "localhost:5001",
    "registry-repository": "contoso-shop"
  }
  

  A value that differs per machine or target overrides the committed one in the AppHost user secrets — typically registry-endpoint for AKS, an Azure Container Registry login server (pwsh):

  dotnet user-secrets set 'Parameters:registry-endpoint' 'myregistry.azurecr.io' --project <apphost.csproj>
  

  or for one session with a Parameters__<name> environment variable (${env:Parameters__registry-endpoint} = 'myregistry.azurecr.io'; the name is matched case-insensitively). dev deploy resolves each in the order Aspire's configuration does — environment variable, then user secret, then appsettings.Production.json (none ships), then appsettings.json — and the plan prints each value and that source. A user secret left over for a committed value keeps winning; remove it with dotnet user-secrets remove 'Parameters:<name>' --project <apphost.csproj>. The values appear in the aspire command line, so a forwarded parameter is never a secret — secrets (postgres-password, the Entra client secret) stay in user secrets or env vars, never in appsettings.json.

• Preflight runs before aspire and reports every problem at once, then exits non-zero with nothing run: Aspire CLI ≥ 13.6; for kubernetes, Helm ≥ 4.2, a current kubectl context (printed — check it) whose API answers (kubectl get --raw /version), every required parameter set (each missing one is listed with the command that sets it), and for a kind context (kind-<cluster>) that kind get clusters lists the cluster and the registry at registry-endpoint answers its /v2/ API. The API and registry checks give up after 5 seconds and every other probe after 20 (e.g. a credential plugin waiting for a login), reported as timed out; if a parameter is missing and dotnet user-secrets list failed, the report says the secrets could not be read.

• Any kubectl context works — AKS, an on-prem cluster, or a local kind cluster. dev deploy never creates a cluster, installs an ingress controller or switches context.

• dev deploy migrate applies the published idempotent migrations (safe to re-run) for the target, after a confirmation (--yes skips it; without a terminal and without --yes it refuses), prints one summary line, and exits with the underlying tool's exit code. It runs the file dev publish <target> wrote under artifacts/aspire-output/<target>/efmigrations/; when that is missing it refuses with the exact dev publish <target> command rather than publishing for you (publishing is its own gated step, and you should know which script runs). Per target it runs what the Postgres and migrations table below lists: compose — the running Compose project from <runtime> compose ls (--project-name picks one when several run; the runtime is ASPIRE_CONTAINER_RUNTIME, else docker); kubernetes — kubectl exec in the k8s-namespace parameter's namespace on the current context (same preflight as dev deploy, minus Helm and the registry); aca — the bundle through a temporary firewall rule that is always deleted, even on failure (Azure Container Apps below).

• dev open opens the deployed app in the browser (--no-browser prints the URL; with no opener on PATH it prints it too — on WSL it uses wslview, then explorer.exe). kubernetes: if the ingress controller's Service has an external (LoadBalancer) address, it opens that; otherwise it runs kubectl port-forward --namespace ingress-nginx service/ingress-nginx-controller 8080:80 in the foreground, opens http://localhost:8080, and Ctrl+C stops the forward. --port picks another local port (a taken one is refused with that hint); --controller-namespace / --controller-service name a controller other than the kind recipe's. compose: http://localhost:<port> from INGRESS_PORT in the published .env, else the ingress-port parameter (default 8080). aca: https://<fqdn> of the ingress container app (az containerapp show --name ingress --resource-group <rg> --query properties.configuration.ingress.fqdn).

• aca resource group for both: --resource-group, else Azure__ResourceGroup, else the AppHost user secret Azure:ResourceGroup — the values dev deploy --target aca uses; the subscription comes from the same preflight as dev deploy.

• dev deprovision runs aspire destroy for the same target after the same preflight, minus the registry check (for kubernetes it prints the kubectl context first). Deploy parameters are optional there: each one that is set is forwarded the same way (--Parameters:<name>=<value>), and a missing one is never refused. It deletes the deployment's data (Compose volumes, the Kubernetes postgres claim), so Aspire asks for confirmation; --yes skips the prompt. Without a terminal and without --yes it refuses.

• aspire destroy is local. It only knows deployments that aspire deploy recorded on the machine — and from the checkout — that deployed. When it fails, dev deprovision prints the manual removal for the target and exits with Aspire's exit code: <runtime> compose down --volumes for the Compose project (<runtime> compose ls finds it), or helm uninstall <release> --namespace <namespace> (the AppHost's helm-release-name and k8s-namespace parameters) plus deleting the postgres-data PersistentVolumeClaim, or for aca az group delete --name <resource-group> (az asks for confirmation) plus the Key Vault purge below. It never falls back to a destructive command on its own.

• Runtime: Compose deploy and teardown go through Aspire, so ASPIRE_CONTAINER_RUNTIME picks the runtime; the verbs call no container CLI themselves (the registry check is an HTTP request).

• Without the dev CLI (it lives in the template's source repository), run the same commands the verbs wrap, and do the preflight yourself (helm version, kubectl config current-context, kubectl get --raw /version):

  aspire deploy  --apphost <apphost.csproj> --environment Production -- --Publish:Target=<target> --Parameters:<name>=<value>
  aspire destroy --apphost <apphost.csproj> --environment Production -- --Publish:Target=<target> [--Parameters:<name>=<value>]
  

  When aspire destroy fails or reports nothing to destroy, nothing was removed; use the manual removal above. dev deploy migrate runs the commands in the Postgres and migrations table, and dev open runs kubectl port-forward --namespace ingress-nginx service/ingress-nginx-controller 8080:80 (kind) and opens http://localhost:8080.

Local Kubernetes with kind

A kind cluster is just another kubectl context: give it a local registry the nodes can pull from, install ingress-nginx once as cluster infrastructure, then deploy, migrate and open. The full pwsh and bash recipe (registry, cluster, node registry mapping, ingress, deploy, tear down) is in local-kubernetes-with-kind.md.

Production-safety rules

These never appear in published output. Each is enforced by the target's aspire-tests suite — extend the suite when you add a new publish-mode branch.

Rules for new code:

• Gate publish-only behavior on builder.ExecutionContext.IsPublishMode / IsRunMode, never on a template flag — every flag combination must publish.
• Anything dev-convenient (REPL, mock auth, log forwarding, dashboard commands) is run-mode or Development-only. Publish runs as Production.
• Without the yarp flag there is no ingress: the published output exposes nothing, and the operator adds their own edge.

Secrets and parameters

Every value that differs per deployment is an AddParameter, never a literal in code; a non-secret default every machine shares (the app's identity) is committed in the AppHost appsettings.json Parameters section, not in the AddParameter call. Secrets are AddParameter(name, secret: true) (or a generated secret such as Postgres' password).

• Non-secret deploy configuration that names the app is committed in the AppHost appsettings.json Parameters section (see Deploying). Per-machine values and secrets go in AppHost user secrets Parameters:<name> or Parameters__<name> environment variables, which override the committed value. dev deploy refuses until the target's required ones resolve and forwards them to Aspire; interactive aspire deploy prompts for any other unset parameter.
• Parameters such as ingress-class, postgres-storage-capacity and helm-chart-version are baked into the chart at publish time; change them by re-publishing, not helm --set.
• Under a plain helm install (no aspire deploy), the Postgres password appears under two keys — secrets.postgres.postgres_password and secrets.web_server.postgres_password — and both must carry the same value. aspire deploy fills both from the one parameter.
• Entra settings (entra-enabled, entra-tenant-id, entra-client-id, entra-client-secret, entra-public-origin) are parameters with Entra off by default; a passkey-only deployment needs none of them.

Postgres and migrations per target

Migrations are explicit in every deployed environment: the AppHost never auto-migrates a deployment. web-server does not migrate at startup and tolerates a not-yet-migrated database. The published idempotent SQL script (efmigrations/web-migrations.sql) is safe to re-run.

Apply them with dev deploy migrate --target <target> (Deploying above). The last column is what it runs — run it yourself in a generated app without the dev CLI (<runtime> is docker or podman; dev deploy migrate passes the running project's --project-name and --file from <runtime> compose ls):

The script is piped on stdin (< efmigrations/web-migrations.sql in bash; in pwsh Get-Content -Raw efmigrations/web-migrations.sql | <command>).

• Run the script after the database is up and before (or right after) the app starts serving.
• Compose also publishes the self-contained migration bundle; it is a host binary, not an image, so the SQL script is the default path. The Helm chart carries the script only — Helm rejects chart files over 5 MiB.
• -T / -i with PGPASSWORD from the container's own environment is required: the image enforces password auth even on the in-container socket, and a piped session cannot prompt.

Ingress topology

All public traffic enters through the YARP ingress, which owns the routing table (generated web /api prefixes, the api catch-all, /grpc prefix strip, and the public-host forwarding for web routes). The routing is therefore identical in run mode, Compose and Kubernetes.

• Public host travels in X-Forwarded-Host. YARP sends the destination host as Host on every route and sets X-Forwarded-Host to the browser's host on web-server routes, overwriting any value the client sent. web-server reads it only to select the passkey RP ID from WebAuthn:AllowedRpIds; a value outside that list is rejected. Nothing else consumes forwarded headers (no UseForwardedHeaders). If you put another proxy in front of the ingress, it may set X-Forwarded-Host too; YARP still overwrites it with the Host it received, so make that proxy preserve the public Host.

• Compose: the ingress is the only service with a host port. Put TLS in front of it (your reverse proxy or load balancer).

• Azure Container Apps: the ingress container app is the only one with external ingress (ACA terminates HTTPS on its public FQDN); web, api and grpc have internal ingress only.

• Kubernetes: the chart carries one networking.k8s.io Ingress (cluster-ingress) whose default backend is the YARP ingress' http endpoint. TLS terminates at the cluster's ingress controller. The class is the ingress-class parameter (default nginx).

• The chart does not install an ingress controller. A controller is cluster-scoped infrastructure; an app chart that installs one collides with every other release. Install one per cluster.

• Do not replace YARP with per-service controller routes. That forks the routing table into a second implementation per target and loses the X-Forwarded-Host overwrite and the /grpc prefix strip, which every controller vendor expresses differently.

• Behind any proxy that terminates TLS, set Authentication:Entra:PublicOrigin on web-server explicitly when Entra is on; it is not derived from the ingress URL.

Azure

An existing AKS cluster is a Kubernetes target: point the kubectl context at it, use the cluster's registry (for example an Azure Container Registry) as registry-endpoint, choose the controller's class as ingress-class, and run the Kubernetes commands above. The Kubernetes target uses nothing Azure-specific, so the same chart runs on any cluster.

• Do not use AddAzureKubernetesEnvironment. It provisions and owns the cluster (aspire destroy deletes it), ties cluster lifecycle to one app, and its documented ingress path depends on preview features. Share an existing cluster instead.
• Do not host Postgres data on ACA container volumes. They are Azure Files (SMB) shares; a database belongs on a managed Postgres service there.
• Adding any Azure-provisioning environment is a new Publish:Target value with its own production-safety suite — follow the same pattern as the existing targets, never a second environment beside them.

Azure Container Apps (Publish:Target=aca)

Choose ACA for a small or mostly idle app with no cluster to share; choose AKS (the Kubernetes target) when a cluster exists, is shared, or the deployment must stay portable. The publish-only AppHost provisions a Container Apps environment (no dashboard), ingress/web/api/grpc container apps (only the ingress external) and an Azure Database for PostgreSQL Flexible Server whose firewall rule is AllowAllAzureIps (the admin password is the barrier; aca-publish-tests pins the rule). Deploy with dev deploy --target aca, migrate with dev deploy migrate --target aca --resource-group <rg>, open with dev open --target aca --resource-group <rg>, remove with dev deprovision --target aca.

Cost model, what the AppHost provisions, the deploy commands, the migration bundle by hand (firewall rule, connection string), where the Postgres credentials live, expected deploy problems (slow first deploy, "Server is busy", soft-deleted Key Vault names, web hop host) and deprovision detail: azure-container-apps.md.

Container-runtime neutrality

• Generated Compose output is a standard compose file: Docker Compose, Podman Compose, or any compliant runtime runs it.
• Aspire picks the runtime it detects; ASPIRE_CONTAINER_RUNTIME overrides it (docker, podman). Tooling must go through Aspire's runtime selection — never hard-code the docker CLI in scripts or dev commands.
• aspire publish needs no runtime at all, so publish gates run anywhere; only aspire deploy and image builds need one. New runtimes (for example WSL containers) become usable when Aspire supports them, with no AppHost change.

Related

• AppHost program.cs Design region — per-decision reasoning behind every rule above.
• tools/dev-cli/endpoints/deploy-command.cs / deprovision-command.cs — dev deploy / dev deprovision; their Design regions record the preflight and the aspire destroy hand-off.
• tools/dev-cli/endpoints/deploy-migrate-command.cs / open-command.cs — dev deploy migrate / dev open; services/deploy-operate.cs records why migrate refuses instead of publishing, how the Compose project is found, and the firewall-rule cleanup.
• aspire-tests compose-publish-tests / kubernetes-publish-tests / aca-publish-tests — the production-safety suites.