proxy-aiops

Proxy AIops

Disclaimer: Community-maintained open-source project, not affiliated with, endorsed by, or sponsored by Traefik Labs, the Caddy project, HAProxy Technologies, or the HAProxy project. Traefik, Caddy and HAProxy are trademarks of their respective owners. Source at github.com/AIops-tools/Proxy-AIops under the MIT license.

Governed reverse-proxy operations — 28 MCP tools across Traefik (API + /metrics), Caddy (admin API) and HAProxy (Data Plane API v2), every one wrapped with the bundled @governed_tool harness: a local unified audit log under ~/.proxy-aiops/, policy engine, token/runaway budget guard, undo-token recording, and descriptive risk tiers. A per-target platform field selects the API shape, so the same tools work on all three proxies and one config can span a mixed edge. An explicit support matrix raises teaching errors for ops a platform cannot do — never a silent no-op. Credentials are stored encrypted (~/.proxy-aiops/secrets.enc, Fernet + scrypt) — never plaintext on disk; Traefik/Caddy secrets are optional (unauthenticated localhost is the common case).

Standalone: the governance harness is bundled in the package (proxy_aiops.governance) — no external skill-family dependency. Behaviour is covered by a mock-based test suite; docs/VERIFICATION.md is the checklist for a live run (all three platforms are free/self-hostable, so a small lab is enough).

What This Skill Does

The four flagship analyses are transparent heuristics that report their numbers, never a black-box verdict: backend_health_rca groups down upstreams per service and maps the health-check failure class (connection refused / L4 timeout / TLS / L7 / DNS / maint) to a cause + action; cert_expiry_sweep buckets certs by days-to-expiry with per-platform renewal hints; error_rate_rca ranks services by 5xx share vs the fleet baseline and maps the dominant code (502/503/504/500) to a cause; route_conflict_analysis finds shadowed routes, dead routes, and redirect loops.

Quick Install

uv tool install proxy-aiops
proxy-aiops init       # wizard: pick platform (traefik/caddy/haproxy) + optional encrypted secret
proxy-aiops doctor

When to Use This Skill

• Get a one-shot snapshot (overview / version_info / list_entrypoints)
• Investigate 502/503/504 spikes (error_rate_rca) → dominant code → cause
• Find why an upstream/backend is down (list_upstreams, backend_health_rca)
• Sweep TLS cert expiry across the edge (certs --sweep / cert_expiry_sweep)
• Audit routing hygiene (route_conflict_analysis — shadowed/dead routes, redirect loops) and answer "which route serves this host?" (find_route)
• Safely drain/return an haproxy server (set_server_state, reversible + undo-recorded) or adjust its weight (set_server_weight)
• Safely edit caddy config (set_config_value / delete_config_path / load_config — prior config captured, undo replays the restore)

Do NOT use when the target is not a Traefik/Caddy/HAProxy proxy — route hypervisor, storage, backup, cluster, network-device, or OT/industrial work to the appropriate other AIops-tools skill. Do NOT use for firewall rules — use firewall-aiops.

Related Skills — Skill Routing

Common Workflows

1. A 5xx spike — is it the app or the backend?

1. proxy-aiops doctor → confirm the proxy's API is reachable before you trust any number that follows.
2. proxy-aiops overview → the one-shot picture: platform/version, entrypoints, and route/service counts, so you know the blast radius.
3. proxy-aiops analyze errors --rate 5 --min-requests 100 → services ranked by 5xx share against the fleet baseline, with the dominant status code mapped to a cause (503 no upstream available / 502 connection failed / 504 timeout / 500 app error). The --min-requests floor keeps a single failed request on a quiet service from outranking a real incident.
4. proxy-aiops analyze health --service → the same service from the backend side: which servers are failing their health check and what class of failure it is. If the servers are healthy, the 5xx is coming from the application, and no amount of proxy work will fix it — hand it off.
5. If one server is the problem, take it out of rotation gracefully: proxy-aiops services upstreams to get the exact server name, then proxy-aiops server state drain --dry-run and re-run for real (double-confirm; the prior state is captured as the undo descriptor). drain lets in-flight connections finish — reach for maint only when you need it out now.
6. Re-run proxy-aiops analyze errors to confirm the rate dropped.
7. Failure branch: if draining one server just moves the load onto the next one to fall over, you are shedding capacity you do not have — put it straight back with proxy-aiops undo list → undo apply (restores the prior state, not a hardcoded ready) before you drain a second. Note server state / server weight are haproxy runtime operations; on a traefik or caddy target the tool raises a teaching error naming the right mechanism rather than silently doing nothing.

2. Certificates about to expire

1. proxy-aiops certs --sweep --warn-days 30 --critical-days 7 → the TLS domain inventory with each cert live-probed on port 443 and bucketed expired / critical / warning, plus a renewal hint.
2. proxy-aiops certs --sweep --port 8443 for any entrypoint not on 443 — the sweep probes one port at a time, so a non-standard listener needs its own pass.
3. proxy-aiops overview and proxy-aiops routes list → map each expiring domain back to the routes that actually serve it, so you renew what is in use and ignore what is not.
4. Renew through the platform's own mechanism (ACME for traefik/caddy), then re-run the sweep to confirm the new expiry date.
5. Failure branch: on a haproxy target the sweep returns a teaching note rather than results — haproxy serves certs from .pem files on disk, outside this tool's API surface, so check those with your file-level tooling. If a probe fails to connect, distinguish "cert is bad" from "port is closed" with proxy-aiops routes find before assuming a certificate problem.

3. "Why is this hostname hitting the wrong backend?"

1. proxy-aiops routes find --path /api → best-matching routes, most specific first. This is the direct answer to "who serves this request".
2. proxy-aiops routes show → the full rule, priority, middlewares, and the service it points at.
3. proxy-aiops analyze conflicts → shadowed routes (fully covered by an earlier or higher-priority route), dead routes (the service is missing, or has zero servers up), and redirect loops — each finding names the covering route or the missing service rather than just flagging a number.
4. proxy-aiops services show and proxy-aiops services upstreams → confirm the service the route resolves to actually has healthy servers behind it.
5. Fix the ordering/priority at its source: on caddy via proxy-aiops config set (recipe 4); on traefik, in the provider that generated the route (labels, file provider, CRD) — traefik's API is read-only, and the tool says so explicitly instead of pretending to write.
6. Failure branch: if routes find returns nothing, the request is not matching any route at all — check proxy-aiops overview for the entrypoints and confirm the listener you think you are hitting exists. A "dead route" finding whose service is missing usually means a config was applied referencing a service that was never created; fixing the route without creating the service just moves the 404.

4. Edit a caddy config subtree, reversibly

1. proxy-aiops config snapshot → the whole current config; take this before you change anything, so you have an out-of-band copy independent of the undo store.
2. proxy-aiops config search → locate the config path holding the value you want (searching beats guessing at caddy's nested JSON paths).
3. proxy-aiops config get → read the exact current subtree you are about to replace.
4. proxy-aiops config set '' --dry-run → preview the write.
5. Re-run without --dry-run (double-confirm) — the prior subtree is fetched and captured, and an inverse undo descriptor is recorded with an _undo_id.
6. Validate: proxy-aiops routes list, proxy-aiops analyze conflicts, and proxy-aiops analyze errors → confirm the edit did what you meant and did not shadow an existing route.
7. Failure branch: proxy-aiops undo list → undo apply restores the captured subtree exactly. If the config is too broken for a targeted undo, the config snapshot from step 1 is your fallback via load_config — but note load_config and config delete are risk=high with --dry-run + double confirmation at the CLI. load_config replaces the entire config, so it is a last resort, not a first instinct.

Governance & Safety

The skill delivers reads and writes and records them; it does not decide whether a write is permitted. That is your agent's judgement, or the permission of the account you connect it with (a read-only HAProxy Data Plane API role, a scoped Traefik/Caddy admin API — writes then fail at the server). There is no read-only switch, policy file, or approval gate.

• Audit is the guarantee, and it is not bypassable. Every operation — MCP and CLI alike — is logged to ~/.proxy-aiops/audit.db (relocatable via PROXY_AIOPS_HOME): params (secrets redacted), result, status, duration, and the risk tier. The CLI writes the same row the MCP path does.
• PROXY_AUDIT_APPROVED_BY / PROXY_AUDIT_RATIONALE are optional annotations recorded on the audit row (who/why); they are never required and never block.
• Runaway guard — a safety backstop, not authorization: the same call looped in a tight window trips a circuit breaker. Disable with PROXY_RUNAWAY_MAX=0.
• Writes support --dry-run / dry_run=True and double confirmation at the CLI; CLI writes execute through the same governed tools, so they are audited + undo-recorded.
• Reversible writes capture the real fetched before-state and record an inverse descriptor that replays against the tool's own signature.
• Traefik targets accept no writes at all — the support matrix teaches you to edit the provider source instead.

References

• references/capabilities.md — full tool + platform + API-path reference
• references/cli-reference.md — CLI command reference
• references/setup-guide.md — onboarding, credentials, and connectivity
• docs/VERIFICATION.md — live-verification checklist (what the mock suite covers, and what a real-proxy run must prove)