stop-bk.yaml

Overview

The stop-bk.yaml file is an Ansible playbook that orchestrates the shutdown process of a service or application stack managed via Docker Compose. It provides a structured approach to stopping containers gracefully, with fallback to a forced termination if necessary. This file is primarily used to manage the lifecycle of Docker containers within the directory specified by the BK_DIR variable.

Detailed Breakdown

This playbook consists of three sequential tasks:

1. Graceful shutdown request before stop

• Task name: Graceful shutdown request before stop

• Description: This task includes another Ansible task file named graceful-shutdown.yaml. The referenced file is expected to contain the logic needed to initiate a clean shutdown of the services, allowing them to close connections, save state, or cleanup resources before container termination.

• Parameters: None directly; relies on the included task file.

• Usage: Ensures that services have the chance to stop gracefully, reducing the risk of data loss or corruption.

2. Compose stop

• Task name: Compose stop

• Module: ansible.builtin.shell

• Description: This task runs the command docker compose stop within the directory specified by the BK_DIR variable.

• Parameters:

  • chdir: The directory where the docker-compose.yml file is located, set by {{ BK_DIR }}.

  • cmd: The shell command to execute: docker compose stop.

• Functionality: Attempts to stop all running containers gracefully by sending stop signals, allowing containers to exit cleanly.

• Return: The task returns the result of the shell command execution, including the exit status, stdout, and stderr, which can be used for logging or error handling.

• Usage Example:

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

3. Compose stop (hard)

• Task name: Compose stop (hard)

• Module: ansible.builtin.shell

• Description: Runs the command docker compose kill within the same directory.

• Parameters:

  • chdir: Same as above, set by {{ BK_DIR }}.

  • cmd: The shell command docker compose kill.

• Functionality: Forcefully kills all running containers, immediately terminating processes without allowing cleanup. This is used as a fallback when the graceful stop does not succeed.

• Return: Similar to the previous task, it returns the shell execution results.

• Usage: Used to ensure containers are stopped in all scenarios, especially if graceful shutdown fails or times out.

Implementation Details

• The playbook assumes that BK_DIR is defined in the Ansible inventory or playbook vars, pointing to the directory containing the Docker Compose configuration (docker-compose.yml or docker-compose.yaml).

• The sequence reflects a best practice shutdown approach:

  1. Attempt a graceful shutdown via an included task.

  2. Try to stop containers normally with docker compose stop.

  3. If containers remain, forcibly kill them with docker compose kill.

• This approach reduces service downtime and potential data loss by prioritizing clean exits.

Interaction with Other Parts of the System

• The playbook depends on the graceful-shutdown.yaml task file, which should define the actual shutdown signals or API calls to the running services.

• The environment variable BK_DIR must be correctly set and accessible to ensure the shell commands are executed in the correct context.

• This playbook is likely invoked as part of a larger deployment or maintenance workflow to manage container lifecycle.

• It interacts with the Docker Engine through the docker compose CLI, which manages container orchestration.

Mermaid Diagram - Workflow of stop-bk.yaml

flowchart TD
A[Start stop-bk.yaml] --> B[Include graceful-shutdown.yaml]
B --> C[Run "docker compose stop" in BK_DIR]
C --> D[Run "docker compose kill" in BK_DIR]
D --> E[End]

This diagram illustrates the linear flow of tasks executed in this playbook, emphasizing the sequential execution from graceful shutdown request to forced container termination.