Satellite via Docker
Section: 1
Prerequisites
- Docker Engine version
18.03.0and above - Admin privileges on the Docker host
- 'docker-compose' installed, if 'docker compose' is not supported on your OS
- At least 4 CPUs
- At least 8 GB RAM
1. Download Docker Compose file
Levo provides pre-built Docker images for the Satellite that can be installed via Docker Compose.
2. Install Satellite
Execute the following from the directory where the Docker Compose file was downloaded.
export LEVOAI_AUTH_KEY='Authorization Key'
docker compose pull && docker compose up -d
Depending on the region you are installing in, you may need to set a different Levo base URL for the satellite.
For example, if the satellite will be used with app.india-1.levo.ai, the installation command will be:
export LEVOAI_AUTH_KEY='Authorization Key'
export LEVOAI_BASE_URL='https://api.india-1.levo.ai'
docker compose pull && docker compose up -d
If
docker compose ...complains with "docker: 'compose' is not a docker command.", you have can trydocker-composeinstead.
3. Verify connectivity with Levo.ai
a. Check Satellite health
The Satellite is comprised of four sub components 1) levoai-collector, 2) levoai-rabbitmq, 3)levoai-satellite, and 4) levoai-tagger.
Wait a couple of minutes after the installation, and check the health of the components by executing the following:
docker ps -f name=levoai
If the Satellite is healthy, you should see output similar to below.
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
2b32cd6b9ced levoai/collector:stable "/usr/local/bin/levo…" 10 seconds ago Up 8 seconds 0.0.0.0:4317->4317/tcp, 9411/tcp levoai-collector
06f3c597cad0 levoai/satellite:stable "gunicorn --capture-…" 10 seconds ago Up 9 seconds 0.0.0.0:9999->9999/tcp levoai-satellite
89026034c567 levoai/satellite:stable "python -OO /opt/lev…" 10 seconds ago Up Less than a second levoai-tagger
f74524d02fbd bitnami/rabbitmq:3.10 "/opt/bitnami/script…" 10 seconds ago Up 9 seconds 5551-5552/tcp, 0.0.0.0:4369->4369/tcp, 5671/tcp, 0.0.0.0:5672->5672/tcp, 0.0.0.0:15672->15672/tcp, 0.0.0.0:25672->25672/tcp, 15671/tcp levoai-rabbitmq
b. Check connectivity
Execute the following to check for connectivity health:
docker logs levoai-tagger | grep "Ready to process; waiting for messages."
If connectivity is healthy, you will see output similar to below.
{"level": "info", "time": "2022-06-07 08:07:22,439", "line": "rabbitmq_client.py:155", "version": "fc628b50354bf94e544eef46751d44945a2c55bc", "module": "/opt/levoai/e7s/src/python/levoai_e7s/satellite/rabbitmq_client.py", "message": "Ready to process; waiting for messages."}
4. Note down Host:Port information
The Collector now runs in a container, and is reachable on the host via port 4317 (on all the host's network interfaces).
Please note down either the host's IP address or domain name. The Sensor will be configured to communicate with the Collector at <Host's IP|Domain-Name>:4317.
Please proceed to install traffic capture sensors.
Satellite Lifecycle Management
Upgrade the Satellite
- Navigate to directory where you have the Docker Compose file.
- Reinstall the Satellite. The install always pulls the latest Docker images for the Satellite.
Note: If the re-installation fails, please Uninstall the Satellite and then reinstall.
Uninstall the Satellite
Ensure you are in the same directory where you downloaded the
Execute the below command:
docker compose down --remove-orphans -v
List Satellite's containers
docker ps | grep -E 'levoai/collector|bitnami/rabbitmq|levoai/satellite|levoai/tagger'
Get logs of a specific container
docker logs <container id>
Tail logs of a specific container
docker logs -f <container id>
Get logs for last 1 minute
docker logs <container id> --since 1m
Configuration
Change the minimum number of URLs that the satellite needs to observe to detect an API endpoint.
To detect an API endpoint, Satellite waits for at least '10' URLs to match that endpoint URL pattern. This number may cause delays in detecting API endpoints when there is not enough load.
If you want to change this number to suit your environment:
Export the environment variable
LEVOAI_MIN_URLS_PER_PATTERN- for example :export LEVOAI_MIN_URLS_PER_PATTERN=3Reinstall the Satellite to pickup the new configuration
Troubleshooting
Tagger Errors
The Tagger component sends API endpoint metadata information to Levo.ai. API Observability will not function if the Tagger is in an errored state.
Please see sample output below from docker ps | grep -E "levoai/collector|levoai/satellite|bitnami/rabbitmq", that shows the Tagger (2nd line item) in an errored state.
65fe40867c70 levoai/collector:stable "/usr/local/bin/levo…" 5 minutes ago Up 5 minutes 0.0.0.0:4317->4317/tcp, 9411/tcp levoai-collector
45d6c4cccb28 levoai/satellite:stable "python -OO /opt/lev…" 5 minutes ago Restarting (1) 55 seconds ago levoai-tagger
721b5431369a levoai/satellite:stable "gunicorn --capture-…" 5 minutes ago Up 5 minutes 0.0.0.0:9999->9999/tcp levoai-satellite
a00dc710d4af bitnami/rabbitmq:3.10 "/opt/bitnami/script…" 5 minutes ago Up 5 minutes 5551-5552/tcp, 0.0.0.0:4369->4369/tcp, 5671/tcp, 0.0.0.0:5672->5672/tcp, 0.0.0.0:15672->15672/tcp, 0.0.0.0:25672->25672/tcp, 15671/tcp levoai-rabbitmq
Below are common error scenarios:
Authentication Errors
The Tagger component authenticates with Levo.ai using the Authorization Key. If Tagger is unable to authenticate, it will error out.
Check for authentication errors in the Tagger logs:
docker logs levoai-tagger | grep "Exception: Failed to refresh access token"
If there are exception messages, you have an incorrect or stale Authorization Key. Please contact support@levo.ai for further assistance.
Connectivity Errors
Check for connectivity errors in the Tagger logs:
docker logs levoai-tagger | grep "ConnectionRefusedError: [Errno 111] Connection refused"
If there are exception messages, Tagger is unable to connect to dependent services. It generally establishes connection after 3/4 retries. Please contact support@levo.ai for further assistance.
Section: 2
Install on Docker using Shell Script
1. Download Shell Script File
Levo provides Shell Script file for the Satellite that can be installed via Docker.
Download
2. Install Satellite
Permissions: Ensure the script has executable permissions.
Otherwise, run the following command to add executable permissions.
chmod +x ./levo_satellite.sh
Set the following environment variables.
export LEVOAI_AUTH_KEY='Authorization Key'
export LEVOAI_ORG_ID='Org ID'
Depending on the region you are installing in, you may need to set a different Levo base URL for the satellite.
For example, if the satellite will be used with app.india-1.levo.ai, the installation command will be:
export LEVOAI_BASE_URL='https://api.india-1.levo.ai'
i. Start Levo Satellite
Execute following command to start Levo satellite.
./levo_satellite.sh start
If you are running the script with sudo, ensure that the environment variables are also set with sudo. Otherwise, the script will not have access to these variables.
Alternatively, you can use the -E flag with sudo to preserve the user-defined environment variables, like this:
sudo -E ./levo_satellite.sh start
This ensures the script can access the required environment variables without explicitly redefining them under sudo.
ii. Stop the Levo Satellite
Execute following command to stop or uninstall Levo satellite components.
./levo_satellite.sh stop
iii. Restart the Levo Satellite
To restart the Levo satellite components, execute the following command.
./levo_satellite.sh restart
iv. Upgrade the Levo Satellite
Execute the following command to upgrade the existing satellite setup.
Running this command will download the latest docker compose file and restarts all the satellite components.
./levo_satellite.sh upgrade
v. Share Satellite logs with Levo Support
Execute the following command to collect logs from all Satellite components. This will create an archive as /tmp/levoaisatellite_logs%date-time%.tar.gz
./levo_satellite.sh get-logs
Need Help?
For further assistance, please reach out to Levo.ai Support.