diff --git a/contrib/tools/kyverno-mcp-server/README.md b/contrib/tools/kyverno-mcp-server/README.md new file mode 100644 index 000000000..82d3ea7cf --- /dev/null +++ b/contrib/tools/kyverno-mcp-server/README.md @@ -0,0 +1,94 @@ +# Kyverno MCP Server + +This directory contains the Kubernetes deployment and configuration files for running the [Kyverno MCP Server](https://github.com/Fulcria-Labs/kyverno-mcp-server) within the kagent ecosystem. + +## What is Kyverno? + +[Kyverno](https://kyverno.io/) is a CNCF Graduated policy engine for Kubernetes. It allows cluster administrators to manage security, compliance, and best practices using policies as Kubernetes resources. The Kyverno MCP Server makes these policy operations accessible to AI agents. + +## Capabilities + +The MCP server exposes 8 tools for policy management: + +| Tool | Description | +|------|-------------| +| `list_policies` | List ClusterPolicies or namespace-scoped policies | +| `get_policy` | Get detailed policy configuration | +| `explain_policy` | Human-readable explanation of what a policy does | +| `list_policy_reports` | Compliance status from policy reports | +| `get_policy_violations` | Find non-compliant resources | +| `check_resource_compliance` | Check if a specific resource is compliant | +| `generate_policy` | Generate common policy templates | +| `get_compliance_summary` | Cluster-wide compliance percentage | + +## Installation + +### Prerequisites + +- Kubernetes cluster with [Kyverno](https://kyverno.io/docs/installation/) installed +- kagent deployed to the cluster + +### 1. Build and Load the MCP Server Image + +```bash +# Clone the MCP server repo +git clone https://github.com/Fulcria-Labs/kyverno-mcp-server.git +cd kyverno-mcp-server + +# Build the container image +docker build -t kyverno-mcp-server:latest . + +# If using Kind, load the image +kind load docker-image kyverno-mcp-server:latest --name kagent +``` + +### 2. Deploy the MCP Server + +```bash +kubectl apply -f deploy-kyverno-mcp-server.yaml +``` + +This creates: +- ServiceAccount with read-only access to Kyverno CRDs and policy reports +- ClusterRole and ClusterRoleBinding +- Service exposing port 8089 (MCP) +- Deployment running the MCP server + +### 3. Register with kagent + +```bash +kubectl apply -f kyverno-remote-mcpserver.yaml +``` + +### 4. Create the Kyverno Agent + +```bash +kubectl apply -f kyverno-agent.yaml +``` + +## Usage + +Once deployed, the Kyverno agent will appear in the kagent UI. You can ask it questions like: + +- "What policies are deployed in my cluster?" +- "Are there any policy violations?" +- "Explain the disallow-privileged policy" +- "Generate a policy to require resource limits" +- "What's the overall compliance status?" + +## Troubleshooting + +```bash +# Check MCP server status +kubectl get pods -n kagent -l app.kubernetes.io/name=kyverno-mcp-server +kubectl logs -n kagent -l app.kubernetes.io/name=kyverno-mcp-server + +# Verify Kyverno is installed +kubectl get crd | grep kyverno +``` + +## Learn More + +- [Kyverno Documentation](https://kyverno.io/docs/) +- [Kyverno MCP Server Source](https://github.com/Fulcria-Labs/kyverno-mcp-server) +- [MCP Protocol](https://modelcontextprotocol.io/) diff --git a/contrib/tools/kyverno-mcp-server/deploy-kyverno-mcp-server.yaml b/contrib/tools/kyverno-mcp-server/deploy-kyverno-mcp-server.yaml new file mode 100644 index 000000000..db06dc7c2 --- /dev/null +++ b/contrib/tools/kyverno-mcp-server/deploy-kyverno-mcp-server.yaml @@ -0,0 +1,100 @@ +apiVersion: v1 +kind: ServiceAccount +metadata: + name: kyverno-mcp-server + namespace: kagent +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: kyverno-mcp-server +rules: + - apiGroups: ["kyverno.io"] + resources: ["clusterpolicies", "policies", "policyexceptions"] + verbs: ["get", "list", "watch"] + - apiGroups: ["wgpolicyk8s.io"] + resources: ["clusterpolicyreports", "policyreports"] + verbs: ["get", "list", "watch"] + - apiGroups: [""] + resources: ["namespaces"] + verbs: ["get", "list"] +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: kyverno-mcp-server +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: kyverno-mcp-server +subjects: + - kind: ServiceAccount + name: kyverno-mcp-server + namespace: kagent +--- +apiVersion: v1 +kind: Service +metadata: + name: kyverno-mcp-server + namespace: kagent + labels: + app.kubernetes.io/name: kyverno-mcp-server +spec: + ports: + - name: mcp + port: 8089 + targetPort: 8089 + protocol: TCP + selector: + app.kubernetes.io/name: kyverno-mcp-server +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: kyverno-mcp-server + namespace: kagent + labels: + app.kubernetes.io/name: kyverno-mcp-server +spec: + replicas: 1 + selector: + matchLabels: + app.kubernetes.io/name: kyverno-mcp-server + template: + metadata: + labels: + app.kubernetes.io/name: kyverno-mcp-server + spec: + serviceAccountName: kyverno-mcp-server + containers: + - name: kyverno-mcp-server + image: ghcr.io/kagent-dev/kyverno-mcp-server:latest + imagePullPolicy: IfNotPresent + # To use a locally built image instead, set: + # image: kyverno-mcp-server:latest + # imagePullPolicy: Never + ports: + - name: mcp + containerPort: 8089 + env: + - name: MCP_PORT + value: "8089" + - name: MCP_HOST + value: "0.0.0.0" + resources: + requests: + cpu: 100m + memory: 128Mi + limits: + cpu: 500m + memory: 256Mi + readinessProbe: + tcpSocket: + port: 8089 + initialDelaySeconds: 5 + periodSeconds: 10 + livenessProbe: + tcpSocket: + port: 8089 + initialDelaySeconds: 10 + periodSeconds: 30 diff --git a/contrib/tools/kyverno-mcp-server/kyverno-agent.yaml b/contrib/tools/kyverno-mcp-server/kyverno-agent.yaml new file mode 100644 index 000000000..52ec7d8a5 --- /dev/null +++ b/contrib/tools/kyverno-mcp-server/kyverno-agent.yaml @@ -0,0 +1,55 @@ +apiVersion: kagent.dev/v1alpha2 +kind: Agent +metadata: + name: kyverno-agent + namespace: kagent +spec: + declarative: + modelConfig: default-model-config + stream: true + systemMessage: |- + You are a Kubernetes policy expert specializing in Kyverno. You help users + understand, manage, and troubleshoot their Kyverno policies. + + # Capabilities + - List and inspect Kyverno policies (both ClusterPolicies and namespace-scoped) + - Explain what policies do in plain English + - Check compliance status and find policy violations + - Generate common policy templates + - Provide a compliance summary across the cluster + + # Instructions + - When users ask about policies, start by listing them to understand what's deployed + - For compliance questions, use get_compliance_summary first for an overview + - When troubleshooting violations, use get_policy_violations to find specific issues + - Explain policies in simple terms - many users are new to Kyverno + - If generating policies, always explain what the generated policy does + - Recommend "Audit" mode for new policies so they don't block workloads immediately + - If you don't know something, say so rather than making things up + - For questions outside Kyverno scope, suggest appropriate tools or documentation + + # Response format + - ALWAYS format your response as Markdown + - Use tables for listing multiple items + - Include actionable next steps when reporting violations + - When showing YAML, use code blocks + tools: + - mcpServer: + apiGroup: kagent.dev + kind: RemoteMCPServer + name: kyverno-mcp-server + toolNames: + - list_policies + - get_policy + - list_policy_reports + - get_policy_violations + - check_resource_compliance + - generate_policy + - explain_policy + - get_compliance_summary + type: McpServer + description: >- + Kyverno policy management agent - helps users understand, manage, and + troubleshoot Kubernetes policies. Can list policies, explain what they do, + check compliance, find violations, and generate policy templates. + type: Declarative diff --git a/contrib/tools/kyverno-mcp-server/kyverno-remote-mcpserver.yaml b/contrib/tools/kyverno-mcp-server/kyverno-remote-mcpserver.yaml new file mode 100644 index 000000000..dff0b5eb1 --- /dev/null +++ b/contrib/tools/kyverno-mcp-server/kyverno-remote-mcpserver.yaml @@ -0,0 +1,11 @@ +apiVersion: kagent.dev/v1alpha2 +kind: RemoteMCPServer +metadata: + name: kyverno-mcp-server + namespace: kagent +spec: + protocol: SSE + url: "http://kyverno-mcp-server:8089/sse" + timeout: 30s + sseReadTimeout: 5m0s + description: "Kyverno policy management - list, inspect, explain, and audit Kubernetes policies"