Templates

App templates are opinionated Helm charts that make it easy to deploy common workload types via podplane deploy. Each template handles the boilerplate - networking, TLS, ingress - so you only need to provide the basics like an app name and your container image.

podplane deploy <template> --name <name> --image <image>

Environment variables can be set with Docker-style -e / --env flags:

podplane deploy web --name hello --image ghcr.io/podplane/hello:latest \
  -e HELLO_MESSAGE="G'Day World!"

Use KEY=value to pass an explicit value, or KEY to read the value from the local environment. Environment variables are stored in the rendered Deployment and Helm release metadata, so use them for non-secret configuration only.

Templates may have component dependencies. If the required addon components aren’t installed, the CLI will prompt you to install them.

To update an existing app (e.g. to deploy a new image version), simply re-run podplane deploy with the same --name.

Under the hood deploy runs helm upgrade --install.

`web`

The web template deploys a web application with automatic TLS and ingress routing.

Component dependencies: traefik, cert-manager, gateway-api-crds

What You Get

A Deployment running your container alongside a Caddy sidecar for TLS termination
A ClusterIP Service exposing HTTPS (port 443)
A Gateway API HTTPRoute attached to the platform’s Traefik gateway
A cert-manager Certificate for pod-internal mTLS
A BackendTLSPolicy ensuring encrypted gateway-to-service traffic

Your app container serves plain HTTP on port 80 by default - the Caddy sidecar handles all TLS. No TLS configuration is needed in your app. Use --set app.port=<port> if your image listens on a different plain HTTP port.

Template values

Use podplane deploy flags for universal inputs such as app name, image, and environment variables.

The web template also supports the ergonomic routing flags --hostname and --path.

Template-specific values can be set with --set e.g.:

Value	Default	Description
`app.port`	`80`	Plain HTTP port exposed by the app container
`route.hostname`	`""`	External hostname for routing; `--hostname` maps here
`route.path`	`/`	URL path prefix for routing; `--path` maps here
`metrics.http`	`true`	Enable Caddy HTTP metrics

Example

podplane deploy web \
  --name hello \
  --image ghcr.io/podplane/hello:latest \
  --hostname hello.example.com \
  -e HELLO_MESSAGE="G'Day World!"

How It Works

External Traffic
  → HTTPRoute (hostname + path matching)
    → Traefik Gateway
      → BackendTLSPolicy (verified mTLS)
        → Service (:443)
          → Caddy sidecar (TLS termination, reverse proxy to localhost:<port>)
            → App container (<port>, plain HTTP)

The Caddy sidecar mounts a cert-manager-issued TLS certificate and reverse proxies to your app on 127.0.0.1:<port>. The BackendTLSPolicy verifies the connection from the gateway to the service using the platform’s self-signed CA bundle.

`worker`

The worker template deploys a background worker process with no ingress or TLS.

Component dependencies: None

What You Get

A Deployment running your container
No Service, no ingress, no TLS - the worker is not externally reachable

This is suitable for queue consumers, cron-like processors, or any workload that initiates its own outbound connections rather than serving HTTP traffic.

Template values

Use podplane deploy flags for universal inputs such as worker name, image, and environment variables. Worker-specific configuration should be exposed as schema-backed template values and set with --set.

Example

podplane deploy worker \
  --name email-sender \
  --image myorg/email-sender:latest \
  -e QUEUE=default

Template values contract

Every template chart must include values.schema.json. The schema is the contract for supported template values and is used by Podplane to validate common ergonomic flags before invoking Helm.

podplane deploy keeps a small stable set of universal flags: --name, --image, -e / --env, --namespace, Kubernetes context flags, and --auto-approve. These apply to deploy itself rather than to any one template.

Some flags are common ergonomic shortcuts for template values. Today --hostname maps to route.hostname, and --path maps to route.path. Because not every template supports routing, the deploy command checks the template’s values.schema.json and fails loudly if one of these flags is used with an unsupported template.

Template-specific configuration uses Helm-compatible --set syntax instead of dedicated Podplane flags:

podplane deploy web --name hello --image ghcr.io/podplane/hello:latest \
  --set app.port=8080

Seeds CLI Overview