Public engineering project · v0.1.0 local suite and GitHub Actions verified 23–24 July 2026

Kubernetes Operations Audit

A typed, read-only Python CLI that audits Kubernetes workload, storage, networking, GitOps, and security signals and renders terminal, Markdown, HTML, and JSON reports.

Project type: Infrastructure Tool
Domain: Reliability and operations
Language: Python
Status: Validated

View public repository All projects

Executive summary

Operational problem

A growing Kubernetes environment needs a repeatable health review that separates operational issues from inventory, tolerates missing optional APIs, and never exposes Secret values.

Implemented solution

The official Kubernetes Python client feeds fault-isolated checks for cluster, workload, storage, networking, GitOps, and security signals. Pydantic models keep Rich terminal, Jinja2 Markdown and HTML, and JSON output aligned.

Outcome

An operator can run one read-only scan, inspect a concise terminal result, and publish a sanitized report without converting unavailable integrations into a misleading clean state.

Technical and operational context

The implementation combines Python packaging, typed models, Kubernetes API integration, fault isolation, report rendering, mocked tests, and strict static-analysis configuration in a compact operator tool.

Architecture

A small Kubernetes client adapter supplies isolated checks. Typed findings feed terminal, Markdown, HTML, and JSON renderers; configuration or API failures become explicit report findings.

Kubernetes API
Read-only client
Isolated checks
Typed findings
Terminal output
Markdown / HTML / JSON reports

Implementation

Audits node, workload, storage, networking, GitOps, certificate, external-secret, and security hygiene signals
Produces terminal, Markdown, HTML, and JSON reports from the same typed model
Continues remaining checks when one optional integration fails and records the collection warning
Reports Secret counts without retrieving Secret values

Key decisions and trade-offs

Typed reports instead of terminal-only output

Pydantic models keep terminal, Markdown, HTML, and JSON output consistent. Report comparison remains future work in the reviewed local version.

Fault isolation instead of fail-fast optional checks

Missing optional namespaces and CRDs become warnings while core inspection continues, keeping partial coverage visible.

Read-only inspection by design

The client uses Kubernetes read APIs and reports Secret counts only, reducing the consequences of running an audit during troubleshooting.

Security, reliability, and observability

Read-only collection

The client inspects cluster state and has no mutation command.

Fault-isolated checks

A failed optional integration becomes a warning while the remaining checks continue.

Sanitized publication

Example reports omit private cluster identifiers and Secret values; raw local reports remain excluded from publication.

Infrastructure concepts demonstrated

Nodes
Workload controllers
Services
Ingress
PVCs and PVs
Flux and Argo CD
cert-manager
Security contexts

Published evidence

Local quality-gate record

Sanitized live output

package version: 0.1.0
pytest: 16 passed
Ruff lint: passed
Ruff format: 37 files formatted
mypy: no issues in 30 source files
report formats: terminal, Markdown, HTML, JSON
mutation commands: none

Validation

Checks shown here are project-specific; no portfolio-wide claim is applied automatically.

Local package metadata identifies version 0.1.0
Fresh pytest run passed all 16 mocked cases in 0.21 seconds
Ruff lint passed and all 37 Python files matched Ruff formatting
Strict mypy reported no issues across 30 source files
The latest public GitHub Actions CI run completed successfully on 23 July 2026
Sanitized Markdown and JSON examples are included

Evidence and links

Links are limited to public-safe source material and sanitized evidence. Credentials, state, plans, identifiers, private topology, and backup contents are intentionally excluded.

k3s platform model

The public-safe platform relationships assessed by the tool.

Architecture catalogue

Diagram sources, evidence boundaries, and verification notes.

Lessons learned

Partial collection must remain visible because unavailable access is different from inspected healthy state.
Inventory findings and operational failures need separate severity semantics.
One typed model prevents terminal and published reports from disagreeing.

Limitations

The tool reports Kubernetes and supported optional API state; it cannot infer external systems absent from those APIs.
A hygiene finding is not necessarily an active incident and still requires operator context.
Historical report comparison and scheduled recurring audits are not implemented in the reviewed local version.

Next improvement

Implement a versioned report-comparison command before making any historical-drift or CI-gate claim.