kubectl cluster-info

When to Use kubectl cluster-info

kubectl cluster-info is one of the first commands you should run when troubleshooting cluster connectivity. It contacts the Kubernetes API server and prints the URLs of the control plane and any installed cluster services such as CoreDNS, the Kubernetes Dashboard, or metrics-server.

Basic Usage

When you run the command without any subcommands, it provides a concise summary:

kubectl cluster-info
# Output:
# Kubernetes control plane is running at https://192.168.1.100:6443
# CoreDNS is running at https://192.168.1.100:6443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy

This tells you the API server address and confirms your kubeconfig is correctly pointing to a live cluster. If you receive a connection refused or timeout error, the problem lies in your network configuration, VPN, or kubeconfig settings.

The dump Subcommand

For comprehensive debugging, cluster-info dump gathers cluster state across multiple namespaces:

# Dump everything to a directory
kubectl cluster-info dump --output-directory=/tmp/cluster-dump

# Dump only specific namespaces
kubectl cluster-info dump --namespaces=kube-system,monitoring --output-directory=/tmp/debug

The dump includes:

• Node descriptions and status
• Pod listings and logs from system namespaces
• Event streams
• ReplicationController and Service information

This output is invaluable when filing issues with cluster providers or upstream Kubernetes. Many support teams will request a cluster dump as a first step.

Interpreting the Output

The cluster-info output reveals the internal service proxy URLs. These URLs follow the pattern:

https://<api-server>/api/v1/namespaces/<namespace>/services/<service>:<port>/proxy

You can use kubectl proxy to access these services locally through the API server proxy, which is useful for accessing dashboards or internal metrics endpoints without exposing them externally.

Comparing with Other Diagnostic Commands

| Command | Purpose | |---------|---------| | kubectl cluster-info | Shows API server URL and service endpoints | | kubectl version | Shows client and server version information | | kubectl get nodes | Lists nodes and their status | | kubectl get componentstatuses | Checks health of etcd, scheduler, controller-manager |

Using with Multiple Clusters

When managing multiple clusters, always verify which cluster you are targeting:

# Check current context first
kubectl config current-context

# Then verify the cluster endpoint
kubectl cluster-info

# Or specify context explicitly
kubectl cluster-info --context=staging

Automation and Scripting

In CI/CD pipelines, kubectl cluster-info serves as a readiness gate:

#!/bin/bash
# Wait for cluster to be reachable
until kubectl cluster-info &>/dev/null; do
  echo "Waiting for cluster..."
  sleep 5
done
echo "Cluster is reachable."

This pattern is common in bootstrap scripts and Helm chart test suites. The command exits with a non-zero code when the API server is unreachable, making it ideal for shell conditionals.

Security Considerations

The output of cluster-info can reveal internal network topology. Avoid sharing the raw output in public channels. The dump subcommand may capture pod logs containing sensitive environment variables or secrets, so treat dump directories with the same care as production credentials.