Ansible Sandbox Documentation | Argobox

Introduction

Welcome to the documentation for the ArgoBox Ansible Sandbox. This interactive environment allows you to safely experiment with Ansible playbooks designed to manage various aspects of a modern infrastructure setup, including web servers, containerized applications, and Kubernetes clusters.

This documentation provides details on the available playbooks, the underlying infrastructure design of the sandbox environment, and best practices for writing and testing your own automation scripts.

Purpose

The primary goal of the sandbox is to provide a hands-on learning experience for Ansible in a pre-configured, safe environment that mirrors real-world scenarios.

Sandbox Overview

The Ansible Sandbox provides you with temporary access to a set of virtual machines (VMs) where you can execute pre-defined Ansible playbooks or even upload and run your own. The environment is reset periodically to ensure a clean state for each session.

Key Features

Isolated environment with multiple target VMs.
Pre-loaded collection of common Ansible roles and playbooks.
Ability to select and run specific playbooks via a web interface.
Real-time output streaming of playbook execution.
Network access between sandbox VMs for testing multi-tier applications.
Environment reset functionality.

Launch Ansible Sandbox

Infrastructure Design

The sandbox environment consists of several virtual machines managed by the main ArgoBox infrastructure, typically running on Proxmox VE. These VMs are provisioned specifically for sandbox use and are isolated from the core production services.

Components

Component	Description	OS	Purpose
Control Node	The VM where Ansible commands are executed from.	Debian 12	Runs Ansible engine, hosts playbooks.
Web Server Node	Target VM for web server playbooks (Nginx/Apache).	Ubuntu 22.04	Simulates a typical web server.
Database Node	Target VM for database playbooks (PostgreSQL/MySQL).	Debian 12	Simulates a database server.
Docker Node	Target VM with Docker installed for container playbooks.	Ubuntu 22.04	Runs Docker containers via Compose.

Networking

All sandbox VMs are placed on a dedicated, isolated VLAN with controlled access to simulate a realistic network environment.

Available Playbooks

The following playbooks are available for execution within the sandbox environment. Each playbook demonstrates different Ansible concepts and common infrastructure tasks.

Web Server Deployment (Nginx)

Installs and configures the Nginx web server on the 'Web Server Node'. Includes setting up a basic virtual host and ensuring the service is running.

---
- name: Deploy Nginx Web Server
  hosts: web_server_node # Corresponds to inventory group
  become: yes # Execute tasks with sudo
  tasks:
    - name: Update apt cache
      ansible.builtin.apt:
        update_cache: yes
      tags: [install]

    - name: Install Nginx
      ansible.builtin.apt:
        name: nginx
        state: present
      tags: [install]

    - name: Ensure Nginx service is started and enabled
      ansible.builtin.service:
        name: nginx
        state: started
        enabled: yes
      tags: [configure]

    - name: Deploy basic index page (template example)
      ansible.builtin.template:
        src: templates/index.html.j2 # Example template path
        dest: /var/www/html/index.nginx-debian.html # Default Nginx path
        owner: root
        group: root
        mode: '0644'
      tags: [configure]

Docker Compose Stack (Example: Portainer)

Deploys a simple Docker Compose application (e.g., Portainer) on the 'Docker Node'. Requires Docker and Docker Compose to be pre-installed on the target.

K3s Kubernetes Cluster (Basic Setup)

Installs a single-node K3s cluster on the 'Control Node'. Note: This is a simplified setup for demonstration.

---
- name: Install K3s Single Node Cluster
  hosts: control_node # Install on the control node itself for demo
  become: yes
  tasks:
    - name: Download K3s installation script
      ansible.builtin.get_url:
        url: https://get.k3s.io
        dest: /tmp/k3s-install.sh
        mode: '0755'

    - name: Execute K3s installation script
      ansible.builtin.command:
        cmd: /tmp/k3s-install.sh
        creates: /usr/local/bin/k3s # Avoid re-running if k3s exists
      register: k3s_install_result
      changed_when: k3s_install_result.rc == 0

    - name: Ensure K3s service is started
      ansible.builtin.service:
        name: k3s
        state: started
        enabled: yes

    - name: Wait for Kubeconfig to be available
      ansible.builtin.wait_for:
        path: /etc/rancher/k3s/k3s.yaml
        timeout: 60

    - name: Read Kubeconfig file
      ansible.builtin.slurp:
        src: /etc/rancher/k3s/k3s.yaml
      register: k3s_kubeconfig

    - name: Display Kubeconfig hint (for manual use)
      ansible.builtin.debug:
        msg: "K3s installed. Use 'sudo k3s kubectl get nodes' or copy Kubeconfig."

Simplified Setup

This playbook installs a basic single-node K3s cluster. Production setups require more complex configuration, multiple nodes, and security considerations.

LAMP Stack Installation

Installs Apache, MySQL (MariaDB), and PHP on the 'Web Server Node'.

Code example for LAMP stack coming soon...

Basic Security Hardening

Applies basic security measures like installing fail2ban and configuring UFW firewall rules on a target node.

Code example for security hardening coming soon...

Advanced Topics

Using Custom Roles

Learn how to structure your automation using Ansible Roles for better reusability and organization. Examples of common role structures will be provided.

Details on custom roles coming soon...

Variables and Inventory Management

Understand how to manage variables for different environments (e.g., development, production) and how to define your infrastructure using Ansible inventory files (static and dynamic).

Details on variables and inventory coming soon...

Ansible Best Practices

Explore recommended practices for writing effective, maintainable, and idempotent Ansible playbooks, including task naming, using handlers, and managing secrets.

Best practices details coming soon...

Reference

Common CLI Commands

A quick reference for frequently used Ansible CLI commands.

Command	Description
`ansible --version`	Check Ansible version.
`ansible-inventory --list -i inventory.yml`	List inventory hosts and groups.
`ansible all -m ping -i inventory.yml`	Ping all hosts in inventory.
`ansible-playbook playbook.yml -i inventory.yml`	Run a playbook.
`ansible-playbook playbook.yml --check`	Perform a dry run of a playbook.
`ansible-playbook playbook.yml --limit web_servers`	Run playbook only on specific hosts/groups.
`ansible-vault create secrets.yml`	Create an encrypted vault file.
`ansible-playbook playbook.yml --ask-vault-pass`	Run playbook asking for vault password.

Troubleshooting Tips

Common issues and how to resolve them when working with the sandbox or Ansible in general.

Connection Errors: Ensure SSH keys are correctly configured and target VMs are reachable. Check firewall rules.
Permission Denied: Use `become: yes` for tasks requiring root privileges. Verify sudo configuration on target nodes.
Module Not Found: Ensure required Ansible collections or Python libraries are installed on the control node.
Idempotency Issues: Review tasks to ensure they only make changes when necessary (e.g., use `creates` argument for command/shell modules).
Variable Undefined: Check variable definitions, scope (host_vars, group_vars), and precedence. Use `-v` or `-vvv` for verbose output.