Deploy Sensor Collector in Kubernetes

Deploy in Cloud

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.

Step 1: Download Sensor Collector Helm Charts

Cisco Crosswork 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 Crosswork Assurance as follows:

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

Where:
- tenant url = The tenant URL for your {{variable.CPCA-short}} deployment
- zone = The zone for the {{variable.RR}} 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 where you will initiate your Sensor Collector installation, then extract its contents.

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
├── pcaAuthArtifact
├── sensor-collector-install.sh
└── values.yaml

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 - TLS Setup (Gateway Sensor Collectors only)

Note: Not required for CSV.
A server certificate is essential for the Gateway Sensor Collector to securely communicate with a Telemetry Collector or Assurance Sensor.

You have the following two options:

• Generate a self-signed certificate (instructions in this article)
• Utilize a certificate issued by a trusted Certificate Authority (CA)

It is the customer's choice if they wish to use self-signed certificates, or certificates signed by a trusted Certificate Authority. In either case, they must make the appropriate files available at the time of the Sensor Collector installation.

Within the .env file extracted from your .tar file, you will find the following environment variables:

AGENT_SERVER_CERTIFICATE_FILE="./tls.crt"
AGENT_SERVER_KEY_FILE="./tls.key"

These inform the install process where to find the certificate and associated public key file for use in establishing the WebSocket server for the sensor agents and collectors.

You must either provide these files using the default naming (i.e., copy a tls.crt and tls.key file into your working directory) or modify the values for the above environment variables to point to your files.

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

╰─ ./sensor-collector-install.sh
Perform 'helm install' of Sensor Collector instance to Kubernetes cluster

    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
            AGENT_SERVER_CERTIFICATE_FILE set ------- PASS
            AGENT_SERVER_KEY_FILE set --------------- PASS

        Verify required support files present:
                values.yaml - PRESENT
                ./tls.crt - PRESENT
                ./tls.key - PRESENT

    Preflight checks passed

Installing data-collector instance of type dataGateway with name sensor-collector to namespace cisco-sensor-collectors
- Server certificate for sensor agent authentication will be imported from ./tls.crt
- Server certificate key for sensor agent authentication will be imported from ./tls.key

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 0.700.0-fips installed for zone DataGateway.

General Notes:
--------------
Analytics Endpoints:
   - Deployment: deployment.mypca.net:443
   - Tenant    : tenant.mypca.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"}'

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: gdf-rep.gdf-rep.npav.accedian.net:443
   - Tenant    : gino.gdf-rep.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 csv and Gateway Sensor Collector variants must expose ports to allow external access to the Sensor Collector. For the csv variant, this is the port where the SFTP server (used for ingesting .csv files into the system) is exposed. For the Data 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 csv Sensor Collector, the SFTP server port is assigned with the filewatcher.nodePort parameter.

For the Data 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 csv Sensor Collector, the filewatcher.nodePort defaults to 3000. For a Data 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.

Deploy On-Prem

This guide covers Kubernetes deployments that pull the Sensor Collector Helm chart and container images through the built-in registry included in your Crosswork Assurance deployment. The built-in registry eliminates the need for direct access to external container registries -- air-gapped and connected deployments follow the same procedure.

Prerequisites

• A Kubernetes cluster with helm (v3.8+) and kubectl configured.
• Network connectivity from the cluster nodes to the Crosswork Assurance deployment.
• A configured Sensor Collector zone in Crosswork Assurance.
• The cluster's container runtime must trust the Crosswork Assurance CA certificate (if self-signed). See Step 4.

Step 1: Download Helm Package

The Helm package is generated dynamically and includes pre-authenticated credentials, a pre-populated values.yaml, and an automated install script.

Via UI

1. Navigate to Sensors > Collectors > Sensor Collectors.
2. Select your configured Sensor Collector from the list.
3. Click the ellipsis (three dots) on the right.
4. Choose Download (Kubernetes).

Via API

GET https://{{tenant-url}}/api/v4/ingestion/sensor-collector/{{zone}}/helm-package

Where:

• tenant-url -- The tenant URL for your Crosswork Assurance deployment.
• zone -- The zone name of the Sensor Collector instance you wish to deploy.

Authentication: Include a valid Bearer token in the Authorization header.

Step 2: Transfer and Extract the Package

Transfer the .tar.gz file to the machine where you run helm commands against your cluster.

tar -xzf sensor-collector-<zone>-helm.tar.gz

After extraction, you should have the following structure:

.env                          # Deployment variables (namespace, zone, registry)
.oci_token                    # Pre-authenticated download token
values.yaml                   # Pre-populated Helm values
sensor-collector-install.sh   # Automated install script

Step 3: Review Installation Prerequisites

Namespace and Instance Name

The .env file includes:

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

You can override either value to customize your deployment.

Helm Chart Source

The install script pulls the Helm chart directly from the Crosswork Assurance built-in registry -- no manual chart download is required. The chart reference is configured automatically in the .env file.

Step 4: Configure Container Runtime CA Trust (If Required)

If your Crosswork Assurance deployment uses a self-signed TLS certificate, the container runtime on every cluster node must trust the Crosswork Assurance CA before it can pull images.

The sensor-collector-install.sh script includes an automated preflight check that verifies CA trust. If the check fails, it provides node-specific remediation instructions.

Manual Configuration

For k0s (Embedded Cluster)

Important: Do NOT use config_path in containerd configuration -- it conflicts with the k0s embedded registry mirrors.

# On EACH node:
sudo mkdir -p /etc/crosswork-assurance-ca
sudo cp pca_ca.crt /etc/crosswork-assurance-ca/ca.crt

sudo mkdir -p /etc/k0s/containerd.d
cat <<TOML | sudo tee /etc/k0s/containerd.d/ca-trust.toml
[plugins."io.containerd.grpc.v1.cri".registry.configs."<registry-host>".tls]
  ca_file = "/etc/crosswork-assurance-ca/ca.crt"
TOML
# k0s auto-restarts containerd when files change in /etc/k0s/containerd.d/

For Standard containerd (non-k0s)

# On EACH node:
sudo mkdir -p /etc/crosswork-assurance-ca
sudo cp pca_ca.crt /etc/crosswork-assurance-ca/ca.crt

sudo mkdir -p /etc/containerd/certs.d/<registry-host>
cat <<TOML | sudo tee /etc/containerd/certs.d/<registry-host>/hosts.toml
server = "https://<registry-host>"
[host."https://<registry-host>"]
  ca = "/etc/crosswork-assurance-ca/ca.crt"
TOML
sudo systemctl restart containerd

Replace <registry-host> with the registry hostname from the HELM_CHART_REGISTRY variable in your .env file.

Step 5: Customize Values

The values.yaml file is pre-populated with your zone-specific configuration. Review and customize as needed:

For Multi-Node Clusters

Storage Class

ha:
  storageClassName: nfs

Load Balancer

For high availability, set the service type to LoadBalancer:

service:
  type: LoadBalancer

Eviction Delay

ha:
  tolerationSeconds: 60

For Single-Node Clusters

No additional customization is required beyond the defaults.

Node Ports

For Gateway Sensor Collectors, the openMetricsGateway.agentProxyPort and openMetricsGateway.metricsGatewayPort values are pre-populated from your connector configuration.

For Filewatcher Sensor Collectors, the filewatcher.nodePort defaults to 30000.

Important: The default Gateway ports (55777 and 55888) are outside the valid Kubernetes node port range (typically 30000-32767). Verify that your port assignments are within your cluster's valid range.

Step 6: Install Sensor Collector

Run the install script:

chmod +x sensor-collector-install.sh
./sensor-collector-install.sh

The script performs the following:

1. Registry login -- Authenticates to the Crosswork Assurance built-in registry using the pre-authenticated download token.
2. CA trust preflight -- Verifies that the container runtime trusts the Crosswork Assurance CA certificate.
3. Zone formatting -- Converts the zone name to a Kubernetes-compatible label.
4. Prerequisites check -- Verifies helm, kubectl, and required files are present.
5. Helm install -- Runs helm upgrade --install with --atomic --wait to deploy the Sensor Collector.

Expected Output

  Sensor Collector Helm Installer
  ================================
  Release:    sensor-collector-<zone>
  Namespace:  cisco-sensor-collectors
  Version:    <version>

    Performing preflight checks...
        helm installed ------------------------------ PASS
        kubectl installed --------------------------- PASS
        KUBERNETES_INSTANCE_NAME set ------------ PASS
        KUBERNETES_NAMESPACE set ---------------- PASS
        values.yaml - PRESENT

    Preflight checks passed

Installing sensor-collector with helm release name sensor-collector-<zone> to namespace cisco-sensor-collectors

  Installation complete.

How It Works

The Crosswork Assurance built-in registry handles image and chart distribution:

• Connected deployments: Images and charts are fetched from the upstream Cisco registry on demand.
• Air-gapped deployments: Images and charts are served from the Replicated embedded registry -- no external network access required.
• Authentication: The download token is validated by the registry's auth subrequest, scoped to read-only (pull-only).
• Image pull secrets: The values.yaml includes a pre-configured pullSecrets entry so that kubelet can authenticate to the built-in registry when pulling the container image.

Troubleshooting

Related Documentation

• Integrated Registry for Sensor Collector
• Sensor Collector System Requirements for Kubernetes
• Configure Sensor Collector