deployah

Deployah

Deployah is a CLI that deploys apps to Kubernetes. You write a short spec. Deployah turns it into a running Helm release. That flow is Spec-to-Release: like Source-to-Image (S2I), but for the deploy step. S2I builds your image. Deployah runs your release.

The binary embeds the Helm and Kubernetes clients. It installs nothing in your cluster. You do not maintain a chart.

Who this is for

Deployah is for teams that already use Kubernetes and want a clear ownership boundary between the app and the platform.

• App / developer owns deployah.yaml: image, port, resources, expose intent, scaling, persistence, workers. No Kubernetes context. No real domain names.
• Platform owns deployah.platform.yaml: cluster contexts, domains, TLS, and profiles (placement, security, monitor labels, and related policy).

You still need a cluster you can reach (kubeconfig). Deployah talks to that cluster itself.

Use Deployah when

• You want multi-environment app deploys without maintaining a chart per app
• Platform policy (domains, TLS, profiles) should change without editing every app spec
• The common shapes are enough: Deployment/StatefulSet, Service, Ingress, HPA, PVC, workers, ServiceMonitor/PodMonitor

Do not use Deployah when

• You already have a Helm chart and release process you trust for that app
• You only need a one-shot (kubectl create deployment or helm install of a third-party chart)
• You need an operator-managed database or other specialized controllers

You operate Kubernetes yourself. Spec-to-Release replaces a per-app chart with a short app spec and a platform map.

For how Deployah compares to DevSpace, Werf, Score, Epinio, and Kubero, see docs/comparison.md.

Features

• Spec-to-Release - short deployah.yaml becomes a Helm release; no chart to maintain
• Ownership split - app owns the spec; platform owns contexts, domains, TLS, and profiles
• Any reachable cluster - uses your kubeconfig; installs nothing in the cluster
• One binary - embeds Helm and the Kubernetes client (no separate helm / kubectl required)
• Services and workers - HTTP services with Ingress, or role: worker without Service/Ingress
• Stateless and stateful - Deployments or StatefulSets, optional PVCs, volume resize
• Custom environments - name your own environments (local, staging, prod), plus prefix-matched targets like review/pr-123; platform maps each one to a cluster, domains, and TLS
• Profiles - platform policy for placement, security, resources, and scrape labels
• Autoscaling and health - HPA, ready/alive checks (HTTP/TCP or exec for workers)
• Metrics - ServiceMonitor / PodMonitor when Prometheus Operator is present
• Extras - custom manifests and CRDs under .deployah/
• Plan, then deploy - deployah plan inspects changes and is read-only; deployah deploy validates, runs guards, and runs Helm

Current limitations

• Deployah does not build images. Give it an image that already exists in a registry your cluster can pull from.
• Stateful with persistence needs Kubernetes 1.32 or newer. Deployah checks the API version and fails fast on older clusters. Identity-only stateful components have no such floor.
• The schemas are alpha. App manifests are at v1-alpha.5 and platform files at platform/v1-alpha.3; expect breaking changes between releases.

Contents

• Get it running
  • Installation
  • Requirements
  • Quick start
  • Examples
• Understand the model
  • How Deployah works
  • What Deployah decides for you
  • Concepts
• Look things up
  • Guides
  • Commands
  • Schema reference
• Contribute
  • Community
  • Development
  • License

Installation

Homebrew

brew install deployah-dev/tap/deployah

Using Nix (recommended)

If you have Nix installed:

# Run without installing
nix run github:deployah-dev/deployah

# Or add it to your flake.nix
inputs.deployah.url = "github:deployah-dev/deployah";

Install with Go

go install deployah.dev/deployah@latest

Requirements

Deployah is a single binary. You do not need the helm, kubectl, or kind command-line tools. Deployah includes Helm, the Kubernetes client, and Kind as libraries, so it talks to your cluster by itself.

• Deploy to a cluster you already have: you only need access to it (a kubeconfig). No container runtime is required.
• Use the built-in local cluster (deployah cluster up): you need a container runtime, either Docker or Podman. This is the only extra tool, and it is needed only for the local cluster.

Quick start

A full local deploy takes about five minutes. For the local cluster you need Docker or Podman running (see Requirements).

You do not need an existing Kubernetes cluster. Deployah can make a local one for you.

Deployah reads two files, with two different owners (see Who this is for):

• deployah.yaml - what to run. You write this one.
• deployah.platform.yaml - where it runs. In this walkthrough, deployah cluster up writes it for you. On a real cluster, a platform team writes it once.

1. Start a local cluster

deployah cluster up

This creates a small local Kubernetes cluster (using Kind) and gives it the context name kind-deployah.

2. Create a spec

Save this as deployah.yaml in an empty folder. It runs the public nginx image, so you do not need to build anything.

apiVersion: v1-alpha.5
project: my-first-app
components:
  web:
    image: nginx:latest
    port: 80
    environments: [local]   # deploy this component in the "local" environment
    expose: true

expose: true gives the component a hostname made from its name (here web.127.0.0.1.nip.io) with HTTPS, all decided by the platform file.

You do not write deployah.platform.yaml here: deployah cluster up already created it and registered the local environment with a domain and a Kubernetes context. See the platform file guide for its shape.

3. Deploy

deployah deploy local

4. See it running

# Show the status of your project
deployah status my-first-app

# Show the local cluster and the URLs you can open
deployah cluster status

deployah cluster status prints a ready-to-use URL for your app. Open it in your browser to see the nginx welcome page.

You can also stream the logs:

deployah logs my-first-app

5. Clean up

# Remove the app
deployah delete my-first-app local

# Stop and delete the local cluster
deployah cluster down

Next, read Concepts for the vocabulary, then pick the guide you need from Guides.

Examples

Runnable specs live under examples/. Start with examples/nginx: the same flow as the quick start, ready to copy.

How Deployah works

Deployah turns your deployah.yaml spec into a running Kubernetes deployment in three steps.

flowchart LR
    subgraph phase1["1. Read the spec"]
        direction TB
        A["YAML spec"] --> B["Parse"] --> C["Validate"]
    end
    subgraph phase2["2. Resolve config"]
        direction TB
        D["Pick environment"] --> E["Apply variables"] --> F["Merge platform / defaults"]
    end
    subgraph phase3["3. Deploy"]
        direction TB
        G["Build Helm values"] --> H["Install release"]
    end
    phase1 --> phase2 --> phase3

1. Read the spec. Deployah reads your deployah.yaml and checks it against a JSON Schema.
2. Resolve config. Deployah picks the environment you asked for, substitutes your variables, merges the platform file and any profiles, and fills in defaults.
3. Deploy. Deployah builds Helm values from your spec and installs a Helm release on your cluster. You do not write a Helm chart.

The spec is a smaller surface than the Kubernetes API on purpose, so step 2 adds fields you did not write. You can read the result before anything is applied:

deployah plan <environment>

deployah plan renders the chart and compares it with the previous release baseline selected by Helm, so it needs cluster access. Human output shows resource changes as YAML, hook tasks, and a Chart CRDs section for Helm's chart-CRD lifecycle. For an existing release it also compares that baseline with live cluster state (drift). Secret values stay hidden unless you pass --show-secrets, which reveals them in human output and in JSON. Use -o json for machine-readable output. For the resolved hostname, TLS mode, context, and runtime environment without a cluster, use deployah resolve <environment> (--output json for machine-readable output).

For how Deployah compares to similar tools (DevSpace, Werf, Score, Epinio, Kubero), see docs/comparison.md.

What Deployah decides for you

These are the defaults step 2 fills in. Most are overridable. deployah plan shows the rendered resources; deployah resolve shows hostname, TLS, and resolved runtime environment.

Deployah generates these common shapes: Deployment, StatefulSet, Service, headless Service, Ingress, HPA, PVC, ServiceMonitor, and PodMonitor. With tls.mode: selfSigned it also emits a TLS Secret for the hostname. Anything outside that set goes in as plain Kubernetes YAML under .deployah/; see custom manifests and CRDs.

Concepts

• Project. One app, with a name. The name prefixes the Kubernetes resources Deployah creates. It is the project field in your spec.

• Component. One deployable part of your project, such as a web service or a background worker. A project has one or more components.

• Role. What a component is for:

  • service: it serves traffic and can be exposed (the default).
  • worker: a long-running background task, not exposed.

• Task. Run-to-completion work (preDeploy, postDeploy, schedule, or manual). See Tasks.

• Kind. The component's kind field: stateless (the default) or stateful (StatefulSet with stable identity; optional per-pod volumes). This field has nothing to do with Kind, the tool that runs the optional local cluster. See Stateful workloads and Storage classes.

• Workload matrix. role and kind combine independently. Run-to-completion work is tasks:, not a component role.

  Capability	service+stateless	service+stateful	worker+stateless	worker+stateful
  Deployment	Y	-	Y	-
  StatefulSet	-	Y	-	Y
  ClusterIP Service	Y	Y	-	-
  Headless Service	-	Y	-	Y
  Ingress	Y	Y	-	-
  HPA	Y	Y	Y	Y
  Persistence	Y	Y	Y	Y
  Health (TCP/HTTP)	Y	Y	-	-
  Health (exec)	Y	Y	Y	Y
  ServiceMonitor	Y	Y	-	-
  PodMonitor	-	-	Y	Y

• Environment. A target such as dev, staging, or prod. Each environment can use a different cluster, different files, and different variables.

  The word environments appears in three places, and each one does a different job:

  Where	This guide calls it	What it does
  environments in the platform file	environment registry	Declares which environment names exist, and maps each to a cluster context, domains, and TLS
  environments at the top of deployah.yaml	environment overrides	Optional per-environment substitution variables and env file
  environments inside a component	environment filter	Restricts that component to the listed environments

• Resource preset. Set CPU and memory without Kubernetes units. Use resourcePreset: small instead of writing exact values. This is not the same as a profile.

• Profile. A named deployment policy owned by the platform team (node placement, security context, domain and resource ceilings, monitor labels, and more). Components select one or more with profiles: [...]. See Profiles.

• Health checks. Services get automatic TCP/HTTP ready and alive checks. Workers use process-exit by default, or optional health.alive.exec. See Health checks and Worker components.

• Bring your own image. Deployah does not build images. You give it an image that already exists in a registry your cluster can pull from. Build your image in CI (or locally), then let Deployah deploy it.

Guides

Field-level detail lives in docs/:

Commands

Run deployah <command> --help for the full details of any command. A complete, generated reference for every command and flag is in docs/cli/.

Deployah can also generate a shell completion script: run deployah completion (use -o to write it to a file). See deployah completion --help for details.

Global flags

These work with every command:

Working with apps

Working with the local cluster

Schema reference

Deployah validates your spec and platform file with JSON Schema.

• Manifest schema version: v1-alpha.5
• Manifest schema: internal/spec/schema/v1-alpha.5/manifest.json
• Manifest environments schema: internal/spec/schema/v1-alpha.5/environments.json
• Platform schema version: platform/v1-alpha.3
• Platform schema: internal/spec/schema/platform/v1-alpha.3/platform.json

For the latest schema and examples, see the schema directory in the repository.

Community

Use GitHub Discussions for questions, early ideas, and showcases. Use Issues for bugs, feature requests, and design proposals. See CONTRIBUTING.md for how to contribute code and docs. Report security issues privately using SECURITY.md.

• Questions: Q&A
• Ideas: Ideas
• Start here: Welcome to Deployah Discussions
• Contributing: CONTRIBUTING.md
• Security: SECURITY.md
• Code of conduct: CODE_OF_CONDUCT.md

Development

The Nix flake is the main dev and CI interface. With direnv (the .envrc uses use flake), the tools load when you enter the repo.

nix develop

Format, lint, and tidy

nix run .#fmt                  # format Go (gofumpt + gci)
nix run .#lint                 # golangci-lint
nix run .#lint-md              # markdownlint
nix run .#tidy                 # go mod tidy
nix run .#update-vendor-hash   # refresh vendorHash after go.sum changes

Tests

Unit and integration tests are split by build tag. Plain go test ./... skips the integration tests.

nix run .#test-unit          # unit tests with the race detector
nix run .#test-integration   # scenario tests in internal/testing

Coverage profiles are written to coverage-unit.out and coverage-integration.out.

Running e2e tests locally

You need Docker. The suite creates a Kind cluster named deployah and deletes it afterwards.

DEPLOYAH_E2E_FORCE=1 nix run .#test-e2e

Without Docker the suite skips. With CI=true it fails. Put e2e.yaml in scenarios/<name>/ to run that spec on Kind. Generate a skeleton with:

go test ./internal/e2e/ -tags e2e -run TestE2EFixtures/<name> -e2e.scaffold

-e2e.preserve keeps the namespace after a failure.

Build and run

nix build              # build the deployah binary
nix run . -- --help    # run without installing
nix run .#demo         # render docs/demo/tapes into docs/assets/ (see docs/demo)
nix run .#publish-demo # sync docs/assets/ to R2 (needs R2_* env vars)

CI

GitHub Actions runs flake validation, lint/fmt/tidy checks, nix run .#test-unit, nix run .#test-integration, and nix run .#test-e2e on pull requests and pushes to main. Commit deployah.yaml, expected/, e2e.yaml, and .deployah/ under scenarios/. CI reads those files from a clean checkout.

nix flake check   # runs the pre-commit hooks (lint, markdownlint, links, tidy, nixfmt)

Format Nix files with nix fmt.

License

Deployah is licensed under the Apache License 2.0.