Ending a batch or a play deliberately · Ansible

The failure keywords stop a run when Ansible notices something wrong. Sometimes you notice something wrong — a precondition that is not met, a state that means proceeding is pointless, a maintenance window that has closed — and there is no failure for a keyword to react to.

ansible.builtin.meta provides four verbs for stopping on purpose, each with a different reach.

Verb	Stops	Everything else
`end_host`	this host, for the rest of the play	continues
`end_batch`	the current batch	later batches still run
`end_play`	the whole play, all batches	later plays still run
`end_role`	the current role	the rest of the play continues

end_batch and end_role are the two that need a version note: end_batch requires ansible-core 2.12 or later, and end_role 2.18 or later. This course targets 2.21, so both are available.

The reach of each verb, observed

One playbook, six hosts, serial: 2, with the stop conditioned on h03 — which is the first host of the second batch. Only the verb changes.

Read-only / Safethe test— Local connections and debug tasks only; nothing is changed. The AFTER task reports which hosts got past the stop.

- name: Which hosts survive the stop
hosts: batchlab
gather_facts: false
serial: 2
tasks:
  - name: Stop deliberately
    ansible.builtin.meta: end_batch
    when: inventory_hostname == 'h03'

  - name: After
    ansible.builtin.debug:
      msg: 'AFTER {{ inventory_hostname }}'

Read-only / Safeexecuted on ansible-core 2.21.3— The hosts that reached the AFTER task, for each verb. Batches are h01+h02, h03+h04, h05+h06.

$ ansible-playbook -i inv6.ini meta.yml

meta: end_batch   AFTER reached by:  h01 h02        h05 h06
meta: end_play    AFTER reached by:  h01 h02
meta: end_host    AFTER reached by:  h01 h02    h04 h05 h06

Read each line against the batch boundaries:

end_batch ended batch two. h04 — the innocent batch-mate — was stopped as well, and then batch three ran normally. This is the verb whose name is most likely to mislead: it does not stop the rollout, it skips the rest of this batch and carries on.

end_play ended everything. h04 stopped, and batches three onwards never ran at all.

end_host stopped only h03. h04 continued to the end of the play, and every later batch ran. This is the surgical one.

end_batch does not stop a rollout

If your intent is “something is wrong, stop deploying”, end_batch is the wrong verb. It abandons the current batch and proceeds to the next one, which on a rolling deploy means moving on to fresh hosts having just decided that the change is unsafe.

The verb is for the case where the current batch has nothing further worth doing — every host in it was already at the target version, say — and the run should move on. That is a genuine case, and it is not the one people reach for the verb to express.

For “stop deploying”, use end_play.

There is one more edge worth knowing, and the module documentation states it directly: with serial set to 0 or left undefined, end_batch “behaves the same as end_play”. So the same task changes meaning depending on whether the play is batched — harmless while the play has a serial, and a silent widening the day somebody removes it.

Where each one belongs

end_host — this host is not a candidate.

The common case: a host that does not need the change, or cannot take it, and where that is a normal condition rather than an error.

Read-only / Safeskipping a host that is already at the target version— Read-only up to the meta task. Hosts already running the target version leave the play cleanly instead of running every subsequent task with a when: clause.

    - name: Read the currently deployed version
    ansible.builtin.slurp:
      src: /etc/app/deployed-version
    register: deployed
    failed_when: false

  - name: Nothing to do on this host
    ansible.builtin.debug:
      msg: 'Already at {{ release_version }}, leaving the play'
    when: (deployed.content | default('') | b64decode | trim) == release_version

  - name: Leave the play for hosts already at the target version
    ansible.builtin.meta: end_host
    when: (deployed.content | default('') | b64decode | trim) == release_version

The alternative — putting the same when: on all fifteen subsequent tasks — is what end_host exists to replace. It is also strictly worse, because the fifteenth when: is the one somebody will forget.

end_play — the run should not continue.

A precondition that applies to the whole change. The maintenance window closed. A dependency is unavailable. A canary batch reported something that means the remaining batches must not proceed.

Read-only / Safestopping the rollout when the window closes— Read-only. Placed at the top of a batched play, this is evaluated once per batch, so a long rollout stops at the first batch boundary after the window ends.

    - name: Stop the rollout if the maintenance window has closed
    ansible.builtin.debug:
      msg: >-
        Maintenance window closed at {{ window_end }}. Stopping before
        batch {{ ansible_play_batch | join(', ') }}. Hosts not yet
        deployed remain on the previous version.
    run_once: true
    when: (ansible_date_time.iso8601 > window_end) | default(false)

  - name: End the play at the window boundary
    ansible.builtin.meta: end_play
    when: (ansible_date_time.iso8601 > window_end) | default(false)

Because a batched play re-executes per batch, a check like this at the top of the task list runs before every batch — so it stops the rollout at a batch boundary rather than mid-batch, which is the cheap place to stop.

ansible_date_time comes from fact gathering, so this needs gather_facts: true or an explicit setup task.

end_role — this role has nothing further to do.

Available from 2.18. It ends the current role for the host and continues with the rest of the play. Useful in a role that establishes early that it is not applicable, without the role having to guard every task.

The problem with all of them

A play ended with meta is a successful run.

Read-only / Safethe exit code of a deliberate stop— Executed on 2.21.3. The play stopped at h03 and never touched h05 or h06. Exit code 0, and the recap shows no failures.

$ ansible-playbook -i inv6.ini endplay.yml; echo EXIT=$?

PLAY RECAP *********************************************************************
h01                        : ok=1    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
h02                        : ok=1    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

EXIT=0

Nothing in that output says the rollout stopped early. failed=0, exit 0, and four of the six hosts have no recap line at all — not even h03, the host that triggered the stop, or h04 beside it. The recap reports hosts that completed work, so a run that stopped after batch one is textually identical to a successful run against a two-host fleet.

A deliberate stop is indistinguishable from a completed run

This is the trap the curriculum names as “the difference between a deliberate stop and a silent one”.

A scheduler that runs your rollout nightly and checks the exit code will record a success. A CI pipeline will go green. An operator scanning the recap will see no failures. And two thirds of the fleet was never deployed to.

If a meta stop means the work did not complete, the play has to say so in a way something reads:

    - name: Announce the stop before ending the play
      ansible.builtin.debug:
        msg: >-
          ROLLOUT STOPPED: {{ stop_reason }}.
          Deployed: {{ deployed_count | default('unknown') }} of
          {{ ansible_play_hosts_all | length }} hosts.
      run_once: true

    - name: Record the incomplete rollout as a failure
      ansible.builtin.fail:
        msg: 'Rollout stopped before completion: {{ stop_reason }}'
      run_once: true

Using fail instead of end_play gives a non-zero exit code and a recap line that says so. The cost is that it is a failure, which will page somebody — and for a maintenance window closing normally, that is wrong.

The honest rule: meta: end_play for a stop that is a normal outcome, fail for a stop that means something needs attention. A window closing on schedule is the first. A canary reporting a bad health check is the second, and dressing it up as a clean stop is how a broken deploy gets recorded as a successful night.

`clear_host_errors`

The counterpart verb: instead of removing hosts, it puts them back.

Upstream names it as the way to reactivate hosts that were marked unreachable — it restores failed and unreachable hosts to the active list so that subsequent tasks run against them again.

There is one defensible use. A play that deliberately disconnects hosts — a network reconfiguration, a reboot performed outside the reboot module — expects hosts to drop out and expects them back. Clearing the errors after they return is repair.

Under the hood

The meta verbs are not modules in the usual sense. They carry no module code to the managed node and execute entirely on the controller, manipulating the play iterator directly. That is why they are instant, why they work with gather_facts: false, and why the failure and success semantics feel different from ordinary tasks.

Each verb operates on a different part of the iterator state:

end_host marks the single host as finished with the play. Its entry is removed from the active list, and the remaining tasks are dispatched to everyone else — verified above, where h04 continued after h03 stopped.

end_batch ends the iteration for the current slice, which returns control to the loop that takes the next slice. The loop is unaffected, so the next batch is taken normally. This is precisely why end_batch does not stop a rollout — it terminates one iteration of the thing that is doing the batching, not the batching itself.

end_play ends the iteration and the slicing loop, so no further batch is taken. It does not raise a failure condition, which is why the playbook executor proceeds to the next play and why the exit code is zero.

clear_host_errors writes to the same failed and unreachable records that max_fail_percentage and the recap read from. Since max_fail_percentage computes its ratio from the failed record at the end of each task, clearing that record between tasks resets the denominator the threshold is measured against — which is the mechanism behind the warning above, and a good illustration of why these records are worth understanding as state rather than as output.

What happens if end_play runs inside a batch that has already changed hosts?

The changes stay. meta: end_play stops future work; it does not undo past work.

This is the same property as every other stop in this part, and it is worth restating because “end the play” sounds tidier than it is. Hosts in the current batch that already ran the template task have the new file. Hosts that already had their handler flushed are running it. Ansible has no rollback and meta does not add one.

The practical consequence for a rolling deploy: place the end_play check at the top of the task list, where it runs before the batch has touched anything, rather than in the middle where it strands the batch halfway. A stop that occurs before the first change is clean; a stop that occurs after the drain and before the return-to-service is the capacity-loss incident this part keeps warning about.

If you cannot guarantee the placement — because the condition can only be evaluated after some work has been done — then the stop needs a block/always around it so the batch can put itself back.

Knowledge check

Why this matters

Most of this part is about Ansible noticing a problem. This lesson is about you noticing one, and the gap between the two is where the useful preconditions live: the maintenance window, the dependency that is not ready, the canary result that a health check cannot express.

The meta verbs give you clean ways to act on those, and they share one dangerous property. A deliberate stop looks exactly like a completed run. Exit zero, no failures, and the untouched hosts absent rather than flagged. Everything downstream — the scheduler, the pipeline, the dashboard, the person skimming the log at the end of a long night — will read it as success.

So the verb is only half the pattern. The other half is saying, in something that gets read, how much of the fleet you actually deployed to. A rollout that stopped at 30% and reported nothing is worse than one that failed loudly, because the first one nobody comes back to finish.