diagnose-network-issue

X-McKay's avatarfrom X-McKay

Diagnose network connectivity issues for pods. Checks DNS resolution, service connectivity, and network policies. Use when pods cannot communicate with other services. Keywords: network issue, DNS, connectivity, service unreachable, network policy, CNI.

⭐1stars🔀0forks📁View on GitHub🕐Updated Jan 11, 2026
[Incident Response]

When & Why to Use This Skill

This Claude skill automates the complex process of diagnosing Kubernetes pod network connectivity issues. By systematically verifying DNS resolution, service reachability, and NetworkPolicy configurations, it enables SREs and DevOps engineers to rapidly pinpoint root causes like CNI failures or restrictive security rules, significantly reducing Mean Time to Repair (MTTR) in cloud-native environments.

Use Cases

  • Troubleshooting 'Service Unreachable' or 'Connection Timeout' errors between microservices to determine if the fault lies in DNS resolution or network routing.
  • Identifying and auditing restrictive Kubernetes NetworkPolicies that are inadvertently blocking legitimate egress traffic from application pods to external databases or APIs.
  • Rapidly diagnosing connectivity failures during production incidents to distinguish between application-level configuration errors and underlying cluster infrastructure issues.
  • Validating network connectivity for newly deployed pods in a namespace to ensure all required service paths are open and functional.
namediagnose-network-issue
description>
other services. Keywordsnetwork issue, DNS, connectivity, service unreachable,
domaink8s
categorydiagnostic
requires-approvalfalse
confidence0.75

Diagnose Network Issue

Preconditions

Before applying this skill, verify:

  • Pod name and namespace are known
  • Pod is in Running state
  • Network issue symptoms are observed

Actions

1. Get Pod Details

Check pod networking configuration.

mcp_tool: kubernetes-mcp-server/pods_get
params:
  name: $pod_name
  namespace: $namespace
timeout: 30s

2. Check DNS Resolution

Execute DNS lookup inside the pod.

mcp_tool: kubernetes-mcp-server/pods_exec
params:
  name: $pod_name
  namespace: $namespace
  command: ["nslookup", "kubernetes.default"]
timeout: 30s

3. Check Service Connectivity

Test connection to target service.

mcp_tool: kubernetes-mcp-server/pods_exec
params:
  name: $pod_name
  namespace: $namespace
  command: ["wget", "-O-", "-T5", "$target_service"]
timeout: 30s

4. Get Network Policies

Check if network policies affect the pod.

mcp_tool: kubernetes-mcp-server/resources_list
params:
  apiVersion: networking.k8s.io/v1
  kind: NetworkPolicy
  namespace: $namespace
timeout: 30s

5. Check Pod Events

Look for network-related events.

mcp_tool: kubernetes-mcp-server/events_list
params:
  namespace: $namespace
timeout: 30s

Success Criteria

The skill succeeds when:

  • DNS resolution works (kubernetes.default resolves)
  • No blocking network policies found
  • Root cause identified

Failure Handling

If diagnosis is inconclusive:

  1. Check CNI plugin logs on the node
  2. Verify kube-proxy is running
  3. Escalate with gathered diagnostic info

Examples

Input Context:

{
  "pod_name": "web-app-abc123",
  "namespace": "default",
  "target_service": "http://api-service:8080"
}

Output:

{
  "dns_working": true,
  "service_reachable": false,
  "network_policies": ["deny-external"],
  "diagnosis": "NetworkPolicy 'deny-external' blocking egress traffic",
  "recommendation": "Add egress rule to allow traffic to api-service"
}