Helm Chart Troubleshooting
This guide addresses common issues encountered during the deployment of the Tenable Kubernetes Helm chart.
Start here:
- If helm install exited with an error in the terminal, see Helm Install Fails.
- If the command completed but the cluster is missing or showing under the wrong account, see Helm Install Succeeds, but Something Is Wrong.
- If pods are crashing or the connection drops after a successful deployment, see Pods Fail or Connection Drops after Deployment.
Helm Install Fails
These errors occur during helm install. The command fails in the terminal because the pre-install hook — a validation job that runs during chart deployment — cannot complete, or because the provided account details are incorrect.
Pre-Install Hook Failure (Proxy/Network Blockage)
Symptom: The helm install command fails with a timeout or error indicating the hook failed.
Terminal Output:
Error: UPGRADE FAILED: pre-upgrade hooks failed: 1 error occurred: job kubernetes-cluster-pre-install-job failed: BackoffLimitExceeded
Diagnosis: Inspect the logs of the failed job to determine the cause.
-
Find the exact pod name:
Copykubectl get pods -n <your-namespace> - Check the logs:
kubectl logs job/kubernetes-cluster-pre-install-job-<suffix> -n <your-namespace>
Log Error to Look For:
System.Net.Http.HttpRequestException
Cause: This indicates a possible networking blockage. A corporate proxy, firewall, or deep packet inspection tool is intercepting the connection to Tenable's backend (app.tenable.com), or the pod is attempting to route internal Kubernetes API traffic through the proxy.
Solution:
- Configure Proxy — In values.yaml, ensure proxyUrl is set correctly. See Helm Optional Command Parameters (CLI).
- Set NO_PROXY — You must configure the NO_PROXY environment variable to include the Kubernetes API server domain (for example, kubernetes.default.svc). If this is missing, the job tries to reach the local API through the proxy and fails.
JSON
"containerEnvironmentVariables": [
{
"name": "NO_PROXY",
"value": "kubernetes.default.svc,10.0.0.0/8,.svc.cluster.local"
}
]
Image Pull Failures (403 Forbidden)
Symptom: The helm install hangs, or pods fail with status ImagePullBackOff or ErrImagePull.
Event Output: Failed to pull image... 403 Forbidden.
Cause:
- Firewall — A corporate firewall is blocking access to the public registry containers.tenable.com.
- Caching — The Helm client is trying to pull an outdated chart version (for example, 1.1.2) from local cache instead of the latest supported version.
Solution:
- Update Repo — Run helm repo update tenable to force the client to fetch the latest tags.
- Test Connectivity — Run wget or curl -v https://containers.tenable.com from a node or pod in the cluster to verify reachability.
- Private Registry — If the cluster is air-gapped, mirror the images to your private registry and update the registry, registryUsername, and registryPassword values in values.yaml. See Clusters with a Private Registry.
Account Verification Failure (TenantNotExist)
Symptom: The helm install fails with BackoffLimitExceeded, but the job logs reveal a logical error rather than a network exception.
Log Error:
Failure { ... httpResponseMessageContent="TenantNotExist" ... }
Cause: The accountId provided in the Helm command is incorrect, or the target cloud account has not been onboarded (connected) to Tenable One Cloud Exposure before running the installation.
Solution:
- Onboard First — Ensure the cloud account (AWS/Azure/GCP) is fully connected in the Tenable Console.
- Verify ID — If installing on an on-premises cluster, verify the Account ID in the Kubernetes Clusters (Agent) wizard and pass it explicitly: --set accountId=<ID>.
Helm Install Succeeds, but Something Is Wrong
These errors appear after helm install completes successfully. The cluster is either associated with the wrong account scope, or resources fail to populate in the dashboard.
Cluster Associated with Wrong Account
Symptom: The Helm chart installs successfully, but the cluster appears under the On-Premises Default Account instead of the specific cloud account scope (for example, AWS/Azure).
Cause: Tenable automatically detects the cloud provider. If the cloud account was not integrated with Tenable before the Helm installation, the system defaults to the on-premises scope. See Cluster Account Location.
Solution: You cannot move a live cluster between accounts. Reinstall is required.
- Run helm uninstall tenable-cloud-security-kubernetes-cluster -n <namespace>.
- Ensure the cloud account is connected in the Tenable user interface.
- Re-run helm install.
Resource Sync Hanging
Symptom: Installation succeeds, but resources do not appear in the dashboard. Logs may show "failed to query regions".
Cause: The target tenant or account is disabled in the Tenable backend, preventing region queries.
Solution: Verify the account status in the Tenable platform settings to ensure the tenant is enabled.
Pods Fail or Connection Drops after Deployment
These issues occur after the installation command succeeds. Even if Helm reports "Deployed," components may fail to connect or crash.
Connector Pod Errors and Reverse Tunnel Failure
Symptom: The Tenable Console status is Connection Failed.
Diagnosis: Even if Helm succeeded, verify the connector pod is running and check its logs.
-
Check status:
Copykubectl get pods -l app.kubernetes.io/name=kubernetes-cluster-connector -n <namespace> - Check logs:
kubectl logs -l app.kubernetes.io/name=kubernetes-cluster-connector -n <namespace>
Specific Check (Tunnel): Look for errors indicating the pod cannot reach the tunnel endpoint (for example, us1-tunnel.internal.app.tenable.com or connect to server error). The connector requires access to both the API (app.tenable.com) and the dedicated tunnel endpoint.
Cause:
- Zombie Tunnel — The backend failed to establish the reverse tunnel to the Kubernetes API.
- Duplicate Install — Two concurrent installations of the connector (for example, in different namespaces) are causing conflicts.
Solution:
- Restart Pod — Delete the connector pod to force a restart and re-initiate the tunnel handshake.
kubectl delete pod -l app.kubernetes.io/name=kubernetes-cluster-connector -n <namespace>
- Check for Multiple Installations — Use the following command to check for identical deployments in different namespaces.
kubectl get pod -l app.kubernetes.io/name=kubernetes-cluster-connector -A
Sensor Permission Denied (PSS)
Symptom: The Sensor pods (DaemonSet) fail to start, crash, or logs show permission errors.
Cause: The Sensor requires privileged access (hostPID: true, privileged: true, hostPath mounts) to scan the node. The cluster's Pod Security Standards (PSS) are blocking these permissions.
Solution: Exempt the Tenable namespace from restrictive policies.
kubectl label namespace <namespace> pod-security.kubernetes.io/enforce=privileged
Cyclical Reboot (On-Premises)
Symptom: Nodes in an on-premises cluster enter a reboot loop after the sensor is installed.
Cause: Incompatibility between the Tenable Sensor (eBPF probes) and the specific OS/kernel version.
Solution: Disable the Sensor immediately and contact Tenable Support with kernel logs.
helm upgrade tenable-cloud-security-kubernetes-cluster tenable/tenable-cloud-security-kubernetes-cluster --set sensor.enabled=false