start-bk.yaml

Overview

The start-bk.yaml file is an automation playbook script designed to manage the lifecycle of a Docker-based application environment, specifically related to a block keeper component. It uses Ansible's shell module to execute Docker Compose commands and Docker CLI operations, controlling the pulling of images, network creation, container orchestration, key generation, synchronization, and selective restarting of services.

This file is primarily used to:

• Pull Docker images using Docker Compose.

• Create a custom Docker network if necessary.

• Bring down running Docker Compose services conditionally.

• Generate BLS (Boneh–Lynn–Shacham) cryptographic keys for node identity.

• Synchronize startup across multiple nodes.

• Start or upgrade Docker Compose services.

• Conditionally restart the logrotate service in Docker Compose.

The playbook uses conditional execution extensively based on environment variables and flags, allowing flexible orchestration depending on the deployment scenario (e.g., initial start, upgrade, or synchronization).

Playbook Tasks and Their Functions

1. Compose pull

- name: Compose pull
  ansible.builtin.shell:
    chdir: "{{ BK_DIR }}"
    cmd: docker compose pull
  when:
    - DO_START or (UPGRADE is defined and 'compose' in UPGRADE)
    - SUBNODE_ID is not defined or SUBNODE_ID == 0 or (PULL_ALL is defined and PULL_ALL)

Purpose:
Pulls the latest Docker images for the services defined in the Docker Compose file located in the BK_DIR directory.

Parameters:

• BK_DIR: Directory path where the Docker Compose YAML files reside.

• Conditions:

  • The playbook should perform this task if starting (DO_START is true) or if an upgrade includes the 'compose' component.

  • It only runs if no SUBNODE_ID is set, or the SUBNODE_ID is zero, or a global pull flag (PULL_ALL) is true.

Return:
Executes the shell command docker compose pull to update images.

Usage Example:
This task ensures that the latest images are available before starting or upgrading the service.

2. Create ackinacki-net manually

- name: Create ackinacki-net manually
  ansible.builtin.shell:
    cmd: docker network create ackinacki-net
  ignore_errors: true
  when:
    - CREATE_NET
    - DO_START
    - not UPGRADE is defined or not UPGRADE

Purpose:
Creates a custom Docker network named ackinacki-net. This network is presumably used for container connectivity isolated from default networks.

Parameters:

• CREATE_NET: Flag indicating whether to create the network.

• DO_START: Indicates the environment is starting.

• UPGRADE: The task is skipped during upgrades.

Return:
Runs docker network create ackinacki-net. Errors are ignored (for example, if the network already exists).

Usage Example:
Run when starting fresh environments that require a dedicated Docker network.

3. Compose down

- name: Compose down
  ansible.builtin.shell:
    chdir: "{{ BK_DIR }}"
    cmd: docker compose down --remove-orphans
  ignore_errors: true
  when: UPGRADE is defined and 'deep-compose' in UPGRADE

Purpose:
Stops and removes all Docker Compose services, including orphaned containers not defined in the Compose file.

Parameters:

• BK_DIR: Directory of Docker Compose setup.

• UPGRADE: Only executed if a deep-compose upgrade is specified.

Return:
Runs docker compose down --remove-orphans to clean up running services.

Usage Example:
Used during deep upgrade processes to fully stop existing container sets before redeployment.

4. Create BLS keys

- name: Create BLS keys
  ansible.builtin.shell:
    cmd: "docker run --rm --entrypoint /usr/local/bin/node-helper -v {{ BK_DIR }}/bk-configs:/staking {{ STAKING_IMAGE }} bls --path block_keeper{{ NODE_ID }}_bls.keys.json"
    creates: "{{ BK_DIR }}/bk-configs/block_keeper{{ NODE_ID }}_bls.keys.json"
  when: '"block_keeper" ~ NODE_ID ~ "_bls.keys.json" not in OTHER_KEYS'

Purpose:
Generates Boneh–Lynn–Shacham (BLS) cryptographic keys for the block keeper node, which are essential for node identification and cryptographic operations.

Parameters:

• BK_DIR: Base directory containing configuration files.

• STAKING_IMAGE: Docker image used for staking-related helper commands.

• NODE_ID: Identifier for the block keeper node.

• OTHER_KEYS: List of existing keys to avoid regeneration.

Return:
Runs a Docker container that executes the node-helper tool with the bls command to generate keys. The command is skipped if the key file already exists.

Usage Example:
Used to ensure each block keeper node has unique cryptographic keys before starting operations.

5. Synchronize network startup

- name: Synchronize network startup
  include_tasks: synchronized-start.yaml
  when: SYNCHRONIZED_START is defined

Purpose:
Includes another task file (synchronized-start.yaml) to synchronize the startup across multiple nodes.

Parameters:

• SYNCHRONIZED_START: Flag indicating whether synchronization is required.

Return:
Delegates execution to a separate task file managing coordinated startup.

Usage Example:
Used in multi-node deployments to ensure nodes start in a controlled sequence.

6. Compose up

- name: Compose up
  ansible.builtin.shell:
    chdir: "{{ BK_DIR }}"
    cmd: docker compose up -d --remove-orphans
  when: DO_START or (UPGRADE is defined and UPGRADE | length > 0)

Purpose:
Starts Docker Compose services in detached mode, removing orphaned containers.

Parameters:

• BK_DIR: Directory containing Docker Compose configuration.

• Conditions:

  • Run if starting (DO_START is true) or if an upgrade operation is defined.

Return:
Runs docker compose up -d --remove-orphans to launch containers.

Usage Example:
Starts or upgrades service containers after pulling images or performing other preparatory tasks.

7. Compose restart logrotate

- name: Compose restart logrotate
  ansible.builtin.shell:
    chdir: "{{ BK_DIR }}"
    cmd: docker compose restart "logrotate{{ NODE_ID if (NUMBERED_SERVICES | default(true)) else "" }}"
  when:
    - DO_START
    - logrotate is defined and logrotate.changed

Purpose:
Restarts the logrotate service container, optionally with a node-specific suffix, if the logrotate configuration has changed.

Parameters:

• BK_DIR: Directory for Docker Compose files.

• NODE_ID: Node identifier for number-suffixed services.

• NUMBERED_SERVICES: Flag indicating whether services are numbered.

• logrotate.changed: Flag indicating if the logrotate configuration changed.

• DO_START: Ensures restarting only happens during start.

Return:
Executes docker compose restart for the logrotate container to apply changes immediately.

Usage Example:
Applies configuration changes to logging rotation without full container restart.

Important Implementation Details

• Conditional Execution: Most tasks rely on complex Boolean expressions evaluating environment or playbook variables to control execution flow. This supports flexible deployment strategies such as selective upgrades, fresh starts, or partial service management.

• Use of Docker CLI inside Shell Module: The playbook uses Ansible's shell module rather than Docker-specific modules, to run Docker Compose and Docker CLI commands directly, ensuring compatibility with custom scripts and network setup.

• Idempotency: The creates directive in the BLS key generation task ensures keys are only created once per node, preventing unnecessary regeneration. The network creation task ignores errors to avoid failures if the network already exists.

• Modular Synchronization: The inclusion of synchronized-start.yaml enables modular management of coordinated startup logic, isolating complex synchronization workflows from this main orchestration script.

Interaction with Other System Components

• Configuration Directory (BK_DIR): All Docker Compose commands and key generation operate relative to this directory, which contains Docker Compose YAML files and configuration files.

• Staking Image (STAKING_IMAGE): The BLS key generation depends on a specialized Docker image designed for staking operations, indicating interaction with staking-related components.

• Other Playbooks and Tasks: The inclusion of synchronized-start.yaml references a related playbook that handles startup synchronization across multiple nodes in the network.

• Environment Variables and Flags: Many task executions rely on variables like DO_START, UPGRADE, SUBNODE_ID, and PULL_ALL, which are expected to be defined elsewhere in the deployment or orchestration environment.

• Docker Network: The custom ackinacki-net network is created to facilitate container communication, potentially isolating block keeper nodes from other Docker networks.

Mermaid Diagram: Task Flow in start-bk.yaml

flowchart TD
A[Compose pull]
B[Create ackinacki-net]
C[Compose down]
D[Create BLS keys]
E[Synchronized start]
F[Compose up]
G[Compose restart logrotate]
A --> B
B --> C
C --> D
D --> E
E --> F
F --> G
style C fill:#f9f,stroke:#333,stroke-width:2px
style E fill:#bbf,stroke:#333,stroke-width:2px

• Arrows represent the typical logical sequence of execution considering conditions.

• Compose down (C) is executed only during deep upgrades.

• Synchronized start (E) is modular and conditional.

• Tasks may be skipped based on evaluated conditions but are shown here in potential order.

End of start-bk.yaml Documentation