Why PlatformOps AI

PlatformOps AI helps operators investigate platform workloads without giving an AI model unrestricted infrastructure access. It can inspect namespaces, pods, events, logs, Services, Endpoints, Ingresses, Prometheus signals, ArgoCD applications, and Jenkins builds, then return operator-readable reports with evidence and limitations.

The current release focuses on read-only Kubernetes, Prometheus, and delivery investigation. The architecture is designed to grow into source control, controlled orchestration, and approval-gated remediation.

Jenkins appears in examples because it is a familiar platform workload, but PlatformOps AI is not Jenkins-specific. It can inspect any Kubernetes namespace or service that your kubeconfig can read and that you include in the namespace allowlist.

For the current system design, see the architecture diagram.

Install

pip install platformops-ai

Requirements:

• Python 3.11+
• Kubernetes access through kubeconfig or an in-cluster service account

Confirm your Kubernetes context first:

kubectl config current-context
kubectl get nodes

Quick Start

List cluster nodes:

platformops k8s nodes

Scan multiple allowed namespaces and rank what needs attention:

platformops scan cluster --allowed-namespaces argocd,jenkins,monitoring

Investigate a namespace with pod status, events, and bounded log excerpts:

platformops k8s investigate --namespace jenkins --allowed-namespaces jenkins

Generate a deterministic diagnosis report:

platformops diagnose k8s --namespace jenkins --allowed-namespaces jenkins

Diagnose a service path:

platformops diagnose service jenkins --namespace jenkins --allowed-namespaces jenkins

Use the same commands for any namespace or service:

platformops diagnose k8s --namespace argocd --allowed-namespaces argocd
platformops diagnose k8s --namespace monitoring --allowed-namespaces monitoring
platformops diagnose service argocd-server --namespace argocd --allowed-namespaces argocd

Correlate Kubernetes diagnosis with Prometheus:

platformops diagnose k8s \
  --namespace jenkins \
  --allowed-namespaces jenkins \
  --prometheus-url http://prometheus.monitoring.svc:9090

Check delivery health from ArgoCD and Jenkins:

platformops delivery argocd apps --namespace jenkins
platformops delivery jenkins builds --job platform/jenkins
platformops diagnose delivery --namespace jenkins --job platform/jenkins

Investigate one app across Kubernetes, service-path, Prometheus, ArgoCD, and Jenkins:

platformops investigate app jenkins \
  --namespace jenkins \
  --job platform/jenkins

Use JSON output when you want machine-readable evidence:

platformops --output json diagnose k8s --namespace jenkins --allowed-namespaces jenkins

Use markdown output for incident notes:

platformops --output markdown diagnose service jenkins --namespace jenkins --allowed-namespaces jenkins

What It Can Diagnose

v0.6.1 includes deterministic Kubernetes, service-path, cluster triage, Prometheus correlation, delivery, and app investigation rules for:

• CrashLoopBackOff-style restarts
• ImagePullBackOff and image pull failures
• Pending or unschedulable pods
• readiness failures
• restarted but currently ready pods
• empty namespaces
• ranked findings across allowed namespaces
• policy and provider errors
• Prometheus target-down correlation
• Prometheus firing-alert correlation
• Services with missing ready endpoints
• Ingress routes attached to a service
• ArgoCD degraded, missing, or out-of-sync applications
• failed, unstable, aborted, or running Jenkins builds
• cross-source app evidence chains and likely explanations

Example output:

Status: warning
Namespace 'jenkins' needs attention.

Findings
- [warning] jenkins-0 restarted but is currently ready
  jenkins-0 is currently ready (2/2) but has 4 restart(s).

Recommended next actions
- Compare restart timestamps with node restarts, upgrades, or deploys
- Inspect previous logs if the restart is recent or recurring

CLI Reference

Kubernetes inventory:

platformops k8s nodes
platformops k8s namespaces
platformops k8s pods --namespace default

Kubernetes evidence:

platformops k8s pod POD_NAME --namespace default
platformops k8s events --namespace default
platformops k8s events --namespace default --pod POD_NAME
platformops k8s logs POD_NAME --namespace default --tail-lines 100
platformops k8s logs POD_NAME --namespace default --previous
platformops k8s services --namespace default
platformops k8s endpoints SERVICE_NAME --namespace default
platformops k8s ingresses --namespace default

Kubernetes investigation and diagnosis:

platformops k8s investigate --namespace default --allowed-namespaces default
platformops diagnose k8s --namespace default --allowed-namespaces default
platformops diagnose service SERVICE_NAME --namespace default --allowed-namespaces default
platformops scan cluster --allowed-namespaces default,jenkins,monitoring

Prometheus evidence:

platformops prometheus --prometheus-url http://localhost:9090 query up
platformops prometheus --prometheus-url http://localhost:9090 targets
platformops prometheus --prometheus-url http://localhost:9090 alerts

Delivery evidence:

platformops delivery argocd apps
platformops delivery argocd apps --namespace jenkins
platformops delivery jenkins builds
platformops delivery jenkins builds --job platform/jenkins --limit 5
platformops diagnose delivery --namespace jenkins --job platform/jenkins
platformops investigate app jenkins --namespace jenkins --job platform/jenkins

Connection options:

platformops k8s --context my-context nodes
platformops k8s --provider fake nodes
platformops k8s --provider fixture --fixture tests/scenarios/crashloopbackoff.json investigate --namespace platformops-demo

Safety option:

--allowed-namespaces default,jenkins,monitoring

When set, PlatformOps only returns namespace-scoped evidence from the allowed namespaces.

Verify Your Cluster

Start by listing namespaces:

platformops k8s namespaces

Then inspect the namespaces that matter in your environment:

platformops diagnose k8s --namespace argocd --allowed-namespaces argocd
platformops diagnose k8s --namespace jenkins --allowed-namespaces jenkins
platformops diagnose k8s --namespace monitoring --allowed-namespaces monitoring

For service-path checks, list services first:

platformops k8s services --namespace argocd --allowed-namespaces argocd

Then diagnose a specific service:

platformops diagnose service argocd-server --namespace argocd --allowed-namespaces argocd

Cluster scans inspect multiple allowed namespaces and rank findings across that selected scope. Single namespace and single service commands are still useful when you already know where to look.

MCP Server

PlatformOps also ships an MCP server:

platformops-mcp-k8s

The MCP server is for AI applications that support the Model Context Protocol. PlatformOps provides the tools; your MCP host provides the chat UI, model, and tool-calling loop.

User
  -> MCP host and selected LLM
  -> PlatformOps MCP server
  -> Kubernetes, Prometheus, ArgoCD, and Jenkins APIs

Example MCP client configuration:

{
  "mcpServers": {
    "platformops-kubernetes": {
      "command": "platformops-mcp-k8s",
      "env": {
        "PLATFORMOPS_K8S_PROVIDER": "api",
        "PLATFORMOPS_K8S_ALLOWED_NAMESPACES": "default,jenkins"
      }
    }
  }
}

Use fake mode when you want to test tool discovery without a cluster:

{
  "mcpServers": {
    "platformops-kubernetes": {
      "command": "platformops-mcp-k8s",
      "env": {
        "PLATFORMOPS_K8S_PROVIDER": "fake",
        "PLATFORMOPS_PROMETHEUS_PROVIDER": "fake",
        "PLATFORMOPS_DELIVERY_PROVIDER": "fake"
      }
    }
  }
}

Use API mode for a real cluster. The MCP server uses the kubeconfig or service account available to the process:

{
  "mcpServers": {
    "platformops-kubernetes": {
      "command": "platformops-mcp-k8s",
      "env": {
        "PLATFORMOPS_K8S_PROVIDER": "api",
        "PLATFORMOPS_K8S_ALLOWED_NAMESPACES": "argocd,jenkins,monitoring",
        "PLATFORMOPS_PROMETHEUS_URL": "http://localhost:9090",
        "PLATFORMOPS_DELIVERY_PROVIDER": "api",
        "PLATFORMOPS_ARGOCD_URL": "https://argocd.example.com",
        "PLATFORMOPS_ARGOCD_TOKEN": "...",
        "PLATFORMOPS_JENKINS_URL": "https://jenkins.example.com",
        "PLATFORMOPS_JENKINS_USER": "...",
        "PLATFORMOPS_JENKINS_TOKEN": "..."
      }
    }
  }
}

Example questions to ask your MCP host:

What pods are unhealthy in the jenkins namespace?
Scan argocd, jenkins, and monitoring and rank what needs attention.
Diagnose the argocd-server service in the argocd namespace.
Check whether ArgoCD or Jenkins explains the jenkins namespace issue.
Investigate the jenkins app across Kubernetes, service, Prometheus, ArgoCD, and Jenkins.
Check whether Prometheus has firing alerts related to monitoring.
List Kubernetes services in the jenkins namespace.

Available MCP tools:

• get_nodes()
• list_namespaces()
• list_pods(namespace=None)
• get_pod(namespace, name)
• list_events(namespace, pod_name=None)
• get_pod_logs(namespace, name, container=None, tail_lines=100)
• list_services(namespace)
• get_endpoints(namespace, service_name)
• list_ingresses(namespace)
• investigate_namespace(namespace, tail_lines=50)
• diagnose_namespace(namespace, tail_lines=80)
• diagnose_service_path(name, namespace, tail_lines=80)
• scan_cluster(namespaces=None, tail_lines=80)
• list_argocd_apps(namespace=None)
• list_jenkins_builds(job_name=None, limit=10)
• diagnose_delivery(namespace=None, app_name=None, job_name=None, build_limit=10)
• investigate_app(app, namespace, service_name=None, argocd_app=None, jenkins_job=None, tail_lines=80)
• prometheus_query(query)
• prometheus_targets()
• prometheus_alerts()

The MCP server does not require an LLM API key. It exposes tools and evidence to an MCP-capable host; the host owns model selection.

Configuration

Environment variables:

PLATFORMOPS_K8S_PROVIDER=api
PLATFORMOPS_K8S_ALLOWED_NAMESPACES=default,jenkins
PLATFORMOPS_K8S_CONTEXT=
PLATFORMOPS_K8S_IN_CLUSTER=false
PLATFORMOPS_PROMETHEUS_PROVIDER=api
PLATFORMOPS_PROMETHEUS_URL=http://localhost:9090
PLATFORMOPS_PROMETHEUS_BEARER_TOKEN=
PLATFORMOPS_DELIVERY_PROVIDER=api
PLATFORMOPS_ARGOCD_URL=https://argocd.example.com
PLATFORMOPS_ARGOCD_TOKEN=
PLATFORMOPS_JENKINS_URL=https://jenkins.example.com
PLATFORMOPS_JENKINS_USER=
PLATFORMOPS_JENKINS_TOKEN=

Provider modes:

• api: use the real Kubernetes API through kubeconfig or in-cluster config
• fake: use deterministic built-in sample data
• fixture: use a local JSON fixture file

Prometheus can be configured with --prometheus-url, PLATFORMOPS_PROMETHEUS_URL, or fixture/fake provider modes for tests and demos.

Delivery can be configured with --delivery-provider fake|fixture|api, --delivery-fixture, or ArgoCD/Jenkins environment variables.

Security Model

PlatformOps AI is read-only in v0.x.

It does not support:

• arbitrary shell commands
• arbitrary kubectl commands
• create, update, patch, or delete operations
• automatic restarts, scaling, rollbacks, or deployments

It does support:

• official Kubernetes API reads
• official ArgoCD, Jenkins, and Prometheus API reads
• namespace allowlists
• bounded log reads
• structured evidence envelopes
• deterministic diagnosis without an LLM

Do not commit kubeconfigs, service-account tokens, .env files, LLM keys, private certificates, or sensitive logs.

Local Development

git clone https://github.com/FAHID-KHAN/platformops-ai.git
cd platformops-ai
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest

Run with fixture data:

platformops k8s --provider fixture \
  --fixture tests/scenarios/crashloopbackoff.json \
  investigate --namespace platformops-demo \
  --allowed-namespaces platformops-demo

Project Status

Current release: v0.6.1 - Cross-Source App Investigation

Roadmap:

• v0.7.0: orchestrated investigation experiments
• v1.0.0: approval-gated remediation

Documentation

• Documentation index
• Current setup diagram
• Architecture overview
• Kubernetes diagnosis runbook
• Prometheus correlation runbook
• Service path diagnosis runbook
• Cluster triage runbook
• Delivery investigation runbook
• App investigation runbook
• MCP server runbook
• Roadmap
• ADR index
• Security policy