helm-me 0.1.3

Python DSL and CLI for rendering and deploying simple Kubernetes apps.

helm-me

Define Kubernetes apps in Python or YAML, then deploy and operate them with one CLI.

helm-me is aimed at teams that want something lighter than a full Helm chart for day-to-day app deployments, but still want repeatable manifests, typed configuration, and operational commands such as ops pods, ops logs, ops shell, and ops port-forward.

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.

Before you start

• Python 3.11+
• Access to a Kubernetes cluster through a working kubeconfig
• kubectl for interactive commands such as shell, exec, cp, and port-forward

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

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 Quick Start guide for the full walkthrough, including a Python DSL example and importing existing deployments.

Common Tasks

Task	Command
Validate a spec	helm-me lint deploy.yaml
Print rendered manifests	helm-me render deploy.yaml
Deploy an app	helm-me deploy deploy.yaml --yes
List pods	helm-me ops pods <app>
Show pods, services, and ingresses	helm-me ops status <app>
Stream logs	helm-me ops logs <component> <app> -f
Open interactive shell	helm-me ops shell <component> <app>
Scale a component	helm-me ops scale <component> <replicas> <app>
Select the active app	helm-me app use <app>
Import an existing deployment	helm-me app import <name> --namespace <ns>
Generate a spec from a live deployment	helm-me app generate-spec <name> --fmt yaml

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.

• Quick Start — first deployment, first commands, and first import
• Advanced Settings — namespace, kubeconfig, params, secrets, storage, imports, local dev
• 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

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 Settings.

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

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 the Quick Start.

How do secrets and storage work? secretEnv, inline secrets, SQLite volumes, PostgreSQL/Redis storage, and PVC uploads are covered in Advanced Settings.