README.md

metadata

title: AgentCTL – Kubernetes Agent UI
emoji: 🧠
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 4.42.0
app_file: app.py
pinned: false

AgentCTL — LLM-Driven Kubernetes Automation

Natural Language → Kubernetes Jobs, Deployments & CronJobs

Built for real clusters via Minikube + kubectl proxy + ngrok or Cloudflare Tunnel.

---

🚀 Overview

AgentCTL is an agentic workflow system that converts natural language instructions into Kubernetes manifests (Jobs, Deployments, CronJobs) and applies them to a real Kubernetes cluster.

It works by exposing your cluster via:

• kubectl proxy
• a public tunnel (ngrok or cloudflared)
• a Gradio web UI
• a lightweight NL → YAML agent (heuristic + optional OpenAI LLM)

---

✨ Features

• Natural language → Kubernetes YAML
• Supports:
  • Jobs
  • Deployments
  • CronJobs
• Optional OpenAI LLM YAML refinement
• Cluster dashboard (Jobs, Pods, Deployments, CronJobs)
• Pod logs viewer
• Pure HTTP client — no kubeconfig required

---

🧱 Architecture

Gradio UI → AgentCTL (NL→YAML) → K8sClient (HTTP) → Kubernetes API

---

📦 Installation

pip install -r requirements.txt

or

conda create -n agentctl python=3.10 -y
conda activate agentctl
pip install -r requirements.txt

---

🧪 Minikube Setup

minikube start --driver=docker
kubectl get pods -A

Expose API publicly:

kubectl proxy   --port=8001   --address=0.0.0.0   --accept-hosts='.*'   --accept-paths='.*'

Tunnel:

ngrok http 8001

---

🌐 Environment Variables

export K8S_API_BASE_URL="https://xxxx.ngrok-free.dev"
export K8S_NAMESPACE="default"
export K8S_VERIFY_SSL=false

Enable LLM YAML:

export AGENTCTL_USE_LLM=true
export OPENAI_API_KEY="sk-..."
export OPENAI_MODEL="gpt-4o-mini"

---

▶️ Run the App

python app.py

Open:

http://localhost:7860

---

📝 Usage Examples

🟦 Job

run a python job to preprocess data

🟧 Deployment

Prompt
create an nginx deployment with 3 replicas

Example
**Generated YAML:**

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  namespace: default
  labels:
    app: agentctl-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: agentctl-deployment
  template:
    metadata:
      labels:
        app: agentctl-deployment
    spec:
      containers:
        - name: main
          image: nginx:1.27-alpine
          ports:
            - containerPort: 80

🟩 CronJob

Prompt
schedule a python cleanup script every 5 minutes

example
apiVersion: batch/v1
kind: CronJob
metadata:
  name: agentctl-cronjob
  namespace: default
spec:
  schedule: "*/5 * * * *"
  jobTemplate:
    spec:
      template:
        metadata:
          labels:
            app: agentctl-cronjob
        spec:
          restartPolicy: Never
          containers:
            - name: main
              image: python:3.11-slim
              command:
                - /bin/sh
                - -c
                - python cleanup.py

---

🚀 Deploy to Hugging Face Spaces

1. Create a Space (Gradio)
2. Upload project files
3. Set environment variables
4. Run the UI remotely controlling your real cluster

---

🔐 Security Notes

• ngrok + kubectl proxy is for demos only
• For real environments use:
  • Cloudflare Tunnel
  • RBAC service accounts
  • Namespaced permissions

---

❤️ Credits

Built by Murali Chandran (codeninja3d)
AI Agents • Kubernetes • MLOps

---

📄 License

MIT License