helm-me 0.1.2

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

Open docs/quickstart.md for the full step-by-step guide, including a Python DSL example and importing an existing deployment.

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 --output deploy.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 docs/API.md for the field-level reference.

Documentation Map

• docs/quickstart.md — first deployment, first commands, and first import
• docs/advanced-settings.md — namespace, kubeconfig, params, secrets, storage, imports, local dev
• docs/API.md — 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

What users usually ask next

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 docs/advanced-settings.md.

How do I target another cluster or context? Pass --kubeconfig, --context, and optionally --namespace. You can also save defaults in .helm-me.toml. See docs/advanced-settings.md.

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 docs/quickstart.md.

How do secrets and storage work? secretEnv, inline secrets, SQLite volumes, PostgreSQL/Redis storage, and PVC uploads are covered in docs/advanced-settings.md.