Piceli

Kubernetes infrastructure as typed Python: model it, plan it, apply it safely, and observe it

Documentation: https://docs.pynenc.org/projects/piceli/en/stable/

Source Code: https://github.com/pynenc/piceli

Piceli describes a Kubernetes application in typed Python, shows you exactly what would change in the cluster, and applies only the plan you approved. Every change is journaled, so an interrupted deploy resumes where it stopped and a bad release rolls back. One command, piceli deploy, takes an app from source to a running, checked release; piceli status and piceli access tell you whether it is up and forward its ports to your laptop.

It is a Python-native alternative to hand-maintained YAML, Kustomize overlays and Helm templates, and it also runs the delivery loop: a GitOps controller, one environment per branch and a web UI. It still accepts plain YAML/JSON and kubernetes client objects, so you can migrate gradually; piceli publish, piceli render --out and piceli chart export OCI artifacts, manifests and Helm charts when a cluster wants them. When to use Piceli lists what it covers and its current limits, and the same app in Piceli, Helm, Kustomize, cdk8s and Pulumi compares them side by side (a CI test checks that all five render the same objects).

Status: pre-alpha. APIs change between releases, always with a changelog entry. Each documentation page states its maturity (stable, preview or experimental); the roadmap lists them all.

What's new in 0.4.0

• piceli deploy: build, deliver by digest, plan, apply and check in one journaled, resumable run that skips every unchanged stage.
• Post-deploy checks (http, exec, metric, Python) with automatic rollback when one fails.
• Field-level diffs and true no-op plans (piceli release diff).
• piceli status and piceli access: is the app up, which URLs, and supervised loopback port forwards declared in the model.
• piceli import live|yaml: turn a running namespace or a folder of manifests into a typed app module.
• One engine: the legacy delete-and-recreate engine is gone; every change goes through server-side apply, the journal and resume.

See the changelog for the complete list, including breaking changes.

Web UI

Piceli's experimental web workspace connects infrastructure, configuration, source versions and deployment evidence:

• Infrastructure overview: explore source → component → environment relationships, inspect a selected component, compare commits and image digests across environments, and follow reported problems to their workloads.
• Sources and environments: compact repository/ref rows link directly to their components and environments. Full revisions, polling errors, health and the existing Sync, Promote, Approve and Wake flows remain accessible.
• Applications and resources: searchable cards or tables, Kubernetes ownership diagrams, configuration and conditions, scoped container logs and supervised access forwards.
• Deployment history: previous saved plans, including expired reviews and plans without recorded runs. Open a plan for its execution order, dependencies and searchable resource diffs; compare desired configurations between recorded revisions.
• Runs and logs: per-resource outcomes, visual journal transitions, captured diagnostic output, raw journal evidence and recovery links.
• Cluster, GitOps and Pipelines: node/controller/registry status, branch state and exact-plan approvals, including the separate approval after image delivery. Actions depend on the session's configured permissions.

From a source checkout, with uv, Node.js and npm installed, open the current UI with one command:

make ui

It builds the production frontend and opens a disposable sample workspace, normally at http://127.0.0.1:4178. No cluster or credentials are required; plain bookmarks and fresh browsers work. Keep the terminal running and press Ctrl+C to stop. If the default port is busy, the command prints and opens the free port it selected.

For your own cluster, install piceli[ui] and name the target explicitly:

pip install "piceli[ui]"
piceli ui serve --kubeconfig /absolute/path/config --context my-context --namespace my-app

Open the launch URL printed by this real-target service, including its one-time token. Use --profile NAME for a saved credential profile, or the UI guide for trusted release/Pipeline definitions and in-cluster installation. Composition users open an installed UI with piceli access ui --cluster infra.py:my_cluster.

Screenshots and recording use disposable contributor fixtures. History shows plans and execution evidence saved by the service; missing snapshots and uncaptured output are labelled explicitly. Captured logs retain their separate logs permission, and opening a historical plan does not renew its approval.

See the web UI guide for the navigation map and the in-cluster installation guide for OIDC and deployment permissions. The workspace supports Light, Dark and System appearance, keyboard search with Ctrl/⌘ K, and desktop, tablet and phone layouts.

GitOps and per-branch environments (0.13.0)

piceli gitops enable installs a controller in the cluster that polls your Git repository and keeps one environment per branch at its head, with the same plans, approvals and checks as piceli deploy. piceli env and piceli envs create, list and tear down those environments, and piceli promote deploys a reviewed commit to main. See GitOps and Environments. The controller is experimental.

Installation

pip install piceli        # or: uv add piceli

Python 3.12 or later. Optional extras: piceli[telemetry] (OTLP deployment telemetry), piceli[gcp] (GKE cluster helpers) and piceli[aws] (AWS Secrets Manager as a secret source). The PyPI release can lag behind main while the project is pre-alpha; to follow main: pip install git+https://github.com/pynenc/piceli.git.

Quick start

You need a cluster reachable through an explicit kubeconfig file, and kubectl on your PATH (for checks and port forwards). A disposable kind cluster works:

kind create cluster --name hello --kubeconfig hello.kubeconfig
kubectl --kubeconfig hello.kubeconfig create namespace hello

Describe the app, where it runs and how to check it in app.py:

from piceli import App, Checks, Pipeline, Target

target = Target.kubeconfig(
    "hello.kubeconfig",  # an explicit file; never ~/.kube/config
    context="kind-hello",  # an explicit context; never current-context
    namespace="hello",
)

app = App("hello")
web = app.deployment(
    "web",
    image=(
        "docker.io/library/nginx:1.27"
        "@sha256:6784fb0834aa7dbbe12e3d7471e69c290df3e6ba810dc38b34ae33d3c1c05f7d"
    ),
    ports=[80],
    ready=app.probe.http("/", 80),
)
app.service(web, port=80, access=app.access.forward(local=18080, health="/"))

pipeline = Pipeline(app, target, checks=Checks.http(web, "/", expect=200))

Render it, review the plan, approve that exact plan, and reach the app:

piceli render app.py:app --namespace hello   # the manifests; never contacts a cluster
piceli deploy app.py:pipeline --plan         # what would change, and a combined hash
piceli deploy app.py:pipeline --approve <combined-hash>   # runs exactly that plan
piceli status app.py:pipeline                # is it up, and at which URLs
piceli access app.py:pipeline                # forwards http://127.0.0.1:18080/

Run piceli deploy again without changes and the plan reports no changes, so nothing is applied. Change the app and only what changed moves. If a run is interrupted, piceli deploy app.py:pipeline --resume continues it.

Next steps:

• Getting started walks through the same app step by step.
• Deploy an app from source adds pinned image builds and delivery to a registry or node.
• Releases from a spec covers release.toml, adoption, secrets, rollback and resume.
• From kubectl scripts to Piceli imports what already runs in a namespace.

Key features

• Typed apps: Deployments, Services, config, secrets, volumes and network policies declared with piceli.App, validated as you write them. Templates, kubernetes client objects and YAML/JSON can be mixed into the same release. piceli render prints plain manifests without a cluster.
• Plan before apply: every change is computed against the live cluster (with server-side dry runs, so defaults are not reported as changes), shown field by field, and executed only with an explicit approval of its hash.
• One recoverable engine: server-side apply with UID and resourceVersion preconditions, dependency ordering, readiness waits and a durable journal. resume, stop and rollback work on every release.
• Safe by default: Piceli only talks to the kubeconfig file and context you name, never changes objects it does not own unless you adopt them, never prunes Namespaces, PersistentVolumes, PersistentVolumeClaims or Secrets, and never prints secret values.
• Source to release: pinned containerized builds, source identity, and image delivery by digest to an OCI registry, a node-local registry or a node's containerd. Nothing is pushed or deployed implicitly.
• Checks and rollback: http, exec, metric and Python checks run after every apply; a failed check can re-apply the previous release automatically.
• Status and access: piceli status says whether the app is up and how to reach it; piceli access supervises the port forwards the model declares.
• Import: piceli import live and piceli import yaml generate a typed module from running objects or existing manifests.
• Built for agents and CI: machine output as JSON on stdout, fixed error codes explained by piceli explain, the whole command tree with side effects and approval rules from piceli help-json, and a public fake Kubernetes API (piceli.testing) for your own tests.
• GitOps and environments (experimental): piceli gitops enable keeps one environment per branch at its head; piceli env and piceli envs operate on them.
• Web UI (experimental): pip install "piceli[ui]" and piceli ui serve provide an infrastructure explorer, compact source/environment inventories, resource inspection and saved deployment evidence through the same reviewed plans; it can also be installed in the cluster with OIDC. In-cluster delivery from the UI is disabled by default; see the web UI page.

For coding agents

Start with Using Piceli from an agent: which commands only read, which need the owner's approval, the output contract and how to recover from errors. The documentation index for language models is llms.txt. To change Piceli itself, read AGENTS.md.

Requirements

• Python 3.12 or later.
• Kubernetes 1.34 to 1.37 (the four most recent minor versions, each tested on kind; see Supported Kubernetes versions).
• A kubeconfig file with a context for the target cluster. Piceli never uses ~/.kube/config, KUBECONFIG or the current context implicitly: the file and context are named in the pipeline, the release spec or on the command line.
• kubectl on PATH for checks, piceli access and the node-local registry; docker with buildx for containerized builds.

Contributing

Contributions are welcome. See CONTRIBUTING.md for setup, tests and pull request guidelines.

Community and support

• GitHub Issues: bug reports, feature requests and questions
• Documentation: guides, command reference and error codes
• Roadmap: feature maturity and direction
• Security: report vulnerabilities privately, see SECURITY.md

Piceli is developed alongside Pynenc, but it does not depend on it and works with any Kubernetes workload.

License

Piceli is made available under the MIT License.