pre-upgrade-stop.yaml

Overview

This YAML file defines a set of Ansible tasks that coordinate the graceful shutdown of various services and nodes prior to performing an upgrade. It is specifically focused on stopping Docker Compose-managed containers and Aerospike database services in a controlled manner. The file ensures that the shutdown process respects the upgrade context, executing only the relevant steps for the components involved in the upgrade.

Tasks and Their Functionality

1. Node graceful shutdown step 1

• Purpose: Begins the graceful shutdown process of the node.

• Implementation Detail: This task includes another task file graceful-shutdown.yaml, which likely contains a broader set of shutdown instructions or commands for the node.

• Usage: This inclusion ensures that all generic shutdown steps defined elsewhere are executed as the first step.

2. Node graceful shutdown step 2 (for compose upgrade)

• Purpose: Shuts down the Docker Compose container corresponding to the node that is being upgraded.

• Module Used: ansible.builtin.shell

• Commands:

  • Changes directory to BK_DIR (a variable representing the base directory for deployment).

  • Executes docker compose down "node{{ NODE_ID }}" to stop and remove the Compose container for the specific node.

• Conditional Execution:

  • Runs only if the upgrade involves 'compose'.

  • Ensures that compose is defined and has changed (compose.changed).

• Parameters:

  • BK_DIR: Working directory for the Docker Compose command.

  • NODE_ID: Identifier of the node to be shut down.

  • UPGRADE: List or string that includes components to be upgraded.

• Return Value: This task does not return a value but performs side effects on the system by stopping containers.

• Example Usage:

  - name: Upgrade Compose containers
    vars:
      UPGRADE: ['compose']
      compose:
        changed: true
      NODE_ID: 1
      BK_DIR: /opt/deployment
    import_tasks: pre-upgrade-stop.yaml
  

3. Aerospike shutdown for upgrade

• Purpose: Stops the Aerospike Docker Compose service prior to upgrade.

• Module Used: ansible.builtin.shell

• Commands:

  • Changes directory to BK_DIR.

  • Executes docker compose stop aerospike to stop the Aerospike container gracefully.

• Conditional Execution:

  • Runs only if the upgrade involves 'aerospike'.

  • Ensures that aerospike is defined and has changed (aerospike.changed).

• Parameters:

  • BK_DIR: Working directory for the Docker Compose command.

  • UPGRADE: List or string that includes components to be upgraded.

• Return Value: Performs the side effect of stopping the Aerospike service.

• Example Usage:

  - name: Upgrade Aerospike service
    vars:
      UPGRADE: ['aerospike']
      aerospike:
        changed: true
      BK_DIR: /opt/deployment
    import_tasks: pre-upgrade-stop.yaml
  

Important Implementation Details

• The file uses Ansible's conditional when statements to selectively execute shutdown steps based on which components are marked for upgrade.

• The use of docker compose down vs docker compose stop distinguishes between stopping and removing containers (down) and simply stopping them (stop).

• The directory context (chdir) for Docker Compose commands ensures that the commands are run in the correct environment where the Compose files and related resources reside.

• The modular inclusion of graceful-shutdown.yaml allows reuse and separation of concerns for shutdown procedures.

Interaction with Other System Components

• graceful-shutdown.yaml: This file is included as a first step, indicating that it contains foundational shutdown tasks that must be executed before the node-specific Compose containers or services are stopped.

• Docker Compose Environment: The tasks directly interact with Docker Compose to manage container lifecycle during the upgrade process.

• Upgrade Orchestration: This file works within the broader upgrade orchestration logic, which sets the UPGRADE variable and manages which components require restart or shutdown.

• Variables and Inventory: The file relies on variables such as BK_DIR, NODE_ID, compose, and aerospike which are likely set in the inventory or playbook that includes this task file.

Mermaid Diagram

flowchart TD
A[Start Pre-Upgrade Stop] --> B[Include graceful-shutdown.yaml]
B --> C{Is 'compose' in UPGRADE and compose.changed?}
C -- Yes --> D[Run: docker compose down node{{NODE_ID}}]
C -- No --> E
D --> E{Is 'aerospike' in UPGRADE and aerospike.changed?}
E -- Yes --> F[Run: docker compose stop aerospike]
E -- No --> G[End]
F --> G

This diagram illustrates the flow of tasks in pre-upgrade-stop.yaml, showing conditional execution paths for node and Aerospike container shutdowns.