hyperledger.fabricx.configtxgen

Generates Fabric-X configtx.yaml and genesis block artifacts with configtxgen through binary or container entry points.

Role Defaults

See defaults/main.yaml for the generated role defaults and inline variable descriptions.

ansible-doc

You can view the role documentation in your terminal running:

ansible-doc -t role hyperledger.fabricx.configtxgen

Tasks

config/build

Render the configtxgen configuration file

Generate configtx.yaml for Fabric-X genesis block creation. Render the config template from the selected crypto and armageddon artifact roots, then place it under configtxgen_artifacts_dir. The template switches between the binary and container artifact paths based on configtxgen_use_bin.

- name: Render the configtxgen configuration file
  vars:
    # Base build directory for `configtxgen_artifacts_dir`.
    config_build_dir: "/opt/fabricx/build/configtxgen"
    # Directory used for the generated config file and genesis block artifacts.
    configtxgen_artifacts_dir: "{{ config_build_dir }}/configtxgen-artifacts"
    # Dispatch selector for the public start entry point and the config template branch selection. When false, the container path is used.
    configtxgen_use_bin: false
    # Container mount path for fetched crypto artifacts.
    configtxgen_container_crypto_artifacts_dir: /tmp/crypto-artifacts
    # Container mount path for armageddon artifacts.
    configtxgen_armageddon_container_artifacts_dir: /tmp/armageddon-artifacts
    # Generated configuration file name written by `config/build` and mounted by `container/start`.
    configtxgen_config_file: configtx.yaml
    # Shared config binary file name consumed by the config template.
    configtxgen_armageddon_binpb_file: shared_config.binpb
    # Organization map rendered into `configtx.yaml`, keyed by domain, each carrying its own `orderers` and `peers` node lists so a single organization can appear on both sides of the network.
    configtxgen_orgs_by_domain: {}
    # Config profile passed to `configtxgen`.
    configtxgen_profile_id: OrgsChannel
    # Directory containing fetched crypto artifacts used by the binary path and container mounts.
    fetched_artifacts_dir: "/opt/fabricx/artifacts/crypto"
    # Directory containing armageddon artifacts used by the binary path and container mounts.
    armageddon_artifacts_dir: "/opt/fabricx/artifacts/armageddon"
    # Policy type for the orderer organization Readers policy.
    configtxgen_orderer_org_policies_readers_type: Signature
    # Rule for the orderer organization Readers policy. `{msp_id}` is replaced with the organization's own MSP id.
    configtxgen_orderer_org_policies_readers_rule: "OR('{msp_id}.member')"
    # Policy type for the orderer organization Writers policy.
    configtxgen_orderer_org_policies_writers_type: Signature
    # Rule for the orderer organization Writers policy. `{msp_id}` is replaced with the organization's own MSP id.
    configtxgen_orderer_org_policies_writers_rule: "OR('{msp_id}.member')"
    # Policy type for the orderer organization Admins policy.
    configtxgen_orderer_org_policies_admins_type: Signature
    # Rule for the orderer organization Admins policy. `{msp_id}` is replaced with the organization's own MSP id.
    configtxgen_orderer_org_policies_admins_rule: "OR('{msp_id}.admin')"
    # Policy type for the orderer organization Endorsement policy.
    configtxgen_orderer_org_policies_endorsement_type: Signature
    # Rule for the orderer organization Endorsement policy. `{msp_id}` is replaced with the organization's own MSP id.
    configtxgen_orderer_org_policies_endorsement_rule: "OR('{msp_id}.member')"
    # Policy type for the peer organization Readers policy.
    configtxgen_peer_org_policies_readers_type: Signature
    # Rule for the peer organization Readers policy. `{msp_id}` is replaced with the organization's own MSP id.
    configtxgen_peer_org_policies_readers_rule: "OR('{msp_id}.member')"
    # Policy type for the peer organization Writers policy.
    configtxgen_peer_org_policies_writers_type: Signature
    # Rule for the peer organization Writers policy. `{msp_id}` is replaced with the organization's own MSP id.
    configtxgen_peer_org_policies_writers_rule: "OR('{msp_id}.member')"
    # Policy type for the peer organization Admins policy.
    configtxgen_peer_org_policies_admins_type: Signature
    # Rule for the peer organization Admins policy. `{msp_id}` is replaced with the organization's own MSP id.
    configtxgen_peer_org_policies_admins_rule: "OR('{msp_id}.admin')"
    # Policy type for the peer organization Endorsement policy.
    configtxgen_peer_org_policies_endorsement_type: Signature
    # Rule for the peer organization Endorsement policy. `{msp_id}` is replaced with the organization's own MSP id.
    configtxgen_peer_org_policies_endorsement_rule: "OR('{msp_id}.member')"
    # Policy type for the Application Readers policy.
    configtxgen_application_policies_readers_type: ImplicitMeta
    # Rule for the Application Readers policy.
    configtxgen_application_policies_readers_rule: ANY Readers
    # Policy type for the Application Writers policy.
    configtxgen_application_policies_writers_type: ImplicitMeta
    # Rule for the Application Writers policy.
    configtxgen_application_policies_writers_rule: ANY Writers
    # Policy type for the Application Admins policy.
    configtxgen_application_policies_admins_type: ImplicitMeta
    # Rule for the Application Admins policy.
    configtxgen_application_policies_admins_rule: MAJORITY Admins
    # Policy type for the Application Endorsement policy.
    configtxgen_application_policies_endorsement_type: ImplicitMeta
    # Rule for the Application Endorsement policy.
    configtxgen_application_policies_endorsement_rule: MAJORITY Endorsement
    # Policy type for the Application SnapshotEndorsement policy. Required from committer v1.0.5 (fabric-x-common v0.2.9) onward.
    configtxgen_application_policies_snapshot_endorsement_type: Signature
    # Rule for the Application SnapshotEndorsement policy. When left undefined, the rule is generated from `configtxgen_application_policies_snapshot_endorsement_operator` and `configtxgen_application_policies_snapshot_endorsement_ou` as an operator combining every application organization's MSP OU.
    configtxgen_application_policies_snapshot_endorsement_rule: "string"
    # Operator combining every application organization's MSP OU in the generated SnapshotEndorsement rule. Only used when `configtxgen_application_policies_snapshot_endorsement_rule` is left undefined.
    configtxgen_application_policies_snapshot_endorsement_operator: OR
    # MSP OU required from every application organization in the generated SnapshotEndorsement rule. Only used when `configtxgen_application_policies_snapshot_endorsement_rule` is left undefined.
    configtxgen_application_policies_snapshot_endorsement_ou: member
    # Policy type for the Application CheckpointEndorsement policy. Required from committer v1.0.5 (fabric-x-common v0.2.9) onward.
    configtxgen_application_policies_checkpoint_endorsement_type: Signature
    # Rule for the Application CheckpointEndorsement policy. When left undefined, the rule is generated from `configtxgen_application_policies_checkpoint_endorsement_operator` and `configtxgen_application_policies_checkpoint_endorsement_ou` as an operator combining every application organization's MSP OU.
    configtxgen_application_policies_checkpoint_endorsement_rule: "string"
    # Operator combining every application organization's MSP OU in the generated CheckpointEndorsement rule. Only used when `configtxgen_application_policies_checkpoint_endorsement_rule` is left undefined.
    configtxgen_application_policies_checkpoint_endorsement_operator: OR
    # MSP OU required from every application organization in the generated CheckpointEndorsement rule. Only used when `configtxgen_application_policies_checkpoint_endorsement_rule` is left undefined.
    configtxgen_application_policies_checkpoint_endorsement_ou: member
    # Policy type for the Application LifecycleEndorsement policy.
    configtxgen_application_policies_lifecycle_endorsement_type: Signature
    # Rule for the Application LifecycleEndorsement policy. When left undefined, the rule is generated from `configtxgen_application_policies_lifecycle_endorsement_operator` and `configtxgen_application_policies_lifecycle_endorsement_ou` as an operator combining every application organization's MSP OU.
    configtxgen_application_policies_lifecycle_endorsement_rule: "string"
    # Operator combining every application organization's MSP OU in the generated LifecycleEndorsement rule. Only used when `configtxgen_application_policies_lifecycle_endorsement_rule` is left undefined.
    configtxgen_application_policies_lifecycle_endorsement_operator: OR
    # MSP OU required from every application organization in the generated LifecycleEndorsement rule. Only used when `configtxgen_application_policies_lifecycle_endorsement_rule` is left undefined.
    configtxgen_application_policies_lifecycle_endorsement_ou: member
    # Policy type for the Orderer Readers policy.
    configtxgen_orderer_policies_readers_type: ImplicitMeta
    # Rule for the Orderer Readers policy.
    configtxgen_orderer_policies_readers_rule: ANY Readers
    # Policy type for the Orderer Writers policy.
    configtxgen_orderer_policies_writers_type: ImplicitMeta
    # Rule for the Orderer Writers policy.
    configtxgen_orderer_policies_writers_rule: ANY Writers
    # Policy type for the Orderer Admins policy.
    configtxgen_orderer_policies_admins_type: ImplicitMeta
    # Rule for the Orderer Admins policy.
    configtxgen_orderer_policies_admins_rule: MAJORITY Admins
    # Policy type for the Orderer BlockValidation policy.
    configtxgen_orderer_policies_block_validation_type: ImplicitMeta
    # Rule for the Orderer BlockValidation policy.
    configtxgen_orderer_policies_block_validation_rule: MAJORITY Writers
    # Policy type for the Channel Readers policy.
    configtxgen_channel_policies_readers_type: ImplicitMeta
    # Rule for the Channel Readers policy.
    configtxgen_channel_policies_readers_rule: ANY Readers
    # Policy type for the Channel Writers policy.
    configtxgen_channel_policies_writers_type: ImplicitMeta
    # Rule for the Channel Writers policy.
    configtxgen_channel_policies_writers_rule: ANY Writers
    # Policy type for the Channel Admins policy.
    configtxgen_channel_policies_admins_type: ImplicitMeta
    # Rule for the Channel Admins policy.
    configtxgen_channel_policies_admins_rule: MAJORITY Admins
  ansible.builtin.include_role:
    name: hyperledger.fabricx.configtxgen
    tasks_from: config/build

inspect

Detect whether configtxgen needs to run

Fingerprint the rendered configtx.yaml, the Armageddon shared-config binary, and every fetched crypto artifact, then compare it against the fingerprint recorded by the previous run. Publishes configtxgen_input_fingerprint and configtxgen_must_run as facts for start to consume. Without a previous state file there is no baseline, so configtxgen_must_run is set unconditionally, and configtxgen runs once to establish one. Fingerprinting the Armageddon binary rather than only configtx.yaml is what lets a crypto-only change, which does not alter configtx.yaml itself, still trigger regeneration.

- name: Detect whether configtxgen needs to run
  vars:
    # Base build directory for `configtxgen_artifacts_dir`.
    config_build_dir: "/opt/fabricx/build/configtxgen"
    # Directory used for the generated config file and genesis block artifacts.
    configtxgen_artifacts_dir: "{{ config_build_dir }}/configtxgen-artifacts"
    # Generated configuration file name written by `config/build` and mounted by `container/start`.
    configtxgen_config_file: configtx.yaml
    # Genesis block filename written by `configtxgen`, used to detect whether it already exists.
    configtxgen_genesis_block_file: "{{ configtxgen_channel_id }}_block.pb"
    # Filename that tracks a fingerprint of the rendered config, the Armageddon shared-config binary, and the crypto inputs, used to detect changes since the last run.
    configtxgen_state_file: configtxgen-state.yaml
    # Shared config binary file name consumed by the config template.
    configtxgen_armageddon_binpb_file: shared_config.binpb
    # Channel identifier passed to `configtxgen` and used in the output block filename.
    configtxgen_channel_id: "{{ channel_id }}"
    # Channel identifier for `configtxgen_channel_id`.
    channel_id: "fabricx-main-channel"
    # Directory containing armageddon artifacts used by the binary path and container mounts.
    armageddon_artifacts_dir: "/opt/fabricx/artifacts/armageddon"
    # Directory containing fetched crypto artifacts used by the binary path and container mounts.
    fetched_artifacts_dir: "/opt/fabricx/artifacts/crypto"
  ansible.builtin.include_role:
    name: hyperledger.fabricx.configtxgen
    tasks_from: inspect

bin/build

Build the configtxgen binary on the control node

Build the configtxgen binary from the Fabric-X source tree on the control node. The compiled executable is written to cli_bin_dir and reused by the binary start entry point.

- name: Build the configtxgen binary on the control node
  vars:
    # Git host for `configtxgen_bin_package`.
    configtxgen_git_hub_url: github.com
    # Repository path for `configtxgen_bin_package`.
    configtxgen_git_repo: hyperledger/fabric-x
    # Git reference used by the binary build and install entry points.
    configtxgen_git_commit: v1.0.2
    # Go package path for the `configtxgen` source tree.
    configtxgen_source_code_package: tools/configtxgen
    # Executable name used by the binary and container entry points.
    configtxgen_bin_name: configtxgen
    # Directory used as the `configtxgen` binary destination or lookup path.
    cli_bin_dir: "/opt/fabricx/bin"
  ansible.builtin.include_role:
    name: hyperledger.fabricx.configtxgen
    tasks_from: bin/build

bin/install

Install the configtxgen binary into the local bin directory

Install the configtxgen Go package through the shared bin role. The installed executable lands in cli_bin_dir and is then used by the binary start entry point.

- name: Install the configtxgen binary into the local bin directory
  vars:
    # Git host for `configtxgen_bin_package`.
    configtxgen_git_hub_url: github.com
    # Repository path for `configtxgen_bin_package`.
    configtxgen_git_repo: hyperledger/fabric-x
    # Go package path for the `configtxgen` source tree.
    configtxgen_source_code_package: tools/configtxgen
    # Go package reference used by `bin/install`.
    configtxgen_bin_package: "{{ configtxgen_git_hub_url }}/{{ configtxgen_git_repo }}/{{ configtxgen_source_code_package }}"
    # Git reference used by the binary build and install entry points.
    configtxgen_git_commit: v1.0.2
    # Executable name used by the binary and container entry points.
    configtxgen_bin_name: configtxgen
    # Directory used as the `configtxgen` binary destination or lookup path.
    cli_bin_dir: "/opt/fabricx/bin"
  ansible.builtin.include_role:
    name: hyperledger.fabricx.configtxgen
    tasks_from: bin/install

bin/start

Generate a genesis block with the configtxgen binary

Run the local configtxgen binary to generate the channel genesis block. The output block is written beneath configtxgen_artifacts_dir as configtxgen_genesis_block_file; with the bundled example channel, that becomes fabricx-main-channel_block.pb.

- name: Generate a genesis block with the configtxgen binary
  vars:
    # Channel identifier for `configtxgen_channel_id`.
    channel_id: "fabricx-main-channel"
    # Base build directory for `configtxgen_artifacts_dir`.
    config_build_dir: "/opt/fabricx/build/configtxgen"
    # Directory used as the `configtxgen` binary destination or lookup path.
    cli_bin_dir: "/opt/fabricx/bin"
    # Executable name used by the binary and container entry points.
    configtxgen_bin_name: configtxgen
    # Channel identifier passed to `configtxgen` and used in the output block filename.
    configtxgen_channel_id: "{{ channel_id }}"
    # Config profile passed to `configtxgen`.
    configtxgen_profile_id: OrgsChannel
    # Directory used for the generated config file and genesis block artifacts.
    configtxgen_artifacts_dir: "{{ config_build_dir }}/configtxgen-artifacts"
    # Genesis block filename written by `configtxgen`, used to detect whether it already exists.
    configtxgen_genesis_block_file: "{{ configtxgen_channel_id }}_block.pb"
  ansible.builtin.include_role:
    name: hyperledger.fabricx.configtxgen
    tasks_from: bin/start

container/start

Generate a genesis block with the configtxgen container

Run configtxgen in a container to generate the channel genesis block. The container consumes the rendered configtx.yaml plus mounted crypto and armageddon artifacts, then writes configtxgen_genesis_block_file beneath configtxgen_container_artifacts_dir.

- name: Generate a genesis block with the configtxgen container
  vars:
    # Channel identifier for `configtxgen_channel_id`.
    channel_id: "fabricx-main-channel"
    # Base build directory for `configtxgen_artifacts_dir`.
    config_build_dir: "/opt/fabricx/build/configtxgen"
    # Directory used for the generated config file and genesis block artifacts.
    configtxgen_artifacts_dir: "{{ config_build_dir }}/configtxgen-artifacts"
    # Container name used by the container entry point.
    configtxgen_container_name: configtxgen
    # Image registry endpoint for `configtxgen_image`.
    configtxgen_registry_endpoint: "{{ lookup('env', 'CONFIGTXGEN_REGISTRY_ENDPOINT') or 'docker.io/hyperledger' }}"
    # Image repository name for `configtxgen_image`.
    configtxgen_image_name: fabric-x-tools
    # Image tag for `configtxgen_image`.
    configtxgen_image_tag: 1.0.2
    # Full container image reference for `configtxgen`.
    configtxgen_image: "{{ configtxgen_registry_endpoint }}/{{ configtxgen_image_name }}:{{ configtxgen_image_tag }}"
    # Executable name used by the binary and container entry points.
    configtxgen_bin_name: configtxgen
    # Channel identifier passed to `configtxgen` and used in the output block filename.
    configtxgen_channel_id: "{{ channel_id }}"
    # Config profile passed to `configtxgen`.
    configtxgen_profile_id: OrgsChannel
    # Container mount path for `configtx.yaml`.
    configtxgen_container_config_dir: /tmp/config
    # Container output directory used by `container/start`.
    configtxgen_container_artifacts_dir: /tmp/configtxgen-artifacts
    # Generated configuration file name written by `config/build` and mounted by `container/start`.
    configtxgen_config_file: configtx.yaml
    # Genesis block filename written by `configtxgen`, used to detect whether it already exists.
    configtxgen_genesis_block_file: "{{ configtxgen_channel_id }}_block.pb"
    # Container mount path for armageddon artifacts.
    configtxgen_armageddon_container_artifacts_dir: /tmp/armageddon-artifacts
    # Container mount path for fetched crypto artifacts.
    configtxgen_container_crypto_artifacts_dir: /tmp/crypto-artifacts
    # Directory containing armageddon artifacts used by the binary path and container mounts.
    armageddon_artifacts_dir: "/opt/fabricx/artifacts/armageddon"
    # Directory containing fetched crypto artifacts used by the binary path and container mounts.
    fetched_artifacts_dir: "/opt/fabricx/artifacts/crypto"
  ansible.builtin.include_role:
    name: hyperledger.fabricx.configtxgen
    tasks_from: container/start

start

Dispatch genesis block generation to binary or container

Inspect the existing genesis block, then select the binary or container execution path for configtxgen, based on configtxgen_use_bin, only when the inputs changed since the last run. Both execution paths consume the rendered configuration and emit the same configtxgen_genesis_block_file artifact name.

- name: Dispatch genesis block generation to binary or container
  vars:
    # Dispatch selector for the public start entry point and the config template branch selection. When false, the container path is used.
    configtxgen_use_bin: false
    # Base build directory for `configtxgen_artifacts_dir`.
    config_build_dir: "/opt/fabricx/build/configtxgen"
    # Directory used for the generated config file and genesis block artifacts.
    configtxgen_artifacts_dir: "{{ config_build_dir }}/configtxgen-artifacts"
    # Filename that tracks a fingerprint of the rendered config, the Armageddon shared-config binary, and the crypto inputs, used to detect changes since the last run.
    configtxgen_state_file: configtxgen-state.yaml
  ansible.builtin.include_role:
    name: hyperledger.fabricx.configtxgen
    tasks_from: start