--- title: "Deploy Sensor Collector in Kubernetes" slug: "deploy-sensor-collector-in-kubernetes-1" updated: 2026-11-20T21:12:38Z published: 2026-11-20T21:12:38Z canonical: "docs.crossworkassurance.cisco.com/deploy-sensor-collector-in-kubernetes-1" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.crossworkassurance.cisco.com/llms.txt > Use this file to discover all available pages before exploring further. # Deploy Sensor Collector in Kubernetes Which procedure should I follow? - **Cloud deployments:** Follow[[this section]](/latest/docs/deploy-sensor-collector-in-kubernetes-1#deploy-in-cloud) of the article to get instructions on download the docker package. - **On-Prem Controlled Availability deployments:** Follow [this section](/latest/docs/deploy-sensor-collector-in-kubernetes-1#deploy-onprem) of the article. Your deployment includes a built-in registry that simplifies container image downloads. For more information, see [Integrated Registry for Sensor Collector](/latest/docs/oci-registry-for-sensor-collector). **IMPORTANT NOTE:** All upgraded or Controlled Availability release deployments will need to enable this Built-in Registry feature **OCI PROXY** from [Feature Flags](/latest/docs/crosswork-assurance-feature-flags). This is accessible to users with the tenant-admin role or to Deployment Administrators via the Platform Administration UI. **By default, all new installations will turn this feature on.** ## Deploy in Cloud This article explains how to deploy Sensor Collectors in a Kubernetes environment and assumes you have already [configured your Sensor Collector](/latest/docs/configure-sensor-collector), met the required [system requirements](/latest/docs/sensor-collector-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. ![Download Kubernetes](https://cdn.document360.io/01d1de5e-a375-4fbc-aa82-666ac04c2113/Images/Documentation/Screenshot%202025-10-06%20at%203.03.49%E2%80%AFPM.png?sv=2026-02-06&spr=https&st=2026-11-22T22%3A02%3A18Z&se=2026-11-22T23%3A02%3A18Z&sr=b&sp=r&sig=wKAW9pqhuvyc0tpDKVEpRkJo13llV2XO08lqpTNss3g%3D) ### 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. ![Screenshot 2025-10-06 at 3.03.49 PM.png](https://cdn.document360.io/01d1de5e-a375-4fbc-aa82-666ac04c2113/Images/Documentation/Screenshot%202025-10-06%20at%203.03.49%E2%80%AFPM(1).png?sv=2026-02-06&spr=https&st=2026-11-22T22%3A02%3A18Z&se=2026-11-22T23%3A02%3A18Z&sr=b&sp=r&sig=MHlcZXNt0f5iX9TtCA63%2FrDCognCfpfv1VaRnkH0KYY%3D) #### 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](/latest/docs/generate-a-self-signed-certificate)) - 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](/docs/deploy-sensor-collector-in-kubernetes-1#step-4-configure-container-runtime-ca-trust-if-required). --- ### 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--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 <".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/ cat </hosts.toml server = "https://" [host."https://"] 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- Namespace: cisco-sensor-collectors 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- 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 | Symptom | Cause | Resolution | | --- | --- | --- | | `x509: certificate signed by unknown authority` during image pull | Container runtime doesn't trust Crosswork Assurance CA | Complete Step 4 on all cluster nodes | | `x509` error during `helm pull` | Helm client doesn't trust Crosswork Assurance CA | Pass `--ca-file pca_ca.crt` (handled automatically by the install script) | | `unauthorized` during chart pull | Download token expired | Re-download the Helm package to get a fresh token | | Install script aborts at preflight | Missing `helm`, `kubectl`, or `.env` variables | Install prerequisites and verify `.env` contents | | Helm install times out | Image pull backoff on nodes | Check node-level CA trust and network connectivity to Crosswork Assurance | | Pod in `ImagePullBackOff` | Registry unreachable or auth failure | Verify `HELM_CHART_REGISTRY` in `.env`, check node connectivity | --- ### Related Documentation - [Integrated Registry for Sensor Collector](/latest/docs/oci-registry-for-sensor-collector) - [Sensor Collector System Requirements for Kubernetes](/latest/docs/sensor-collector-system-requirements-for-kubernetes) - [Configure Sensor Collector](/latest/docs/configure-sensor-collector) **© 2026 Cisco and/or its affiliates. All rights reserved.** For more information about trademarks, please visit: [Cisco trademarks](https://www.cisco.com/c/en/us/about/legal/trademarks.html)[](https://www.cisco.com/c/en/us/about/legal/trademarks.html) For more information about legal terms, please visit: [Cisco legal terms](https://www.cisco.com/c/en/us/about/legal/terms-conditions.html)