Typed Kubernetes clients, controllers and admission webhooks for Python 3.14+.
Use Pydantic models to read and write Kubernetes resources. Register controllers, webhooks and lifecycle hooks with decorators; Cloudcoil supplies watches, retries, status persistence, Events and generated deployment manifests.
uv add 'cloudcoil[kubernetes]'
# Include HTTPS admission hosting when needed:
uv add 'cloudcoil[operator,kubernetes]'Choose a model version that matches your cluster; see versioning. These docs track repository source and can describe APIs ahead of the published release. To run the examples here, use the source checkout quickstart.
from cloudcoil.models.kubernetes.core.v1 import Pod
for pod in Pod.list(namespace="default"):
print(pod.name)Async code uses await Pod.async_list(...). Configuration comes from your
kubeconfig locally or the Pod's ServiceAccount in a cluster.
from cloudcoil.models.kubernetes.core.v1 import ConfigMap
from cloudcoil.application import Application
app = Application("configmap-labeler")
configs = app.controller(ConfigMap, label_selector="example.com/manage=true")
@configs.reconcile()
async def reconcile(config: ConfigMap) -> ConfigMap:
config.data = {**(config.data or {}), "managed-by": "cloudcoil"}
return config
if __name__ == "__main__":
app.main()Save this as app.py. python app.py manifests generates RBAC offline;
python app.py run starts the controller. Returning a changed resource saves a
guarded patch; unchanged returns cause no write. Exceptions retry with backoff.
For an operator with several responsibilities, register named stages with
@controller.stage(condition=..., depends=...). A stage can hold one handler or
first-match cases. raise Wait("RollingOut", after=10) pauses the pass and retries
later. A status derived from ReconcileStatus gets automatic Ready conditions.
See the stage and case guide.
| Task | Start here |
|---|---|
| Install and run a first controller | Getting started |
| Read, write, build, watch or stream logs | Resources, logs |
| Define or generate typed models | Custom resources, model generation |
| Reconcile, own children and finalize objects | Controllers |
| Structure stages, cases, status and Events | Stages and reporting |
| Read dependencies and register watches | Live and cached reads |
| Default and validate API requests | Admission |
| Package an application and generate RBAC/TLS manifests | Deployment |
| Handle process startup and leadership changes | Lifespans |
| Find a complete implementation | Patterns, Widget demo |
| Test or embed the runtime | Testing, runtime |
The documentation site also includes the API reference, model integrations and release workflow.
Licensed under Apache-2.0.