Skip to main content

Ansible Scripting Guide

This documentation explains how to leverage Ansible playbooks within Level to automate tasks across endpoints.

Updated yesterday

Ansible provides agentless automation for configuration management, application deployment, and general task execution. The sections below cover prerequisites, Level’s execution model, Windows-specific considerations, and best practices.

Prerequisites

  • Ansible on a Control Machine

    • Ensure ansible and ansible-playbook are installed globally on a Linux or macOS host. Refer to Ansible’s installation guides for Ubuntu, CentOS, or macOS.

    • Verify installation with:

      ansible --version
      ansible-playbook --version
  • Level Account and Agent Deployment

    • A Level account must be set up, with the Level agent deployed to all target devices (Windows, macOS, or Linux). The agent handles playbook distribution and real-time output streaming.

  • SSH Connectivity for Unix Endpoints

    • Confirm SSH access is configured on Linux and macOS devices. Ansible’s default connection method is SSH.

  • Python/Ansible on Windows Endpoints

    • Since playbooks execute locally on Windows devices, each Windows endpoint requires a Unix-like environment (WSL, Cygwin, or MinGW) with Python and Ansible installed and configured.


Level’s Playbook Execution Model

  1. Playbook Distribution

    • When an Ansible-based script is triggered in Level, the playbook file is downloaded to every target device.

  2. Local Execution on Each Endpoint

    • Each endpoint runs the playbook locally using its installed Ansible environment.

  3. Real-Time Output Streaming

    • Level’s agent captures stdout/stderr as tasks proceed and streams live feedback to the Level console.

Advantages of Local Execution

  • Scalability: Parallel execution across many endpoints avoids overloading a central control node.

  • Resilience: If a device temporarily loses connectivity, the playbook continues locally and reports results when reconnected.

  • Transparency: Per-host output appears immediately in the Level UI, aiding troubleshooting and auditing.


Configuring the Ansible Inventory (For Local Testing)

Although Level does not use a central control node for execution, an inventory file on a Unix-based control machine remains useful for local testing.

Example /etc/ansible/hosts File

[servers]
10.0.0.10
10.0.0.11
10.0.0.12

[servers:vars]
ansible_ssh_user=user ansible_ssh_private_key_file=/home/user/.ssh/priv_key
  1. Define Groups and Hosts

    • [servers] lists IP addresses or hostnames.

  2. Specify Group Variables

    • Set ansible_ssh_user and ansible_ssh_private_key_file to enable passwordless SSH.

  3. Connectivity Test

    ansible all -m ping
    • Expected output:

      10.0.0.10 | SUCCESS => { "ping": "pong" }
      10.0.0.11 | SUCCESS => { "ping": "pong" }
      10.0.0.12 | SUCCESS => { "ping": "pong" }

For dynamic environments, consider a dynamic inventory script or syncing a shared inventory file to endpoints before execution.


Example Playbook

A simple playbook can verify network connectivity by pinging all hosts.

---
- name: Network test playbook
hosts: all

tasks:
- name: Ping host
ansible.builtin.ping:

Playbook Components

  • name: Describes the playbook purpose (“Network test playbook”).

  • hosts: all Targets all hosts in the inventory.

  • ansible.builtin.ping: Uses Ansible’s built-in ping module.

Sample Local Output
Running locally with ansible-playbook network_test.yml yields:

PLAY [Network test playbook] *************************************************

TASK [Gathering Facts] *******************************************************
ok: [10.0.0.10]
ok: [10.0.0.11]
ok: [10.0.0.12]

TASK [Ping host] ************************************************************
ok: [10.0.0.10]
ok: [10.0.0.11]
ok: [10.0.0.12]

PLAY RECAP *******************************************************************
10.0.0.10 : ok=2 changed=0 unreachable=0 failed=0
10.0.0.11 : ok=2 changed=0 unreachable=0 failed=0
10.0.0.12 : ok=2 changed=0 unreachable=0 failed=0

Level’s UI will show similar task-by-task output, streaming as each host completes.


Creating a Level Script for Ansible Playbooks

To run an Ansible playbook via Level, follow these steps:

  1. Navigate to Automation → Scripts

  2. Add New Script

    • Name: e.g., “Ansible Network Test”

    • Interpreter: Select Shell (Bash for Unix or PowerShell for Windows).

    • Script Content (Unix):

      #!/bin/bash
      ansible-playbook /path/to/network_test.yml
    • Script Content (Windows with WSL):

      wsl ansible-playbook /mnt/c/LevelPlaybooks/network_test.yml
  3. Attach the Playbook File

    • Upload network_test.yml to Level’s file repository or ensure endpoints can access a shared location.

  4. Target Devices

    • Select Linux/macOS or Windows endpoints. Level downloads both the playbook and wrapper script to each chosen device.

  5. Execution

    • Run on Demand: Execute immediately.

    • Schedule: Set to run at specific intervals (e.g., nightly, weekly).

  6. Review Output

    • Live task results appear in Level’s console, indicating success or failure for each host.


Setting Up Ansible on Windows Endpoints

Because playbooks run locally on Windows devices, an Ansible-compatible environment is required. Two common approaches:

Option A: Windows Subsystem for Linux (WSL)

  1. Enable WSL

    • In PowerShell as Administrator:

      wsl --install
    • Reboot when prompted.

  2. Install a Linux Distro

    • From the Microsoft Store, install Ubuntu (or Debian).

    • In the Ubuntu shell:

      sudo apt update && sudo apt upgrade -y
      sudo apt install -y python3 python3-pip
      pip3 install ansible
    • Confirm with:

      ansible --version
  3. Invoke Ansible from PowerShell

    • Use a wrapper command:

      wsl ansible-playbook /mnt/c/LevelPlaybooks/network_test.yml

Option B: Cygwin or MinGW (Git Bash)

  1. Install Cygwin or Git for Windows

    • Include packages for Python3, pip, and OpenSSH during installation.

  2. Install Ansible via pip

    pip3 install ansible
  3. Use Bash Wrapper in Level Script

    • PowerShell script points to Cygwin’s Bash:

      C:\cygwin64\bin\bash.exe -lc "ansible-playbook /cygdrive/c/LevelPlaybooks/network_test.yml"

Either solution ensures a POSIX-like shell on Windows, allowing Ansible to run similarly to Unix endpoints.


Handling Inventory and Credentials Locally on Each Endpoint

Since each host executes playbooks independently, common inventory references need adaptation:

  1. hosts: localhost and Local Connection

    ---
    - name: Local network test
    hosts: localhost
    connection: local

    tasks:
    - name: Ping remote servers from this host
    ansible.builtin.shell: |
    ansible all -i /etc/ansible/hosts -m ping
    register: ping_results

    - name: Show ping results
    ansible.builtin.debug:
    var: ping_results.stdout_lines
    • connection: local ensures execution on the endpoint itself.

    • The playbook can reference a central or locally-synced inventory (/etc/ansible/hosts).

  2. Credential Management

    • SSH keys or WinRM credentials must exist on each endpoint to authenticate against remote targets.

    • Consider using an SSH agent or encrypted vault for sensitive data.

This setup lets Windows hosts function as “control nodes” for downstream Ansible tasks while still managed by Level.


Best Practices and Troubleshooting

  1. Manual Environment Validation

    • Log into a test endpoint and run:

      ansible-playbook /path/to/playbook.yml --check
    • Using --check (dry run) verifies syntax and connectivity.

  2. Wrapper Script Error Handling

    #!/bin/bash
    ansible-playbook /path/to/playbook.yml
    if [ $? -ne 0 ]; then
    echo "Playbook failed on $(hostname)" >&2
    exit 1
    fi
    • Level flags non-zero exits as failures.

  3. Inventory Synchronization

    • For dynamic environments, generate or sync inventory files via Level before playbook execution.

    • Evaluate dynamic inventory scripts that query cloud providers or CMDBs.

  4. Windows Version Consistency

    • Align Python and Ansible versions across Windows endpoints to avoid module or dependency mismatches.

  5. Verbose Logging

    • Use Ansible flags (-v, -vv, or -vvv) in the wrapper script to capture detailed logs.

    • Redirect logs to a file on each endpoint for audit trails.


Example Workflow

  1. Create and Test Playbook on a Control Machine

    • Develop network_test.yml.

    • Run locally:

      ansible-playbook network_test.yml
  2. Distribute Playbook via Level

    • Upload network_test.yml to Level’s file repository or ensure each endpoint can access a shared path.

  3. Configure a Level Script

    • Linux/macOS:

      #!/bin/bash
      ansible-playbook /path/to/network_test.yml
    • Windows (WSL):

      wsl ansible-playbook /mnt/c/LevelPlaybooks/network_test.yml
  4. Execute or Schedule

    • Run immediately to verify.

    • Schedule nightly to maintain ongoing health checks.

  5. Monitor Output in Level UI

    • View real-time task results per host, checking for any failures or unreachable endpoints.


Additional Resources

  • Ansible Official Documentation

    • Comprehensive guides on playbooks, modules, and inventory management.

  • Level Documentation Hub

  • Community Playbooks on Ansible Galaxy

    • Browse pre-built roles and adapt as needed.

Experiment with advanced Ansible modules, such as ansible.builtin.copy, ansible.builtin.yum, or Windows-specific modules like ansible.windows.win_feature to automate patching, software installs, or configuration tasks across a heterogeneous environment.

Did this answer your question?