Manual VM Configuration to Ansible Blueprint

What and Why

Manually configuring servers over SSH does not scale and produces drift: every box ends up slightly different, nothing is reproducible, and the knowledge of how a server was set up lives only in someone's head or a stale wiki page. Ansible is an agentless configuration-management tool that connects over SSH and applies desired state described in YAML playbooks. Tasks are idempotent, so running a playbook repeatedly converges every host to the same declared state without causing harm on re-runs. This is the first step toward configuration-as-code and a stepping stone to immutable infrastructure.

The migration captures tribal knowledge as reviewable code and makes server configuration repeatable, auditable, and consistent across a fleet.

Phases

Assessment. Catalogue servers, their roles (web, database, cache, queue), and the packages, users, services, files, and kernel settings configured on each. Capture the manual steps from runbooks and tribal knowledge before they are lost, and note where servers have drifted apart. Group hosts into logical inventories by role and environment.

Design. Structure the project with inventory (static files or dynamic inventory from the cloud provider), group and host variables, and a role-based layout following Ansible's recommended directory structure. Plan secret handling with Ansible Vault or an external secrets manager so credentials never sit in plaintext in the repo. Decide how playbooks run: from a control node, locally with ansible-pull, or through CI/CD, and define a convergence schedule.

Roles. Convert manual steps into reusable Ansible roles with idempotent tasks, handlers for service restarts, templated config files (Jinja2), and sensible defaults. Keep roles small and composable, prefer purpose-built modules over raw shell, and test roles with Molecule against throwaway containers or VMs to prove idempotency.

Migration. Apply roles to existing servers in waves, starting with non-production. Run in check mode (--check --diff) first to preview changes, then apply. Reconcile each host to the declared state, remove the need for manual SSH edits, and document any host-specific exceptions as variables rather than one-off commands.

Automation. Run playbooks from CI/CD on change, gate with linting (ansible-lint) and Molecule tests in the pipeline, and schedule periodic convergence runs to catch and correct drift. Pair Ansible with Terraform so Terraform provisions infrastructure and Ansible configures it. As maturity grows, fold configuration into image builds (Packer) to move toward immutable infrastructure.

Key Risks and Mitigations

• Configuration drift. Manual edits reintroduce drift after a playbook run. Run scheduled convergence playbooks, alert on changes detected during convergence, and forbid out-of-band SSH changes by policy.
• Non-idempotent tasks. Shell commands that are not idempotent break repeatability and can cause damage on re-runs. Prefer Ansible modules over raw command/shell, use creates/changed_when guards, and test idempotency with Molecule (a second run should report zero changes).
• Secret handling. Secrets embedded in playbooks or variables leak. Use Ansible Vault or an external manager, restrict access, and scan the repo for plaintext secrets.

Recommended Tooling

Ansible with a role-based layout, Ansible Vault or an external secrets manager (Vault), ansible-lint and Molecule for testing, Terraform for provisioning, and CI/CD (GitHub Actions or similar) to run and gate playbooks.

Success Metrics

Track configuration drift, provisioning and configuration lead time, change failure rate for config changes, and idempotency (zero changes on a repeat run).

Prerequisites

SSH access to target hosts, a Python interpreter on managed nodes, a secrets management approach, and a CI/CD system to run playbooks.