Deploy Sensor Collector in Docker

Deploy in Cloud

This article explains how to deploy Sensor Collectors in a Docker environment. It assumes you have already configured your Sensor Collector and met all system requirements.

Note: The steps in the procedure differ slightly depending on whether you are deploying a Gateway Sensor Collector (which receives time-series data in a "push" mode), or a CSV Sensor Collector (which collects time-series data from CSV files).

The Gateway mode requires a server certificate for secure communication with a Telemetry Collector or Assurance Sensor. You have two options for certificate generation:

• Generate a self-signed certificate (instructions provided in this article), or
• Use a certificate issued by a trusted Certificate Authority (CA).

Step 1: Download Docker Package

To download the Docker package:

1. Navigate to the Sensors > Collectors > Sensor page.
   This page displays a list of all Sensor Collectors that have been configured on the platform tenant.

2. Select your configured Sensor Collector from the list.

3. Click the ellipsis (three dots) in the upper-right corner.

4. Choose Download (Docker).
   This action initiates the download of the package to your local machine.

Note: The package is built dynamically, which may take a few minutes. A banner displaying "Preparing file for download..." will indicate the process is underway. Screenshot:

To provide visual status on download progress, there is a download icon that is grey and bounces while downloading and will turn green when the download is complete.

In progress:

Complete:

Step 2: Transfer the Package

Once downloaded you can transfer the .tar file to the target machine where the Sensor Collector will be deployed.

Step 3: Obtain Server Certificate (Gateway Only)

A server certificate is essential for the Gateway Sensor Collector to securely communicate with a Telemetry Collector or Assurance Sensor.
Note: This step is not required for CSV type deployments.

For this, you have two options:

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

Step 4: Initialize Sensor Collector Directory

To initialize the Sensor Collector Directory:

1. Run the following commands to create the directory, move the archive, and extract its contents:

mkdir sensorCollectorDir

mv sensorCollectorArchive.tar.gz sensorCollectorDir

cd sensorCollectorDir/

gunzip sensorCollectorArchive.tar.gz 

tar xvf sensorCollectorArchive.tar

Step 5: Copy Certificates: (Gateway Only)

To copy the certificates into the Sensor Collector's target directory:

1. Enter the following commands:

# go to the folder where sensorCollector is unpacked

mkdir .tls_custom

# copy ca.crt ca.key tls.crt tls.key files into sensorCollector's ".tls_custom" folder

cp {path to your certificates}/ca.crt .tls_custom/
cp {path to your certificates}/ca.key .tls_custom/
cp {path to your certificates}/tls.crt .tls_custom/
cp {path to your certificates}/tls.key .tls_custom/

Step 6: Run the Sensor Collector

Setting Proxy Variables (if your environment uses a proxy):

If your network uses a proxy server to access the internet, add the following lines to the .env file, replacing the proxy address with your organization's proxy settings:

http_proxy=proxy.yourdomain.com:80
HTTP_PROXY=proxy.yourdomain.com:80
https_proxy=proxy.yourdomain.com:80
HTTPS_PROXY=proxy.yourdomain.com:80

Example:
If your proxy is proxy.esl.cisco.com:80, then:

http_proxy=proxy.esl.cisco.com:80
HTTP_PROXY=proxy.esl.cisco.com:80
https_proxy=proxy.esl.cisco.com:80
HTTPS_PROXY=proxy.esl.cisco.com:80

Note:
If you do not configure the proxy, the installation may fail with errors related to authentication or connectivity.
Always review your network environment and update the .env file accordingly before starting the Sensor Collector.

Once you have updated the .env file as required, you can start the Sensor Collector.

1. Execute the run.sh shell script to start the Sensor Collector:

# run roadrunner
./run.sh

Now that you have executed the run.sh shell script above, check that Sensor Collector is running correctly. You can obtain information on these instructions here.

If you experience any issues running the Sensor Collector, you can access information on troubleshooting Sensor Collector here.

Deploy On-Prem (Controlled Availability Only)

This section of the article covers Docker deployments that pull the Sensor Collector image 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. For more details see On-Prem Continuous Delivery Release Notes

Prerequisites

• Docker Engine installed on the target host.
• Network connectivity from the target host to the Crosswork Assurance deployment.
• A configured Sensor Collector zone in Crosswork Assurance.

Step 1: Download Docker Package

The Docker package is generated dynamically and includes all artifacts needed for deployment, including pre-authenticated credentials.

Via UI

1. Navigate to Sensors > Collectors > Sensor Collectors.
2. Select your configured Sensor Collector from the list.
3. Click the ellipsis (three dots) in the upper-right corner.
4. Choose Download (Docker).

The package is built dynamically. A banner displays "Preparing file for download..." while the process is underway.

Via API

GET https://{{tenant-url}}/api/v4/ingestion/sensor-collector/{{zone}}/docker-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 the Package

Transfer the downloaded .tar.gz file to the target host where the Sensor Collector will run.

Step 3: Extract the Package

mkdir sensor-collector
tar -xzf sensor-collector-<zone>-docker.tar.gz -C sensor-collector
cd sensor-collector

After extraction, you should have the following structure:

sensor-collector/
.docker/config.json    # Pre-authenticated registry credentials
.auth/keyFile          # Authentication artifact
.env                   # Deployment-specific environment variables
.oci_token             # Pre-authenticated download token (used by run.sh)
adh-roadrunner.yml     # Roadrunner application configuration
run.sh                 # Startup script
pca_ca.crt             # (optional) Crosswork Assurance root CA certificate

Step 4: Configure Proxy (If Required)

If your network uses an HTTP proxy to reach the Crosswork Assurance deployment, add the following to the .env file:

http_proxy="proxy.yourdomain.com:80"
HTTP_PROXY="proxy.yourdomain.com:80"
https_proxy="proxy.yourdomain.com:80"
HTTPS_PROXY="proxy.yourdomain.com:80"

Step 5: Trust the Crosswork Assurance CA Certificate (If Required)

If your Crosswork Assurance deployment uses a self-signed TLS certificate, the Docker daemon on the target host must trust the Crosswork Assurance CA. The pca_ca.crt file included in the package is the Crosswork Assurance root CA.

Configure Docker to trust this CA:

# Replace <registry-host> with the registry hostname from your .env
# (the DOCKER_REGISTRY_URL value without the trailing slash)
sudo mkdir -p /etc/docker/certs.d/<registry-host>
sudo cp pca_ca.crt /etc/docker/certs.d/<registry-host>/ca.crt

If the pca_ca.crt file is not present in the package, your Crosswork Assurance deployment uses a publicly-trusted certificate and this step can be skipped.

Step 6: Run the Sensor Collector

Execute the startup script:

./run.sh

The run.sh script will:

1. Authenticate to the Crosswork Assurance built-in registry using the pre-configured credentials.
2. Pull the Sensor Collector container image.
3. Start the Sensor Collector container with the configuration from .env and adh-roadrunner.yml.

How It Works

The Crosswork Assurance built-in registry handles image distribution:

• Connected deployments: Images are fetched from the upstream Cisco registry on demand.
• Air-gapped deployments: Images are served from the embedded registry bundled with your installation -- no external network access required.
• Authentication: The download token embedded in .docker/config.json is pre-scoped to pull-only access.

Troubleshooting

Related Documentation

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