Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 29 ยท Projects

Project: Deploy an Application with Rolling Updates

Deploy an application with Ansible using release directories, an atomic symlink swap, a systemd unit template, serial rollout, health checks and automatic rollback.

Copying files over the old version works until the day a deploy fails halfway and the site serves a mix of old and new files. The pattern used by many deployment tools avoids that: every release goes into its own directory, and a current symlink points at the live one. Switching versions is then a single, near-instant change of a link, and rolling back means pointing the link at the previous directory.

In this project you will write a playbook with that structure: a service user and directories, a release unpacked from an artifact, a symlink swap, a systemd unit generated from a template, a rollout that goes through the servers a few at a time, a health check, and a rollback when the check fails. It builds on Project: Provision a Web Server and uses ideas from Handlers, Tags and Task Control and Ansible with Docker, Terraform and CI/CD.

Ansible, systemd and real servers cannot run on this site, so the playbook and unit file are read-only. The runnable examples are JavaScript stand-ins that simulate the release directories, the link swap, the rollback and the cleanup rule. They model the logic, not Ansible.

The directory layout

TEXT
/opt/shop/
  releases/
    20261030T101500/     <- an older release
    20261031T081000/     <- the live release
  shared/
    config.env           <- survives every deploy
  current -> releases/20261031T081000
flowchart LR
  A["Unpack new release<br/>releases/NEW"] --> B["Link shared files<br/>into NEW"]
  B --> C["Swap link<br/>current -> NEW"]
  C --> D["Restart service"]
  D --> E{"Health<br/>check ok?"}
  E -- yes --> F["Prune old releases"]
  E -- no --> G["Link back to previous<br/>and restart"]

The old release stays on disk untouched, which is what makes both the swap and the rollback fast.

The release name is a timestamp (20261031T081000), which sorts correctly as text, so "newest" is easy to compute. Data that must survive deployments, such as the environment file, lives in shared/, not inside a release.

The systemd unit template

A small template creates the service. The variables keep the unit generic; the current path means the unit file itself never changes between releases.

INI
# templates/shop.service.j2
[Unit]
Description=Shop application
After=network.target

[Service]
User={{ app_user }}
WorkingDirectory={{ app_root }}/current
EnvironmentFile={{ app_root }}/shared/config.env
ExecStart={{ app_root }}/current/bin/shop --port {{ app_port }}
Restart=on-failure

[Install]
WantedBy=multi-user.target

The playbook

The first play prepares everything that does not change between releases. The second play does the rolling deployment. Both are in one file, deploy.yml.

YAML
- name: Prepare servers
  hosts: app
  become: true
  vars:
    app_user: shop
    app_root: /opt/shop
    app_port: 8080
  tasks:
    - name: Create the service user
      ansible.builtin.user:
        name: "{{ app_user }}"
        system: true
        shell: /usr/sbin/nologin
        create_home: false

    - name: Create the directories
      ansible.builtin.file:
        path: "{{ item }}"
        state: directory
        owner: "{{ app_user }}"
        group: "{{ app_user }}"
        mode: "0755"
      loop:
        - "{{ app_root }}"
        - "{{ app_root }}/releases"
        - "{{ app_root }}/shared"

    - name: Install the shared environment file
      ansible.builtin.template:
        src: config.env.j2
        dest: "{{ app_root }}/shared/config.env"
        owner: "{{ app_user }}"
        group: "{{ app_user }}"
        mode: "0640"
      notify: restart shop

    - name: Install the systemd unit
      ansible.builtin.template:
        src: shop.service.j2
        dest: /etc/systemd/system/shop.service
        mode: "0644"
      notify:
        - reload systemd
        - restart shop

  handlers:
    - name: reload systemd
      ansible.builtin.systemd:
        daemon_reload: true

    - name: restart shop
      ansible.builtin.systemd:
        name: shop
        state: restarted
        enabled: true

- name: Roll out the release
  hosts: app
  become: true
  serial:
    - 1
    - "50%"
  max_fail_percentage: 0
  vars:
    app_user: shop
    app_root: /opt/shop
    app_port: 8080
  tasks:
    - name: Choose the release name once
      ansible.builtin.set_fact:
        release: "{{ lookup('pipe', 'date -u +%Y%m%dT%H%M%S') }}"
      when: release is not defined

    - name: Remember the release that is live now
      ansible.builtin.stat:
        path: "{{ app_root }}/current"
      register: live

    - name: Deploy and verify
      block:
        - name: Create the release directory
          ansible.builtin.file:
            path: "{{ app_root }}/releases/{{ release }}"
            state: directory
            owner: "{{ app_user }}"
            group: "{{ app_user }}"
            mode: "0755"

        - name: Unpack the artifact
          ansible.builtin.unarchive:
            src: "{{ artifact_url }}"
            dest: "{{ app_root }}/releases/{{ release }}"
            remote_src: true
            owner: "{{ app_user }}"
            group: "{{ app_user }}"
            creates: "{{ app_root }}/releases/{{ release }}/bin/shop"

        - name: Point current at the new release
          ansible.builtin.file:
            src: "{{ app_root }}/releases/{{ release }}"
            dest: "{{ app_root }}/current"
            state: link

        - name: Restart the service
          ansible.builtin.systemd:
            name: shop
            state: restarted

        - name: Wait for the health check
          ansible.builtin.uri:
            url: "http://127.0.0.1:{{ app_port }}/health"
            status_code: 200
          register: health
          until: health.status == 200
          retries: 10
          delay: 3

      rescue:
        - name: Point current back at the previous release
          ansible.builtin.file:
            src: "{{ live.stat.lnk_source }}"
            dest: "{{ app_root }}/current"
            state: link
          when: live.stat.islnk | default(false)

        - name: Restart the previous version
          ansible.builtin.systemd:
            name: shop
            state: restarted
          when: live.stat.islnk | default(false)

        - name: Stop this host's rollout
          ansible.builtin.fail:
            msg: "Release {{ release }} failed its health check; rolled back."

Read the second play from the top and each decision becomes clear.

  • serial and max_fail_percentage. The first batch is a single canary host, then 50 percent of the fleet, then everything that is left. With max_fail_percentage: 0, one failed host stops the entire rollout, so a broken release harms at most one server.
  • The release name is chosen by set_fact, which evaluates the pipe lookup (it runs date on the control node) once and stores the text. Do not put the lookup directly in vars: a play variable is evaluated again each time it is used, so two tasks could see different seconds. Each host picks its own timestamp, which is fine because every host uses its own directory; if you need one name for the whole rollout, pass -e release=... from your pipeline (extra vars win, so the when skips the task).
  • stat records the live release before anything changes. If current is a symlink, live.stat.lnk_source holds its target, which is exactly what the rollback needs.
  • creates: on unarchive makes the unpack idempotent: when the program is already in the release directory, the task is skipped. For code kept in Git, replace the unpack task with ansible.builtin.git (repo, version, dest).
  • block, rescue is the rollback. Any failure inside the block, including a health check that never reaches 200, jumps into rescue, which points the link back and restarts. The final fail task makes the host count as failed, so max_fail_percentage can halt the rollout.
  • The link task has state: link, so it makes current point to the new directory and reports changed only when the target differs.

On the very first deploy there is no previous release, so the rescue tasks are skipped by their when and the host simply stays failed for you to investigate.

Stand-in: release directories, swap and rollback

The model below keeps a list of releases and a current pointer, runs five deployments, makes the last one fail its health check, and keeps only three releases. The failed release stays on disk for debugging, exactly as it would in the real layout.

JS Release directories, symlink swap and rollback

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice that v5 is still in the list after the rollback. That is intentional: you can look at the files that failed. The next successful deploy will prune it.

Cleaning up old releases

Releases take disk space, so a final task removes the oldest ones. It must keep the newest few and never delete the target of current, which after a rollback may be an old release.

YAML
- name: List the releases
  ansible.builtin.find:
    paths: "{{ app_root }}/releases"
    file_type: directory
  register: found

- name: Remove old releases
  ansible.builtin.file:
    path: "{{ item }}"
    state: absent
  loop: "{{ (found.files | map(attribute='path') | sort | reverse | list)[keep_releases:] }}"
  when: item != live_target

Here keep_releases might be 3 and live_target is the path current points at (read it with stat again after the swap). The slice [3:] selects everything except the newest three.

JS Which releases can be pruned?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The "rolled back" line is the case that bites people: the live release is the oldest one, and a naive "delete the oldest" rule would delete the running application.

Running the deployment

Terminal
ansible-playbook -i inventories/production deploy.yml --syntax-check
ansible-playbook -i inventories/production deploy.yml --check --diff
ansible-playbook -i inventories/production deploy.yml -e artifact_url=https://artifacts.example.com/shop-1.8.0.tar.gz

Keep the artifact immutable (one URL per version, never overwritten), and consider a checksum on the download (checksum: "sha256:...") so a corrupted or tampered archive is rejected. A real application also needs database migrations, which are best run once (run_once: true) before the first batch, and only if they are backward compatible with the old version still running on the hosts that have not been updated yet.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why deploy into a new release directory and swap a symlink instead of overwriting files in place?

    The old release is never touched while the new one is unpacked. Switching the link is quick, and so is switching it back.
  2. 2. What happens when a task inside a block fails?

    rescue is the error handler of a block. In this project it points the link back at the previous release and restarts the service.
  3. 3. With serial: [1, "50%"] and max_fail_percentage: 0, what limits the damage of a bad release?

    The canary batch of one host fails first, and a 0 percent failure allowance aborts the play, so the remaining hosts keep the old version.
  4. 4. Why must the prune step never simply delete the oldest release?

    A rollback makes an older release the live one. The prune rule has to exclude the target of the current link, whatever its age.

Summary

  • Release directories plus a current symlink give fast, safe switches and instant rollbacks; data that must persist lives in shared/.
  • A systemd unit template points at current, so the unit does not change between releases.
  • serial batches and max_fail_percentage limit the blast radius; a canary host goes first.
  • block with rescue records the previous release with stat and restores it when the health check fails.
  • creates: keeps unpacking idempotent; prune old releases but never the one current points to.
  • Run migrations once and keep them compatible with both versions during a rolling update.

Next: Project: Security Baseline Role.