deployah

Deployah

WARNING: Deployah is experimental and under active development.

Deployah is a CLI tool that makes deploying applications effortless by leveraging Helm—no Kubernetes or Helm expertise required.

Installation

Using Nix (Recommended)

If you have Nix installed:

# Run directly without installation
nix run github:deployah-dev/deployah

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

Install with Go

go install deployah.dev/deployah@latest

Development

The flake is the canonical dev and CI interface. With direnv (.envrc uses use flake), tools load automatically 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

Tests

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

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

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

Build and run

nix build              # build the deployah binary
nix run . -- --help    # run without installing

CI

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

Format Nix files with nix fmt.

Prerequisites

Before using Deployah, ensure you have:

• Kubernetes cluster access (local or remote)

For local development, you can use kind or minikube.

Quick Start

1. Create a deployah.yaml manifest in your project root.

2. (Optional) Add a .env or .env.<envName> file for environment-specific variables.

3. Run Deployah:

   deployah deploy production
   

How It Works

Deployah transforms your simple deployah.yaml manifest into a complete Kubernetes deployment through an 8-phase pipeline:

flowchart LR
    %% Phase 1: Input Processing
    subgraph phase1["🔵 Phase 1: Input Processing"]
        direction TB
        A["📄 YAML"] --> B["🔍 Parse"] --> C["✅ Validate"]
    end
    
    %% Phase 2: Configuration Resolution
    subgraph phase2["🟣 Phase 2: Configuration Resolution"]
        direction TB
        D["🌍 Environment"] --> E["🔄 Variables"] --> F["⚙️ Defaults"]
    end
    
    %% Phase 3: Deployment
    subgraph phase3["🟢 Phase 3: Deployment"]
        direction TB
        G["📊 Helm Values"] --> H["🚀 Deploy"]
    end
    
    %% Connect phases with animated edges
    phase1 e1@--> phase2
    phase2 e2@--> phase3  
    
    e1@{animate: true}
    e2@{animate: true}
    %% Enhanced styling with better colors and effects
    style A fill:#e3f2fd,stroke:#1976d2,stroke-width:3px,color:#000
    style B fill:#bbdefb,stroke:#1976d2,stroke-width:3px,color:#000
    style C fill:#90caf9,stroke:#1976d2,stroke-width:3px,color:#000
    
    style D fill:#f3e5f5,stroke:#7b1fa2,stroke-width:3px,color:#000
    style E fill:#e1bee7,stroke:#7b1fa2,stroke-width:3px,color:#000
    style F fill:#ce93d8,stroke:#7b1fa2,stroke-width:3px,color:#000
    
    style G fill:#e8f5e8,stroke:#2e7d32,stroke-width:3px,color:#000
    style H fill:#4caf50,stroke:#2e7d32,stroke-width:4px,color:#fff
    
    %% Subgraph styling with better borders and backgrounds
    style phase1 fill:#f8f9ff,stroke:#1976d2,stroke-width:3px,stroke-dasharray: 8 4
    style phase2 fill:#faf5ff,stroke:#7b1fa2,stroke-width:3px,stroke-dasharray: 8 4
    style phase3 fill:#f0fff0,stroke:#2e7d32,stroke-width:3px,stroke-dasharray: 8 4
    
    %% Node styling with rounded corners and shadows
    classDef pipelineNode fill-opacity:0.95,stroke-opacity:0.9,rx:8,ry:8
    class A,B,C,D,E,F,G,H pipelineNode

The Pipeline

The deployment process is organized into three logical phases:

🔵 Phase 1: Input Processing

1. Parse → Read and validate your YAML manifest structure
2. Validate → Check against JSON Schema for correctness and type safety

🟣 Phase 2: Configuration Resolution

1. Resolve Environment → Select the right environment configuration based on CLI arguments and manifest definitions
2. Substitute Variables → Replace ${VARIABLES} with actual values using clear precedence rules
3. Apply Defaults → Fill in sensible defaults from schema patterns and resource presets

🟢 Phase 3: Deployment

1. Generate Helm Values → Convert to Helm-compatible format with proper resource mappings
2. Deploy → Use Helm to deploy to Kubernetes with monitoring and error handling

Each phase has specific error handling and validation, ensuring deployments are safe and predictable.

Design Principles

• Developer-First Experience: Prioritize simplicity and developer productivity over advanced features. Most applications follow similar deployment patterns, so Deployah provides sensible defaults and clear variable substitution.

• Layered Validation Strategy: Multi-layer validation with JSON Schema at the core. This provides standardized validation with clear error messages, supports API versioning, and allows for both schema and business rule validation.

• Explicit Variable Precedence: Clear, documented variable substitution hierarchy prevents confusion about which values take precedence and enables environment-specific overrides while maintaining security.

• Schema-Driven Defaults: Extract default values from JSON Schema rather than hardcoding them. This creates a single source of truth for validation and defaults, ensuring automatic consistency.

What Deployah Solves

• Kubernetes Complexity: Eliminates the need to understand Helm charts, Kubernetes manifests, or cluster-specific configurations. Deployah handles all the underlying complexity while providing a clean interface.

• Configuration Management: Single manifest file with environment-specific overrides, clear variable substitution, and explicit precedence rules. No more scattered configuration files or environment-specific scripts.

• Deployment Safety: Built-in validation prevents common deployment mistakes, ensures resource specifications are reasonable, and provides clear error messages with actionable suggestions.

• Team Consistency: Standardized deployment patterns across teams and projects, reducing onboarding time and preventing configuration drift between environments.

• Environment Management: Explicit environment selection prevents accidental deployments to wrong environments, with clear error messages guiding users to correct usage.

Under the Hood

Deployah uses a Helm chart library as its foundation, automatically generating the appropriate Kubernetes resources (Deployments, Services, Ingress, HPA) based on your component definitions. The tool handles all the Helm complexity while providing a clean, declarative interface.

Environments & Configuration

Deployah supports multiple environments (e.g., dev, staging, prod) for flexible deployments.

Minimal Example

You can omit the environments section for a single default environment:

components:
  my-app:
    image: my-image:${IMAGE}

Multiple Environments

If you define more than one environment, you must specify which one to use:

environments:
  - name: dev
    variables:
      FOO: bar
  - name: prod
    variables:
      FOO: baz
components:
  my-app:
    image: my-image:${IMAGE}

Selection rules:

• If environments is omitted, Deployah uses a built-in default environment.
• If only one environment is defined, it is used automatically.
• If multiple environments are defined, you must specify the environment argument: deployah deploy <name>.
• If you do not specify an environment argument and multiple environments exist, Deployah will show an error listing available environments.

Examples

# Deploy to production using default manifest path
deployah deploy production

# Deploy to staging with an explicit manifest path
deployah deploy staging -f ./path/to/deployah.yaml

Variable Substitution Precedence

When substituting variables in your deployah.yaml manifest, Deployah uses the following precedence (lowest to highest):

1. Environment Definition Variables:
   Defined in the variables field of the selected environment in your manifest.
2. Env File Variables:
   Loaded from the resolved environment file (e.g., .env.production).
3. OS Environment Variables:
   From your shell, with the DPY_VAR_ prefix (these override all others).

Example:

# In deployah.yaml
environments:
  - name: production
    variables:
      APP_ENV: manifest

# In .env.production
DPY_VAR_APP_ENV=envfile

# In your shell
export DPY_VAR_APP_ENV=osenv

The value used for ${APP_ENV} will be osenv.

Note: In deployah.yaml, reference variables without the DPY_VAR_ prefix (e.g., ${IMAGE}).

File Usage: Deployah vs. Application

• Deployah only reads deployah.yaml and .env files.
• Deployah only uses variables from .env that start with DPY_VAR_.
• Variables in .env (or .env.<envName>) that do NOT start with DPY_VAR_ are available for your application, but are ignored by Deployah.
• config.yaml and config.<envName>.yaml are ignored by Deployah (they're for your app).

Environment File Conventions

• Default environment:
  • Deployah uses .env for variable substitution (only variables starting with DPY_VAR_).
  • The application uses config.yaml for its configuration.
• Named environments:
  • Deployah uses .env.<envName> for variable substitution (e.g., .env.production).
  • The application uses config.<envName>.yaml for its configuration.

Example: Default and Named Environments

Default:

# deployah.yaml
components:
  my-app:
    image: my-image:${IMAGE}

# .env
DPY_VAR_IMAGE=my-image:latest
BAR=baz  # For your app, ignored by Deployah

# config.yaml (for your app)
someAppSetting: true

Named (production):

# .env.production
DPY_VAR_IMAGE=my-image:prod
DPY_VAR_API_URL=https://api.example.com
APP_SECRET=supersecret  # For your app, ignored by Deployah

# config.production.yaml (for your app)
someAppSetting: false
apiUrl: https://api.example.com

Why This Approach?

• Minimal for beginners, powerful for experts
• No accidental deployments to the wrong environment
• No magic or hidden defaults
• Easy to document and reason about

Available Commands

Deployah provides several commands for managing your deployments:

# Deploy to an environment
deployah deploy <environment>

# List available environments and components
deployah list

# Check deployment status
deployah status

# View application logs
deployah logs

# Validate your manifest
deployah validate

# Delete deployments
deployah delete

# Get help for any command
deployah <command> --help

Troubleshooting

Common Issues

Environment not found

Error: environment "production" not found

Solution: Check your deployah.yaml file for the correct environment name, or list available environments with deployah list.

Variable substitution failed

Error: variable ${IMAGE} not found

Solution: Ensure the variable is defined in your environment file (.env or .env.<envName>) with the DPY_VAR_ prefix, or in your shell environment.

Kubernetes connection failed

Error: unable to connect to Kubernetes cluster

Solution: Verify your kubectl configuration and cluster connectivity with kubectl cluster-info.

Helm chart generation failed

Error: failed to generate Helm values

Solution: Check your manifest syntax and ensure all required fields are present. Run deployah validate to check for issues.

Getting Help

For more details, see the documentation or run:

deployah --help
deployah <command> --help

Schema Reference

Deployah uses JSON Schema for validation. The schema defines the structure and validation rules for your deployah.yaml manifest.

• Schema Version: v1-alpha.1
• Schema Location: internal/manifest/schema/v1-alpha.1/manifest.json
• Environment Schema: internal/manifest/schema/v1-alpha.1/environments.json

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