Kubernetes Connector

The Kubernetes connector provides deep visibility into your clusters with 11 live tools and comprehensive ETL ingestion of workloads, networking, and configuration into the knowledge graph.

Authentication

The Kubernetes connector supports two authentication modes: an external kubeconfig file or in-cluster service account credentials.

Kubeconfig File

Provide the path to a kubeconfig file or the raw kubeconfig content:

{
  "name": "Production Cluster",
  "source_type": "kubernetes",
  "config": {
    "kubeconfig": "/path/to/kubeconfig",
    "context": "prod-cluster"
  }
}

Or provide the kubeconfig content inline:

{
  "name": "Production Cluster",
  "source_type": "kubernetes",
  "config": {
    "kubeconfig_data": "apiVersion: v1\nclusters:\n- cluster:\n    server: https://k8s.example.com:6443\n    certificate-authority-data: LS0t...\n  name: prod\n...",
    "context": "prod"
  }
}

Variable	Required	Description
kubeconfig / KUBECONFIG	Yes (or in-cluster)	Path to the kubeconfig file
kubeconfig_data	No	Raw kubeconfig YAML content (alternative to file path)
context	No	Kubeconfig context to use (defaults to current context)

In-Cluster Authentication

When Agentcy is deployed inside a Kubernetes cluster, it can use the pod's service account token automatically:

{
  "name": "Self Cluster",
  "source_type": "kubernetes",
  "config": {
    "in_cluster": true
  }
}

TIP

Create a dedicated ClusterRole and ClusterRoleBinding for the Agentcy service account. See RBAC Configuration below.

Live Tools (11)

Tool	Description	Arguments
k8s_list_pods	List pods with status, restarts, and resource usage	namespace?, label_selector?
k8s_get_pod	Get detailed pod info including containers, events, and volumes	name, namespace
k8s_get_pod_logs	Retrieve container logs from a pod	name, namespace, container?, tail_lines?, since?
k8s_list_deployments	List deployments with replica counts and rollout status	namespace?, label_selector?
k8s_get_deployment	Get detailed deployment info including strategy and conditions	name, namespace
k8s_get_deployment_status	Get the rollout status of a deployment	name, namespace
k8s_list_services	List services with type, cluster IP, and external endpoints	namespace?
k8s_list_namespaces	List all namespaces with status and labels	--
k8s_list_nodes	List cluster nodes with capacity, allocatable resources, and conditions	--
k8s_list_configmaps	List ConfigMaps in a namespace	namespace?, label_selector?
k8s_list_events	List events in a namespace	namespace?, field_selector?

Example: Agent Using Kubernetes Tools

User: "Are any pods crashing in the production namespace?"

Agent: Let me check the pods in production.
→ Calls k8s_list_pods(namespace: "production")
→ Finds 2 pods with CrashLoopBackOff status
→ Calls k8s_get_pod_logs(name: "api-server-7f8b9c-x4k2p", namespace: "production", tail_lines: 50)
→ Reports: "The api-server pod is crash-looping due to a database connection timeout.
  Last error: 'Failed to connect to postgres:5432 — connection refused'"

User: "What's the rollout status of the api-server deployment?"

Agent: I'll check the deployment status.
→ Calls k8s_get_deployment_status(name: "api-server", namespace: "production")
→ Reports: "Deployment api-server: 3/3 replicas ready, rollout complete."

ETL Ingestion

When you trigger a sync, the Kubernetes connector ingests the following resources into the knowledge graph.

Nodes Created

Node Label	Properties	K8s Resource
Pod	name, namespace, status, phase, node_name, restart_count, ip, start_time, image	Pod
Deployment	name, namespace, replicas, ready_replicas, strategy, selector, image	Deployment
Service	name, namespace, type, cluster_ip, external_ip, ports, selector	Service
Namespace	name, status, labels, annotations	Namespace
Node	name, status, roles, capacity_cpu, capacity_memory, os_image, kubelet_version	Node
ConfigMap	name, namespace, data_keys	ConfigMap
Event	name, namespace, type, reason, message, involved_object, last_timestamp	Event
Ingress	name, namespace, hosts, paths, tls_enabled, ingress_class	Ingress

Relationships Created

Relationship	From	To
RUNS_IN	Pod	Namespace
SCHEDULED_ON	Pod	Node
MANAGED_BY	Pod	Deployment
EXPOSES	Service	Pod
ROUTES_TO	Ingress	Service
MOUNTS	Pod	ConfigMap
CONTAINS	Namespace	Deployment, Service

Graph Queries

-- Find all pods on a specific node with their deployments
MATCH (p:Pod)-[:SCHEDULED_ON]->(n:Node),
      (p)-[:MANAGED_BY]->(d:Deployment)
WHERE n.name = "node-01"
RETURN d.name, p.name, p.status, p.restart_count

-- Find the full request path: Ingress → Service → Pod → Node
MATCH (i:Ingress)-[:ROUTES_TO]->(s:Service)-[:EXPOSES]->(p:Pod)-[:SCHEDULED_ON]->(n:Node)
WHERE i.hosts CONTAINS "api.example.com"
RETURN i.name, s.name, p.name, n.name, p.status

-- Find pods mounting a specific ConfigMap
MATCH (p:Pod)-[:MOUNTS]->(cm:ConfigMap)
WHERE cm.name = "app-config"
RETURN p.name, p.namespace, p.status

-- Cross-namespace service dependencies
MATCH (s1:Service)-[:EXPOSES]->(p1:Pod)-[:RUNS_IN]->(ns1:Namespace),
      (s2:Service)-[:EXPOSES]->(p2:Pod)-[:RUNS_IN]->(ns2:Namespace)
WHERE ns1 <> ns2
RETURN ns1.name, s1.name, ns2.name, s2.name

RBAC Configuration

Create a read-only ClusterRole for the Agentcy connector:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: agentcy-reader
rules:
  - apiGroups: [""]
    resources:
      - pods
      - pods/log
      - services
      - namespaces
      - nodes
      - configmaps
      - events
    verbs: ["get", "list", "watch"]
  - apiGroups: ["apps"]
    resources:
      - deployments
    verbs: ["get", "list", "watch"]
  - apiGroups: ["networking.k8s.io"]
    resources:
      - ingresses
    verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: agentcy-reader-binding
subjects:
  - kind: ServiceAccount
    name: agentcy
    namespace: agentcy
roleRef:
  kind: ClusterRole
  name: agentcy-reader
  apiGroup: rbac.authorization.k8s.io

Configuration Reference

{
  "name": "Production Cluster",
  "source_type": "kubernetes",
  "config": {
    "kubeconfig": "/path/to/kubeconfig",
    "context": "prod-cluster",
    "namespaces": ["production", "staging"],
    "exclude_namespaces": ["kube-system", "kube-public"],
    "sync_pods": true,
    "sync_deployments": true,
    "sync_services": true,
    "sync_configmaps": true,
    "sync_events": true,
    "sync_nodes": true,
    "sync_ingresses": true,
    "label_selector": "app.kubernetes.io/managed-by=helm"
  }
}

Field	Type	Default	Description
kubeconfig	string	~/.kube/config	Path to kubeconfig file
kubeconfig_data	string	--	Raw kubeconfig YAML content
context	string	current context	Kubeconfig context to use
in_cluster	bool	false	Use in-cluster service account auth
namespaces	string[]	all	Only ingest these namespaces
exclude_namespaces	string[]	[]	Skip these namespaces during ingestion
sync_pods	bool	true	Include pods in ingestion
sync_deployments	bool	true	Include deployments in ingestion
sync_services	bool	true	Include services in ingestion
sync_configmaps	bool	true	Include ConfigMaps in ingestion
sync_events	bool	true	Include events in ingestion
sync_nodes	bool	true	Include cluster nodes
sync_ingresses	bool	true	Include Ingress resources
label_selector	string	--	Only ingest resources matching this label selector

Troubleshooting

Error	Cause	Fix
401 Unauthorized	Kubeconfig token expired or service account missing	Refresh kubeconfig or verify service account token
403 Forbidden	RBAC role lacks required permissions	Update the ClusterRole with missing resources/verbs
Connection refused	API server unreachable from Agentcy	Check network connectivity and firewall rules
No such context	Specified context not found in kubeconfig	Run kubectl config get-contexts to list available contexts
Timeout	API server is slow or cluster is overloaded	Increase timeout or reduce the number of namespaces to sync

Verifying Access

Test your credentials from the command line:

# Verify cluster access
kubectl cluster-info --context prod-cluster

# Test pod listing
kubectl get pods --all-namespaces --context prod-cluster

# Check RBAC permissions
kubectl auth can-i list pods --all-namespaces \
  --as=system:serviceaccount:agentcy:agentcy