Why FreeIPA container upgrades need a plan before production
If you run or plan to run FreeIPA servers as containers, you need an upgrade plan from day one, not after the first production incident. The freeipa-container README warns that teams who skip this step end up with an end-of-life cluster carrying known security issues three years later. The plan comes before the first production deployment, because it decides which image tags you run, how you test rebuilds, and who approves a change. Start with the freeipa/freeipa-container README and the repository it lives in, then write the plan around your own environment.
FreeIPA server images are rebuilt regularly and published with tags that match their base operating system. Keeping current therefore means choosing the tag that matches your OS, pulling rebuilds as they appear, and testing each one before it reaches a production replica. The README also suggests copying images into your own registry namespace, which gives you control over when a rebuild enters your environment. Confirm with the project which tags are currently maintained for your base OS and how long each one receives rebuilds, because that window sets how often you must move.
A container image does not change what a FreeIPA upgrade can do. The supported path between FreeIPA releases still governs, including replica order, maintenance windows and checks after each server. A new image on a single container does not replace a planned topology change. This page covers the container-specific decisions, while the replicated-topology update guide and the operating system upgrade guides cover the server-side steps that apply regardless of how FreeIPA is packaged. Read those before you change a production tag.
What recent FreeIPA 4.13 releases change for existing deployments
This table maps each change in the FreeIPA 4.13.0 and 4.13.4 releases to what an existing containerized server must verify or update. Read it as a checklist: confirm the image version first, then review each row against your DNS clients, certificate workflows and maintenance schedule. The main takeaway is that the 4.13.4 security update is the change that most needs a dated action.
| Change | Impact on a container deployment | Action needed |
|---|---|---|
| Web UI beta (4.13.0) | The new web interface ships as a first beta, so existing administrators may see a different console after an image change. | Confirm the image tag, decide whether staff may use the beta, and keep the existing UI path documented for administrators. |
| DNS over TLS between clients and IdM DNS servers (4.13.0) | Clients that query IdM DNS can use encrypted transport, which depends on client and server configuration and container network rules. | Review resolver settings on enrolled clients, confirm at least two DNS servers in each client's resolver configuration, and check that the container's port exposure matches the design. |
| LDAP system accounts (4.13.0) | Service accounts used by applications and integrations are handled differently, so existing bind credentials and their references may need review. | Inventory every application that binds to the directory, confirm each bind account still works after the image change, and record the account owners. |
| ipa-idrange-fix tool (4.13.0) | Provides a repair path for ID range problems. It changes directory data, so it should not run as a routine step. | Run it only when a documented ID range issue exists, take a backup first, and run it inside the maintenance window on the correct server. |
| Random certificate serial numbers by default (4.13.0) | New certificates get random serial numbers. Tools or audit processes that assumed sequential serials may report differences. | Check whether any internal process, report or CA-related script depends on serial order, and update it before the change reaches production. |
| Security fixes for two CVEs, including LDAP access control flaws (4.13.4) | The release fixes LDAP access control flaws that could let unauthenticated clients obtain credentials, which makes this update time-sensitive. | Schedule the 4.13.4 image update as a priority, confirm the running version on every container, and record the date each server was updated. |
| Hardened authentication checks across the API (4.13.4) | API authentication checks are stricter, so scripts or automation that call the API may fail after the update. | Test every API client, playbook and monitoring check in staging against the 4.13.4 image before rolling it to production. |
| Image tag to FreeIPA version mapping | Image tags follow the base operating system, so the tag alone does not show the FreeIPA version in use. | Confirm with the release notes which image tag carries which FreeIPA version, and record that mapping in your own registry. |
What to back up and inventory before pulling a new image
A container image change replaces the software around your FreeIPA data but not the data itself, so the work before it is about being able to return to a known state. The cards below cover the backup, the local configuration, the image record, the staging copy and the dependencies that a rollback or a failed start will depend on.
A verified ipa-backup on the first server
Take an ipa-backup on the first server, the one that handles certificate renewal and CRL publication by default, and confirm it completes and can be read back. Record when it was taken relative to the planned change. The backup guide warns that restoring an outdated backup into an active replica topology can break replication, so confirm the backup timing and restore procedure with the backup guide before the window opens. Keep a copy outside the container host.
Inventory of local customizations
List every volume mount, environment variable, custom script, wrapper unit and sidecar attached to the FreeIPA container. Container images are rebuilt often, so a mount path or variable that worked on the old tag can behave differently after the change. Store the inventory in version control next to the deployment definition so that a reviewer can compare it with the new run command and spot anything dropped or renamed.
Current image tag and digest
Record the exact image tag and the immutable digest of the running server container, along with the base operating system the tag matches. Tags move when images are rebuilt, so the tag alone does not identify what is running. The digest is the reference you will return to if the new image fails. Also record the image source you pull from, whether quay.io, docker.io or your own registry namespace.
Staging copy of topology and data
Build a staging environment that mirrors production: the same number of servers, the same replica roles, a recent backup restored into it and the same client enrollment pattern. Run the new image there first and test authentication, certificate issuance and replication before any production server changes. Staging is only useful if its data is recent enough to reflect production, so record the backup date used for the test.
Client and integration dependencies
List what depends on the server: the DNS server addresses in client resolver configuration, Kerberos realm settings, cross-forest trusts, OTP or RADIUS proxy targets, Samba file servers, automation that calls the API and monitoring checks. Each item is a place where a new image could behave differently. Confirm with the owner of each dependency what they need to see during the change and how they will report a failure.
Which image sourcing model fits your environment
Pulling the project's published images directly means your deployment references the images the FreeIPA container project publishes to quay.io/freeipa/freeipa-server or docker.io/freeipa/freeipa-server. The project rebuilds these images regularly and tags them to match the base operating system, so the tag you choose determines which OS line you follow. Update timing is set by the project's rebuild schedule and by whenever your team decides to pull, which means the change window is effectively yours but the content is not.
- Update timing: Your team chooses when to pull, but new contents arrive on the project's rebuild cadence, not yours.
- Scanning and approval: You still need to scan each pulled image and approve it before it reaches a replica, because the project's build is not your build.
- Rebuild and retention: Keep a record of which image digest each server runs so you can roll back to a known image.
- Drift risk: A floating tag can change under you between pulls, so servers in one topology may end up on different builds.
- Dependency on the registry: Confirm with your team how pulls are reached from air-gapped or restricted networks before you depend on this path.
Before relying on this model, confirm which tags your OS line uses and how your team will detect a changed image.
The freeipa-container README suggests tagging the published images into your own namespace for stricter control. In this model your team copies a reviewed image into a registry you run or administer, then points every FreeIPA server at that copy. The project's build still supplies the contents, but the decision about which copy runs, and when it changes, moves to your change process. The README states this as a suggestion, so confirm with your registry vendor what access, retention and scanning features are available before you design around them.
- Update timing: Your team decides when a new project image is promoted into your namespace and when servers move to it.
- Scanning and approval: Scan and approve the image once in your namespace, then reuse the approved artifact across all replicas.
- Rebuild and retention: Set how long older approved images stay available so that a rollback target always exists.
- Pinning: Reference a tag for readability and a digest for certainty, and record both in your change tickets.
- Drift risk: Drift shrinks because every server pulls the same approved artifact, but a stale mirror can leave you on an older build with known issues.
Ask your team who owns promotion, how often the mirror is checked for new project builds, and how a security fix gets from the project into your namespace.
Building your own image from the project's container sources gives you the most control over the image contents, and the most responsibility for them. Your team starts from the freeipa-container repository, builds an image on your own base and pipeline, and publishes it to your registry. This model suits organizations that must control every layer, but it moves the work of tracking upstream fixes, rebuilding after base image updates and testing the result onto your team. Confirm the build steps and supported base operating systems in the repository's documentation before you commit to this path.
- Update timing: Your build pipeline sets the schedule, and you must watch upstream changes yourself to know when a rebuild is needed.
- Scanning and approval: Your team scans the base image, packages and the FreeIPA layers, and approves the build as a new artifact.
- Rebuild and retention: Plan recurring rebuilds for base image and package updates, and keep build inputs versioned so any image can be reproduced.
- Drift risk: Your image can diverge from the published image through local edits, different base contents or delayed rebuilds, and that divergence must be documented.
- Ownership cost: Staff time for builds, tests and upstream tracking recurs for as long as you run this model.
Before choosing this model, ask who will own rebuilds, how upstream security fixes will reach your build within your change window, and how you will prove the image matches its inputs.
Upgrade sequence with checks and rollback points
This sequence moves a containerized FreeIPA topology to a new image tag one server at a time, with a named check and a rollback point at every stage so that a failed step never leaves the whole identity service without a working server.
Confirm the upgrade plan and target image
Before any change, the platform owner and the FreeIPA administrator confirm the written upgrade plan the project asks for, record the target image tag and its base operating system, and check the release notes for the version in that tag. The check is a signed-off change record that names the target tag, the replica order, the maintenance window and the owner of each rollback decision. Ask the vendor or project for any version-specific upgrade notes before accepting the target, because the README's guidance is to plan the upgrade before production use rather than after problems appear.
Back up the first server and record the current image
Take a full FreeIPA backup on the server that handles certificate renewal and CRL publication, which the backup documentation says is the first server by default, and store it outside the container host. Record the exact image digest and tag running on every server, along with the replication status output. The check is a backup you have confirmed is readable, plus a written inventory of current images. This is the first rollback point: if anything later fails, the previous image and this backup are what you return to, and you must not restore an older backup into an active replica topology without a replication review.
Rehearse the change in staging
Build a staging topology that mirrors production replica count, DNS roles, CA roles and client types, then run the same image change there in the same order. Confirm the container runtime commands for pulling, stopping, starting and reporting on the FreeIPA container against the freeipa-container README, since the exact invocation depends on your runtime and host layout. The check is a rehearsal log showing replication stays healthy, the CA and DNS services answer, and a test client can authenticate at every stage. Use the rehearsal to time your own steps, because no duration should be assumed in advance.
Update one replica in production with health checks
Change the image on a single production replica during a maintenance window, with the rest of the topology still on the previous image. Once the container is back, check that the directory service starts, replication agreements show no errors, Kerberos answers token requests, and the certificate authority and DNS services respond if this replica runs them. The check is a clean health report for that server before you move to the next. If a check fails, stop the change, return that replica to the recorded previous image, and confirm replication recovers before doing anything else.
Confirm DNS and client behavior after each server
After each replica is updated, verify name resolution against it, confirm that clients listed with at least two DNS servers in resolv.conf still resolve and authenticate, and test a Kerberos login and an SSSD lookup from a representative client in each site. The check is a short test script whose results match the pre-change baseline. Watch for clients that reach only the server you just changed, because a failure there will look like a client problem rather than a server one. Keep the previous image on the host until this check has passed on every server.
Repeat the sequence across remaining servers
Work through the remaining replicas one at a time in the replica order from your plan, running the health and client checks after each. Hold the change if replication shows errors, if a certificate or CRL task has not completed, or if a client test fails, and resolve the cause before continuing. The check is that every server reports the target image and passes the same checks as the first one. Keep each replica's previous image available for the whole run, since a later failure may need you to roll back a server that already passed.
Promote the image tag only after checks pass
Once the full topology is confirmed healthy and clients have been tested across sites, update your internal image reference or tag so that new deployments pull the tested image. Do not remove the previous image from your own registry or host until the topology has stayed healthy through a defined observation period agreed in your plan. The check is a record showing the promoted tag, the digest, the completion time and the sign-off from the platform and identity owners. This final rollback point keeps the earlier image available until you are confident the new one is stable.
How to test a container upgrade and roll it back safely
Staged testing has one job: prove that a new FreeIPA server image keeps every service that depends on the directory working before any production replica runs it. Build a test topology that mirrors production, with at least two replicas, the same CA and DNS roles, and clients enrolled the way your fleet is enrolled. Then check authentication from both sides. Kerberos logins should succeed for password and OTP users, kinit should work from representative Linux clients, and LDAP binds from applications should return the expected entries. Confirm that certificate issuance and renewal behave as they did before, including the server that holds the CA renewal and CRL roles. Verify DNS resolution from clients against each DNS server in their resolv.conf, and confirm replication health with replica status checks after every container restart. If you use AD trusts, OTP proxying to RADIUS or other integrations, test those flows explicitly, because they rarely appear in a simple login test.
Rollback is a decision you make before the change, not during an incident. Record the image digest or tag currently running on each replica, keep that image in your own registry so it can be pulled after upstream rebuilds, and write down the order in which replicas will be returned to service. Take a full backup with ipa-backup and confirm it restores into a lab topology, because an untested backup is not a recovery plan. The backup documentation warns that restoring an outdated backup into an active replica topology can break replication, so decide in advance which backup you would use and who approves restoring it. Package-based FreeIPA updates cannot be downgraded, so the pinned image and verified backup are your recovery path. Confirm the container-specific rollback steps with the freeipa-container README and the FreeIPA backup and restore guide before you rely on them.
What makes a FreeIPA container upgrade take longer
This table compares the factors that expand or shrink the work of upgrading containerized FreeIPA servers, from topology and customization to integrations and approval steps. Read each row as a question to answer about your own environment before you set a schedule. The main takeaway is that the number of servers and the local changes inside them usually matter more than the image itself.
| Driver | Why it matters | Effect on the work |
|---|---|---|
| Replicas per datacenter | The recommended two to three replicas per datacenter means each site has several servers that must be upgraded and checked in sequence. | More replicas mean more rounds of image replacement, health checks and replication verification before the next server can move. |
| Replication agreements | The recommendations cap each replica at four replication agreements, so the topology is a set of links you must map before changing any node. | A dense mesh of agreements makes it harder to confirm that every server has replicated cleanly before the next step begins. |
| First server also runs PKI or DNS | The backup documentation notes that the first server handles certificate renewal and CRL publication by default. | Upgrading that server needs extra care with the CA and DNS roles, and the team should confirm which server holds each role before starting. |
| Local customizations inside containers | Changes made inside a running container can be lost when the image is replaced, and they may conflict with a new base image. | Each customization needs to be documented, rebuilt into your own image or moved to mounted configuration, and retested. |
| Directory size and backup volume | Larger directories take longer to back up and restore, and a backup taken before the upgrade is the main rollback path. | Larger data sets lengthen the pre-upgrade backup and the restore rehearsal, and they widen the window for change during the upgrade. |
| Number of clients and resolv.conf dependencies | Enrolled clients and their DNS settings depend on the IPA servers being reachable, and the recommendations call for at least two DNS servers in each resolv.conf. | Wide client populations and hard-coded DNS entries require planned checks so that an upgraded server does not break logins elsewhere. |
| Integrations with Keycloak, Samba or AD trusts | External identity providers, file servers and cross-forest trusts rely on IPA services and their configuration staying stable. | Each integration adds test cases after the upgrade and may require coordination with the teams that own those systems. |
| Depth of the staging environment | A staging topology that mirrors production replicas, DNS roles and integrations gives evidence that the upgrade plan works. | A shallow staging environment shifts discovery of problems into production, while a close copy lengthens preparation but reduces surprises. |
| Number of registries and approval gates | Pulling images through your own registry and approval steps adds controls such as image copying, scanning and sign-off. | Each registry hop and approval gate adds lead time to every upgrade cycle, so confirm the approval path before the window is set. |
What buyers ask before hiring help with a FreeIPA container upgrade
What drives the cost of a FreeIPA container upgrade?
The biggest cost driver is how many FreeIPA servers are in the topology, how many sites they span, and how much of the work must happen inside change windows. Each server needs preparation, the image change, validation and a rollback plan, so the work scales with the number of servers and the testing around them. You pay for planning and test work, for hands-on execution, and for the post-upgrade checks. Ask any provider to price each of these separately in the written scope, and ask which parts are one-time and which recur if you later want ongoing support.
Can our own team upgrade FreeIPA containers without outside help?
Yes, a team with container, Linux and identity experience can do it, provided it reads the project's upgrade guidance and tests the change before production. The risks are less about the command sequence and more about replication health, certificate roles on the first server, and backups taken before the change. If your staff has not run an identity service in production before, outside help is most useful for the plan, the test run and the first production pass. Your team can then take over the repeatable steps.
How long does a FreeIPA container upgrade usually take?
Duration depends on the number of replicas, how many are in each datacenter, how much maintenance time you can book, and how long your staging tests take. Test coverage of your own clients and applications often takes longer than the server work itself. No standard duration is set here, so ask for a timeline in the written scope that shows each stage. For spacing and order between servers, use the replicated-topology update guide on the FreeIPA project site as the reference for timing questions.
What do we need to provide for the upgrade work?
You need administrative access to the container hosts and the FreeIPA topology, a registry or namespace where you will pin images, and a documented list of clients and integrations that must keep working. You also need approved change windows and a recent, restorable backup of each server. Test data helps: a staging copy of the directory, sample user logins and sample certificate requests let you confirm behavior before production. Name a contact who can approve each maintenance window.
How do written scope, fixed fee and quotes work for this engagement?
Most DeployOpen engagements are fixed-scope, so the scope, deliverables and timelines are agreed in writing before work starts. A quote follows from that written scope rather than from a published price list. A good scope lists the servers and images in play, the staging environment, the test cases, the change windows, the rollback steps and the evidence you will receive. Ask what is excluded, such as application changes on your clients, and what triggers a change request during the work.
What happens if the upgrade fails partway through?
A safe plan defines the stopping point and the rollback path before the first server changes. Because FreeIPA replicas depend on each other, a failed step on one server should halt the sequence until replication and services are verified. Restoring from a backup taken before the change is the usual recovery route, and the backup documentation warns that restoring an outdated backup into an active replica topology can break replication, so restores need a planned procedure. Ask the provider to describe who makes the stop decision, how the incident is recorded, and how the next attempt is rescheduled.
Which image tags and registry setup should we confirm before the upgrade?
Confirm which base operating system your FreeIPA server image is built on, because the project publishes server images with tags that match that base system. Confirm whether your team will copy the chosen image into your own registry namespace so that you control which build reaches production. Check the project's README for the current tag list and rebuild schedule before you pin a version. Record the exact image digest you tested so the production server runs the same build.
Does a container upgrade affect certificates and compliance evidence?
It can, because the first server normally handles certificate renewal and CRL publication, and the upgrade changes which server runs these roles. Confirm the renewal and CRL roles before and after the change, and keep the test results and change records as operational evidence. DeployOpen prepares systems, controls and evidence for compliance assessments, but it does not issue audit reports or certifications, so independent auditors and certification bodies remain responsible for those decisions.
How DeployOpen scopes, delivers and supports the upgrade
DeployOpen plans, builds, tests and documents FreeIPA server container upgrades inside infrastructure you control. We start from a written scope and an upgrade plan that fits your topology, then move images through staged environments before anything reaches production.
How we scope
- Inventory every FreeIPA server container, its base OS tag, image source and replica role in each site.
- Record which servers run the CA renewal and CRL roles, DNS and NTP, and how clients reach them.
- Agree the target image tags, registry namespace, rebuild cadence and test environments in writing before work starts.
How we build
- Mirror approved FreeIPA server images into your own registry under a namespace you control, with pinned digests.
- Rehearse the upgrade in a staging topology restored from a recent backup, then run checks after each server.
- Document rollback limits, replica order and maintenance windows so your team can repeat the procedure.
How we hand over
- Deliver the upgrade plan, runbooks, registry configuration and test results as written deliverables.
- Walk your operations team through the procedure and the post-upgrade health checks on your own servers.
- Confirm with your team which tasks stay internal and which need a retainer or a new scoped engagement.
How we support
- Engagements are fixed-scope, and ongoing support, upgrades and continuous testing are available as retainers.
- Retainers can cover scheduled image rebuilds, staged rollouts of new tags and periodic review of the upgrade plan.
- Confirm response expectations, change windows and escalation contacts in the written agreement before go-live.
