Deploy with Ansible

This guide provides a complete Ansible role for installing and enrolling LinuxGuard. Credentials are encrypted with Ansible Vault so no secrets appear in plaintext in your repository. The role is idempotent — safe to run repeatedly against already-enrolled servers.

Prerequisites

• Ansible 2.9+ or ansible-core 2.12+ installed on the control node

• Target hosts reachable via SSH with sudo access

• A LinuxGuard API key and tenant ID (from the LinuxGuard console)

Role Structure

The role follows the standard Ansible role directory layout. Create this structure under your roles/ directory, or generate the skeleton with ansible-galaxy role init linuxguard:

roles/
└── linuxguard/
    ├── defaults/
    │   └── main.yml       # Default variable values (lowest precedence)
    ├── handlers/
    │   └── main.yml       # Handler: restart agent service
    ├── meta/
    │   └── main.yml       # Role metadata (galaxy_info, dependencies)
    └── tasks/
        └── main.yml       # Core task list

Encrypting Secrets with Ansible Vault

Use ansible-vault encrypt_string to encrypt individual values. This approach encrypts the value while keeping the variable name visible in version control, making it easy to audit which variables are vault-protected.

Run these commands on your control node and paste the output into defaults/main.yml:

ansible-vault encrypt_string '<YOUR_API_KEY>' --name 'linuxguard_api_key'
ansible-vault encrypt_string '<YOUR_TENANT_ID>' --name 'linuxguard_tenant_id'

Each command prompts for a vault password and prints an encrypted block. Copy the full output (including the !vault | line) into your defaults file as shown in the next section.

Role Files

defaults/main.yml

---
# Values encrypted with: ansible-vault encrypt_string '<value>' --name '<varname>'
linuxguard_api_key: !vault |
  $ANSIBLE_VAULT;1.1;AES256
  # paste output from encrypt_string here
linuxguard_tenant_id: !vault |
  $ANSIBLE_VAULT;1.1;AES256
  # paste output from encrypt_string here

tasks/main.yml

---
- name: Install LinuxGuard agent
  command: >
    bash -c "curl -fsSL https://packages.linuxguard.io/install-linuxguard.sh | bash -s -- --yes"
  args:
    creates: /usr/bin/linuxguard-agent

- name: Enable and start LinuxGuard service
  service:
    name: linuxguard-agent
    enabled: true
    state: started

- name: Enroll LinuxGuard agent
  command: >
    linuxguard-agent enroll
    --api-key={{ linuxguard_api_key }}
    --tenant-id={{ linuxguard_tenant_id }}
  args:
    creates: /var/lib/linuxguard/config
  notify: Restart LinuxGuard agent

Note: The args: creates: /var/lib/linuxguard/config guard on the enroll task skips enrollment if the agent is already enrolled. See Automated Deployment Overview for details on the agent's built-in idempotency behavior.

handlers/main.yml

---
- name: Restart LinuxGuard agent
  service:
    name: linuxguard-agent
    state: restarted

meta/main.yml

---
galaxy_info:
  author: your_username
  description: Install and enroll LinuxGuard agent
  license: MIT
  min_ansible_version: "2.9"
dependencies: []

Running the Role

Create a site.yml playbook at the root of your project to apply the role to your inventory:

---
- hosts: all
  become: true
  roles:
    - linuxguard

Run the playbook and supply the vault password:

ansible-playbook site.yml --ask-vault-pass
# Or with a vault password file:
ansible-playbook site.yml --vault-password-file ~/.vault_pass

Note: If you use AWX or Ansible Tower, store the vault password as a Credential object. The --ask-vault-pass flag is not needed — AWX injects the vault password automatically.

Inline Playbook (Alternative)

If you prefer a single-file playbook without a role structure, the equivalent inline form requires no directory layout:

---
- hosts: all
  become: true
  vars:
    linuxguard_api_key: !vault |
      $ANSIBLE_VAULT;1.1;AES256
      # paste output from encrypt_string here
    linuxguard_tenant_id: !vault |
      $ANSIBLE_VAULT;1.1;AES256
      # paste output from encrypt_string here
  tasks:
    - name: Install LinuxGuard agent
      command: >
        bash -c "curl -fsSL https://packages.linuxguard.io/install-linuxguard.sh | bash -s -- --yes"
      args:
        creates: /usr/bin/linuxguard-agent

    - name: Enable and start LinuxGuard service
      service:
        name: linuxguard-agent
        enabled: true
        state: started

    - name: Enroll LinuxGuard agent
      command: >
        linuxguard-agent enroll
        --api-key={{ linuxguard_api_key }}
        --tenant-id={{ linuxguard_tenant_id }}
      args:
        creates: /var/lib/linuxguard/config

  handlers:
    - name: Restart LinuxGuard agent
      service:
        name: linuxguard-agent
        state: restarted

Run the same way: ansible-playbook site.yml --ask-vault-pass.

Verifying the Deployment

Add a verification task at the end of tasks/main.yml to confirm the agent is running after each playbook run:

- name: Verify LinuxGuard agent is running
  service_facts:

- name: Assert LinuxGuard agent is active
  assert:
    that: "'linuxguard-agent' in services and services['linuxguard-agent'].state == 'running'"
    fail_msg: "LinuxGuard agent is not running"

This task fails the play immediately if the service is not active, surfacing installation or enrollment errors before the run is marked successful. Enrolled servers also appear in the LinuxGuard console under Infrastructure within a few minutes of enrollment.

---

Related: Automated Deployment Overview | Installation | Configuration