Deploying Onagre Agent with Ansible

Overview

For teams managing fleets of servers, Ansible provides a repeatable and idempotent way to deploy the Onagre Agent across your infrastructure. This page provides a ready-to-use playbook and role structure.

---

Prerequisites

• Ansible 2.9+ installed on your control node
• Target hosts running a systemd-based Linux distribution (Debian, Ubuntu, RHEL, etc.)
• SSH access with root or sudo privileges on target hosts
• Your Onagre agent token (available from the Onagre UI)

---

Inventory Setup

Define your target hosts in your inventory. You can group them by role or environment:

inventory/hosts.ini

[onagre_agents]
web-01 ansible_host=192.168.1.10
web-02 ansible_host=192.168.1.11
db-01  ansible_host=192.168.1.20

[onagre_agents:vars]
onagre_token=YOUR_TOKEN_HERE

Tip

Use ansible-vault to encrypt your token instead of storing it in plain text:

ansible-vault encrypt_string 'YOUR_TOKEN_HERE' --name 'onagre_token'

---

Playbook

playbooks/deploy-onagre-agent.yml

---
- name: Deploy Onagre Agent
  hosts: onagre_agents
  become: true
  vars:
    onagre_agent_version: "latest"
    onagre_agent_name: "default"
    onagre_agent_binary: "/usr/local/bin/onagent@{{ onagre_agent_name }}"
    onagre_agent_service: "onagent@{{ onagre_agent_name }}"
    onagre_base_url: "https://d.onag.re"

  tasks:
    - name: Determine architecture
      ansible.builtin.set_fact:
        onagre_arch: >-linux-x64- name: Download Onagre Agent binary
      ansible.builtin.get_url:
        url: "{{ onagre_base_url }}/agent-{{ onagre_arch }}"
        dest: "{{ onagre_agent_binary }}"
        mode: "0755"
        force: true
      notify: Restart Onagre Agent

    - name: Create systemd service file
      ansible.builtin.template:
        src: onagent.service.j2
        dest: "/etc/systemd/system/{{ onagre_agent_service }}.service"
        mode: "0644"
      notify:
        - Reload systemd
        - Restart Onagre Agent

    - name: Enable and start Onagre Agent
      ansible.builtin.systemd:
        name: "{{ onagre_agent_service }}"
        enabled: true
        state: started

  handlers:
    - name: Reload systemd
      ansible.builtin.systemd:
        daemon_reload: true

    - name: Restart Onagre Agent
      ansible.builtin.systemd:
        name: "{{ onagre_agent_service }}"
        state: restarted

---

Service Template

Create the Jinja2 template referenced by the playbook:

templates/onagent.service.j2

[Unit]
Description=Onagre Agent ({{ onagre_agent_name }})
After=network.target

[Service]
LimitNOFILE=65535
Environment=TOKEN={{ onagre_token }}
ExecStart={{ onagre_agent_binary }}
RestartSec=5
Restart=always
User=root

[Install]
WantedBy=multi-user.target

---

Directory Structure

ansible/
├── inventory/
│   └── hosts.ini
├── playbooks/
│   └── deploy-onagre-agent.yml
└── templates/
    └── onagent.service.j2

---

Running the Playbook

Deploy to all hosts:

ansible-playbook -i inventory/hosts.ini playbooks/deploy-onagre-agent.yml

Deploy to a specific host:

ansible-playbook -i inventory/hosts.ini playbooks/deploy-onagre-agent.yml --limit web-01

With a vaulted token:

ansible-playbook -i inventory/hosts.ini playbooks/deploy-onagre-agent.yml --ask-vault-pass

---

Updating Agents

Re-run the same playbook — it will download the latest binary and restart the service if it changed:

ansible-playbook -i inventory/hosts.ini playbooks/deploy-onagre-agent.yml

The force: true option on the download task ensures the binary is always refreshed.

---

Uninstalling Agents

To remove agents from your fleet, use this playbook:

playbooks/uninstall-onagre-agent.yml

---
- name: Uninstall Onagre Agent
  hosts: onagre_agents
  become: true
  vars:
    onagre_agent_name: "default"
    onagre_agent_binary: "/usr/local/bin/onagent@{{ onagre_agent_name }}"
    onagre_agent_service: "onagent@{{ onagre_agent_name }}"

  tasks:
    - name: Stop and disable Onagre Agent
      ansible.builtin.systemd:
        name: "{{ onagre_agent_service }}"
        state: stopped
        enabled: false
      ignore_errors: true

    - name: Remove service file
      ansible.builtin.file:
        path: "/etc/systemd/system/{{ onagre_agent_service }}.service"
        state: absent
      notify: Reload systemd

    - name: Remove agent binary
      ansible.builtin.file:
        path: "{{ onagre_agent_binary }}"
        state: absent

  handlers:
    - name: Reload systemd
      ansible.builtin.systemd:
        daemon_reload: true

---

Summary

Using Ansible to deploy Onagre agents provides a scalable, repeatable, and auditable approach suitable for managing agents across large infrastructure. The playbook handles architecture detection, binary deployment, service management, and updates in a single run.

For single-server deployments, consider the install script or manual installation instead.