FreeIPA automation with ansible-freeipa

How ansible-freeipa deploys and manages FreeIPA as code

If your team has to rebuild FreeIPA repeatably or grow it to more servers, keep the configuration in version control and apply it with Ansible. The ansible-freeipa collection is the documented Ansible collection for this job. Its README lists cluster deployments of server, replica and client roles in one playbook, one-time-password support for client installation and an inventory plugin. DeployOpen plans and runs this work inside your own cloud accounts, data centers or air-gapped networks, so the playbooks, inventories and secrets stay under your control. The collection is community-maintained, and no vendor edition sits behind it, so the support path is your own team, DeployOpen under a written scope, or the project itself.

Before you commit to this approach, confirm the version floor on each side. The README requires Ansible 2.14 or later on the controller and FreeIPA 4.6 or later on managed nodes. Check these against the FreeIPA release you plan to run, since the controller and the nodes do not have to share a version and each has its own upgrade path. Ask the collection's maintainers or read the release notes in the repository before you pin versions, and record the chosen versions in the same repository as the playbooks so a rebuild uses the same combination.

The main design decision is how much of the topology to describe in code. A single playbook can define the first server, its replicas and enrolled clients, but the order of operations matters: the first server must exist before replicas join, and replicas must exist before clients enroll against them. Plan the inventory groups around that order, keep secrets such as admin passwords and enrollment one-time passwords in an encrypted store rather than in plain inventory files, and rehearse a rebuild in a non-production environment. Treat playbook runs as changes to a live identity service, because a mistake in replication or certificate configuration can affect every host that authenticates through it.

What you need before the first playbook run

The ansible-freeipa collection depends on two version floors and on the network services FreeIPA itself relies on. Confirm each item below before you write the first inventory, because a playbook that fails halfway through a server install is harder to recover from than one that never starts.

Controller on Ansible 2.14 or later

The machine that runs ansible-playbook must run Ansible 2.14 or later. Check the version on the controller itself, not on a laptop that merely launches jobs, and pin it in your build image so a later package update does not change behavior. Confirm that the controller can reach every managed node over SSH and that the collection version you install matches the FreeIPA release on your nodes.

Managed nodes on FreeIPA 4.6 or later

Every managed node that the playbook configures must run FreeIPA 4.6 or later. Existing servers on older releases need an upgrade plan before automation touches them, because the collection assumes the server and client behavior of the supported range. Ask your team to list the FreeIPA version on each server and replica from the inventory you plan to use.

DNS names and time sync

FreeIPA depends on forward and reverse DNS resolving correctly for every server and client, and Kerberos fails when clocks drift apart. Confirm that each host's fully qualified name resolves both ways before the run, and that all nodes sync time from the same source. A playbook can create records correctly and still fail authentication if these two basics are wrong.

Dedicated servers and two DNS servers

Plan dedicated hosts for FreeIPA servers rather than sharing them with other applications, since the deployment recommendations advise against co-location. Each client's resolv.conf should list at least two DNS servers so that a single failed resolver does not stop logins. Check these settings in the inventory and in the base image, because the playbook will not correct a client's resolver configuration for you.

Admin passwords kept out of playbooks

Installing and enrolling FreeIPA involves the directory manager and admin passwords, and one-time passwords for client enrollment. Keep these in a vault or secrets manager that the controller reads at run time, and never commit them to the inventory or to a shared repository. Decide before the first run who may retrieve these values, and rotate them after the initial build.

Configuring a FreeIPA cluster with one playbook

This sequence takes a team from an inventory file to a working FreeIPA cluster with replicas, enrolled clients and first identity policies, with a check after each stage so problems surface before the next layer is added. Module names and variable keys should be confirmed against the ansible-freeipa collection documentation for your release.

Prepare the inventory and variables
The platform team defines the FreeIPA server, replica and client groups in the Ansible inventory, sets the realm, domain and DNS settings, and stores passwords and the directory manager credentials in an encrypted vault. Confirm the group names and variable keys against the collection's role documentation, since they differ between releases. Done means ansible-inventory --list shows every host in the expected group, and the vault decrypts on the controller. Controller must run Ansible 2.14 or later, and managed nodes must run FreeIPA 4.6 or later.
Install the ansible-freeipa collection
The operator installs the ansible-freeipa collection on the controller from the Galaxy or source channel your organization approves, pinning the version so the playbook behaves the same on rebuilds. Record the collection version in your repository next to the playbook. Done means the collection lists correctly and a dry-run syntax check passes against the inventory. Confirm the supported platform list for your operating system family before you pin the version.
Deploy the first server
The playbook runs the server role against the first IPA server, which creates the realm, the directory, the Kerberos KDC and the optional DNS and certificate authority services you selected. Run it once against this host only before adding anything else, because the first server holds the initial configuration that replicas copy. Done means ipa server-find returns the server, kinit admin succeeds, and the web UI or API answers on the expected host name.
Add replicas per site
The replica role joins additional servers to the topology, with replicas placed in each datacenter as your deployment recommendations describe. Keep replication agreements within the recommended limit per replica and confirm which replicas run the certificate authority or DNS. Done means ipa-replica-manage list shows the expected agreements, and ipa-replica-manage or ipa-replica-manage list-ruv reports no errors. Check replication again after each host finishes, not only at the end of the run.
Enroll clients
The client role enrolls Linux hosts, using one-time passwords for installation where your process requires it, and configures SSSD on each node. Enrollment should happen after the replicas are stable so clients can reach a nearby server from their resolver list. Done means id returns the expected directory identity for a test account on a sample of hosts, and a test Kerberos login works from one client to another enrolled machine.
Configure users, groups and host access
The playbook creates users, groups and host-based access control rules using the user and HBAC modules, then sudo rules where they apply. Keep the policy in the same repository so changes go through review. Done means a test user in the intended group can log in to an allowed host and is refused on a host outside the rule, and ipa hbactest returns the expected result for both cases. Confirm module names and the exact rule parameters in the collection documentation.
Configure DNS and certificates
The DNS and certificate modules create records, zones and certificate profiles or service certificates that your environment needs, and the playbook records which server owns each function. Verify that clients resolve service names through IPA DNS and that certificate requests complete. Done means ipa dnsrecord-find returns the expected records, a test forward and reverse lookup resolves from a client, and ipa cert-find lists the issued certificate. Confirm the DNS settings against your realm naming plan before you apply them.
Test the full run and repeat it
Run the complete playbook a second time against the same inventory, then compare the output to the first run. A converged deployment reports no unexpected changes, and any change you see points to a setting that is not idempotent or a drift on a host. Keep this run in your change process and rerun it after each inventory change. Done means the second run reports only expected changes and the checks from the earlier steps still pass.

Which roles and modules manage which FreeIPA objects

Server, replica and client roles are the part of the ansible-freeipa collection that builds the topology itself: the first server, the replicas that join it, and the hosts that enroll. The ansible-freeipa README lists deploying server, replicas and clients in one playbook as a supported pattern, but a single playbook that touches every layer is rarely the right boundary for production. Platform engineers should own the server and replica roles, because these changes affect replication, certificate authority duties and DNS for the whole realm.

Topology changes: Adding or removing a replica changes replication agreements, which the deployment recommendations cap at no more than four per replica.
Dedicated servers: Keep server roles on hosts that run nothing else, as the deployment recommendations advise.
Backup coupling: Run backups from the same role set so restore steps match the topology they came from.
Restricted access: Limit who can run the server playbook, since a mistake here can break replication across sites.
Version pinning: Pin the collection and FreeIPA versions on server nodes before any change.

Confirm the exact role and variable names in the collection before writing the playbook, since the module and role set changes between releases.

How playbook state, replication and backups interact

The first thing to design for is that FreeIPA is a multi-master system. Running an ansible-freeipa playbook against one server does not change only that server: user, group, host, policy and certificate data is replicated across the topology. A role that creates a host group, an HBAC rule or a sudo rule on one replica will appear on every other replica, so the inventory should be treated as describing a shared directory, not a set of independent machines. Decide which host the playbook targets for each kind of change, and keep those choices consistent across runs so that operators do not change the same object from two servers at the same time.

The deployment recommendations give the topology limits that the playbook should encode. They advise at least two to three replicas in each datacenter, no more than four replication agreements per replica, and at least one replica per datacenter running PKI or DNS if those services are used. Keep these numbers in the inventory design, not only in documentation, so that a new replica role cannot quietly push a server past the agreement limit. Also confirm, with the current FreeIPA documentation for your version, which server holds certificate renewal and CRL publication, because that role affects where certificate tasks should run and what happens when that server is rebuilt.

Backups belong in the automation design, not in a manual runbook. FreeIPA provides ipa-backup and ipa-restore, with full backups or online data-only backups. The backup documentation warns that restoring an outdated backup into an active replica topology can break replication, so a restore is a topology decision, not a file copy. Plan a schedule that runs on each server, store copies off the host, record which server and time each backup came from, and make restore steps an explicit, approval-gated workflow that stops replicas first. Test the restore path in a lab built from the same playbooks before you need it, and confirm the procedure with your own platform team and the current backup and restore page.

Mapping playbook variables to FreeIPA objects

This table maps each main area of an ansible-freeipa playbook to the FreeIPA objects it creates or changes, the source of truth you should keep for it, and who should approve edits. Use it to decide where a change belongs before you touch a variable file. Confirm exact variable names in the collection documentation for your release.

Playbook area	FreeIPA objects it manages	Source of truth	Who approves changes
Inventory groups	Server, replica and client roles on each host, including which hosts run the first server and which join as replicas	Inventory file under version control, mirrored by the host records in your own asset system	Platform engineering lead, with the identity owner for any change to server or replica roles
Variable files for users and groups	User accounts, groups and group membership in the IdM directory	HR or identity system export, with the variable file as the reviewed copy in Git	Identity administrator, with HR confirmation for joiner, mover and leaver changes
Policy definitions for HBAC	Host-based access control rules that decide which users and groups may log in to which hosts and services	Access matrix maintained by the system owner, stored as variables in Git	Application or system owner for each host group, with security review for broad rules
Policy definitions for sudo	Sudo rules that map groups to allowed commands on hosts or host groups	Written privilege catalogue per host group, kept with the playbook	Security team for privileged commands, with the system owner for scope
Zone definitions for DNS	DNS zones and records managed by IdM DNS, including service records used for discovery	Zone file or IPAM inventory kept in Git, with records generated from it	Network or DNS owner, with a second reviewer for changes to zones used by clients
OTP settings and enrolled tokens	OTP token configuration and the enrollment steps for client installation with one-time passwords	Token register and enrollment record kept by the identity team, not in plain-text variables	Identity administrator, with the user's manager or service desk confirming enrollment
Secrets and vault values	Passwords, one-time passwords and keytab material passed to roles at run time	Secrets manager or Ansible Vault, never plain variable files	Security owner, with access limited to the people who run the playbook

Securing the automation pipeline and the managed servers

A playbook that can create admins, enroll hosts and change policy has the reach of a privileged administrator. The controls below limit who and what can run it, how its secrets are stored, and which FreeIPA release it targets. Treat the controller, the repository and the FreeIPA servers as one trust chain.

Vault-encrypted admin and enrollment secrets

Keep the FreeIPA admin password, replica credentials and client enrollment secrets in Ansible Vault or an external secret store, never in inventory files or plain variables. Restrict who holds the vault password and rotate it when a team member leaves. Confirm that CI logs do not echo variables that contain these values, since a single leaked log line can expose an administrative credential.

One-time enrollment secrets handled as credentials

OTP-based client enrollment is supported by the collection, and the one-time password works as a bearer credential until it is used or expires. Generate it just before the enrollment run, pass it through the vault, and avoid storing it in build artifacts or tickets. Check in FreeIPA that each enrolled host consumed its password, and revoke any that were generated for hosts that were never built.

Least-privilege controller access

Run the playbook from a dedicated controller host with restricted network access to the FreeIPA servers, and limit the SSH or API identity used for runs to what each playbook needs. Prefer role-scoped FreeIPA accounts over the admin account where the module allows it, and review sudo rights on the controller. Confirm that the controller itself is patched and that its access logs are retained.

Separate pipeline identities per environment

Use distinct controller credentials, vault passwords and FreeIPA identities for lab, staging and production realms, so a test run cannot modify production users or policies. Keep the inventory for each environment in its own repository path and require a different approval to target production. Verify that a staging token cannot reach production replica hostnames.

Reviewed playbook changes before replicas

Require peer review for every change to roles that touch users, HBAC, sudo, certificates or DNS, and run them with check mode and a diff before they reach production replicas. Because replicas replicate changes, a wrong group or HBAC rule spreads across the topology quickly. Record who approved each run so the change history can be matched against FreeIPA audit logs.

Current 4.x releases for the controlled nodes

Keep FreeIPA servers on a supported 4.x release that includes the security fixes. The 4.13.4 release notes describe fixes for LDAP access control flaws that could let unauthenticated clients obtain credentials, along with hardened authentication checks. Confirm the installed release on every replica before each playbook run, and plan the upgrade ahead of automation changes that depend on newer modules.

Common failures when running ansible-freeipa

This table lists the failures most likely to stop an ansible-freeipa run, with the cause, a check to run before retrying, and the fix. Work through the rows in order, since the controller and node version checks come first and the DNS and time checks prevent confusing errors later. The main takeaway is that most failed runs trace back to environment prerequisites rather than to the playbook itself.

Failure	Likely cause	Check and fix
Controller below Ansible 2.14	The control node runs an older Ansible release than the collection requires.	Run ansible --version on the controller. Upgrade Ansible to 2.14 or later, then rerun the playbook.
Managed node below FreeIPA 4.6	A server or client runs an IPA release older than the minimum the collection supports.	Check the installed FreeIPA package version on each managed node. Upgrade the node or pin the playbook to nodes that meet the minimum.
DNS does not resolve the server	Clients or replicas cannot resolve the IdM server's fully qualified name, so enrollment and discovery fail.	Query the server name from each node with the system resolver. Confirm forward and reverse records and that at least two DNS servers appear in resolv.conf, per the deployment recommendations.
Time skew breaks Kerberos	Clock drift between controller, servers and clients exceeds what Kerberos tolerates, so ticket requests are rejected.	Compare the output of timedatectl on each host and confirm NTP sync is active. Fix time synchronization before rerunning the role.
Replica enrollment fails on agreement limits	The target topology would give a replica more than four replication agreements, the limit in the deployment recommendations.	Review the existing topology with the replication tooling before adding the replica. Add a replica elsewhere or remove an unneeded agreement, then rerun.
Playbook conflicts with manual changes	Settings changed by hand in the web UI or CLI differ from the variables in the playbook, so reruns overwrite or fail on them.	Export current objects and compare with the playbook variables. Move manual changes into the playbook or revert them, and keep one source of truth for each object.

Questions teams ask before automating FreeIPA

What drives the effort and cost of building FreeIPA playbooks?

The size of the playbook work follows from the topology and the number of configuration areas you want code to own. A single server with a few clients is a much smaller job than a multi-site cluster with replicas, client enrollment, backups and DNS settings all driven from one inventory. Other drivers are the number of distinct environments (lab, staging, production), how many existing settings must be captured from a running deployment, and how much of your access policy, sudo and HBAC rules, and certificate handling you want in code. Costs have two parts: one-time design and build, and ongoing changes as your policies evolve. When you request a quote, ask for the list of roles and modules in scope, the environments covered, who writes and who reviews the playbooks, and what testing against a non-production topology is included.

Can our team automate FreeIPA without a partner?

Yes, if your team already runs Ansible and understands FreeIPA's server, replica and client roles. The ansible-freeipa collection is open source under the project's own terms, and the README describes cluster deployment of servers, replicas and clients in one playbook, plus one-time-password client enrollment and an inventory plugin. The harder parts are ordering (a first server must exist before replicas join), safe handling of secrets, and testing changes against a topology that resembles production. Ask yourself whether you have engineers who can read FreeIPA's replication and certificate behavior, and whether someone can own the playbooks after handover. A partner is most useful when the team is short on that depth or needs the work done on a fixed timeline.

How long does a first cluster build take with ansible-freeipa?

Duration depends on topology more than on the playbook syntax. A single server with clients has fewer moving parts than a deployment with several replicas across sites, where replication agreements, DNS placement and certificate authority roles must be planned together. FreeIPA's deployment recommendations suggest at least two to three replicas in each datacenter and no more than four replication agreements per replica, so the count of servers and their links shapes the sequence of runs. The build also depends on how quickly your network, DNS, certificates and change approvals are ready. No duration is given here because none was supplied for this topic. Ask any provider for a milestone plan that names each topology stage, the test runs before production, and the dependencies that could move the schedule.

What does the work need from our side before it starts?

The work needs access and decisions that only your organization can provide. Typically this includes:

Lab and production environments with network paths, load balancers and firewall rules documented for each site.
Accounts for the controller, managed nodes, the source repository and secrets storage, with least privilege for the people running playbooks.
DNS ownership and zone plans, since FreeIPA's recommendations call for at least two DNS servers in each client's resolv.conf.
Agreed change windows for first runs on production servers, and a named approver for each topology change.
Decisions on where the first server and certificate authority roles live.

Ask the provider which of these they need in writing, and which they expect you to supply before the first workshop.

How do FreeIPA upgrades interact with ansible-freeipa playbooks?

Playbooks describe a desired state, so an upgrade of FreeIPA itself is a separate change that must be tested against the playbooks. The collection's README requires Ansible 2.14 or later on the controller and FreeIPA 4.6 or later on managed nodes, so the controller version, the collection version and the target FreeIPA release must be checked together before any upgrade. Newer FreeIPA releases change behavior: for example, 4.13.0 introduced an early web UI beta and random certificate serial numbers by default, and 4.13.4 fixed security issues, so a playbook that passed on an older release may need review. Ask any provider how they pin versions, how they test an upgrade in a copy of your topology, and how they handle a security release that must land quickly.

Is the ansible-freeipa collection supported by a vendor?

The collection is a community open-source project hosted at freeipa/ansible-freeipa on GitHub, and FreeIPA itself is a community project with no paid edition of its own. Support therefore comes from the project's public channels, from your own engineers, or from a commercial provider you contract with. DeployOpen plans, implements, documents and supports self-hosted open-source platforms in your infrastructure, and ongoing support is available as a retainer. Ask any provider which parts of the playbooks they will support after handover, what response expectations apply in writing, and whether they will track upstream changes to the collection and FreeIPA releases. Nothing in this answer should be read as a vendor warranty for the collection.

Should backups and recovery be part of the playbook design?

Yes, because backup and restore steps change how a topology can be rebuilt. FreeIPA provides ipa-backup and ipa-restore with full or online data-only options. The backup documentation warns that the first server handles certificate renewal and CRL publication by default, and that restoring an outdated backup into an active replica topology can break replication. A playbook can schedule backups and document restore order, but it must not blindly reapply an old state onto live replicas. Ask a provider how they test restores in a non-production topology, where backup files are stored and encrypted, and who approves a restore on production.

How DeployOpen scopes and delivers FreeIPA automation

DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, including FreeIPA. For ansible-freeipa automation, we agree the playbook structure, the target topology and the handover in writing before the build starts, so the code you receive matches the environment it will run in.

How we scope

The written scope lists which server, replica and client roles the playbooks will manage in your environment.
It names the ansible-freeipa modules in use, such as users, HBAC, sudo, DNS and certificates, and which ones stay manual.
It confirms controller and managed node versions against the Ansible 2.14 and FreeIPA 4.6 requirements before work starts.

How we build

We write inventories, roles and playbooks in your own version control, with variables separated from secrets.
We test runs against a non-production FreeIPA topology that mirrors your replica layout before anything reaches production.
We design the backup and restore steps, including how playbooks avoid restoring an outdated backup into an active replica topology.

How we hand over

You receive the playbooks, a runbook for re-running them, and notes on which tasks must not run twice.
Documentation covers OTP client enrollment, smart card setup and any manual steps that remain outside the playbooks.
Your team runs a walkthrough and a restore test so that operators can repeat the procedures without us.

How we support

Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
Ongoing support, upgrades and continuous testing of the automation are available as a retainer.
Ask any quote to state which collection versions, FreeIPA releases and controller changes are included and excluded.