orca-k8s-connector-troubleshoot
Orca Kubernetes Connector Troubleshooting Skill
Answers: "Why isn't my Kubernetes Connector installing or connecting, and how do I fix it myself before opening a support ticket?"
Background
The Kubernetes Connector (aka K8s Tunnel Client, Helm chart orca-tunnel, image k8s-tunnel-client) runs entirely on the customer's own cluster. It opens a read-only outbound tunnel (built on frp) back to Orca so private and self-managed clusters can be scanned without exposing the cluster's API server to Orca. Because it runs on customer infrastructure, failures are invisible to Orca until the customer reports them. Most of what's covered here can be self-diagnosed from helm status, kubectl describe, and pod logs alone — that's the point of this skill.
Quick glossary (so the categories below don't have to re-explain these every time):
| Term | Means |
|---|---|
frp |
The open-source reverse-proxy library the tunnel is built on. TCP only — if a firewall log shows UDP traffic, that's unrelated noise, not the tunnel. |
| Tunnel target | Orca's server-side record of a specific cluster's tunnel. Can go stale (survive after the customer uninstalls the chart) and is only cleanable by Orca support/on-call. |
tunnelId / tunnelToken |
The credential pair from Orca's cluster-onboarding screen. Unique per cluster — never reuse one from a different cluster. |
cloudVendorId |
The cloud-vendor-specific cluster identifier (format varies by vendor — see the Connecting Clusters doc). The single most common typo source in install commands. |
| SCC | OpenShift's Security Context Constraint — its equivalent of a PodSecurityPolicy. |