stop-delete-logs.yaml

Overview

This YAML file defines an Ansible playbook sequence to manage the shutdown and cleanup of logging resources related to a containerized application. Its primary functions are to:

• Perform a graceful shutdown of services using Docker Compose, unless a full data deletion is requested.

• Stop running containers managed by Docker Compose.

• Remove the directory containing node logs.

• Recreate the node logs directory with appropriate permissions.

It is designed to be used in scenarios where log cleanup is necessary, such as preparing for a fresh start or system maintenance, while optionally preserving data based on the DELETE_DATA flag.

Playbook Tasks and Functionality

1. Graceful shutdown request before compose down

• Task Name: Graceful shutdown request before compose down

• Purpose: Includes another task file graceful-shutdown.yaml to initiate a graceful shutdown procedure before stopping Docker Compose services.

• Condition: Executed only when the variable DELETE_DATA is not set to true (when: not DELETE_DATA).

• Details: The included task likely handles signaling or orderly shutdown commands to running services to avoid abrupt termination.

• Interaction: Depends on the external task file graceful-shutdown.yaml for the actual shutdown logic.

2. Compose stop

• Task Name: Compose stop

• Module: ansible.builtin.shell

• Purpose: Runs the shell command docker compose stop in the directory specified by the variable BK_DIR to stop all Docker Compose-managed containers.

• Parameters:

  • chdir: Directory context for running the command, {{ BK_DIR }}.

  • cmd: The shell command docker compose stop.

• Error Handling: Uses ignore_errors: true to allow the playbook to continue even if stopping containers fails.

• Condition: Executed only if DELETE_DATA is not true.

• Usage: This ensures containerized services cease operation cleanly after the graceful shutdown step.

3. Remove node logs dir

• Task Name: Remove node logs dir

• Module: ansible.builtin.file

• Purpose: Deletes the directory containing node logs to clear existing log data.

• Parameters:

  • path: Path to the logs directory, {{ BK_LOGS_DIR }}.

  • state: Set to absent to remove the directory and its contents.

• Usage: Used to clean up log files, which is common in maintenance or reset operations.

4. Recreate node logs dir

• Task Name: Recreate node logs dir exists: {{ BK_LOGS_DIR }}

• Module: ansible.builtin.file

• Purpose: Recreates the node logs directory after its removal, ensuring it exists with the correct permissions.

• Parameters:

  • path: Same as above, {{ BK_LOGS_DIR }}.

  • state: Set to directory to create the directory if missing.

  • mode: Permissions set to u=rwx,g=rwx,o=rwx (read, write, execute for user, group, others).

• Usage: Ensures the application or logging services can write logs to the expected directory after cleanup.

Important Implementation Details

• Conditional Execution: The playbook uses the variable DELETE_DATA as a flag to control whether to perform service shutdown and stopping steps. When DELETE_DATA is true, only log directory removal and recreation occur.

• Error Tolerance: The stopping of Docker containers is wrapped with ignore_errors: true to prevent failure of the entire playbook if containers are not running or stopping fails.

• Directory Permissions: Explicitly sets wide-open permissions on the recreated logs directory (777), allowing all users read/write/execute access, which may be necessary for containerized environments or shared logging systems.

• Modular Shutdown: The graceful shutdown step is modularized into an included task file, promoting reusability and separation of concerns for shutdown procedures.

Interactions with Other Components

• graceful-shutdown.yaml: This included task file, referenced in the first task, is responsible for the detailed graceful shutdown logic. It is critical for orderly stopping of services before container shutdown.

• Environment Variables:

  • BK_DIR: Specifies the working directory where Docker Compose commands are executed; typically the root of the container orchestration setup.

  • BK_LOGS_DIR: Specifies the filesystem path to the node logs directory that gets removed and recreated.

• Docker Compose: The playbook interacts directly with Docker Compose to manage container lifecycle via shell commands.

• Logging System: The file system operations target the logs directory, which is presumably used by applications or services running inside containers for storing runtime logs.

Visual Diagram: Workflow of stop-delete-logs.yaml

flowchart TD
A[Start Playbook] --> B{DELETE_DATA?}
B -- No --> C[Include graceful-shutdown.yaml]
C --> D[Run 'docker compose stop' in BK_DIR]
B -- Yes --> E[Skip shutdown and stop steps]
D --> F[Remove BK_LOGS_DIR]
E --> F
F --> G[Create BK_LOGS_DIR with mode 777]
G --> H[End Playbook]

For further understanding of the graceful shutdown logic, refer to Graceful Shutdown Procedures. For detailed information on Docker Compose commands and lifecycle management, see Docker Compose Management. For environment variable usage and configuration, consult Configuration and Environment Variables.