stop-bm.yaml

Overview

The stop-bm.yaml file is an Ansible playbook snippet designed to manage the stopping of services orchestrated by Docker Compose within a specified directory. It contains two primary tasks that handle service shutdown with different levels of force:

• A graceful stop of all running containers.

• A forced kill of all running containers.

This file is intended to be used as part of automation workflows where controlled shutdown of containerized services is required.

Tasks and Functionality

1. Compose stop

• Purpose: Gracefully stops all Docker Compose services in the target directory.

• Module Used: ansible.builtin.shell

• Parameters:

  • chdir: Specifies the working directory where the docker compose command will be executed. It uses the variable {{ BM_DIR }}, which should be defined elsewhere in the playbook or inventory.

  • cmd: The shell command to execute, here it is docker compose stop.

• Effect: Sends the standard stop signal to all running containers defined in the Docker Compose configuration, allowing them to terminate cleanly.

• Usage Example:

  - name: Compose stop
    ansible.builtin.shell:
      chdir: "/path/to/bm_dir"
      cmd: docker compose stop
  

2. Compose stop (hard)

• Purpose: Forces an immediate shutdown of all Docker Compose services in the target directory.

• Module Used: ansible.builtin.shell

• Parameters:

  • chdir: Same as above, specifies the working directory.

  • cmd: The shell command docker compose kill.

• Effect: Sends a SIGKILL signal to all running containers, terminating them immediately without any graceful shutdown.

• Usage Example:

  - name: Compose stop (hard)
    ansible.builtin.shell:
      chdir: "/path/to/bm_dir"
      cmd: docker compose kill
  

Implementation Details

• Both tasks utilize the ansible.builtin.shell module to execute shell commands in a specific directory.

• The use of docker compose stop and docker compose kill commands aligns with standard Docker Compose CLI commands for container lifecycle management.

• The variable BM_DIR acts as an abstraction to specify the directory containing the Docker Compose files and environment, allowing flexibility in deployment paths.

• This playbook snippet assumes that Docker Compose v2 is installed and accessible in the environment where the playbook runs, as it uses the docker compose syntax (space, not a hyphen).

Interaction with Other System Components

• Variable Dependency: Relies on the definition of BM_DIR variable, which should be set in the inventory, command line, or another part of the Ansible playbook.

• Docker Environment: Must be executed on a host with Docker and Docker Compose installed and properly configured.

• Integration: Typically invoked as part of a larger playbook managing the lifecycle of containerized services, possibly preceding or following tasks such as deployment, updates, or cleanup.

• Error Handling: This file does not include explicit error handling; it inherits Ansible's default behavior for shell task failures, which can be managed at the playbook level.

Visual Diagram

flowchart TD
A[Start Playbook] --> B[Compose stop]
B -->|Executes: docker compose stop| C{Containers stopped?}
C -- Yes --> D[Graceful shutdown complete]
C -- No --> E["Compose stop (hard)"]
E -->|Executes: docker compose kill| F[Forced shutdown complete]

This flowchart illustrates the sequence of operations: initially attempting a graceful stop of Docker Compose services, and if necessary, performing a forced kill to ensure all containers are terminated.