start-bm.yaml

Overview

This Ansible playbook automates the setup and management of a block manager (BM) environment. It primarily handles the creation of necessary directories, copying and registering key files, preparing Docker Compose configurations, setting up scheduled tasks for database rotation, managing Docker networks, and controlling the lifecycle of Docker containers related to the block manager. The playbook ensures that the BM environment is correctly initialized and maintained with appropriate file permissions, scheduled maintenance, and container orchestration.

Detailed Breakdown of Tasks

Directory and File Management

• Ensures block manager directories

  • Module: ansible.builtin.file

  • Purpose: Creates the main block manager directory (BM_DIR) and logs directory (BM_LOGS_DIR) with full read, write, and execute permissions for user, group, and others (mode: u=rwx,g=rwx,o=rwx).

  • Parameters:

    • path: Directory paths from the variable list.

    • state: Ensures the path is a directory.

    • mode: Permissions set to 0777.

  • Usage: Prepares the environment by guaranteeing required directories exist.

• Ensures keys directory exists

  • Module: ansible.builtin.file

  • Purpose: Creates a bm-configs subdirectory inside the BM directory for storing key configuration files.

  • Permissions: User has full permissions, group has none, others have full permissions (mode: u=rwx,g=,o=rwx).

  • Path: {{ BM_DIR }}/bm-configs

• Copy keys file

  • Module: copy

  • Purpose: Copies wallet and signer key files into the bm-configs directory.

  • Parameters:

    • dest: Destination directory for keys.

    • src: Source key files specified by variables BM_WALLET_KEYS and BM_SIGNER_KEYS.

  • Usage: Ensures that cryptographic keys required by the BM are available in the correct directory.

Key Extraction and Fact Registration

• Get public wallet key

  • Module: ansible.builtin.shell

  • Purpose: Extracts the public key from the wallet key file using jq to parse JSON.

  • Command: cat {{ BM_WALLET_KEYS }} | jq -r '.public'

  • Working directory: {{ BM_DIR }}/bm-configs/

  • Registers output in BM_PUBLIC_KEY_OUTPUT.

• Register public wallet key

  • Module: ansible.builtin.set_fact

  • Purpose: Sets an Ansible fact BM_OWNER_WALLET_PUBKEY with the extracted public key from the previous task.

  • Usage: Makes the public key available for subsequent tasks or playbooks.

Docker Compose and Container Management

• Production compose

  • Module: ansible.builtin.template

  • Purpose: Renders a Docker Compose YAML file (compose.yaml) from the Jinja2 template templates/compose.j2.

  • Destination: {{ BM_DIR }}/compose.yaml

  • Permissions: Set to 0644.

  • Usage: Prepares the Docker Compose specification for running the BM services.

• Compose pull

  • Module: ansible.builtin.shell

  • Purpose: Runs docker compose pull in the BM directory to fetch the latest images defined in the Compose file.

  • Working directory: {{ BM_DIR }}

• Create ackinacki-net manually

  • Module: ansible.builtin.shell

  • Purpose: Creates a Docker network named ackinacki-net.

  • Condition: Runs only if CREATE_NET variable is true.

  • Error Handling: Ignores errors if the network already exists.

• Compose UP

  • Module: ansible.builtin.shell

  • Purpose: Starts all services defined in the Docker Compose file in detached mode (docker compose up -d).

  • Working directory: {{ BM_DIR }}

• Compose restart logrotate

  • Module: ansible.builtin.shell

  • Purpose: Restarts the logrotate service/container using Docker Compose.

  • Condition: Runs only if the logrotate configuration changed.

Scheduled Tasks and Maintenance

• Copy cron script

  • Module: ansible.builtin.copy

  • Purpose: Copies the bm-rotate.sh shell script into the BM directory.

  • Permissions: Executable (0755).

  • Owner: Set to the current Ansible user ({{ ansible_user }}).

• Create cron entry

  • Module: ansible.builtin.cron

  • Purpose: Creates a cron job named "rotate BM database" that runs the bm-rotate.sh script daily at 5:00 AM.

  • Cron job:

    {{ BM_DIR }}/bm-rotate.sh >> {{ BM_LOGS_DIR }}/bm-rotate.log
    

  • User: root

  • Cron file: bm_rotate

• Log rotate configuration

  • Module: ansible.builtin.template

  • Purpose: Renders a logrotate shell script from templates/logrotate.j2.

  • Destination: {{ BM_DIR }}/logrotate.sh

  • Permissions: Executable (0755)

  • Registers change status in logrotate for conditional tasks.

Important Implementation Details

• The playbook makes extensive use of Ansible's file and copy modules to ensure directory and file presence with correct permissions.

• It uses jq CLI tool via shell commands to parse JSON wallet key files.

• Docker Compose commands (pull, up, restart) are executed via shell tasks inside the BM directory.

• The playbook conditionally creates a Docker network only when specified, ignoring errors to avoid failures if the network exists.

• Cron jobs are configured to perform database rotation and log rotation to maintain the block manager's operational health.

• Template files (compose.j2 and logrotate.j2) enable dynamic configuration based on variables, aligning with best practices for environment-specific setups.

Interaction with Other System Components

• Docker Ecosystem: The playbook interfaces with Docker to manage service containers and networks critical for block manager operations.

• File System: It manipulates local directories and files for configuration, keys, logs, and scripts.

• System Scheduler: It configures the system's cron daemon to automate maintenance tasks, specifically database rotation.

• Key Management: By copying and extracting wallet keys, it integrates with cryptographic subsystems or wallets used by the block manager.

• Template System: Utilizes Jinja2 templates to generate essential configuration files dynamically.

Visual Diagram

flowchart TD
A[Start: Ensure Directories] --> B[Create BM and Logs directories]
B --> C[Create bm-configs directory]
C --> D[Copy Wallet & Signer Keys]
D --> E[Extract Public Key using jq]
E --> F[Set Public Key Fact]
F --> G[Render Docker Compose Template]
G --> H[Copy bm-rotate.sh Script]
H --> I[Create Cron Job for DB Rotation]
I --> J[Render Logrotate Template]
J --> K[Pull Docker Images]
K --> L{CREATE_NET?}
L -- Yes --> M[Create Docker Network]
L -- No --> N[Skip Network Creation]
M & N --> O[Start Docker Compose Services]
O --> P{Logrotate Changed?}
P -- Yes --> Q[Restart logrotate Container]
P -- No --> R[End]

This flowchart illustrates the sequential steps and conditional logic within the playbook, highlighting directory setup, key management, Docker orchestration, and scheduled maintenance tasks.