cloudcoil
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.
Install
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.
Read resources
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.
Write a controller
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.
Choose a 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.
1 maintainer
Metadata
1 maintainer
Release files for cloudcoil 0.8.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| cloudcoil-0.8.0.tar.gz | 731.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| cloudcoil-0.8.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 914.9 kB
Release files / cloudcoil-0.8.0.tar.gz
| Download URL | cloudcoil-0.8.0.tar.gz |
|---|---|
| Size | 731.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
87961a2bf8b26d48eccfd70ae3a59bdd270348b6eda35e4669b4e07f2602ff9d
|
|
BLAKE2b-256 checksum How to use checksums |
04c448d81195180716ab86aae7d9dd595625aa9ef54dcd16a8745d18acb4214b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 10, 2026.
Transparency logRelease files / cloudcoil-0.8.0-py3-none-any.whl
| Download URL | cloudcoil-0.8.0-py3-none-any.whl |
|---|---|
| Size | 183.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5c28c036dd6c93b0a97290f36eceb4a38c6c79a4b14b6b750f336ce9875fdd86
|
|
BLAKE2b-256 checksum How to use checksums |
7a199e25891df5ef6e4ec4c5c4cc8570a2ba0ca6a453c2ab647ab60f46764f0f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 10, 2026.
Transparency log
