{"canonical_url":"https://engineer.company/glossary/ansible/","content_markdown":"# Ansible\n\n## What it is\n\nAnsible is open-source automation software that connects to machines over SSH\nand brings each one to the configuration described in a set of YAML files: which\npackages are installed, which users and files exist, which services run and how\nthey are set up. The machine Ansible runs from is the control node; the machines\nit configures are managed nodes, and nothing has to be installed on them as an\nagent, because Ansible logs in with the operating system's own credentials and\ndoes its work over that connection. The files list the outcome, and Ansible\nworks out on each host whether that outcome is already true.\n\nThe pieces have plain names. An inventory lists the managed nodes and sorts them\ninto groups such as `web` or `db`, with variables that apply to a whole group or\nto one host. A playbook holds one or more plays, and each play maps a group of\nhosts to a list of tasks. Each task calls a module, a small program that knows\nhow to manage one kind of thing: a package, a file, a service, a user, a\nfirewall rule. The project's own documentation describes playbooks as a\nrepeatable, reusable, simple configuration management and multi-machine\ndeployment system. A role bundles tasks, templates, default variables and\nhandlers under one name, so “a PostgreSQL server” or “a hardened SSH daemon” is\nwritten once and applied to any host that needs it.\n\nA short play shows the shape:\n\n```text\n- name: Web servers serve the site\n  hosts: web\n  become: true\n  tasks:\n    - name: nginx is installed\n      ansible.builtin.package:\n        name: nginx\n        state: present\n\n    - name: nginx runs now and after a reboot\n      ansible.builtin.service:\n        name: nginx\n        state: started\n        enabled: true\n```\n\nEach task names a state, not an action. Most modules check first whether that\nstate already holds and exit without doing anything if it does, so the second\nrun of this play on a configured host changes nothing and says so. That\nproperty, idempotence, is what makes it safe to run the same playbook against\nthe whole fleet every time, instead of tracking which host has had which script\napplied.\n\nPeople asking about Ansible often weigh it against three neighbours. Against a\nshell script, the difference is that a script lists steps and runs them again\nwhether they are needed or not, while a module checks before it acts. Against\nTerraform or Bicep, the difference is the layer: those tools create cloud\nresources such as networks, databases and virtual machines, while Ansible\nconfigures what runs inside a machine once it exists. Many teams use one of\neach. Against Puppet and Chef, the difference is the model: those usually run an\nagent on every machine that pulls its configuration from a central server, while\nAnsible pushes from wherever it is started and needs only SSH on the far side.\n\n## Why it matters\n\nA server set up by hand is only as reproducible as the memory of whoever set it\nup. Six months later nobody can say with confidence why a kernel parameter has\nits value, which package was pinned and why, or what has to happen first when\nthe machine is rebuilt. Writing the setup down as playbooks turns that memory\ninto files that can be read, reviewed in a pull request and run again on a fresh\nmachine with the same result.\n\nThe written form also changes what drift means. When the playbook is the\ndescription of the host, running it in check mode against a live machine reports\nevery place where the two disagree. With the `--diff` flag the report shows the\nlines in each file that would change. A fleet that is converged regularly stays\nclose to its description, and a host that has been edited by hand shows up as a\nchange the next time the playbook runs.\n\nThe model has costs. Ansible acts only when it is run, so drift between runs\nstays until the next one. Tasks run in order, one at a time across all matched\nhosts, and a large playbook against many machines is slower than a script that\ndoes one thing. Logic written in YAML and Jinja2 templates gets hard to follow\nonce a role grows many conditions. And a run that stops partway leaves its hosts\npartly changed, because Ansible has no transaction to roll back.\n\n## What it looks like in practice\n\nSeveral projects on this site show what a written-down estate looks like over\ntime, and what it takes to keep it honest.\n\nThe company's infrastructure as code covers deployed public services and configuration for\nother components, including backup and mail automation whose activation is a separate step.\n[The recorded implementation comprises 19 playbooks and 34 roles](/portfolio/servers-you-can-rebuild-from-scratch/)\nacross 12,065 lines of YAML; those figures describe that stage, not the current repository size.\nA host sits in a tier group whose variables declare which roles it runs, so provisioning with\nno arguments converges every host to its declared state. Idempotence is treated as a contract:\na converged host reports zero changes, and a play that cannot say that is not finished. Four\ncommand namespaces keep the promises apart, from a gate that touches no host to verification\nthat changes a host on purpose and returns a verdict. The page is candid about the cost:\nevery change is slower to make than editing a file on the server, and a converge that\nhalf-applies is worse than one that refuses.\n\nAccess control is another place where a written description pays off.\n[1,000 RBAC rules were configured through Ansible](/portfolio/wrote-1000-rbac-rules-to-secure-linux-servers/)\nacross developer environments, application instances, PostgreSQL, MS SQL and\nLinux servers, each rule tied to one role and one system. The recorded result is\na documented role-based rule set and a repeatable way to apply and review it.\nThat is what the record supports; it does not quantify security-risk reduction\nor setup-time savings.\n\nKeeping the dry run truthful took work of its own.\n[Check mode was made to tell the truth across the whole platform](/portfolio/made-ansible-check-mode-tell-the-truth/)\nafter a dry run in September 2026 stopped on an assertion that was wrong about\nthe host and advised setting a flag that would have relaxed a security sandbox.\nA sweep found six probes deciding on values the host had never given. Probes\nthat read state the run has not touched now run even under check mode; the rest\nare skipped with a message naming what went unverified, and the rule went into\nthe development guide.\n\n## Where it goes wrong\n\nMost Ansible trouble comes from trusting a report more than the mechanism behind\nit.\n\n**A dry run reports a clean result for commands it never ran.** Check mode is a\nsimulation. Modules that support it predict their change; the documentation says\nmodules that lack support report nothing and do nothing. The `command` and\n`shell` modules support it only partly: unless `creates` or `removes` is given,\nthey skip the command and register a result with empty output. Any later `when:`\nthat reads that result decides on a value nobody measured. A probe that only\nreads the host can be told to run anyway, and one that cannot run should say so:\n\n```text\n- name: Read the firewall state, even in check mode\n  ansible.builtin.command: ufw status\n  register: fw\n  check_mode: false\n  changed_when: false\n\n- name: Say what this dry run did not verify\n  ansible.builtin.debug:\n    msg: \"check mode: the service restart was not exercised\"\n  when: ansible_check_mode\n```\n\n**A run stops on its ninth task with the first eight already applied.** When a\ntask fails on a host, Ansible drops that host from the rest of the run and\nleaves whatever it already changed in place. Checks that can run before anything\ntouches a host belong in front of the converge. That is what happened after a\nsecrets change on this site's own estate:\n[a preflight play now validates the vault locally first](/portfolio/added-a-one-second-preflight-for-secrets/),\nrunning the same task files as the real converge in about a second, so a secret\nthat does not resolve costs a two-second refusal on a laptop instead of a partly\napplied change to a live server. The same page notes a trap: facts set during\none play outlive it, so a check and a converge chained into one invocation can\nshare a value the check should have re-read.\n\n**A host nobody touched reports changes on every run.** The `command` and\n`shell` modules report a change every time they run, because they have no way to\nknow what the command did. A playbook full of them never converges to zero, and\nreal changes hide in the noise. Prefer a module that manages the thing directly,\nadd `creates` or `removes`, or tell Ansible when output means a change with\n`changed_when`.\n\n**A password turns up in a log or in the repository.** Variables are plain text\nunless something encrypts them. Ansible Vault encrypts variable files or single\nvalues so they can live in the repository, and `no_log: true` on a task keeps\nits arguments and results out of the output. Run the playbook once with high\nverbosity in a test environment and read what it prints before trusting either.\n\n## Further reading\n\n- [Ansible Community Documentation](https://docs.ansible.com/ansible/latest/index.html)\n  — the project's own entry point to installation, concepts and every guide.\n- [Ansible playbooks](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_intro.html)\n  — plays, tasks, modules, execution order and what idempotence means in\n  practice.\n- [Validating tasks: check mode and diff mode](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_checkmode.html)\n  — what a dry run can and cannot see, and the per-task switches.\n- [How to build your inventory](https://docs.ansible.com/ansible/latest/inventory_guide/intro_inventory.html)\n  — hosts, groups and the variables attached to them.\n- [Protecting sensitive data with Ansible Vault](https://docs.ansible.com/ansible/latest/vault_guide/index.html)\n  — encrypting files and single values that live beside the playbooks.\n- [ansible.builtin.command](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/command_module.html)\n  — the module reference, including its partial check-mode support.\n\n\u003chttps://engineer.company/glossary/ansible/\u003e\n","date_modified":"2026-11-08T02:22:23Z","description":"What Ansible is, how playbooks, roles and inventories fit together, how it compares with Terraform and Puppet, and where dry runs and half-done runs mislead.","formats":{"gemtext":"https://engineer.company/glossary/ansible/index.gmi","gopher":"https://engineer.company/glossary/ansible/gophermap","html":"https://engineer.company/glossary/ansible/","json":"https://engineer.company/glossary/ansible/index.json","markdown":"https://engineer.company/glossary/ansible/index.md","pdf":"https://engineer.company/glossary/ansible/index.pdf"},"kind":"page","language":"en","title":"What is Ansible?","url":"https://engineer.company/glossary/ansible/","version":1}