Connect a Cluster via Helm Chart
This is a how-to guide for connecting clusters to Tenable via Helm chart.
- For a conceptual overview of Kubernetes capabilities, see Kubernetes.
- For a how-to guide about viewing and managing Kubernetes clusters, see Kubernetes Clusters.
- For frequently asked questions, see FAQ: Kubernetes.
Tenable allows you to connect Kubernetes clusters using a Helm chart as an alternative to cloud-native API methods. This method is required for private clusters, on-premises environments, or managed clusters where identity-based or network-based access is restricted. Additionally, Helm is required for Kubernetes features such as sensor-based vulnerability management and admission controller.
Use the following sections to determine whether to use the Helm chart (sensor-based) or cloud-native (agentless) methods for resource synchronization, runtime detection, workload protection, and additional security features.
When to Use the Helm Chart Method?
A Helm chart integration moves your security posture beyond basic metadata discovery to a comprehensive, deep-scan analysis. You should choose this integration method in the following scenarios:
- Establish connectivity — Use this method if your cluster is:
- Managed (Private) — You use a managed (private) cluster where the API server is not accessible from the internet.
- On-premises — You host your infrastructure on customer-managed resources, such as private data centers.
- Enable Kubernetes-specific features — Activate features such as Runtime Detection, Admission Controller, and Vulnerability Management.
-
Meet advanced security or compliance requirements, such as:
- Real-time policy enforcement — Required for the Kubernetes Admission Controller.
- Deep configuration visibility — Provides granular insights into Role-Based Access Control (RBAC) and cluster configurations.
For more details, see Connect Kubernetes Clusters.
Connect Kubernetes Clusters
Before you connect your cluster, determine if your deployment model requires the Helm chart method. Use the Kubernetes cluster Helm chart for private clusters, on-premises environments, and specific security features where cloud-native API methods are not supported.
Kubernetes Resource Sync and Vulnerability Management
| Cloud Provider | Managed (Public) | Managed (Private) | Unmanaged |
|---|---|---|---|
| AWS 1 | Grant relevant permissions (agentless) | Install via Helm chart (sensor) | Install via Helm chart (sensor) |
| Azure 2 | Grant relevant permissions (agentless) | Install via Helm chart (sensor) | Install via Helm chart (sensor) |
| GCP 3 | Grant relevant permissions (agentless) | Install via Helm chart (sensor) | Install via Helm chart (sensor) |
| OCI | Grant relevant permissions (agentless) | Install via Helm chart (sensor) | Install via Helm chart (sensor) |
| On-Premises and any unsupported cloud platform | N/A | N/A | Install via Helm chart (sensor) |
The following features are currently not supported for vulnerability management scanning:
AWS 1 - Fargate is not supported for vulnerability management.
Azure 2 - Virtual nodes are not supported for vulnerability management.
GCP 3 - Autopilot is not supported for vulnerability management.
Runtime Detection
To use Runtime Detection, you must install the sensor by using Helm. This requirement applies to all supported cloud providers across public, private, or unmanaged Kubernetes and OpenShift clusters.
If you are already using the Helm-based sensor for connectivity, you do not need to perform a separate installation. Instead, update your existing deployment with the runtime flag. When you perform the installation or update, include the --set sensor.runtimeDetection=true flag to enable runtime security.
For more details, see Install the Runtime Detection Sensor for Kubernetes.
Admission Controller
To use the Admission Controller you must install the sensor by using Helm. This requirement applies to all supported cloud providers across public, private, or unmanaged Kubernetes and OpenShift clusters.
For more details, see Install Admission Controller.
Add a Kubernetes Cluster Connector (API Token)
Before connecting a cluster via Helm, you must create a cluster connector. This serves as an API token to authenticate secure communication between the cluster and Tenable.
To add a connector:
- In the Tenable One Cloud Exposure Console, navigate to Settings > Integrations > Add Integration > Kubernetes Cluster.
-
Select an account scope in the Organization dropdown. By default, the entire Organization (all accounts) is selected.
Note: When you Add Your Cluster, you must select a connector. The scope you select determines where the connector is available. For example, if you add the connector in the AWS folder, it is only available for selection within that scope. The Resource Sync column on the Kubernetes Clusters page indicates all clusters that use the connector via Kubernetes connector icon. - Enter a meaningful Name for the connector.
- Click Add.
Synchronize Resources for Cloud-Managed Clusters
Tenable recommends that you connect your cloud-managed clusters by using the cloud-based methods described in the documentation for EKS, AKS, GKE, and OKE.
However, if those methods are not possible, you can synchronize cluster resources by using the Kubernetes Cluster Helm chart. This method ensures that Tenable receives an updated inventory of container resources even when a direct cloud-to-cloud connection is unavailable.
You might choose to synchronize via the Helm chart for the following reasons:
- Missing identity-based permissions — This occurs if the Tenable role does not have permissions to access the cluster. While GCP and OCI do not require these permissions, other providers do, and some configurations (such as local authentication in Azure) are not supported by traditional integration.
- Missing network-based access — This occurs if the cluster control plane is not publicly accessible, such as in a private cluster.
You can connect these clusters to Tenable by establishing secure communication using Helm as a package manager.
To synchronize resources for cloud-managed clusters using a Helm chart:
Synchronize Resources for On-Premises or Managed (Private) Clusters
Connect on-premises or private-managed clusters to Tenable to gain full visibility into all identities and resources associated with the cluster. This connection provides data regarding permissions, subscription usage, and security configurations.
To synchronize these clusters, you install a workload (Deployment) by using a Helm chart. This Helm chart includes the Kubernetes resources required to synchronize data and apply security configurations to your cluster. For more details, see How Tenable Connects to Your Cluster via Helm Chart.
To synchronize your on-premises clusters via Helm chart:
Install the Runtime Detection Sensor for Kubernetes
The runtime detection sensor uses eBPF technology to monitor system-level activity and identify suspicious activity within your clusters. The sensor then sends these events to Tenable for near real-time analysis. For more details, see Threat Detection.
To monitor Kubernetes workloads for suspicious activity:
- Ensure you meet all requirements, including network connectivity for runtime detection.
-
Perform one of the following:
- If the cluster is not connected via Helm: Add Your Cluster, and include the --set sensor.runtimeDetection=true parameter in the Helm command.
- If the cluster is already connected via Helm: Upgrade the cluster and include the --set sensor.runtimeDetection=true parameter in the Helm command.
Install Admission Controller
Install the admission controller by using the Helm chart command to connect relevant Kubernetes clusters in your environment. This setup ensures secure connectivity and enables the admission controller to manage policies.
You can install the admission controller during the initial cluster connection or later by upgrading the cluster with this feature.
When you install a Helm chart with the admission controller enabled, the system generates a CA certificate, a server key, and a server certificate. These certificates establish secure communication and trust between the kube-apiserver and the Tenable admission controller webhook server. The certificates remain valid for three years from their generation date.
For detailed instructions, see Add Your Cluster.
Install the Vulnerability Management Sensor for Kubernetes
Scan on-premises and cloud-managed Kubernetes clusters for vulnerabilities by installing the Workload Protection sensor with a Helm chart. The sensor identifies vulnerabilities on the virtual machines (nodes) and the container images running in your cluster.
The sensor queries your package manager and installed libraries to determine what software is installed on the host and the container images running on the node. The sensor then sends this software inventory to Tenable for analysis.
For more details, see Agent-Based Kubernetes Workload Scanning.
To scan Kubernetes workloads for vulnerabilities:
- Ensure you meet all Requirements, including additional requirements for workload scanning.
-
Perform one of the following:
- If the cluster is not connected via Helm: Add Your Cluster, and include the --set sensor.vulnerabilityManagement=true parameter in the Helm command.
- If the cluster is already connected via Helm: Upgrade the cluster and include the --set sensor.vulnerabilityManagement=true parameter in the Helm command.
Add Your Cluster
To add a cluster, you install a Tenable-provided Helm chart using a dynamically generated command.
Requirements
Before you install, verify that your cluster meets the following requirements.
| Cluster Criteria | Requirements |
|---|---|
| Helm Version |
|
| General Resources |
|
| Workload Scanning |
|
| Runtime Detection |
|
| Connectivity |
|
Allowed Destinations
If you restrict outbound traffic from your cluster, allow the following destinations. Wildcard entries apply only to Tenable domains.
| Destination | Purpose |
|---|---|
| containers.tenable.com | Pulls the container images that the Helm chart deploys. |
| charts.tenable.com | Hosts the Tenable Helm repository. Required to run helm repo add. Not required if you use a private registry. |
| app.tenable.com | Communication between your cluster and Cloud Exposure. |
| *.app.tenable.com | Communication between your cluster and Cloud Exposure endpoints for your site, for example <site-code>.app.tenable.com. |
| <site-code>-tunnel.internal.app.tenable.com | Dedicated tunnel endpoint for the connection between your cluster and Cloud Exposure. |
| app.tenable.us and *.app.tenable.us | Required only for United States Gov Cloud environments. |
- The wildcard *.app.tenable.com matches subdomains only. It does not match app.tenable.com, so allow both.
-
Some tools, such as Kubernetes network policies, do not support wildcard FQDNs. In that case, allow explicit hostnames instead of the wildcard entries. For example, for the Singapore site (1sg), allow:
- containers.tenable.com
- charts.tenable.com
- app.tenable.com
- sg1.app.tenable.com
- sg1-tunnel.internal.app.tenable.com Replace sg1 with your site code.
| Region | Site Code |
|---|---|
| United States | us1 |
| Australia | au1 |
| Brazil | br1 |
| Canada | ca1 |
| Europe | eu1 |
| India | in1 |
| Japan | jp1 |
| Singapore | sg1 |
| South Korea | kr1 |
| United Arab Emirates | ae1 |
| United Kingdom | uk1 |
| United States Gov Cloud | usgov1 |
Set Up and Run Helm Command
You add your cluster by configuring and running the helm install command on your cluster.
To add your clusters:
- In the Cloud Exposure Console, navigate to Explore > Kubernetes Clusters.
-
(Optional) In the Organization tree, select an account scope. By default, the console selects the entire organization (all accounts).
Note: The scope you select must match the scope of the Tenable Kubernetes Cluster Connector. For example, if you added the connector in the AWS folder, that connector will only be available for selection within that scope. -
Perform one of the following actions:
- To connect multiple clusters at once (including unmanaged clusters not yet discovered by Tenable), click Add Clusters via Helm.
- (Administrator only) To connect an individual cluster already discovered by Tenable, search for the cluster in the Kubernetes Clusters table, click the three dots menu, and select Install Helm.
- (Administrator only) If your cluster is already connected but you want to install new features, search for the cluster in the Kubernetes Clusters table, click the three dots icon, and click Upgrade Helm.
- Install Helm as a package manager for Kubernetes. Refer to Helm’s documentation to get started.
- Configure kubectl to connect to your cluster.
-
Run the following command to add the Tenable repository:
helm repo add tenable https://charts.tenable.com
(If you use a private registry, skip this step and ensure the chart is available in your internal repository).Note: If you already added the repository, update it to the latest chart by running helm repo update tenable. You must use https://charts.tenable.com, as the previous URL (https://charts.ermetic.com) is deprecated. - Select the relevant connector. If you do not have a connector, add one before you continue. You can use a single connector for all clusters.
- Select the account to associate with the cluster. You can select an account manually or use the automatically detected account.
-
Choose the features you want to use. Your selection impacts the command generated in the next step:
- Resource Sync — Provides visibility for cluster resources and triggers findings on detected misconfigurations.
- (Enterprise license only) Runtime Detection. Monitor events in cluster workloads using an eBPF sensor to detect suspicious activity. For more details, see Threat Detection.
- (Enterprise license only) Admission Controller. Intercepts API requests to enforce policies and validate configurations. For more details, see Admission Controller.
- (Enterprise license only) Vulnerability Management. Scans cluster nodes and container images for vulnerabilities. For more details, including additional requirements, see install the workload protection sensor for Kubernetes.
- To connect and send data to Tenable, run the command that is displayed in the Add Clusters via Helm dialog. This command installs the Kubernetes connector chart on the cluster. The command is dynamically generated based on the selected connector, account scope, and enabled features.
-
(optional) Add any optional parameters to the command.
The following image shows a sample output for the command, when on-premises workload scanning is enabled.
Validate the Deployment
To validate that the sensor is deployed and running, run the following command:
-
kubectl get pods -n tenable-cloud-security-kubernetes-cluster
Note: It typically takes 1–2 minutes for the pods to reach a Running state. The sensor runs per Kubernetes cluster node.
In the example below, there are two nodes.
For troubleshooting issues, see Helm Chart Troubleshooting.
Connect Cloud-Managed Clusters via API
You add your cluster by granting Cloud Exposure the necessary cloud permissions to automatically discover and sync your managed clusters.
To add your clusters:
- In the Cloud Exposure Console, navigate to Explore > Kubernetes Clusters.
-
(Optional) In the Organization tree, select an account scope. By default, the console selects the entire organization (all accounts).
Note: The scope you select must match the scope of the Tenable Kubernetes Cluster Connector. For example, if you added the connector in the AWS folder, that connector will only be available for selection within that scope. - Click Cloud Managed from the connection method options.
- On the Select Clusters step, locate your target clusters in the table. You can use the Name or Account filters to narrow down the list.
-
Select the checkbox next to each cluster you want to connect.
Note: This method is typically used for discovered clusters displaying a Resource Sync status of Missing permissions or Connection failed. - Click Next to proceed to the Scripts step.
- If you selected clusters across different cloud accounts, select the relevant account tab at the top of the script window. You must run the script separately for each account.
-
Verify that your local terminal or cloud shell environment meets the following requirements:
- The cloud provider CLI is installed and authenticated with an active profile or via CloudShell.
- kubectl is installed.
- The authenticated account/profile has explicit write permissions to the target Kubernetes clusters you are connecting.
- Copy the dynamically generated bash script displayed in the console box.
- Run the script either locally in your terminal or directly from your provider's cloud shell to establish secure connection access entries between Tenable and your clusters.
Advanced Cluster Configuration
You can customize your Helm chart installation to suit your specific environment. Choose the method that best fits your workflow:
- Helm Optional Command Parameters (CLI) — Best for quick, one-time changes or simple overrides (such as setting a cluster name or proxy) during the initial installation.
- Values.Yaml File — Best for complex configurations, version-controlled deployments, or when you need to define granular resource limits, affinity rules, and security contexts.
- Private Registry — If you use a custom container registry, see Clusters with a Private Registry.
- Custom CA Certificate — Provide a CA certificate so Tenable components trust an inspection proxy or an internal certificate authority.
Helm Optional Command Parameters (CLI)
Add these parameters to the helm install command to customize your configuration.
| Parameter | Description | Example |
|---|---|---|
| --set name | Override the default cluster name (DNS name). | --set name="cluster1.mycompany.internal" |
| --set accountId | Override the detected account location by selecting a different account ID, or the on-premises default account (opDefault). For more details, see Cluster Account Location. | --set accountId="123456789012", --set accountId=opDefault |
| --set configureIdentity, --set configureNetwork | By default, Tenable connects to your cluster to configure both identity- and network-based access. To override this default and disable one of these forms of access, add one of the following to the command with a value of false, as relevant. For more details, see Kubernetes. | --set configureIdentity="false" |
| --set proxyUrl | Use a proxy server to connect. |
|
Values.Yaml File
For advanced use cases, you can use a values.yaml file to customize the configuration.
To configure your cluster via the values.yaml file:
- Retrieve the file:
helm show values tenable/cloud-security-kubernetes-cluster - Configure the values.yaml file as needed and save it.
-
Append the file to your helm install command:
helm install {...} -f custom-values.yamlNote: The {...} represents the dynamically generated command from the Add Clusters dialog.
Common Values.Yaml Parameters
The values.yaml file contains the following common parameters:
| Parameter | Description | Default |
|---|---|---|
| identity | By default, Tenable connects to your cluster to configure identity-based access. To override this default and disable this access, change to false. | true |
| network | By default, Tenable connects to your cluster to configure network-based access. To override this default and disable this access, change to false. | true |
| registry | If you want to use your own container image registry for the deployment, you can use this parameter to configure it. This parameter is common for all the components. | containers.tenable.com |
| repository | If you want to use your own container image repository for the deployment, you can use this parameter to configure the path. You can edit this parameter for every component independently. | cloud-security/kubernetes-cluster-manager |
| affinity | Defines rules for assigning pods to nodes based on labels and conditions. | |
| annotations | Key-value pairs that are used to attach arbitrary non-identifying metadata to the pod. | |
| labels | Key-value pairs used to identify and select pods and to specify relationships between them. | |
| resources | Specifies the compute resource requirements and limits for the pod, including CPU and memory. | |
| tolerations | Specifies under what conditions a pod can be scheduled onto a node with taints. | |
| resourceNamePrefix | Adds a custom prefix to each resource created in the cluster by Tenable. | kubernetes-cluster |
| proxyUrl | Use a proxy server to connect. |
|
| containerCaCertificate | Provides a custom CA certificate to all Tenable components, for environments behind an inspection proxy or an internal certificate authority. Set the certificate inline with pem, or reference an existing cluster secret with secretName. See Custom CA Certificate. |
Admission Controller Optional Parameters:
| Parameter | Description | Default |
|---|---|---|
| webhook.port | The port number that the webhook is listening on. Make sure that the port is accessible inside the cluster. | 8443 |
| webhook.replicas | The number of the pod instances for the admission controller. | 3 |
| readSecrets | Grants the admission controller permission to list secrets so it can identify the container images being deployed for the Vulnerable Container Images policy. The admission controller inspects only image pull secrets. Set with --set admissionController.readSecrets=true. Requires chart version 1.1.6 or later. | false |
Values.YAML Default Values
YAML
accountId: null
admissionController:
containerImage:
repository: cloud-security/kubernetes-cluster-admission-controller
tag: null
enabled: false
healthPort: 9090
logLevel: "information"
readSecrets: false
networkPolicy:
enabled: false
ingress: {}
pod:
affinity: {}
annotations: {}
containers:
securityContext: {}
labels: {}
resources:
limits:
cpu: "100m"
memory: "256Mi"
requests:
cpu: "100m"
memory: "256Mi"
tolerations: []
replicas: 3
strategy:
rollingUpdate:
maxSurge: 1
maxUnavailable: 0
webhook:
failurePolicy: Ignore
port: 8443
timeoutSeconds: 3
apiKeyToken: ""
apiUrl: ""
clusterId: null
connector:
enabled: true
identity: true
network: true
pod:
affinity: {}
annotations: {}
containers:
securityContext: {}
labels: {}
resources: {}
tolerations: []
containerCaCertificate:
pem: null
secretName: null
containerEnvironmentVariables: []
containerImage:
pullSecrets: []
registry: containers.tenable.com
registryPassword: null
registryUsername: null
repository: cloud-security/kubernetes-cluster-manager
tag: null
containerSecrets:
apiKeyTokenName: null
injectExternally: false
volumeMountPath: "/var/run/secrets/application"
hooks:
pod:
affinity: {}
annotations: {}
containers:
securityContext: {}
labels: {}
resources: {}
tolerations: []
name: null
pod:
affinity: {}
annotations: {}
containers:
securityContext:
runAsUser: 1000
labels: {}
resources:
limits:
cpu: "100m"
memory: "512Mi"
requests:
cpu: "100m"
memory: "512Mi"
tolerations: []
proxyUrl: null
resourceNamePrefix: kubernetes-cluster
sensor:
containerImage:
repository: cloud-security/kubernetes-cluster-sensor
tag: null
dataPath: "/var/lib/tenable"
enabled: false
pod:
affinity: {}
annotations: {}
labels: {}
resources:
limits:
cpu: "1"
memory: "1Gi"
requests:
cpu: "300m"
memory: "256Mi"
tolerations: []
updater:
pod:
affinity: {}
annotations: {}
containers:
securityContext: {}
labels: {}
resources: {}
tolerations: []
Custom CA Certificate
For environments that route traffic through an inspection proxy or rely on an internal certificate authority, you can provide a custom CA certificate so that Tenable components establish trusted connections. Tenable installs the certificate only on its own deployed components. It does not modify cluster-wide trust.
Set the certificate in the containerCaCertificate section of your values.yaml file:
YAML
containerCaCertificate:
pem: <CA certificate in PEM format>
secretName: <name of an existing cluster secret that holds the certificate>
Provide the certificate inline with pem, or reference an existing cluster secret with secretName.
You can also set the certificate from the command line:
- Use --set-file containerCaCertificate.pem=<path> to provide the certificate file.
- Use --set containerCaCertificate.secretName=<name> to reference an existing cluster secret.
Cluster Account Location
When you add a cluster, Tenable attempts to detect the account where the cluster is located:
- Connected cloud accounts — If the associated cloud account is already connected, the cluster is added to the relevant account scope (folder) for that cloud provider.
- Unconnected cloud accounts — If the associated cloud account is not connected, Tenable attempts to identify the location based on the account of the worker node.
-
Manual association — If Tenable cannot detect an account, you can associate the cluster with a different connected account or the On-Premises default account. You can do this by selecting an account from the dropdown menu during the Helm command setup or by using the --set accountId parameter in the Helm command.
Note: While clusters added to the On-Premises default account are typically on-premises, other cluster types may also be mapped to this folder if no other account is detected.
If you override the detected account location, Tenable adds the cluster to the account scope you defined. For more details on using parameters to override locations, see Helm Optional Command Parameters (CLI).

