Ansible Scripting Guide

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

Playbook Distribution
- When an Ansible-based script is triggered in Level, the playbook file is downloaded to every target device.
Local Execution on Each Endpoint
- Each endpoint runs the playbook locally using its installed Ansible environment.
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

Define Groups and Hosts
- [servers] lists IP addresses or hostnames.
Specify Group Variables
- Set ansible_ssh_user and ansible_ssh_private_key_file to enable passwordless SSH.

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:

Navigate to Automation → Scripts
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
```
Attach the Playbook File
- Upload network_test.yml to Level’s file repository or ensure endpoints can access a shared location.
Target Devices
- Select Linux/macOS or Windows endpoints. Level downloads both the playbook and wrapper script to each chosen device.
Execution
- Run on Demand: Execute immediately.
- Schedule: Set to run at specific intervals (e.g., nightly, weekly).
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)

Enable WSL
- In PowerShell as Administrator:
```
wsl --install
```
- Reboot when prompted.

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
```

Invoke Ansible from PowerShell

Use a wrapper command:

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

Option B: Cygwin or MinGW (Git Bash)

Install Cygwin or Git for Windows
- Include packages for Python3, pip, and OpenSSH during installation.
Install Ansible via pip
```
pip3 install ansible
```

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:

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).

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

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.

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.

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.
Windows Version Consistency
- Align Python and Ansible versions across Windows endpoints to avoid module or dependency mismatches.
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

Create and Test Playbook on a Control Machine
- Develop network_test.yml.
- Run locally:
```
ansible-playbook network_test.yml
```
Distribute Playbook via Level
- Upload network_test.yml to Level’s file repository or ensure each endpoint can access a shared path.

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

Execute or Schedule
- Run immediately to verify.
- Schedule nightly to maintain ongoing health checks.
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
- Visit https://docs.level.io for more on scripting and automation.
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.

Linux Install

Actions

Scripting

Detecting and Removing Unauthorized Admins on your Endpoints

Set Variables Directly from Scripts