Hyperledger Fabric-X Ansible Playbooks¶

This directory contains the reusable playbooks that the hyperledger.fabricx collection provides. They compose the collection roles into standard Fabric-X lifecycle operations and are the building blocks for any Ansible project that deploys a Fabric-X network.

Playbook Usage¶

Each playbook can be run by its fully-qualified collection name:

ansible-playbook hyperledger.fabricx.orderer.start

The top-level playbooks prepare shared host resources around the component-specific lifecycle. The normal setup flow runs prerequisites first, logs in to registries when private images are used, creates container networks for container-mode inventories, and then runs the namespaced playbooks for artifacts, configuration, services, and cleanup.

flowchart LR
  PRE[install_prerequisites] --> REG[log_in_container_registry]
  REG --> NET[create_container_networks]
  NET --> NS[namespaced playbooks]
  NS --> RM[remove_container_networks]
  NS -.-> TARGETS[generate_target_hosts]

install_prerequisites.yaml¶

install_prerequisites.yaml prepares the machines that will run Fabric-X services. It first selects one representative inventory host per physical machine, then installs the shared operating-system and runtime prerequisites used by the rest of the collection: container engine support, tmux, OpenSSL, Git, Go, rsync, and chrony.

ansible-playbook hyperledger.fabricx.install_prerequisites --extra-vars '{"target_hosts": "all"}'

Properties:

Target hosts: all by default for host discovery, then the generated machines group for installation.
Nuance: only one representative host per physical machine installs packages, which avoids repeating package operations when several inventory hosts map to the same ansible_host.
Nuance: use target_hosts to prepare only a subset of the inventory.

log_in_container_registry.yaml¶

log_in_container_registry.yaml authenticates the deployment against a private container registry. It logs the container engine in once per physical machine, then creates Kubernetes image pull secrets once per selected Kubernetes namespace when Kubernetes hosts are present.

ansible-playbook hyperledger.fabricx.log_in_container_registry --extra-vars '{"target_hosts": "all"}'

Properties:

Target hosts: all by default for host and namespace discovery, then the generated machines and k8s_namespaces groups for the actual login and pull-secret steps.
Nuance: requires the registry variables consumed by the container and Kubernetes roles, including container_registry, container_registry_username, and container_registry_password.
Nuance: useful before starting container or Kubernetes deployments that pull private images.

create_container_networks.yaml¶

create_container_networks.yaml creates the container networks declared by the selected inventory hosts. It deduplicates work by building one execution target per (ansible_host, container_network) pair, so each required network is created once on each machine that needs it.

ansible-playbook hyperledger.fabricx.create_container_networks --extra-vars '{"target_hosts": "all"}'

Properties:

Target hosts: localhost for discovery, then the generated machines_with_container_networks group for network creation.
Nuance: only hosts with container_network defined contribute a network target.
Nuance: run this before starting container-mode deployments that expect a pre-created network.

remove_container_networks.yaml¶

remove_container_networks.yaml removes the container networks that were created for the selected inventory hosts. It uses the same (ansible_host, container_network) deduplication as the create playbook, which makes cleanup operate once per machine and network.

ansible-playbook hyperledger.fabricx.remove_container_networks --extra-vars '{"target_hosts": "all"}'

Properties:

Target hosts: localhost for discovery, then the generated machines_with_container_networks group for network removal.
Nuance: only hosts with container_network defined contribute a network target.
Nuance: run this after component teardown when the deployment no longer needs its container networks.

generate_target_hosts.yaml¶

generate_target_hosts.yaml regenerates the Makefile helper targets for the selected inventory. It reads groups['all'] and writes target_hosts.mk under project_dir, giving the top-level Makefile one target per inventory host that maps to TARGET_HOSTS.

ansible-playbook hyperledger.fabricx.generate_target_hosts

Properties:

Target hosts: localhost.
Nuance: writes target_hosts.mk to project_dir.
Nuance: normally used by make targets, but it can be run directly after inventory changes when you want the generated host-specific Makefile targets refreshed.

openshift/config_hosts_on_macos.yaml¶

openshift/config_hosts_on_macos.yaml configures macOS /etc/hosts entries for OpenShift Route hosts declared in the current inventory. It maps each route host to the control node's default IPv4 address, which is useful for CRC on macOS when route DNS resolves to 127.0.0.1 but containerized clients need a non-loopback address.

ansible-playbook hyperledger.fabricx.openshift.config_hosts_on_macos --ask-become-pass

Properties:

Target hosts: localhost.
Nuance: macOS only; the playbook fails before editing /etc/hosts on other operating systems.
Nuance: /etc/hosts does not support wildcards, so this playbook enumerates route hostnames from inventory and writes them in one managed block.
Nuance: when a CRC hosts section exists, duplicate inventory route hostnames are removed from CRC's 127.0.0.1 lines.
Nuance: rerun the playbook when the Mac's default-route IPv4 address changes or after CRC rewrites /etc/hosts.

Namespaced Playbooks¶

Namespaced playbooks are collections of playbooks tailored for a specific group of hosts:

Namespace	Description
artifacts	Generates network-wide crypto material and the genesis block on the control node. Not tied to a remote host group.
fabric_ca_server	Operates Fabric CA servers and their PostgreSQL databases: start, enroll admins, register identities, stop, teardown, and wipe.
fabric_ca_client	Prepares the Fabric CA client binary used by enrollment and registration tasks.
orderer	Operates Fabric-X orderer components (routers, batchers, consenters, assemblers) targeting the `fabric_x_orderers` group.
committer	Operates Fabric-X committer services and their PostgreSQL or YugabyteDB backend targeting the `fabric_x_committers` group.
fxconfig	Builds, endorses, and submits Fabric-X configuration transactions including namespace creation. Run after `start` during initialization.
loadgen	Operates load generators: start, stop, reconfigure submission rate at runtime, collect metrics and logs.
monitoring	Operates observability components: Prometheus, Grafana, node exporter, PostgreSQL exporter, Elasticsearch, and Jaeger.
yugabyte	Standalone TLS certificate generation for YugabyteDB clusters. Most YugabyteDB lifecycle is handled through the `committer` namespace.