Kubernetes Deployment Risk Analyzer (CLI)

Overview

This project is a CLI-based Kubernetes deployment risk analyzer designed to act as a pre-merge guardrail in CI/CD pipelines.

It analyzes changes in Kubernetes manifest files and automatically blocks risky configuration changes before they reach production.

The tool focuses on availability-impacting risks and follows policy-as-code principles, making it deterministic, explainable, and CI-safe.

---

Problem Statement

In real-world Kubernetes environments, small configuration changes—such as reducing replica counts or removing readiness probes—can silently introduce downtime risks.

These issues are often caught too late (during or after deployment).

This project solves that by:

• Detecting risky Kubernetes changes at pull request time
• Failing CI automatically when high-risk changes are introduced
• Providing clear, structured risk reports for reviewers

---

What This Tool Does

• Compares old vs new Kubernetes manifests
• Detects risky changes using rule-based analysis
• Outputs a structured risk report
• Returns a non-zero exit code to block CI on risk

Currently enforced rules:

• Replica reduction (availability risk)
• Readiness probe removal (traffic routing risk)

The rule engine is extensible and can be expanded with additional policies.

---

Installation

Prerequisites

• Python 3.9+
• Git

---

Install from GitHub (recommended)

git clone https://github.com/TheJ10/k8s-risk-analyzer-cli.git
cd k8s-risk-analyzer-cli

python -m venv venv
source venv/bin/activate   # Linux/macOS
venv\Scripts\activate      # Windows

pip install -e .

After installation, the CLI command will be available:

k8s-risk-analyzer

---

Usage

Local Usage (Manual Testing)

k8s-risk-analyzer old.yaml new.yaml

• Prints a JSON risk report
• Exit code:
  • 0 → no risk detected
  • 1 → risk detected

---

CI/CD Usage (Primary Use Case)

In CI (GitHub Actions), the tool:

1. Detects changed Kubernetes YAML files in a PR
2. Fetches the old version from the base branch
3. Compares it with the new version from the PR
4. Fails CI if risky changes are found

Git itself provides the “before” and “after” versions — no duplicate files required.

---

Docker Usage (Optional)

You can also run the tool using Docker:

docker build -t k8s-risk-analyzer .
docker run --rm -v $(pwd):/work k8s-risk-analyzer \
  /work/old.yaml /work/new.yaml

This is useful for CI systems or environments without Python installed.

---

Example Output

{
  "overall_severity": "MEDIUM",
  "risk_count": 1,
  "risks": [
    {
      "field": "replicas",
      "risk_level": "HIGH",
      "category": "Availability",
      "reason": "Replica count was reduced.",
      "impact": "Reducing replicas lowers redundancy and increases the chance of downtime.",
      "symptoms": [
        "Service unavailability during pod restarts",
        "Higher error rates during traffic spikes"
      ]
    }
  ]
}

---

CI Behavior (Validated)

• ✅ Safe change (replicas increased) → CI passes
• ❌ Risky change (replicas reduced) → CI fails This behavior was validated using real pull requests.

---

Project Structure

.
├── app/                    # Core analysis logic
├── samples/                # Example Kubernetes manifests
├── tests/                  # Unit tests for analysis logic
├── .github/workflows/      # CI guardrail configuration
├── Dockerfile              # CLI-based container image
├── requirements.txt
├── pyproject.toml
└── README.md

---

Design Priciples

• Deterministic: No AI / no non-deterministic output
• Explainable: Every risk has a clear reason and impact
• CI-first: Designed to run non-interactively in pipelines
• Minimal & Focused: Solves one real DevOps problem well

---

Why This Matters

This project demonstrates:

• Kubernetes configuration analysis
• Policy-as-code thinking
• Practical CI/CD guardrail implementation
• CLI tooling and packaging
• Real-world DevOps workflow

---

Future Enhancements

• Additional Kubernetes risk rules
• Severity customization
• Helm chart diff support
• SARIF / PR annotation output

---

License

MIT

---

Author

Jaspal Gundla