Get started with Ansible automation

Build an inventory, check connectivity, and deploy a small Nginx site with a playbook and explicit platform requirements.

Guance Editorial Team 2026-10-27 3 min read Updated 2026-10-27

Best practices

Illustration of software development and testing

Ansible automates managed systems without requiring a resident Ansible Agent in the usual Linux setup. A control node connects over SSH and runs modules against the target; most Linux modules require a supported Python interpreter there. Inventory identifies the hosts, and YAML playbooks describe the tasks and desired state.

A practical introduction is to configure one inventory, check connectivity and privileges with ad-hoc commands, and then deploy a small web server with a playbook.

The core model

No resident Agent for the usual SSH workflow. Targets still need appropriate connectivity, authentication, and module prerequisites. Network devices and Windows have different requirements.
YAML playbooks. Tasks provide a readable record of what the automation should do.
State-aware modules. Many modules are idempotent, but arbitrary command or shell tasks and external side effects remain the playbook author's responsibility.

Prepare the control node and inventory

Install an Ansible version compatible with your Python environment, preferably in a dedicated virtual environment or through pipx. Prepare SSH access to your test hosts and save this as inventory.ini:

[webservers]
web1 ansible_host=192.168.1.10
web2 ansible_host=192.168.1.11

[webservers:vars]
ansible_user=ubuntu

Replace the example addresses and account with your own. This walkthrough targets Debian or Ubuntu hosts.

Try ad-hoc commands

ansible webservers -i inventory.ini -m ping
ansible webservers -i inventory.ini -a "uptime"
ansible webservers -i inventory.ini -m apt -a "name=nginx state=present" --become

Ansible's ping module checks that Ansible can connect and execute a simple Python-based module; it is not an ICMP ping. Use these commands to establish connectivity and privileges before introducing a larger playbook. The package command requires appropriate privilege escalation.

Deploy a web server

Prepare a local index.html and save the following as site.yml:

- hosts: webservers
  become: true
  tasks:
    - name: Install Nginx
      ansible.builtin.apt:
        name: nginx
        state: present
        update_cache: true
    - name: Start Nginx and enable it at boot
      ansible.builtin.service:
        name: nginx
        state: started
        enabled: true
    - name: Deploy the home page
      ansible.builtin.copy:
        src: index.html
        dest: /var/www/html/index.html
        owner: root
        group: root
        mode: '0644'

With SSH and the necessary sudo permissions configured, run:

ansible-playbook -i inventory.ini site.yml

Verify the resulting service rather than relying only on the task summary. Cache updates can still report changes on later runs, and changed=0 does not prove the application's behavior is correct.

Request the page from its intended access path and check both status and body. For ongoing checks, configure a Guance HTTP synthetic test with the target address, execution nodes, frequency, and response assertions.

Troubleshoot a failed task

Start with the failing module and the output from -vvv. Use --limit web1 to narrow investigation to one host. --check can estimate supported changes without applying them, but module support and skipped tasks limit what a check-mode run proves.

Frequently asked questions

Can Ansible manage Windows?

Yes. WinRM and PSRP are established connection options; supported versions can also use Windows OpenSSH. Follow the Windows documentation for connection, module, PowerShell, and platform requirements. IIS management and patch automation require the corresponding Windows modules and setup.

Can macOS be the control node?

Yes, with supported Python and Ansible versions. Linux is also supported. Native Windows is not a supported control-node platform. WSL can be useful for experiments, but the Ansible documentation does not support it as a production control node.

Where should passwords and keys go?

Use Ansible Vault for sensitive variable files and provide the vault password at runtime, for example with --ask-vault-pass or a protected password source. Keep plaintext credentials out of version control; encryption at rest does not prevent a task from exposing a decrypted value in output.

References

The deployment example must be validated against your target hosts, permissions, and Ansible version; it has not been run against a production service for this article.