kubechain 0.1.0__tar.gz

kubechain-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KubeChain contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kubechain-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: kubechain
+Version: 0.1.0
+Summary: Decide whether a blockchain workload on Kubernetes is production ready.
+Author: ehsanhajian
+License-Expression: MIT
+Project-URL: Repository, https://github.com/ehsanhajian/kubechain
+Project-URL: Issues, https://github.com/ehsanhajian/kubechain/issues
+Project-URL: Changelog, https://github.com/ehsanhajian/kubechain/releases
+Keywords: kubernetes,ethereum,geth,lighthouse,statefulset,node,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Clustering
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: kubernetes>=31
+Requires-Dist: pyyaml>=6
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# KubeChain
+
+KubeChain answers one question: **is my Kubernetes blockchain deployment production ready?**
+
+It reads workloads, Services, Secrets, storage, network policy, and disruption settings. A live check uses get, list, and watch. Secret bytes are discarded. Volume snapshots are observed and never created. The cluster is left as it was found.
+
+ValidatorPulse raises an alert. ChainDiff decides whether a client upgrade is safe. ChainTrace is the view of the process. KubeChain is the view of that same node as a Kubernetes workload.
+
+## Install
+
+Python 3.11 or newer.
+
+```bash
+pip install kubechain
+kubechain --version
+```
+
+The package is published from a GitHub release to [PyPI](https://pypi.org/project/kubechain/). This README is the reference.
+
+## Commands
+
+| Question | Command |
+| --- | --- |
+| Does this manifest set pass? | `check --manifests DIR` |
+| Does this namespace pass? | `check --namespace NS` |
+| One line for a journal? | `check --brief` |
+| Can I keep the answer? | `report` |
+
+`--manifests` needs no cluster. `--context NAME` selects a kubeconfig context for a live read. The two modes are separate. `--json` prints one document. `--brief` and `--json` together print the JSON document only.
+
+## Examples
+
+`examples/ready` is a geth and lighthouse pair that passes. `examples/broken` is the cases that are not ready. `examples/oom` is a saved pod status.
+
+```bash
+kubechain check --manifests examples/ready
+kubechain check --manifests examples/broken
+kubechain check --manifests examples/ready --brief
+kubechain check --manifests examples/ready --profile examples/geth.json
+kubechain report --manifests examples/ready
+kubechain check --namespace nodes
+```
+
+`report` writes `kubechain-report.md`. `--output PATH` chooses the file. A directory is refused. An existing file is overwritten.
+
+## Verdicts
+
+| Verdict | Exit | When |
+| --- | --- | --- |
+| READY | 0 | No warning or critical finding. An info line still exits 0. |
+| REVIEW | 1 | A warning. The workload runs, and a production gap is named. |
+| NOT READY | 2 | A critical finding. Chain data, a secret, or an upgrade would be unsafe. |
+| ERROR | 3 | The manifests, the profile, or the cluster could not be read. |
+
+Every finding has an id, a severity, the object name, a reason, and an action. A check that cannot name an action does not emit a finding.
+
+## What a ready workload looks like
+
+A chain node is a StatefulSet with a claim template, a headless Service, and a JWT mounted as a file. Probes survive a long sync. The disruption budget matches the replica count. A backup signal exists before the next rolling upgrade. A Deployment is for a stateless proxy, not for chain data.
+
+A single replica is a warning. It runs, and it has no failover.
+
+`--manifests` has no pod status and no kubelet stats. The report says restarts were not read, and storage performance was not read. That absence is not a finding. A live read reports OOMKilled, CrashLoopBackOff, and restart counts. Volume usage is reported when kubelet stats can be read. Above 80% is a warning. Above 95% is critical. When the stats endpoint is unavailable, the report says storage performance was not read.
+
+## Clients
+
+The catalog recognizes geth, reth, nethermind, erigon, besu, op-geth, lighthouse, prysm, teku, nimbus, lodestar, op-node, and mev-boost. Each profile sets ports, the data volume, whether a JWT is required, and a floor for CPU, memory, storage, and shutdown grace. The floor is a KubeChain floor. The source line is in `clients.json`.
+
+An unrecognized workload is still listed and is judged only by the generic Kubernetes checks. op-node is the consensus side for op-geth. mev-boost does not sync and does not hold chain data.
+
+`--profile FILE` replaces the built-in profile when the container name matches `comm`. `examples/geth.json` is the sample.
+
+```json
+{
+  "comm": "geth",
+  "p2p_ports": [30303],
+  "rpc_ports": [8545, 8546],
+  "engine_port": 8551,
+  "jwt": true,
+  "data_volume": "data",
+  "cpu": "2",
+  "memory": "8Gi",
+  "storage": "100Gi",
+  "grace_seconds": 300
+}
+```
+
+An unknown field is exit 3.
+
+## Live read
+
+`deploy/kubechain-reader.yaml` is a Role and a binding for the object kinds a live check reads. The verbs are get, list, and watch. Apply it yourself. KubeChain does not apply it.
+
+```bash
+kubectl apply -f deploy/kubechain-reader.yaml -n nodes
+```
+
+Listing a Secret returns its bytes from the API. The CLI discards them. The report prints the Secret name and the mount path.
+
+StorageClass and kubelet volume stats are cluster-scoped. The Role comment says which extra rules those reads need. If they are not granted, the report says so and continues.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```

kubechain-0.1.0/README.md

@@ -0,0 +1,107 @@
+# KubeChain
+
+KubeChain answers one question: **is my Kubernetes blockchain deployment production ready?**
+
+It reads workloads, Services, Secrets, storage, network policy, and disruption settings. A live check uses get, list, and watch. Secret bytes are discarded. Volume snapshots are observed and never created. The cluster is left as it was found.
+
+ValidatorPulse raises an alert. ChainDiff decides whether a client upgrade is safe. ChainTrace is the view of the process. KubeChain is the view of that same node as a Kubernetes workload.
+
+## Install
+
+Python 3.11 or newer.
+
+```bash
+pip install kubechain
+kubechain --version
+```
+
+The package is published from a GitHub release to [PyPI](https://pypi.org/project/kubechain/). This README is the reference.
+
+## Commands
+
+| Question | Command |
+| --- | --- |
+| Does this manifest set pass? | `check --manifests DIR` |
+| Does this namespace pass? | `check --namespace NS` |
+| One line for a journal? | `check --brief` |
+| Can I keep the answer? | `report` |
+
+`--manifests` needs no cluster. `--context NAME` selects a kubeconfig context for a live read. The two modes are separate. `--json` prints one document. `--brief` and `--json` together print the JSON document only.
+
+## Examples
+
+`examples/ready` is a geth and lighthouse pair that passes. `examples/broken` is the cases that are not ready. `examples/oom` is a saved pod status.
+
+```bash
+kubechain check --manifests examples/ready
+kubechain check --manifests examples/broken
+kubechain check --manifests examples/ready --brief
+kubechain check --manifests examples/ready --profile examples/geth.json
+kubechain report --manifests examples/ready
+kubechain check --namespace nodes
+```
+
+`report` writes `kubechain-report.md`. `--output PATH` chooses the file. A directory is refused. An existing file is overwritten.
+
+## Verdicts
+
+| Verdict | Exit | When |
+| --- | --- | --- |
+| READY | 0 | No warning or critical finding. An info line still exits 0. |
+| REVIEW | 1 | A warning. The workload runs, and a production gap is named. |
+| NOT READY | 2 | A critical finding. Chain data, a secret, or an upgrade would be unsafe. |
+| ERROR | 3 | The manifests, the profile, or the cluster could not be read. |
+
+Every finding has an id, a severity, the object name, a reason, and an action. A check that cannot name an action does not emit a finding.
+
+## What a ready workload looks like
+
+A chain node is a StatefulSet with a claim template, a headless Service, and a JWT mounted as a file. Probes survive a long sync. The disruption budget matches the replica count. A backup signal exists before the next rolling upgrade. A Deployment is for a stateless proxy, not for chain data.
+
+A single replica is a warning. It runs, and it has no failover.
+
+`--manifests` has no pod status and no kubelet stats. The report says restarts were not read, and storage performance was not read. That absence is not a finding. A live read reports OOMKilled, CrashLoopBackOff, and restart counts. Volume usage is reported when kubelet stats can be read. Above 80% is a warning. Above 95% is critical. When the stats endpoint is unavailable, the report says storage performance was not read.
+
+## Clients
+
+The catalog recognizes geth, reth, nethermind, erigon, besu, op-geth, lighthouse, prysm, teku, nimbus, lodestar, op-node, and mev-boost. Each profile sets ports, the data volume, whether a JWT is required, and a floor for CPU, memory, storage, and shutdown grace. The floor is a KubeChain floor. The source line is in `clients.json`.
+
+An unrecognized workload is still listed and is judged only by the generic Kubernetes checks. op-node is the consensus side for op-geth. mev-boost does not sync and does not hold chain data.
+
+`--profile FILE` replaces the built-in profile when the container name matches `comm`. `examples/geth.json` is the sample.
+
+```json
+{
+  "comm": "geth",
+  "p2p_ports": [30303],
+  "rpc_ports": [8545, 8546],
+  "engine_port": 8551,
+  "jwt": true,
+  "data_volume": "data",
+  "cpu": "2",
+  "memory": "8Gi",
+  "storage": "100Gi",
+  "grace_seconds": 300
+}
+```
+
+An unknown field is exit 3.
+
+## Live read
+
+`deploy/kubechain-reader.yaml` is a Role and a binding for the object kinds a live check reads. The verbs are get, list, and watch. Apply it yourself. KubeChain does not apply it.
+
+```bash
+kubectl apply -f deploy/kubechain-reader.yaml -n nodes
+```
+
+Listing a Secret returns its bytes from the API. The CLI discards them. The report prints the Secret name and the mount path.
+
+StorageClass and kubelet volume stats are cluster-scoped. The Role comment says which extra rules those reads need. If they are not granted, the report says so and continues.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```

kubechain-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+name = "kubechain"
+version = "0.1.0"
+description = "Decide whether a blockchain workload on Kubernetes is production ready."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+keywords = [
+  "kubernetes",
+  "ethereum",
+  "geth",
+  "lighthouse",
+  "statefulset",
+  "node",
+  "cli",
+]
+authors = [{ name = "ehsanhajian" }]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: System Administrators",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: System :: Clustering",
+  "Topic :: System :: Systems Administration",
+]
+dependencies = [
+  "kubernetes>=31",
+  "pyyaml>=6",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.urls]
+Repository = "https://github.com/ehsanhajian/kubechain"
+Issues = "https://github.com/ehsanhajian/kubechain/issues"
+Changelog = "https://github.com/ehsanhajian/kubechain/releases"
+
+[project.scripts]
+kubechain = "kubechain.cli:main"
+
+[build-system]
+requires = ["setuptools>=84"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+kubechain = ["clients.json"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = [".", "src"]

kubechain-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

kubechain-0.1.0/src/kubechain/__init__.py

@@ -0,0 +1,3 @@
+"""Decide whether a blockchain workload on Kubernetes is production ready."""
+
+__version__ = "0.1.0"

kubechain-0.1.0/src/kubechain/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from kubechain.cli import main
+
+sys.exit(main())

kubechain-0.1.0/src/kubechain/catalog.py

@@ -0,0 +1,152 @@
+"""Built-in client profiles and a local file that overrides one of them."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, replace
+from importlib.resources import files
+from pathlib import Path
+
+
+class ProfileError(Exception):
+    """The profile file cannot be used."""
+
+
+ALLOWED = {
+    "comm",
+    "role",
+    "images",
+    "p2p_ports",
+    "rpc_ports",
+    "engine_port",
+    "jwt",
+    "data_volume",
+    "cpu",
+    "memory",
+    "storage",
+    "grace_seconds",
+    "exempt_probes",
+    "source",
+}
+
+
+@dataclass(frozen=True)
+class Profile:
+    comm: str
+    role: str
+    images: tuple[str, ...]
+    p2p_ports: tuple[int, ...]
+    rpc_ports: tuple[int, ...]
+    engine_port: int | None
+    jwt: bool
+    data_volume: str
+    cpu: str
+    memory: str
+    storage: str
+    grace_seconds: int
+    exempt_probes: bool
+    source: str
+
+
+def catalog() -> dict[str, Profile]:
+    raw = json.loads(files("kubechain").joinpath("clients.json").read_text())
+    return {name: _profile(body) for name, body in raw.items()}
+
+
+def load_profile(path: Path) -> dict:
+    try:
+        data = json.loads(path.read_text())
+    except json.JSONDecodeError as exc:
+        raise ProfileError(f"profile is not JSON: {path}") from exc
+    if not isinstance(data, dict):
+        raise ProfileError("profile must be a JSON object")
+    extra = sorted(set(data) - ALLOWED)
+    if extra:
+        raise ProfileError(f"unknown profile field: {extra[0]}")
+    if "comm" not in data:
+        raise ProfileError("profile needs comm")
+    return data
+
+
+def resolve(container: dict, profiles: dict[str, Profile], overlay: dict | None) -> Profile | None:
+    name = str(container.get("name") or "")
+    image = str(container.get("image") or "")
+    chosen = profiles.get(name) or _by_image(image, profiles)
+    if overlay and overlay.get("comm") == name:
+        return _merge(chosen, overlay)
+    return chosen
+
+
+def _by_image(image: str, profiles: dict[str, Profile]) -> Profile | None:
+    path = image.split("@", 1)[0]
+    slash = path.rfind("/")
+    colon = path.rfind(":")
+    if colon > slash:
+        path = path[:colon]
+    segments = path.split("/")
+    best: Profile | None = None
+    best_len = -1
+    for profile in profiles.values():
+        for hint in profile.images:
+            if hint in segments and len(hint) > best_len:
+                best = profile
+                best_len = len(hint)
+    return best
+
+
+def _merge(base: Profile | None, overlay: dict) -> Profile:
+    if base is None:
+        base = Profile(
+            comm=str(overlay["comm"]),
+            role=str(overlay.get("role") or "unknown"),
+            images=(),
+            p2p_ports=(),
+            rpc_ports=(),
+            engine_port=None,
+            jwt=bool(overlay.get("jwt", False)),
+            data_volume=str(overlay.get("data_volume") or ""),
+            cpu=str(overlay.get("cpu") or ""),
+            memory=str(overlay.get("memory") or ""),
+            storage=str(overlay.get("storage") or ""),
+            grace_seconds=int(overlay.get("grace_seconds") or 30),
+            exempt_probes=bool(overlay.get("exempt_probes", False)),
+            source="Local profile.",
+        )
+    values = {}
+    for key in ("role", "data_volume", "cpu", "memory", "storage", "source"):
+        if key in overlay:
+            values[key] = overlay[key]
+    if "engine_port" in overlay:
+        values["engine_port"] = overlay["engine_port"]
+    if "jwt" in overlay:
+        values["jwt"] = bool(overlay["jwt"])
+    if "exempt_probes" in overlay:
+        values["exempt_probes"] = bool(overlay["exempt_probes"])
+    if "grace_seconds" in overlay:
+        values["grace_seconds"] = int(overlay["grace_seconds"])
+    if "p2p_ports" in overlay:
+        values["p2p_ports"] = tuple(int(port) for port in overlay["p2p_ports"])
+    if "rpc_ports" in overlay:
+        values["rpc_ports"] = tuple(int(port) for port in overlay["rpc_ports"])
+    if "images" in overlay:
+        values["images"] = tuple(overlay["images"])
+    return replace(base, **values)
+
+
+def _profile(body: dict) -> Profile:
+    return Profile(
+        comm=body["comm"],
+        role=body["role"],
+        images=tuple(body.get("images") or ()),
+        p2p_ports=tuple(body.get("p2p_ports") or ()),
+        rpc_ports=tuple(body.get("rpc_ports") or ()),
+        engine_port=body.get("engine_port"),
+        jwt=bool(body.get("jwt")),
+        data_volume=body.get("data_volume") or "",
+        cpu=body.get("cpu") or "",
+        memory=body.get("memory") or "",
+        storage=body.get("storage") or "",
+        grace_seconds=int(body.get("grace_seconds") or 30),
+        exempt_probes=bool(body.get("exempt_probes")),
+        source=body.get("source") or "KubeChain floor.",
+    )