Ansible Sandbox Documentation

Comprehensive guide to infrastructure automation with Ansible playbooks

Introduction

Welcome to the Argobox Ansible Sandbox documentation. This guide provides detailed information about the infrastructure automation playbooks available in the sandbox environment. Whether you're new to Ansible or looking to enhance your infrastructure-as-code skills, this documentation will help you understand the concepts and implementations demonstrated in the sandbox.

What is Ansible?

Ansible is an open-source automation tool that simplifies infrastructure management, application deployment, and task automation. It uses a declarative language to describe system configurations and a push-based architecture to apply those configurations to managed nodes.

Key features of Ansible include:

  • Agentless architecture - no need to install special software on managed nodes
  • YAML-based playbooks that are human-readable and version-controllable
  • Extensive module library for managing virtually any IT system
  • Idempotent execution - safely run the same playbook multiple times
  • Built-in parallelism for scaling across large environments
  • Integration with cloud providers, network devices, and container platforms

Why Infrastructure as Code?

Infrastructure as Code (IaC) treats infrastructure configuration as software code, allowing you to:

  • Version control your infrastructure configurations
  • Automate deployment and reduce human error
  • Create consistent, repeatable environments
  • Enable collaboration among team members
  • Implement testing and validation for infrastructure changes
  • Scale infrastructure management efficiently

The Ansible Sandbox demonstrates these principles by providing real-world examples of infrastructure deployments that you can examine and execute in a safe, isolated environment.

Sandbox Overview

The Ansible Sandbox is a controlled environment that allows you to explore infrastructure automation without affecting production systems. Each sandbox deployment creates isolated virtual machines to safely execute Ansible playbooks.

Sandbox Architecture

The sandbox uses a combination of technologies to provide a realistic yet isolated environment:

  • Proxmox Virtualization: Backend hypervisor for creating lightweight VMs
  • Isolated Network: Private network segments for each sandbox deployment
  • Ansible Control Node: Preconfigured with necessary collections and modules
  • Ephemeral Storage: Non-persistent storage that resets between sessions
  • Resource Limits: CPU, memory, and time boundaries to ensure fair usage

Available Playbooks

The sandbox includes several playbooks of varying complexity:

Playbook Complexity VMs Est. Runtime
Web Server Deployment Basic 1 ~3 min
Docker Compose Stack Intermediate 1 ~5 min
K3s Kubernetes Cluster Advanced 3 ~8 min
LAMP Stack Intermediate 1 ~4 min
Security Hardening Advanced 1 ~6 min

Each playbook demonstrates different aspects of infrastructure automation, from basic web server setup to more complex multi-node deployments.

Sandbox Limitations

Important Constraints

The sandbox environment has the following limitations:

  • 30-minute time limit per session
  • Limited outbound internet access
  • Maximum of 3 VMs per deployment
  • No persistent storage between sessions
  • Resource caps (4 vCPU, 4GB RAM per deployment)

Infrastructure Design

The sandbox uses a modular infrastructure design to isolate each deployment while providing a realistic environment for Ansible automation.

VM Templates

All sandbox playbooks use lightweight VM templates that boot quickly and consume minimal resources:

  • Ubuntu 22.04 LTS: Modern, long-term support Linux distribution
  • Debian 11: Stable, minimal distribution ideal for server deployments
  • CentOS Stream 9: Enterprise-focused distribution for RHEL compatibility

These templates are pre-optimized with:

  • Cloud-init support for dynamic provisioning
  • Python 3 pre-installed for Ansible compatibility
  • Minimal package set for faster deployment
  • SSH key-based authentication

Network Architecture

Each sandbox deployment gets a dedicated private network segment with the following characteristics:

  • Private 192.168.122.0/24 subnet
  • Isolated from other sandbox deployments
  • NAT for limited outbound connectivity
  • DNS resolution for package installations
  • No inbound external access
Network Access

While your deployed services won't be accessible from the public internet, you'll be able to interact with them through the sandbox interface, which provides proxied access to web applications and services deployed in your environment.

Web Server Deployment Playbook

The Web Server Deployment playbook demonstrates how to automate the installation and configuration of an Nginx web server with a custom website.

Playbook Overview

This basic playbook covers:

  • Package installation and management
  • Service configuration and startup
  • File and directory management
  • Template-based configuration
  • Handlers for service restarts

The playbook deploys a simple but fully functional web server with a customizable theme and domain configuration.

Code Structure

The playbook consists of three main components:

  1. Main Playbook: web-server.yml - Defines tasks for installation and configuration
  2. Website Template: templates/index.html.j2 - Jinja2 template for the sample website
  3. Nginx Config Template: templates/nginx.conf.j2 - Virtual host configuration
# Directory structure
web-server/
├── web-server.yml
└── templates/
    ├── index.html.j2
    └── nginx.conf.j2

Key Variables

The playbook uses several configurable variables:

Variable Default Description
web_domain example.local Domain name for the Nginx virtual host
web_root /var/www/html Directory path for website files
enable_https false Whether to configure SSL/TLS
web_color blue Theme color for the sample website

Implementation Details

The playbook follows these steps:

  1. Updates the package repository cache
  2. Installs Nginx and required packages
  3. Creates the web root directory
  4. Deploys a sample website using a Jinja2 template
  5. Configures the Nginx virtual host
  6. Enables the site configuration
  7. Starts and enables the Nginx service

The playbook also includes a handler for restarting Nginx when configuration changes are made, demonstrating the handler notification pattern in Ansible.

Download Web Server Playbook

Ansible Best Practices

The sandbox playbooks demonstrate several Ansible best practices that you can apply to your own automation projects.

Organization

  • Modular Design: Breaking complex deployments into discrete tasks
  • Clear Naming: Using descriptive names for tasks, variables, and files
  • Consistent Structure: Following a standard directory layout for playbooks and roles
  • Separation of Concerns: Keeping variables, tasks, and templates properly organized

Code Quality

  • Idempotence: Ensuring tasks can run multiple times without negative effects
  • Error Handling: Including proper failure conditions and recovery options
  • Validation: Checking inputs and preconditions before making changes
  • Documentation: Adding clear comments and documentation within playbooks

Security Considerations

  • Least Privilege: Using minimal permissions necessary for tasks
  • Secret Management: Properly handling sensitive data
  • Secure Defaults: Starting with secure configuration baselines
  • Hardening: Including security enhancements as part of deployment