Get started

Install & run your first scan

TRL is a CLI-first engine that analyzes and improves Kubernetes manifests before deployment. Deployment is optional — it runs fine as a pure analysis engine or inside CI/CD.

✓ CLI stable ✓ Engines functional ⚠ Cloud deployment in progress

1. Install

# clone and install
git clone https://github.com/ClariOps/trl.git
cd trl
pip install -r requirements.txt

2. Analyze (fastest way to see TRL work)

Analysis-only, no changes to your manifest — ideal for a first look or for reports and demos.

python -m trl explain ./examples/demo/bad.yaml

3. Analyze + Optimize (recommended)

Runs the full pipeline — optimize, validate, and security — without touching your cluster.

python -m trl optimize ./examples/demo/bad.yaml --dry-run

4. Deploy (optional)

Only once you're happy with the result — applies the optimized manifest to a target.

python -m trl optimize ./examples/demo/good.yaml --target=local

Example output

Running explain against an intentionally misconfigured manifest:

$ python -m trl explain ./trl/examples/demo/bad.yaml

📦 Resource: backend
❌ HIGH: privileged-container
⚠ LOW: under-provisioning
⚠ MEDIUM: no-readiness-probe
⚠ MEDIUM: no-liveness-probe
⚠ LOW: latest-tag
⚠ MEDIUM: run-as-root

📦 Resource: backend-service
⚠ MEDIUM: nodeport-exposure

📊 Summary
Errors: 1   Warnings: 6   Optimizations: 0
❌ Status: FAILED

Add --output=json for a machine-readable version, ideal for piping into CI/CD.

Who it's for

DevOps engineers who want consistent, predictable manifests
Backend developers deploying to Kubernetes without deep infra expertise
Startups optimizing cloud cost
Teams enforcing deployment best practices

Reference

CLI Reference

TRL is invoked as python -m trl <command> <file> [flags]. Each command serves a different point in your workflow.

Commands

Command	Purpose
`optimize`	Full pipeline: optimize + validate + security (recommended)
`explain`	Analysis-only, no optimization — ideal for reports and demos
`run`	Execute TRL DSL workflows (experimental)
`deploy`	Apply the CLI-produced manifest to a cluster (optional)

Common flags

Flag	Effect
`--dry-run`	Run the full pipeline without deploying anything
`--target=local`	Deploy target when actually applying manifests
`--output=json`	Machine-readable output for CI/CD pipelines
`--verbose`	Full execution logs from every engine, in order

JSON output shape

What --output=json looks like on a failed run:

{
  "status": "FAILED",
  "summary": {
    "total": 10,
    "errors": 2,
    "warnings": 4,
    "optimizations": 4
  },
  "resources": {
    "full-risk-app": {
      "errors": [
        { "rule": "privileged-container", "severity": "HIGH", "category": "security" },
        { "rule": "run-as-root", "severity": "HIGH", "category": "security" }
      ],
      // ...warnings, optimizations
    }
  }
}

Example manifests

Ship with the repo for trying TRL immediately:

examples/demo/bad.yaml   # intentionally misconfigured
examples/demo/good.yaml  # optimized version

Status codes

Status	Meaning
PASSED	No errors found
FAILED	One or more errors present

Integrate

CI/CD & Helm

TRL is designed to run inside pipelines, and works with Helm charts without needing to parse them directly.

GitHub Actions

Fail the build when TRL reports a FAILED status:

- name: Run TRL
  run: |
    python -m trl optimize ./k8s.yaml --dry-run --output=json > report.json

- name: Fail if issues found
  run: |
    cat report.json | jq -r '.status' | grep FAILED && exit 1 || exit 0

Helm support

TRL does not parse Helm charts directly. Instead, it works with rendered manifests — so it works with any chart, without re-implementing Helm.

helm create mychart
helm template ./examples/helmCharts/mychart | python -m trl optimize - --dry-run

This keeps TRL lightweight and fast. Native Helm support is planned in a future release.

Structure

Architecture

TRL is a pipeline-based system: manifests are normalized into an Intermediate Representation (IR), then passed through independent engines in strict order.

Pipeline flow

Input→ IR→ Optimizer→ Validator→ Security→ Renderer→ Cloud Engine (optional)

Engine contracts

Engine	Can modify IR	Produces reports
Optimizer	Yes — the only engine that can	Yes
Validator	No — detection only	Yes
Security	No — detection only	Yes
Renderer	No	No
Cloud Engine	No — execution only	No

Product layers

Current

TRL Core

IR system, rule engine, optimizer/validator/security, CLI interface. The decision engine — must stay stable and predictable.

Planned

TRL Deploy

One-command deployment wrapping kubectl/Helm with TRL intelligence baked in.

Future

TRL SaaS

Hosted analysis — upload a manifest, get cost and security insights at the team level.

Rule categories

Every rule falls into one category: scaling, security, cost, reliability, or network. Rules are self-contained, deterministic, and never depend on another rule's result.

Trust contract

System guarantees

The non-negotiable behavioral rules that govern TRL. Where architecture describes how the system is built, this describes how it must behave — and takes precedence in case of conflict.

Core guarantee: same input → same output → same decisions. Deterministic, explicit, no hidden behavior.

Deterministic execution — identical input always produces identical output; rule order is fixed.
Explicit mutations only — only the Optimizer can modify IR, and every change is reported.
Detection vs. action — Validator and Security only detect and report; they never modify anything.
No hidden side effects — rules are isolated, stateless, and never depend on each other.
One-directional pipeline — no backward data flow between stages.
Transparent reporting — every finding includes resource, rule, category, and a clear fix.
Deployment safety — the Cloud Engine only executes; it never modifies manifests or applies defaults.
No cross-resource logic (current phase) — each resource is analyzed independently; relationship awareness is planned separately.

What TRL does not guarantee

Perfect optimization for every workload
Replacing Kubernetes tools like kubectl or Helm
Runtime orchestration or post-deployment monitoring

TRL focuses strictly on pre-deployment intelligence.

Direction

Roadmap & Vision

TRL exists to make Kubernetes deployments safe, efficient, and predictable — without requiring deep infrastructure expertise.

What's next

Auto-fix engine for safe, automated remediation
Cloud-specific adaptation layer (AKS, GKE, EKS)
Relationship-aware analysis (cross-resource intelligence)
Rule expansion — cost and reliability
AI-powered suggestions
Hosted SaaS platform
Multi-orchestrator support

Mission

Eliminate misconfiguration, overprovisioning, and hidden risks before they reach production — so every deployment is resource-efficient, secure by default, and aligned with best practices.

Non-goals (current phase)

Runtime orchestration or monitoring
Replacing kubectl or Helm
Implicit or automatic fixes without user consent
Full platform ambitions before the core engine is proven

Install & run your first scan

1. Install

2. Analyze (fastest way to see TRL work)

3. Analyze + Optimize (recommended)

4. Deploy (optional)

Example output

Who it's for

CLI Reference

Commands

Common flags

JSON output shape

Example manifests

Status codes

CI/CD & Helm

GitHub Actions

Helm support

Architecture

Pipeline flow

Engine contracts

Product layers

TRL Core

TRL Deploy

TRL SaaS

Rule categories

System guarantees

What TRL does not guarantee

Roadmap & Vision

What's next

Mission

Non-goals (current phase)

License