Remote Agent
Remote agent is a lightweight python application that is designed to run on customers' data center or any cloud machine. It makes period long poll requests to the avalanchio server over secure http(s) to find any pending task in the queue. If it finds a task, it executes the task in its running environment. To, start the agent you need the agent script, which you can download from the the following repository. The script name is remote_agent.py. The remote_agent.py does not require any external library. Any python3.8+ environment is sufficient to execute the script.
https://github.com/avalanchio/RemoteAgent
Before you start the agent, you need a couple thigs:
| Item | Environment Variable | Description |
|---|---|---|
| API Token | API_TOKEN | Check this document |
| Base endpoint for Avalanchio | AIO_BASE_URL | Webservice endpoint to which remote agent communicates with. For example https://apps.avalanchio.com. |
Steps to setup remote agent in the linux environment
Create a working directory for the agent inside any directory of your choosing. Below example creates the directory under /var/lib.
# Test python version. The version should be 3.8 or above.
python3 --version
# Create an working directory for the agent and make the current user the owner
sudo mkdir /var/lib/avalanchio-agent
sudo chown -R $USER:$USER /var/lib/avalanchio-agent
cd /var/lib/avalanchio-agent
export AIO_TOKEN=<enter the token here without any enclosing quotations>
export AIO_BASE_URL=<enter the base URL>
# Download the latest remote agent script from github.
wget https://raw.githubusercontent.com/avalanchio/RemoteAgent/refs/heads/main/remote_agent.py
# Execute the script and keep it running.
python3 remote_agent.py
Keep the script running. It keep a background communication with the Avalanchio server. If you terminate the script, the remote agent stops. During the task execute temporarily, it create some files under tmp directory in which remote agent is set up to run.
If you want to create a virtual env, run the following steps inside the agent working directory. Virtualenv are useful when you want to use some external libraries and you do not want to interfere with your existing setup.
cd /var/lib/avalanchio-agent
# Create python virtual environment under the agent directory
python3 -m venv venv
# Activate the agent directory
source venv/bin/activate
If you want to run the agent as the background process, you create a systemd service. Below is a template of a systemd file .
/etc/systemd/system/avalanchio-remote-agent.service. You will need sudo privilege to create a systemd service if you are not using root user account.
[Unit]
Description=Avalanchio Remote Agent
After=network.target remote-fs.target nss-lookup.target network-online.target
Requires=network-online.target
[Service]
User=<enter the linux username>
Group=<enter the linux usergroup.If not sure, enter username>
Environment="AIO_TOKEN=<replace with token>"
Environment="AIO_BASE_URL=<repalce with base url>"
ExecStart=/usr/bin/python3 /var/lib/avalanchio-agent/remote_agent.py
SuccessExitStatus=0
TimeoutStopSec=10
Restart=on-failure
RestartSec=5
LogLevelMax=warning
[Install]
WantedBy=multi-user.target
Enable systemd background service
sudo systemctl daemon-reload
sudo systemctl enable avalanchio-remote-agent.service
sudo systemctl start avalanchio-remote-agent.service
sudo systemctl status avalanchio-remote-agent.service
It show the status like below
$ sudo systemctl status avalanchio-remote-agent.service
● avalanchio-remote-agent.service - Avalanchio Remote Agent
Loaded: loaded (/etc/systemd/system/avalanchio-remote-agent.service; enabled; preset: enabled)
Active: active (running) since Tue 2024-12-17 17:39:22 IST; 10s ago
Main PID: 2328432 (python3)
Tasks: 1 (limit: 76944)
Memory: 10.2M (peak: 10.4M)
CPU: 60ms
CGroup: /system.slice/avalanchio-remote-agent.service
└─2328432 /usr/bin/python3 /var/lib/avalanchio-agent/remote_agent.py
Security
Since the agent can execute a script that is sent by the server, that exposes security risks. There is no direct way to mitigate that other than controlling access to task queue, which is done. But, to be extra cautious, run the agent in the environment, that is a secure and has lease amount privileges within the network. Cloud serverless environment such as AWS lambda is a good choice.
Test Remote Agent
To test the remote agent, you can create a simple playbook and execute it to test whether remote agent is working as expected.
from time import time
import platform
import time
import socket
def process(*args, **kwargs):
print("hello world")
return {
"os": platform.system(),
"os_version": platform.release(),
"timezone": str(time.tzname[0]),
"time": time.time(),
"host": socket.gethostname(),
}
Click on the run to execute the script.
To know more about playbook, read this document.
Remove the remote agent
If you want to remove the remote agent, run the following commands.
# Disable, stop and remote systemd service for avalanchio agent.
# You can skip these steps, if you have not setup the agent as a
# background service
sudo systemctl stop avalanchio-remote-agent.service
sudo systemctl disable avalanchio-remote-agent.service
sudo rm -f /etc/systemd/system/avalanchio-remote-agent.service
# Delete the working directory of the agent
sudo rm -rf /var/lib/avalanchio-agent