helm-me

[!WARNING] helm-me is currently in beta. Core workflows are usable, but the CLI surface, YAML schema, Python DSL, and some generated output details may still change significantly between releases.

Define, deploy, and operate Kubernetes apps with a fast, developer-friendly workflow.

helm-me is aimed at developers who want to ship prototypes and internal apps to Kubernetes quickly, without spending more time on chart authoring than on the application itself. It provides a simple app spec in YAML or Python, operational commands for day-2 work, and a path to export a Helm chart when the project grows up.

helm-me sits between raw manifests, repetitive kubectl command sequences, and full Helm chart authoring. It focuses on developer experience: simple app definitions, fast deploys, convenient shell/log/copy workflows, and compatibility with Helm-oriented environments.

Why use it

• Write one app spec instead of hand-maintaining multiple Kubernetes manifests.
• Choose YAML for simple config-driven setups or Python for typed, parameterized specs.
• Use built-in components for web, postgresql, redis, and deploy hooks.
• Import existing deployments and manage them through the same CLI.
• Work with local dev clusters (kind, minikube, k3d) without pushing images first.
• Avoid memorizing long kubectl command sequences for common day-2 tasks.
• Keep moving fast during prototyping, then export to a Helm chart when you need a more standard handoff.

What problem does it solve?

For many small and medium projects, the first Kubernetes deployment is blocked less by the app itself and more by surrounding work:

• writing and maintaining Helm charts
• wiring together repetitive manifests
• remembering operational kubectl commands
• dealing with awkward workflows around minimal or distroless containers

helm-me tries to make Kubernetes feel like a higher-level application workflow: define the app once, deploy it quickly, inspect it with one CLI, and keep an upgrade path to Helm when needed.

When to use it

Use helm-me when:

• you want a simpler app workflow on Kubernetes
• you want to deploy prototypes, internal tools, demos, chats, APIs, or frontend apps quickly
• you want one tool for both deploys and common operational commands
• you want YAML for simple cases and Python when you need parameters or reuse
• you want a path to export a Helm chart later instead of writing one first

Avoid helm-me when:

• you specifically need the full Helm chart packaging and authoring model from day one
• you want GitOps reconciliation to be the primary operating model
• you are building a Kubernetes Operator rather than defining an application
• your team already has a strong, standardized chart platform and does not need a higher-level app workflow

Comparison

Compared with raw manifests:

• helm-me gives you a higher-level app spec, reusable components, and operational commands in one place

Compared with Helm:

• helm-me optimizes for developer speed and lower setup overhead during prototyping, while still keeping a path to export a chart later

Compared with plain kubectl workflows:

• helm-me reduces command memorization and wraps common day-2 tasks such as logs, shell, exec, copy, and port-forward behind app-aware commands

Prerequisites

Before you start, make sure you have:

• Python 3.11+ installed
• kubectl installed (used for interactive commands such as shell, exec, cp, and port-forward)
• A working Kubeconfig (e.g., from kind, minikube, k3d, or a remote cluster)

Installation

Choose one of these flows:

# Run without installing
uvx helm-me --help

# Install as a user tool
uv tool install helm-me
helm-me --help

# Or add it to the current project
uv add helm-me
uv run helm-me --help

All examples below use helm-me .... If you installed it with uv add, run them as uv run helm-me .... If you use uvx, run them as uvx helm-me .... If you use uv tool install, run them exactly as shown.

5-Minute Quick Start

Create a minimal deploy.yaml:

apiVersion: helm-me/v1alpha1
kind: Application
metadata:
  name: hello-app

components:
  backend:
    type: web
    image: traefik/whoami:latest
    port: 80

Validate, inspect, and deploy it:

helm-me lint deploy.yaml
helm-me render deploy.yaml
helm-me deploy deploy.yaml --namespace demo --yes

What you should see: helm-me deploy will render the manifests, create the namespace if it doesn't exist, build constraints, save the deployment in a local registry, and wait for pods to become ready.

Check that it is running:

helm-me ops pods hello-app
helm-me ops logs backend hello-app --tail 50
helm-me ops port-forward backend 8080 hello-app

See the Getting Started guide for the full walkthrough, including a Python DSL example and importing existing deployments.

Project status

helm-me is currently in beta. It is already useful for real prototyping and internal deployments, but you should expect some evolution in command naming, schema details, Python DSL helpers, and generated output.

Common Tasks

Which format should I choose?

Use YAML when:

• you want a simple declarative file
• non-Python users will maintain the spec
• you do not need dynamic parameters beyond static config

Use Python when:

• you want IDE autocomplete and type hints
• you need param()-based environment-driven configuration
• you prefer composing specs in code

Both formats support the same core concepts. See the API Reference for the field-level reference.

Documentation

Full documentation is available at teserak.github.io/helm-me.

• Getting Started — first deployment, first commands, and first import
• Tutorial — deploy, ops, ingress, secrets, storage, local dev
• Advanced — namespace, kubeconfig, params, imports
• API Reference — DSL and YAML reference for app fields, components, and helper constructors

Examples

• examples/minimal/ — smallest possible app in Python and YAML
• examples/full/ — multi-component app with ingress, secrets, and SQLite storage
• examples/with_dbs/ — PostgreSQL + Redis + backend example

FAQ

Is this a Helm replacement? Not exactly. helm-me is better understood as a higher-level application workflow for teams that do not want to start with chart authoring. It can still fit Helm-oriented environments and can export a chart when needed.

Why not just use raw manifests or kubectl? You can, but many teams lose time on repeated YAML structure, long operational commands, and ad hoc workflows around shell access, copying files, logs, and port-forwarding. helm-me tries to make those common tasks easier and more consistent.

Why not just start with Helm? For mature platforms, Helm is often the right end state. But for prototypes, internal tools, demos, and fast-moving apps, chart authoring can become heavier than the app itself. helm-me is meant to reduce that early overhead without blocking a later move to Helm.

Which namespace will be used? If the spec sets namespace, that value is used. If not, the default namespace is the app name. helm-me deploy --namespace ... overrides the spec for that deploy. Full rules are in Advanced / Cluster Config.

How do I target another cluster or context? Pass --kubeconfig, --context, and optionally --namespace. You can also save defaults in .helm-me.toml. See Cluster Config.

Can I manage something that was not deployed by helm-me? Yes. Use helm-me app import ..., optionally with --label when the app does not use standard labels. See Import Existing Deployments.

secretEnv, inline secrets, SQLite volumes, PostgreSQL/Redis storage, and PVC uploads are covered in Secrets & Environment.