knete 0.1.0__tar.gz

knete-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv**
+k8s**
+**egg-info**
+**__pycache__**
+dist**
+Containerfile
+docs/_build/

knete-0.1.0/.gitlab-ci.yml

@@ -0,0 +1,134 @@
+# This file is a template, and might need editing before it works on your project.
+# To contribute improvements to CI/CD templates, please follow the Development guide at:
+# https://docs.gitlab.com/development/cicd/templates/
+# This specific template is located at:
+# https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Python.gitlab-ci.yml
+
+stages:
+ - test
+ - build
+ - deploy
+
+
+# Official language image. Look for the different tagged releases at:
+# https://hub.docker.com/r/library/python/tags/
+image: python:latest
+
+variables:
+  TWINE_REPOSITORY: pypi
+  TWINE_NON_INTERACTIVE: "1"
+
+# Change pip's cache directory to be inside the project directory since we can
+# only cache local items.
+variables:
+  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
+
+# https://pip.pypa.io/en/stable/topics/caching/
+cache:
+  paths:
+    - .cache/pip
+
+before_script:
+  - python --version ; pip --version
+  - pip install virtualenv
+  - virtualenv venv
+  - source venv/bin/activate
+
+test:
+  script:
+    - pip install pycodestyle
+    - pip install --editable ".[test]"
+    - pycodestyle src/
+
+e2e:
+  stage: test
+  image: docker:24.0
+  services:
+    - docker:24.0-dind
+  variables:
+    DOCKER_HOST: tcp://docker:2375
+    DOCKER_TLS_CERTDIR: ""
+    KIND_VERSION: "v0.24.0"
+    KUBECTL_VERSION: "v1.31.0"
+  before_script:
+    - apk update
+    - apk upgrade --no-cache
+    - apk add --no-cache curl bash make python3 py3-pip py3-virtualenv
+    - virtualenv .venv
+    - curl -Lo /usr/local/bin/kind https://kind.sigs.k8s.io/dl/${KIND_VERSION}/kind-linux-amd64
+    - chmod +x /usr/local/bin/kind
+    - curl -Lo /usr/local/bin/kubectl "https://dl.k8s.io/release/${KUBECTL_VERSION}/bin/linux/amd64/kubectl"
+    - chmod +x /usr/local/bin/kubectl
+  script:
+    - |
+      cat <<EOF > kind-config.yaml
+      kind: Cluster
+      apiVersion: kind.x-k8s.io/v1alpha4
+      networking:
+        apiServerAddress: "0.0.0.0"
+        apiServerPort: 6443
+      kubeadmConfigPatches:
+        - |
+          kind: ClusterConfiguration
+          apiServer:
+            certSANs:
+              - "docker"
+      nodes:
+        - role: control-plane
+      EOF
+    - kind create cluster --name knete --config kind-config.yaml
+    - export KUBECONFIG=$CI_PROJECT_DIR/kubeconfig
+    - export KIND_API_SERVER_HOST=docker
+    - bash test.sh
+  timeout: 20m
+
+build:
+  script:
+    - pip install build setuptools-scm
+    - |
+      if [ -z "$CI_COMMIT_TAG" ]; then
+        export SETUPTOOLS_SCM_PRETEND_VERSION=$(python -m setuptools_scm | cut -d'+' -f1)
+      fi
+    - make build
+  artifacts:
+    paths:
+      - dist/*
+  rules:
+    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+
+deploy:
+  image: python:3.11
+  stage: deploy
+  dependencies:
+    - build
+  script:
+    - ls -al
+    - pip install --upgrade twine
+    - twine upload dist/*
+  rules:
+    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
+  environment:
+    name: production
+  id_tokens:
+    PYPI_ID_TOKEN:
+      aud: pypi
+
+deploy_test:
+  image: python:3.11
+  stage: deploy
+  dependencies:
+    - build
+  variables:
+    TWINE_REPOSITORY: testpypi
+  script:
+    - ls -al
+    - pip install --upgrade twine
+    - twine upload dist/*
+  rules:
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+  environment:
+    name: test-pypi
+  id_tokens:
+    TESTPYPI_ID_TOKEN:
+      aud: testpypi

knete-0.1.0/Makefile

@@ -0,0 +1,36 @@
+CLUSTER_NAME ?= knete
+
+.PHONY: all sdist wheel dist upload upload-test clean docs kind-up kind-down kind-reset
+
+all: dist
+
+sdist:
+	python -m build --sdist
+
+wheel:
+	python -m build --wheel
+
+dist:
+	python -m build
+
+build: dist
+
+upload:
+	python -m twine upload dist/*
+
+upload-test:
+	python -m twine upload --repository testpypi dist/*
+
+docs:
+	$(MAKE) -C docs html
+
+clean:
+	rm -rf dist/ build/ src/*.egg-info docs/_build
+
+kind-up:
+	kind create cluster --name $(CLUSTER_NAME)
+
+kind-down:
+	kind delete cluster --name $(CLUSTER_NAME)
+
+kind-reset: kind-down kind-up

knete-0.1.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: knete
+Version: 0.1.0
+Summary: A lightweight Kubernetes controller framework for Python
+License-Expression: MIT
+Project-URL: Repository, https://gitlab.com/oz123/knete
+Keywords: kubernetes,controller,operator,k8s
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx-rtd-theme; extra == "docs"
+
+# knete
+
+<p align="center">
+  <img src="logos/knete.png" alt="knete logo" width="500">
+</p>
+
+A lightweight Python framework for building Kubernetes controllers and admission webhooks.
+
+## Features
+
+- **Controllers** — watch any Kubernetes resource and react to create/update/delete events
+- **Validating webhooks** — reject requests that violate policy
+- **Mutating webhooks** — patch objects on the way in
+- **Composite mutating webhooks** — fan-out multiple mutators to a single endpoint, accumulating all patches in one round-trip
+- **Decorator-style webhooks** — register plain functions instead of subclasses
+- **Manifest generator** — `python -m knete <file.py>` generates all k8s manifests (Deployment, Service, RBAC, WebhookConfigurations) including cert-manager TLS support
+
+## Installation
+
+```bash
+pip install knete
+```
+
+## Quick start
+
+### Controller
+
+```python
+from knete import Controller, Manager
+
+class PodController(Controller):
+    class Meta:
+        resource  = "v1/pods"
+        namespace = "default"
+
+    def on_create(self, name, namespace, labels, spec):
+        print(f"Pod created: {namespace}/{name}")
+
+    def on_delete(self, name):
+        print(f"Pod deleted: {name}")
+
+Manager().register(PodController).start()
+```
+
+### Validating webhook
+
+```python
+from knete import ValidatingWebhook, AdmissionResponse, WebhookServer
+
+class NoLatestTagWebhook(ValidatingWebhook):
+    class Meta:
+        resource   = "apps/v1/deployments"
+        operations = ["CREATE", "UPDATE"]
+        name       = "no-latest-tag"
+
+    def validate(self, name, spec) -> AdmissionResponse:
+        for c in spec.get("template", {}).get("spec", {}).get("containers", []):
+            if c["image"].endswith(":latest") or ":" not in c["image"]:
+                return AdmissionResponse.deny(f"image {c['image']!r} uses :latest tag")
+        return AdmissionResponse.allow()
+
+server = WebhookServer(cert_file="tls.crt", key_file="tls.key")
+server.register(NoLatestTagWebhook)
+server.start()
+```
+
+### Mutating webhook
+
+```python
+from knete import MutatingWebhook, AdmissionResponse
+
+class InjectLabelWebhook(MutatingWebhook):
+    class Meta:
+        resource   = "v1/pods"
+        operations = ["CREATE"]
+        name       = "inject-label"
+
+    def mutate(self, labels) -> AdmissionResponse:
+        if "managed-by" in labels:
+            return AdmissionResponse.allow()
+        return AdmissionResponse.patch([
+            {"op": "add", "path": "/metadata/labels/managed-by", "value": "knete"},
+        ])
+```
+
+### Multiple validators
+
+Register each validating webhook separately — Kubernetes calls them in parallel,
+so total latency is `max(validators)` rather than `sum(validators)`:
+
+```python
+server.register(NoLatestTagWebhook)     # POST /validate/no-latest-tag
+server.register(RequiredLabelsWebhook)  # POST /validate/required-labels
+```
+
+### Decorator style
+
+Skip the class entirely and register plain functions directly on the server:
+
+```python
+server = WebhookServer(cert_file="tls.crt", key_file="tls.key")
+
+@server.validate("apps/v1/deployments", operations=["CREATE", "UPDATE"], name="no-latest-tag")
+def no_latest_tag(name, spec) -> AdmissionResponse:
+    for c in spec.get("template", {}).get("spec", {}).get("containers", []):
+        if c["image"].endswith(":latest") or ":" not in c["image"]:
+            return AdmissionResponse.deny(f"image {c['image']!r} uses :latest tag")
+
+@server.mutate("v1/pods", operations=["CREATE"], name="inject-label")
+def inject_label(labels) -> AdmissionResponse:
+    if "managed-by" not in labels:
+        return AdmissionResponse.patch([
+            {"op": "add", "path": "/metadata/labels/managed-by", "value": "knete"},
+        ])
+
+server.start()
+```
+
+Both styles can be mixed freely. `name` defaults to the function name if omitted.
+
+## Manifest generator
+
+Generate all Kubernetes manifests for your operator or webhook server:
+
+```bash
+# Operator
+python -m knete examples/my_operator.py --name my-operator --image my-operator:v1
+
+# Webhook with cert-manager TLS (generates a self-signed ClusterIssuer)
+python -m knete examples/my_webhook.py --name my-webhook --image my-webhook:v1 --cert-manager
+
+# Webhook using an existing ClusterIssuer
+python -m knete examples/my_webhook.py --name my-webhook --image my-webhook:v1 --cert-manager my-issuer
+```
+
+This writes `k8s/` manifests and a `Containerfile` ready to build. Apply with:
+
+```bash
+kubectl apply -f k8s/
+```
+
+## Examples
+
+| File | What it shows |
+|------|---------------|
+| `examples/webhook_example.py` | Validating + mutating + composite mutating webhooks |
+| `examples/forbid_reserved_prefixes_decorator.py` | Decorator-style validating + mutating webhooks |
+| `examples/example.py` | Basic pod controller |
+| `examples/kyverno_clusterrolebinding.py` | Controller equivalent of a Kyverno generate rule |
+| `examples/kyverno_clusterrolebinding_webhook.py` | Same policy as a mutating webhook with side-effects |
+
+## Requirements
+
+- Python 3.10+
+- cert-manager (optional, for webhook TLS)

knete-0.1.0/README.md

@@ -0,0 +1,155 @@
+# knete
+
+<p align="center">
+  <img src="logos/knete.png" alt="knete logo" width="500">
+</p>
+
+A lightweight Python framework for building Kubernetes controllers and admission webhooks.
+
+## Features
+
+- **Controllers** — watch any Kubernetes resource and react to create/update/delete events
+- **Validating webhooks** — reject requests that violate policy
+- **Mutating webhooks** — patch objects on the way in
+- **Composite mutating webhooks** — fan-out multiple mutators to a single endpoint, accumulating all patches in one round-trip
+- **Decorator-style webhooks** — register plain functions instead of subclasses
+- **Manifest generator** — `python -m knete <file.py>` generates all k8s manifests (Deployment, Service, RBAC, WebhookConfigurations) including cert-manager TLS support
+
+## Installation
+
+```bash
+pip install knete
+```
+
+## Quick start
+
+### Controller
+
+```python
+from knete import Controller, Manager
+
+class PodController(Controller):
+    class Meta:
+        resource  = "v1/pods"
+        namespace = "default"
+
+    def on_create(self, name, namespace, labels, spec):
+        print(f"Pod created: {namespace}/{name}")
+
+    def on_delete(self, name):
+        print(f"Pod deleted: {name}")
+
+Manager().register(PodController).start()
+```
+
+### Validating webhook
+
+```python
+from knete import ValidatingWebhook, AdmissionResponse, WebhookServer
+
+class NoLatestTagWebhook(ValidatingWebhook):
+    class Meta:
+        resource   = "apps/v1/deployments"
+        operations = ["CREATE", "UPDATE"]
+        name       = "no-latest-tag"
+
+    def validate(self, name, spec) -> AdmissionResponse:
+        for c in spec.get("template", {}).get("spec", {}).get("containers", []):
+            if c["image"].endswith(":latest") or ":" not in c["image"]:
+                return AdmissionResponse.deny(f"image {c['image']!r} uses :latest tag")
+        return AdmissionResponse.allow()
+
+server = WebhookServer(cert_file="tls.crt", key_file="tls.key")
+server.register(NoLatestTagWebhook)
+server.start()
+```
+
+### Mutating webhook
+
+```python
+from knete import MutatingWebhook, AdmissionResponse
+
+class InjectLabelWebhook(MutatingWebhook):
+    class Meta:
+        resource   = "v1/pods"
+        operations = ["CREATE"]
+        name       = "inject-label"
+
+    def mutate(self, labels) -> AdmissionResponse:
+        if "managed-by" in labels:
+            return AdmissionResponse.allow()
+        return AdmissionResponse.patch([
+            {"op": "add", "path": "/metadata/labels/managed-by", "value": "knete"},
+        ])
+```
+
+### Multiple validators
+
+Register each validating webhook separately — Kubernetes calls them in parallel,
+so total latency is `max(validators)` rather than `sum(validators)`:
+
+```python
+server.register(NoLatestTagWebhook)     # POST /validate/no-latest-tag
+server.register(RequiredLabelsWebhook)  # POST /validate/required-labels
+```
+
+### Decorator style
+
+Skip the class entirely and register plain functions directly on the server:
+
+```python
+server = WebhookServer(cert_file="tls.crt", key_file="tls.key")
+
+@server.validate("apps/v1/deployments", operations=["CREATE", "UPDATE"], name="no-latest-tag")
+def no_latest_tag(name, spec) -> AdmissionResponse:
+    for c in spec.get("template", {}).get("spec", {}).get("containers", []):
+        if c["image"].endswith(":latest") or ":" not in c["image"]:
+            return AdmissionResponse.deny(f"image {c['image']!r} uses :latest tag")
+
+@server.mutate("v1/pods", operations=["CREATE"], name="inject-label")
+def inject_label(labels) -> AdmissionResponse:
+    if "managed-by" not in labels:
+        return AdmissionResponse.patch([
+            {"op": "add", "path": "/metadata/labels/managed-by", "value": "knete"},
+        ])
+
+server.start()
+```
+
+Both styles can be mixed freely. `name` defaults to the function name if omitted.
+
+## Manifest generator
+
+Generate all Kubernetes manifests for your operator or webhook server:
+
+```bash
+# Operator
+python -m knete examples/my_operator.py --name my-operator --image my-operator:v1
+
+# Webhook with cert-manager TLS (generates a self-signed ClusterIssuer)
+python -m knete examples/my_webhook.py --name my-webhook --image my-webhook:v1 --cert-manager
+
+# Webhook using an existing ClusterIssuer
+python -m knete examples/my_webhook.py --name my-webhook --image my-webhook:v1 --cert-manager my-issuer
+```
+
+This writes `k8s/` manifests and a `Containerfile` ready to build. Apply with:
+
+```bash
+kubectl apply -f k8s/
+```
+
+## Examples
+
+| File | What it shows |
+|------|---------------|
+| `examples/webhook_example.py` | Validating + mutating + composite mutating webhooks |
+| `examples/forbid_reserved_prefixes_decorator.py` | Decorator-style validating + mutating webhooks |
+| `examples/example.py` | Basic pod controller |
+| `examples/kyverno_clusterrolebinding.py` | Controller equivalent of a Kyverno generate rule |
+| `examples/kyverno_clusterrolebinding_webhook.py` | Same policy as a mutating webhook with side-effects |
+
+## Requirements
+
+- Python 3.10+
+- cert-manager (optional, for webhook TLS)

knete-0.1.0/docs/Makefile

@@ -0,0 +1,15 @@
+SPHINXOPTS  ?=
+SPHINXBUILD ?= sphinx-build
+SOURCEDIR    = .
+BUILDDIR     = _build
+
+.PHONY: help clean html
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+
+clean:
+	rm -rf $(BUILDDIR)
+
+html:
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)

knete-0.1.0/docs/api.rst

@@ -0,0 +1,86 @@
+API reference
+=============
+
+.. contents:: On this page
+   :local:
+   :depth: 1
+
+KubeResource
+------------
+
+.. autoclass:: knete.KubeResource
+   :members:
+   :show-inheritance:
+
+Controller
+----------
+
+.. autoclass:: knete.Controller
+   :members:
+   :show-inheritance:
+
+Manager
+-------
+
+.. autoclass:: knete.Manager
+   :members:
+   :show-inheritance:
+
+KubeClient
+----------
+
+.. autoclass:: knete.KubeClient
+   :members:
+   :show-inheritance:
+
+auto_config
+-----------
+
+.. autofunction:: knete.auto_config
+
+from_dict
+---------
+
+.. autofunction:: knete.from_dict
+
+CustomResource
+--------------
+
+.. autoclass:: knete.CustomResource
+   :members:
+   :show-inheritance:
+
+AdmissionResponse
+-----------------
+
+.. autoclass:: knete.AdmissionResponse
+   :members:
+   :show-inheritance:
+
+ValidatingWebhook
+-----------------
+
+.. autoclass:: knete.ValidatingWebhook
+   :members:
+   :show-inheritance:
+
+MutatingWebhook
+---------------
+
+.. autoclass:: knete.MutatingWebhook
+   :members:
+   :show-inheritance:
+
+CompositeMutatingWebhook
+------------------------
+
+.. autoclass:: knete.CompositeMutatingWebhook
+   :members:
+   :show-inheritance:
+
+WebhookServer
+-------------
+
+.. autoclass:: knete.WebhookServer
+   :members:
+   :show-inheritance: