Deploying Sensor Collector in Kubernetes

This article explains how to deploy Sensor Collectors in a Kubernetes environment and assumes you have already configured your Sensor Collector, met the required system requirements, and have a Kubernetes cluster available that can be configured via helm. Note that Sensor Collectors can be deployed in High Availability mode in Kubernetes; set up instructions are provided in line below.

Step 1: Download Sensor Collector Helm Charts

Download the Sensor Collector helm chart to a local file and transfer to the working directory on the machine where you configure your Kubernetes cluster via helm.

sensor-collector-0.700.0-fips.tgz

PCA version 25.7.510 or greater
sensor-collector-0.715.0.tgz

Step 2: Download Helm Helper Artifacts

Cisco Provider Connectivity Assurance provides an endpoint for downloading the Helm helper bundle with some pre-populated artifacts which can be used during the Sensor Collector Helm install. These artifacts can be accessed either via the UI or API.

Helm Helper Artifacts (Download via UI)

To download the Helm helper bundle via the UI:

1. In the UI, navigate to Sensors > Collectors > Sensor Collectors.
2. Select your Sensor Collector from the list.
3. Click the ellipsis (three dots) on the right.
4. Select Download (Kubernetes) from the menu, as shown below.

Helm Helper Artifacts (Download via API)

After authenticating, you can download the artifacts by submitting a GET REST API request to Cisco Provider Connectivity Assurance as follows:

GET https://{{tenant url}}/api/v2/distribution/download-roadrunner-helm?zone={{your zone}}

Where:

• tenant url = The tenant URL for your Provider Connectivity Assurance deployment
• zone = The zone for the Sensor Collector instance you wish to deploy

A .tar file following the naming convention {connector name}-{date}-helm.tar.gz will be downloaded to your machine.

Copy the file to the working directory on the machine where you configure your Kubernetes cluster via helm.

Example:

> cd /opt/data-collector
> cp ~/Downloads/DataGateway-2025008-27-helm.tar.gz .
> tar -xzvf DataGateway-2025008-27-helm.tar.gz

You should now have the following files in your working directory:

 ├── .env
 ├── sensor-collector-install.sh
 └── values.yaml

Step 3: Installation Prerequisites

Selecting a Namespace and Instance Name

The .env file extracted from your .tar file includes (among others) the following environment variables:

KUBERNETES_INSTANCE_NAME="sensor-collector"
KUBERNETES_NAMESPACE="cisco-sensor-collectors"

These dictate the Kubernetes namespace into which you will deploy your Sensor Collector, as well as the instance name for your Helm deployment. You may override either of these defaults by modifying the associated value in the .env file.

Step 4: Customize Values

The values.yaml extracted in step 3 can be customized to meet the needs of your installation. To learn more about how to setup your Kubernetes cluster, see the Sensor Collector System Requirements for Kubernetes

For multiple node clusters

Storage Class

Select the storage class name based on the network-attached StorageClass configured for your cluster. This parameter is optional and doesn't need to be set if your cluster's default storage class is appropriate. For example:

  ha:
    storageClassName: nfs

Load Balancer

By default, the service that hosts the sensor collector is set to NodePort which is not sufficient for allowing Sensor Agents to maintain connections in a node failure scenario. In a multi-node cluster, the service must be se to LoadBalancer to achieve high availability.

  service:
    type: LoadBalancer

Eviction delay for moving pods to a healthy node

When a node fails, Kubernetes will re-create your sensor collector pod on a healthy node. It is configured to wait 30 seconds by default before the pod is moved to the healthy node. Optionally configure the wait time using the HA toleration configuration. For example:

  ha:
     tolerationSeconds: 60

For single node clusters

There are no further customizations required beyond what's specified by default in the included values.yaml file.

Step 5: Install Sensor Collector

The .tar file you downloaded from Provider Connectivity Assurance contains a script named sensor-collector-install.sh. This script runs several pre-flight checks to verify that all prerequisites for the install are met and then performs a Helm installation of the Sensor Collector.

Run the script passing the helm chart downloaded in step 1.

./sensor-collector-install.sh --local-chart ./sensor-collector-0.700.0-fips.tgz

Expected Output

    Performing preflight checks...
        helm installed ------------------------------ PASS

        confirm required environment variables set in local .env file:
            KUBERNETES_INSTANCE_NAME set ------------ PASS
            KUBERNETES_NAMESPACE set ---------------- PASS
            SENSOR_COLLECTOR_TYPE set --------------- PASS

        Verify required support files present:
                values.yaml - PRESENT

    Preflight checks passed

Installing data-collector instance of type dataGateway with name sensor-collector to namespace cisco-sensor-collectors

Results of helm install:

NAME: sensor-collector
LAST DEPLOYED: Wed Aug 27 14:44:40 2025
NAMESPACE: cisco-sensor-collectors
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
Roadrunner application version gfraboni-dev installed for zone DataGateway.

General Notes:
--------------
Analytics Endpoints:
   - Deployment: pca.cisco.npav.accedian.net:443
   - Tenant    : pca.cisco.npav.accedian.net:443

Agent Proxy Node Port: 30001
Metrics Gateway Port : 30000

To get the node IP address(es) for your Kubernetes cluster, run the following command at the command line:
    kubectl get nodes -o jsonpath='{.items[*].status.addresses[?(@.type=="InternalIP")].address}{"\n"}'

If your output resembles the example above, then you have completed your install of the Sensor Collector.

If any of the tested prerequisites were not met, the install will abort, and the user is expected to correct the deficiency before trying again.

Additional Notes

Node Ports

Both the Filewatcher and Gateway Sensor Collector variants must expose ports to allow external access to the Sensor Collector. For the Filewatcher variant, this is the port where the SFTP server (used for ingesting .csv files into the system) is exposed. For the Gateway variant, these are the ports for the Agent Proxy and the Metrics Gateway.

In both cases, static node port assignments are determined by the values in the values.yaml file used during the Helm installation.

For the Filewatcher Sensor Collector, the SFTP server port is assigned with the filewatcher.nodePort parameter.

For the Gateway variant, the ports for the Agent Proxy and the Metrics Gateway are determined by the openMetricsGateway.agentProxyPort and openMetricsGateway.metricsGatewayPort parameters, respectively.

These values are automatically populated when you download the values.yaml file from Provider Connectivity Assurance. For a Filewatcher Sensor Collector, the filewatcher.nodePort defaults to 3000. For a Gateway Sensor Collector, the port assignments are based on the connector configuration you created in the Provider Connectivity Assurance user interface when you created the Sensor Collector.

Important: As mentioned in the Configuration article, the default Gateway ports (55777 and 55888) are outside of the valid port range for most Kubernetes clusters (node port range is typically 30000-32767), so if you are deploying a Gateway to a Kubernetes cluster, you will most likely need to select different values for these ports. The port assignments for any of these ports must respect the valid node port range for your Kubernetes cluster.