main.yaml

Overview

main.yaml is an Ansible playbook designed to orchestrate the lifecycle management of the Block Keeper (BK) system components. It primarily handles tasks such as retrieving the epoch contract code hash, ensuring directory structures, copying configuration files, preparing the host environment, managing the Block Keeper service state (start, stop, upgrade), and performing cleanup operations (deleting data and logs). The playbook conditionally executes various included task files based on specific runtime flags and variables, enabling flexible deployment and maintenance workflows.

Structure and Functionality

The playbook consists of a sequence of named task entries, each executing either a direct Ansible module command or including other task files (include_tasks:). Execution of tasks is gated by conditional expressions (when:), allowing selective operation depending on the environment and desired actions.

Task Entries

1. Get Epoch code hash

• Purpose: Load the code hash of the Block Keeper epoch contract from a file into an Ansible fact (CODE_HASH), if it is not already defined.

• Module Used: ansible.builtin.set_fact

• Parameters:

  • CODE_HASH: Set by reading the contents of ../contracts/bksystem/BlockKeeperEpochContract.code.hash using the lookup plugin.

• Condition: Runs only when CODE_HASH is undefined.

• Usage Example:

- name: Get Epoch code hash
  ansible.builtin.set_fact:
    CODE_HASH: "{{ lookup('ansible.builtin.file', '../contracts/bksystem/BlockKeeperEpochContract.code.hash') }}"
  when: CODE_HASH is not defined

2. Ensure required directories exist

• Purpose: Make sure all necessary directories exist before proceeding with other operations.

• Included Task File: ensure-dirs.yaml

• Condition: Runs when DO_START is true and FAST_UPDATE is false.

• Usage Context: Prepares the filesystem for deployment or service start.

3. Copy static configs

• Purpose: Copy static configuration files needed by the Block Keeper system.

• Included Task File: copy-static-configs.yaml

• Condition: Runs when DO_START is true and FAST_UPDATE is false.

4. Prepare host

• Purpose: Prepare the host environment by performing prerequisite setup tasks.

• Included Task File: prepare-host.yaml

• Condition: Runs when DO_START, PREPARE_HOST are true and FAST_UPDATE is false.

5. Copy deployment configs

• Purpose: Copy deployment-specific configuration files.

• Included Task File: copy-deployment-configs.yaml

• Condition: Runs when either FAST_UPDATE is false or UPGRADE is defined.

6. Pre-upgrade stop

• Purpose: Execute steps necessary to gracefully stop services before an upgrade.

• Included Task File: pre-upgrade-stop.yaml

• Condition: Runs only if UPGRADE is defined.

7. Stop block keeper

• Purpose: Stop the Block Keeper service.

• Included Task File: stop-bk.yaml

• Condition: Runs when DO_STOP is true.

8. Stop and delete data

• Purpose: Stop services and delete all data associated with Block Keeper.

• Included Task File: stop-delete-data.yaml

• Condition: Runs when DELETE_DATA is true.

9. Stop and delete logs

• Purpose: Stop services and delete logs generated by Block Keeper.

• Included Task File: stop-delete-logs.yaml

• Condition: Runs when DELETE_LOGS is true.

10. Ensure required directories exist after deleting something

• Purpose: Re-create necessary directories if data or logs have been deleted.

• Included Task File: ensure-dirs.yaml

• Condition: Runs when either DELETE_DATA or DELETE_LOGS is true.

11. Start block keeper

• Purpose: Start the Block Keeper service.

• Included Task File: start-bk.yaml

• Condition: Runs when DO_START is true or UPGRADE is defined.

12. Bootstrap BK set

• Purpose: Bootstrap the Block Keeper set from a provided URL.

• Included Task File: bootstrap-bk-set.yaml

• Condition: Runs when all of the following are true:

  • BOOTSTRAP_BK_SET_URL is defined and non-empty

  • DO_START or UPGRADE is true, or DO_BOOTSTRAP is defined and true.

Important Implementation Details

• Conditional Execution: The playbook relies heavily on conditionals (when:) to determine which tasks should run based on runtime variables. This enables flexibility for different operation modes such as full start, upgrade, fast update, stop, and cleanup.

• Task Inclusion: Modularization is achieved by including external task files for complex or grouped operations, improving maintainability and readability.

• Use of Ansible Facts: The CODE_HASH fact is set early to ensure the epoch contract code hash is available for subsequent tasks that depend on contract code verification or deployment.

• File Lookup: The code hash is read directly from a file relative to the playbook directory using Ansible's lookup('file', ...) mechanism.

Interactions with Other System Components

• Contract Code Hash File: Reads BlockKeeperEpochContract.code.hash from the contracts directory, which is likely generated by a build or compilation process outside this playbook.

• Included Task Files: Interfaces with several task files (e.g., ensure-dirs.yaml, copy-static-configs.yaml, start-bk.yaml) that encapsulate detailed operations related to system preparation, configuration, and service management.

• Runtime Flags and Variables: The playbook expects various variables (DO_START, FAST_UPDATE, UPGRADE, DELETE_DATA, DELETE_LOGS, BOOTSTRAP_BK_SET_URL, DO_BOOTSTRAP) to be defined externally, possibly through inventory, command line, or other playbooks, allowing integration into larger deployment pipelines.

Visual Diagram

flowchart TD
A[Get Epoch code hash] --> B{DO_START and not FAST_UPDATE?}
B -->|Yes| C[Ensure required directories exist]
B -->|Yes| D[Copy static configs]
D --> E[Prepare host]
E --> F[Copy deployment configs]
F --> G{UPGRADE defined?}
G -->|Yes| H[Pre-upgrade stop]
I[DO_STOP?] --> J[Stop block keeper]
K[DELETE_DATA?] --> L[Stop and delete data]
M[DELETE_LOGS?] --> N[Stop and delete logs]
L & N --> O[Ensure required directories exist after delete]
P{DO_START or UPGRADE?} --> Q[Start block keeper]
R{BOOTSTRAP_BK_SET_URL and (DO_START or UPGRADE or DO_BOOTSTRAP)?} --> S[Bootstrap BK set]
B -->|No| T
I -->|No| T
K -->|No| T
M -->|No| T
G -->|No| T
P -->|No| T
R -->|No| T
style T fill:#f9f,stroke:#333,stroke-width:2px,color:#000

The diagram illustrates the conditional workflow of the playbook, showing how different tasks are executed based on input flags and variables. Tasks are connected in logical order reflecting dependencies and conditional branching.