hyperledger.fabricx.fxadmin¶
Fetches and decodes the Fabric-X channel configuration, patches it, and drives the fxadmin endorse/merge/prepare/submit flow for live network reconfigurations.
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:
Tasks¶
bin/build¶
Build the fxadmin binary
Builds the fxadmin Go binary from the configured Fabric-X source package by delegating compilation to the shared bin role.
- name: Build the fxadmin binary
vars:
# Defines the fxadmin binary name.
fxadmin_bin_name: fxadmin
# Selects the Git ref used by build and install workflows.
fxadmin_git_commit: v1.0.2
# Defines the Git host used to resolve the Fabric-X source repository.
fxadmin_git_hub_url: github.com
# Defines the Fabric-X source repository path.
fxadmin_git_repo: hyperledger/fabric-x
# Defines the Go package path containing the fxadmin source code.
fxadmin_source_code_package: tools/fxadmin
ansible.builtin.include_role:
name: hyperledger.fabricx.fxadmin
tasks_from: bin/build
bin/compute_update¶
Compute a ConfigUpdate with the fxadmin binary
Runs fxadmin compute-update with the control-node fxadmin binary to compute the delta between the current and modified channel configuration.
- name: Compute a ConfigUpdate with the fxadmin binary
vars:
# Defines the channel identifier used to derive the genesis block filename.
channel_id: "fabricx-main-channel"
# Sets the control-node directory searched for CLI binaries used by the steps that run on the control node.
cli_bin_dir: "string"
# Defines the control-node directory where configtxgen writes the genesis block.
configtxgen_artifacts_dir: "/tmp/fabricx/config-build/configtxgen-artifacts"
# Defines the fxadmin binary name.
fxadmin_bin_name: fxadmin
# Defines the control-node reference configuration block fxadmin uses for endpoint discovery, defaulting to the genesis block produced by configtxgen.
fxadmin_current_block: "{{ configtxgen_artifacts_dir }}/{{ channel_id }}_block.pb"
# Defines the local decoded current channel configuration JSON file.
fxadmin_current_config_json: "/tmp/fabricx/config-build/fxadmin-artifacts/current_config.json"
# Defines the local modified channel configuration JSON file produced by `patch_config_value` and consumed by `compute_update`.
fxadmin_modified_config_json: "/tmp/fabricx/config-build/fxadmin-artifacts/modified_config.json"
# Defines the output artifact path written by the current fxadmin command, local to the host the task runs on.
fxadmin_output: "/tmp/fabricx/config-build/fxadmin-artifacts/config_update.pb"
ansible.builtin.include_role:
name: hyperledger.fabricx.fxadmin
tasks_from: bin/compute_update
bin/decode¶
Decode a configuration block with the fxadmin binary
Runs fxadmin decode with the control-node fxadmin binary to convert a protobuf configuration block into JSON.
- name: Decode a configuration block with the fxadmin binary
vars:
# Sets the control-node directory searched for CLI binaries used by the steps that run on the control node.
cli_bin_dir: "string"
# Defines the fxadmin binary name.
fxadmin_bin_name: fxadmin
# Defines the local protobuf-encoded configuration block to decode into JSON.
fxadmin_config_block: "/tmp/fabricx/config-build/fxadmin-artifacts/config.pb"
# Defines the output artifact path written by the current fxadmin command, local to the host the task runs on.
fxadmin_output: "/tmp/fabricx/config-build/fxadmin-artifacts/config_update.pb"
ansible.builtin.include_role:
name: hyperledger.fabricx.fxadmin
tasks_from: bin/decode
bin/follow¶
Follow the ledger with the fxadmin binary
Runs fxadmin follow on the host with the rendered admin configuration to confirm a submitted configuration update commits.
- name: Follow the ledger with the fxadmin binary
vars:
# Defines the fxadmin binary name.
fxadmin_bin_name: fxadmin
# Defines the fxadmin admin configuration filename.
fxadmin_config_file: admin.yaml
# Defines how long `follow` waits for the submitted configuration update to commit.
fxadmin_follow_timeout: 60s
# Defines the latest channel configuration block on the host, as written by `ledger/config_latest`, that fxadmin uses for endpoint discovery.
fxadmin_latest_block: "/tmp/fabricx/orderer-consenter-1/config/fxadmin/config.pb"
# Defines the output artifact path written by the current fxadmin command, local to the host the task runs on.
fxadmin_output: "/tmp/fabricx/config-build/fxadmin-artifacts/config_update.pb"
# Defines the fxadmin remote configuration directory.
fxadmin_remote_config_dir: "{{ remote_config_dir }}/fxadmin"
# Provides the base remote configuration directory used by the role.
remote_config_dir: "/opt/hyperledger/fabricx/config"
ansible.builtin.include_role:
name: hyperledger.fabricx.fxadmin
tasks_from: bin/follow
bin/install¶
Install the fxadmin binary
Installs the fxadmin Go package from the configured Fabric-X source package by delegating to the shared bin role.
- name: Install the fxadmin binary
vars:
# Defines the fxadmin binary name.
fxadmin_bin_name: fxadmin
# Defines the Go package path used to install fxadmin.
fxadmin_bin_package: "{{ fxadmin_git_hub_url }}/{{ fxadmin_git_repo }}/{{ fxadmin_source_code_package }}"
# Selects the Git ref used by build and install workflows.
fxadmin_git_commit: v1.0.2
# Defines the Git host used to resolve the Fabric-X source repository.
fxadmin_git_hub_url: github.com
# Defines the Fabric-X source repository path.
fxadmin_git_repo: hyperledger/fabric-x
# Defines the Go package path containing the fxadmin source code.
fxadmin_source_code_package: tools/fxadmin
ansible.builtin.include_role:
name: hyperledger.fabricx.fxadmin
tasks_from: bin/install
bin/ledger/config_latest¶
Fetch the latest channel configuration block with the fxadmin binary
Runs fxadmin ledger config latest on the host with the rendered admin configuration to fetch the current channel configuration block.
- name: Fetch the latest channel configuration block with the fxadmin binary
vars:
# Defines the fxadmin binary name.
fxadmin_bin_name: fxadmin
# Defines the fxadmin admin configuration filename.
fxadmin_config_file: admin.yaml
# Defines the output artifact path written by the current fxadmin command, local to the host the task runs on.
fxadmin_output: "/tmp/fabricx/config-build/fxadmin-artifacts/config_update.pb"
# Defines the fxadmin remote configuration directory.
fxadmin_remote_config_dir: "{{ remote_config_dir }}/fxadmin"
# Provides the base remote configuration directory used by the role.
remote_config_dir: "/opt/hyperledger/fabricx/config"
ansible.builtin.include_role:
name: hyperledger.fabricx.fxadmin
tasks_from: bin/ledger/config_latest
bin/rm¶
Remove the fxadmin binary
Removes the fxadmin binary from the managed host by delegating cleanup to the shared bin role.
- name: Remove the fxadmin binary
vars:
# Defines the fxadmin binary name.
fxadmin_bin_name: fxadmin
ansible.builtin.include_role:
name: hyperledger.fabricx.fxadmin
tasks_from: bin/rm
bin/transfer¶
Transfer the fxadmin binary
Transfers the previously built fxadmin binary to the managed host by delegating to the shared bin role.
- name: Transfer the fxadmin binary
vars:
# Defines the fxadmin binary name.
fxadmin_bin_name: fxadmin
ansible.builtin.include_role:
name: hyperledger.fabricx.fxadmin
tasks_from: bin/transfer
bin/tx/endorse¶
Endorse a ConfigUpdate with the fxadmin binary
Endorses the staged ConfigUpdate with the fxadmin binary and rendered admin configuration on the host.
- name: Endorse a ConfigUpdate with the fxadmin binary
vars:
# Defines the fxadmin binary name.
fxadmin_bin_name: fxadmin
# Defines the fxadmin admin configuration filename.
fxadmin_config_file: admin.yaml
# Defines the output artifact path written by the current fxadmin command, local to the host the task runs on.
fxadmin_output: "/tmp/fabricx/config-build/fxadmin-artifacts/config_update.pb"
# Defines the fxadmin remote configuration directory.
fxadmin_remote_config_dir: "{{ remote_config_dir }}/fxadmin"
# Provides the base remote configuration directory used by the role.
remote_config_dir: "/opt/hyperledger/fabricx/config"
ansible.builtin.include_role:
name: hyperledger.fabricx.fxadmin
tasks_from: bin/tx/endorse
bin/tx/merge¶
Merge endorsements with the fxadmin binary
Merges the staged endorsements into a single ConfigUpdateEnvelope with the control-node fxadmin binary.
- name: Merge endorsements with the fxadmin binary
vars:
# Sets the control-node directory searched for CLI binaries used by the steps that run on the control node.
cli_bin_dir: "string"
# Defines the fxadmin binary name.
fxadmin_bin_name: fxadmin
# Defines the output artifact path written by the current fxadmin command, local to the host the task runs on.
fxadmin_output: "/tmp/fabricx/config-build/fxadmin-artifacts/config_update.pb"
ansible.builtin.include_role:
name: hyperledger.fabricx.fxadmin
tasks_from: bin/tx/merge
bin/tx/prepare¶
Prepare a transaction with the fxadmin binary
Runs fxadmin tx prepare on the host to turn the merged, endorsed ConfigUpdate envelope into a submittable transaction.
- name: Prepare a transaction with the fxadmin binary
vars:
# Defines the fxadmin binary name.
fxadmin_bin_name: fxadmin
# Defines the fxadmin admin configuration filename.
fxadmin_config_file: admin.yaml
# Defines the output artifact path written by the current fxadmin command, local to the host the task runs on.
fxadmin_output: "/tmp/fabricx/config-build/fxadmin-artifacts/config_update.pb"
# Defines the fxadmin remote configuration directory.
fxadmin_remote_config_dir: "{{ remote_config_dir }}/fxadmin"
# Provides the base remote configuration directory used by the role.
remote_config_dir: "/opt/hyperledger/fabricx/config"
ansible.builtin.include_role:
name: hyperledger.fabricx.fxadmin
tasks_from: bin/tx/prepare
bin/tx/submit¶
Submit a transaction with the fxadmin binary
Runs fxadmin tx submit on the host with the rendered admin configuration to broadcast the prepared transaction.
- name: Submit a transaction with the fxadmin binary
vars:
# Defines the fxadmin binary name.
fxadmin_bin_name: fxadmin
# Defines the fxadmin admin configuration filename.
fxadmin_config_file: admin.yaml
# Defines the prepared transaction file to submit, on the host that submits it.
fxadmin_config_tx: "/tmp/fabricx/orderer-consenter-1/config/fxadmin/config_tx.pb"
# Defines the latest channel configuration block on the host, as written by `ledger/config_latest`, that fxadmin uses for endpoint discovery.
fxadmin_latest_block: "/tmp/fabricx/orderer-consenter-1/config/fxadmin/config.pb"
# Defines the fxadmin remote configuration directory.
fxadmin_remote_config_dir: "{{ remote_config_dir }}/fxadmin"
# Provides the base remote configuration directory used by the role.
remote_config_dir: "/opt/hyperledger/fabricx/config"
ansible.builtin.include_role:
name: hyperledger.fabricx.fxadmin
tasks_from: bin/tx/submit
compute_update¶
Compute a ConfigUpdate
Dispatches ConfigUpdate computation to either the host binary or a transient container based on fxadmin_use_bin.
- name: Compute a ConfigUpdate
vars:
# Defines the output artifact path written by the current fxadmin command, local to the host the task runs on.
fxadmin_output: "/tmp/fabricx/config-build/fxadmin-artifacts/config_update.pb"
# Selects the host-binary workflow instead of the container workflow.
fxadmin_use_bin: false
ansible.builtin.include_role:
name: hyperledger.fabricx.fxadmin
tasks_from: compute_update
config/mtls/transfer¶
Transfer fxadmin mTLS client material
Copies the client certificate and key consumed by fxadmin for mTLS connections into fxadmin_remote_config_dir/mtls.
- name: Transfer fxadmin mTLS client material
vars:
# Defines the certificate path on the host, reused from the node's own TLS identity, that fxadmin presents for mTLS.
fxadmin_mtls_client_cert_path: "{{ remote_config_dir }}/tls/server.crt"
# Defines the private key path on the host, reused from the node's own TLS identity, that fxadmin presents for mTLS.
fxadmin_mtls_client_key_path: "{{ remote_config_dir }}/tls/server.key"
# Defines the fxadmin remote configuration directory.
fxadmin_remote_config_dir: "{{ remote_config_dir }}/fxadmin"
# Provides the base remote configuration directory used by the role.
remote_config_dir: "/opt/hyperledger/fabricx/config"
ansible.builtin.include_role:
name: hyperledger.fabricx.fxadmin
tasks_from: config/mtls/transfer
config/transfer¶
Transfer fxadmin configuration material
Creates the remote fxadmin configuration directory, renders the admin configuration file, and copies the MSP material and, when the target network enables mTLS, the client certificate already present on the host.
- name: Transfer fxadmin configuration material
vars:
# Defines the fxadmin admin configuration filename.
fxadmin_config_file: admin.yaml
# Defines the configuration directory mounted inside the fxadmin container.
fxadmin_container_config_dir: /config
# Defines the MSP directory of the organization user on the host, produced by the component's own crypto setup and copied into the fxadmin configuration directory.
fxadmin_msp_config_path: "{{ remote_config_dir }}/users/ordererorg1-admin@ordererorg1.example.com/msp"
# Defines the MSP identifier written into the rendered admin configuration.
fxadmin_msp_id: "{{ organization.name }}MSP"
# Defines the fxadmin remote configuration directory.
fxadmin_remote_config_dir: "{{ remote_config_dir }}/fxadmin"
# Selects the host-binary workflow instead of the container workflow.
fxadmin_use_bin: false
# Enables mTLS material rendering and transfer for fxadmin, mirroring the target network's mTLS setting.
fxadmin_use_mtls: false
# Enables TLS in the rendered admin configuration, mirroring the target network's TLS setting.
fxadmin_use_tls: false
# Provides organization metadata, including the `organization.user` identity that every fxadmin operation signs with.
organization:
name: "OrdererOrg1"
domain: "ordererorg1.example.com"
user:
name: "ordererorg1-admin"
secret: "ordererorg1-adminPWD"
type: "admin"
# Provides the base remote configuration directory used by the role.
remote_config_dir: "/opt/hyperledger/fabricx/config"
ansible.builtin.include_role:
name: hyperledger.fabricx.fxadmin
tasks_from: config/transfer
container/compute_update¶
Compute a ConfigUpdate with the fxadmin container
Mounts the current and modified configuration JSON files and the reference block read-only into a transient container that runs fxadmin compute-update.
- name: Compute a ConfigUpdate with the fxadmin container
vars:
# Defines the channel identifier used to derive the genesis block filename.
channel_id: "fabricx-main-channel"
# Defines the control-node directory where configtxgen writes the genesis block.
configtxgen_artifacts_dir: "/tmp/fabricx/config-build/configtxgen-artifacts"
# Defines the fxadmin binary name.
fxadmin_bin_name: fxadmin
# Defines the base container name used by fxadmin workflows, suffixed per host so parallel runs never collide.
fxadmin_container_name: "fxadmin-{{ inventory_hostname }}"
# Defines the control-node reference configuration block fxadmin uses for endpoint discovery, defaulting to the genesis block produced by configtxgen.
fxadmin_current_block: "{{ configtxgen_artifacts_dir }}/{{ channel_id }}_block.pb"
# Defines the local decoded current channel configuration JSON file.
fxadmin_current_config_json: "/tmp/fabricx/config-build/fxadmin-artifacts/current_config.json"
# Defines the fxadmin container image.
fxadmin_image: "{{ fxadmin_registry_endpoint }}/{{ fxadmin_image_name }}:{{ fxadmin_image_tag }}"
# Defines the image name used by the fxadmin container image.
fxadmin_image_name: fabric-x-tools
# Defines the image tag used by the fxadmin container image, which must be at least 1.0.2 because earlier tags do not bundle the fxadmin binary.
fxadmin_image_tag: 1.0.2
# Defines the local modified channel configuration JSON file produced by `patch_config_value` and consumed by `compute_update`.
fxadmin_modified_config_json: "/tmp/fabricx/config-build/fxadmin-artifacts/modified_config.json"
# Defines the output artifact path written by the current fxadmin command, local to the host the task runs on.
fxadmin_output: "/tmp/fabricx/config-build/fxadmin-artifacts/config_update.pb"
# Defines the registry endpoint used by the fxadmin container image.
fxadmin_registry_endpoint: "{{ lookup('env', 'FXADMIN_REGISTRY_ENDPOINT') or 'docker.io/hyperledger' }}"
ansible.builtin.include_role:
name: hyperledger.fabricx.fxadmin
tasks_from: container/compute_update
container/decode¶
Decode a configuration block with the fxadmin container
Stages the configuration block into the output directory, then runs fxadmin decode in a transient container that mounts it.
- name: Decode a configuration block with the fxadmin container
vars:
# Defines the fxadmin binary name.
fxadmin_bin_name: fxadmin
# Defines the local protobuf-encoded configuration block to decode into JSON.
fxadmin_config_block: "/tmp/fabricx/config-build/fxadmin-artifacts/config.pb"
# Defines the base container name used by fxadmin workflows, suffixed per host so parallel runs never collide.
fxadmin_container_name: "fxadmin-{{ inventory_hostname }}"
# Defines the fxadmin container image.
fxadmin_image: "{{ fxadmin_registry_endpoint }}/{{ fxadmin_image_name }}:{{ fxadmin_image_tag }}"
# Defines the image name used by the fxadmin container image.
fxadmin_image_name: fabric-x-tools
# Defines the image tag used by the fxadmin container image, which must be at least 1.0.2 because earlier tags do not bundle the fxadmin binary.
fxadmin_image_tag: 1.0.2
# Defines the output artifact path written by the current fxadmin command, local to the host the task runs on.
fxadmin_output: "/tmp/fabricx/config-build/fxadmin-artifacts/config_update.pb"
# Defines the registry endpoint used by the fxadmin container image.
fxadmin_registry_endpoint: "{{ lookup('env', 'FXADMIN_REGISTRY_ENDPOINT') or 'docker.io/hyperledger' }}"
ansible.builtin.include_role:
name: hyperledger.fabricx.fxadmin
tasks_from: container/decode
container/follow¶
Follow the ledger with the fxadmin container
Mounts the rendered admin configuration and the latest block into a transient fxadmin container and runs fxadmin follow.
- name: Follow the ledger with the fxadmin container
vars:
# Defines the fxadmin binary name.
fxadmin_bin_name: fxadmin
# Defines the fxadmin admin configuration filename.
fxadmin_config_file: admin.yaml
# Defines the configuration directory mounted inside the fxadmin container.
fxadmin_container_config_dir: /config
# Defines the base container name used by fxadmin workflows, suffixed per host so parallel runs never collide.
fxadmin_container_name: "fxadmin-{{ inventory_hostname }}"
# Defines how long `follow` waits for the submitted configuration update to commit.
fxadmin_follow_timeout: 60s
# Defines the fxadmin container image.
fxadmin_image: "{{ fxadmin_registry_endpoint }}/{{ fxadmin_image_name }}:{{ fxadmin_image_tag }}"
# Defines the image name used by the fxadmin container image.
fxadmin_image_name: fabric-x-tools
# Defines the image tag used by the fxadmin container image, which must be at least 1.0.2 because earlier tags do not bundle the fxadmin binary.
fxadmin_image_tag: 1.0.2
# Defines the latest channel configuration block on the host, as written by `ledger/config_latest`, that fxadmin uses for endpoint discovery.
fxadmin_latest_block: "/tmp/fabricx/orderer-consenter-1/config/fxadmin/config.pb"
# Defines the output artifact path written by the current fxadmin command, local to the host the task runs on.
fxadmin_output: "/tmp/fabricx/config-build/fxadmin-artifacts/config_update.pb"
# Defines the registry endpoint used by the fxadmin container image.
fxadmin_registry_endpoint: "{{ lookup('env', 'FXADMIN_REGISTRY_ENDPOINT') or 'docker.io/hyperledger' }}"
# Defines the fxadmin remote configuration directory.
fxadmin_remote_config_dir: "{{ remote_config_dir }}/fxadmin"
# Provides the base remote configuration directory used by the role.
remote_config_dir: "/opt/hyperledger/fabricx/config"
ansible.builtin.include_role:
name: hyperledger.fabricx.fxadmin
tasks_from: container/follow
container/ledger/config_latest¶
Fetch the latest channel configuration block with the fxadmin container
Mounts the rendered admin configuration and the staged reference block into a transient fxadmin container and runs fxadmin ledger config latest.
- name: Fetch the latest channel configuration block with the fxadmin container
vars:
# Defines the fxadmin binary name.
fxadmin_bin_name: fxadmin
# Defines the fxadmin admin configuration filename.
fxadmin_config_file: admin.yaml
# Defines the configuration directory mounted inside the fxadmin container.
fxadmin_container_config_dir: /config
# Defines the base container name used by fxadmin workflows, suffixed per host so parallel runs never collide.
fxadmin_container_name: "fxadmin-{{ inventory_hostname }}"
# Defines the fxadmin container image.
fxadmin_image: "{{ fxadmin_registry_endpoint }}/{{ fxadmin_image_name }}:{{ fxadmin_image_tag }}"
# Defines the image name used by the fxadmin container image.
fxadmin_image_name: fabric-x-tools
# Defines the image tag used by the fxadmin container image, which must be at least 1.0.2 because earlier tags do not bundle the fxadmin binary.
fxadmin_image_tag: 1.0.2
# Defines the output artifact path written by the current fxadmin command, local to the host the task runs on.
fxadmin_output: "/tmp/fabricx/config-build/fxadmin-artifacts/config_update.pb"
# Defines the registry endpoint used by the fxadmin container image.
fxadmin_registry_endpoint: "{{ lookup('env', 'FXADMIN_REGISTRY_ENDPOINT') or 'docker.io/hyperledger' }}"
# Defines the fxadmin remote configuration directory.
fxadmin_remote_config_dir: "{{ remote_config_dir }}/fxadmin"
# Provides the base remote configuration directory used by the role.
remote_config_dir: "/opt/hyperledger/fabricx/config"
ansible.builtin.include_role:
name: hyperledger.fabricx.fxadmin
tasks_from: container/ledger/config_latest
container/tx/endorse¶
Endorse a ConfigUpdate with the fxadmin container
Mounts the staged ConfigUpdate and the rendered admin configuration into a transient fxadmin container that writes the endorsement.
- name: Endorse a ConfigUpdate with the fxadmin container
vars:
# Defines the fxadmin binary name.
fxadmin_bin_name: fxadmin
# Defines the fxadmin admin configuration filename.
fxadmin_config_file: admin.yaml
# Defines the configuration directory mounted inside the fxadmin container.
fxadmin_container_config_dir: /config
# Defines the base container name used by fxadmin workflows, suffixed per host so parallel runs never collide.
fxadmin_container_name: "fxadmin-{{ inventory_hostname }}"
# Defines the fxadmin container image.
fxadmin_image: "{{ fxadmin_registry_endpoint }}/{{ fxadmin_image_name }}:{{ fxadmin_image_tag }}"
# Defines the image name used by the fxadmin container image.
fxadmin_image_name: fabric-x-tools
# Defines the image tag used by the fxadmin container image, which must be at least 1.0.2 because earlier tags do not bundle the fxadmin binary.
fxadmin_image_tag: 1.0.2
# Defines the output artifact path written by the current fxadmin command, local to the host the task runs on.
fxadmin_output: "/tmp/fabricx/config-build/fxadmin-artifacts/config_update.pb"
# Defines the registry endpoint used by the fxadmin container image.
fxadmin_registry_endpoint: "{{ lookup('env', 'FXADMIN_REGISTRY_ENDPOINT') or 'docker.io/hyperledger' }}"
# Defines the fxadmin remote configuration directory.
fxadmin_remote_config_dir: "{{ remote_config_dir }}/fxadmin"
# Provides the base remote configuration directory used by the role.
remote_config_dir: "/opt/hyperledger/fabricx/config"
ansible.builtin.include_role:
name: hyperledger.fabricx.fxadmin
tasks_from: container/tx/endorse
container/tx/merge¶
Merge endorsements with the fxadmin container
Mounts the staged endorsements directory into a transient fxadmin container and writes a merged ConfigUpdateEnvelope.
- name: Merge endorsements with the fxadmin container
vars:
# Defines the fxadmin binary name.
fxadmin_bin_name: fxadmin
# Defines the base container name used by fxadmin workflows, suffixed per host so parallel runs never collide.
fxadmin_container_name: "fxadmin-{{ inventory_hostname }}"
# Defines the local directory that collects one endorsement file per required organization before merging.
fxadmin_endorsements_dir: "/tmp/fabricx/config-build/fxadmin-artifacts/endorsements"
# Defines the fxadmin container image.
fxadmin_image: "{{ fxadmin_registry_endpoint }}/{{ fxadmin_image_name }}:{{ fxadmin_image_tag }}"
# Defines the image name used by the fxadmin container image.
fxadmin_image_name: fabric-x-tools
# Defines the image tag used by the fxadmin container image, which must be at least 1.0.2 because earlier tags do not bundle the fxadmin binary.
fxadmin_image_tag: 1.0.2
# Defines the output artifact path written by the current fxadmin command, local to the host the task runs on.
fxadmin_output: "/tmp/fabricx/config-build/fxadmin-artifacts/config_update.pb"
# Defines the registry endpoint used by the fxadmin container image.
fxadmin_registry_endpoint: "{{ lookup('env', 'FXADMIN_REGISTRY_ENDPOINT') or 'docker.io/hyperledger' }}"
ansible.builtin.include_role:
name: hyperledger.fabricx.fxadmin
tasks_from: container/tx/merge
container/tx/prepare¶
Prepare a transaction with the fxadmin container
Mounts the staged endorsed ConfigUpdate and the rendered admin configuration into a transient fxadmin container that runs fxadmin tx prepare.
- name: Prepare a transaction with the fxadmin container
vars:
# Defines the fxadmin binary name.
fxadmin_bin_name: fxadmin
# Defines the fxadmin admin configuration filename.
fxadmin_config_file: admin.yaml
# Defines the configuration directory mounted inside the fxadmin container.
fxadmin_container_config_dir: /config
# Defines the base container name used by fxadmin workflows, suffixed per host so parallel runs never collide.
fxadmin_container_name: "fxadmin-{{ inventory_hostname }}"
# Defines the fxadmin container image.
fxadmin_image: "{{ fxadmin_registry_endpoint }}/{{ fxadmin_image_name }}:{{ fxadmin_image_tag }}"
# Defines the image name used by the fxadmin container image.
fxadmin_image_name: fabric-x-tools
# Defines the image tag used by the fxadmin container image, which must be at least 1.0.2 because earlier tags do not bundle the fxadmin binary.
fxadmin_image_tag: 1.0.2
# Defines the output artifact path written by the current fxadmin command, local to the host the task runs on.
fxadmin_output: "/tmp/fabricx/config-build/fxadmin-artifacts/config_update.pb"
# Defines the registry endpoint used by the fxadmin container image.
fxadmin_registry_endpoint: "{{ lookup('env', 'FXADMIN_REGISTRY_ENDPOINT') or 'docker.io/hyperledger' }}"
# Defines the fxadmin remote configuration directory.
fxadmin_remote_config_dir: "{{ remote_config_dir }}/fxadmin"
# Provides the base remote configuration directory used by the role.
remote_config_dir: "/opt/hyperledger/fabricx/config"
ansible.builtin.include_role:
name: hyperledger.fabricx.fxadmin
tasks_from: container/tx/prepare
container/tx/submit¶
Submit a transaction with the fxadmin container
Mounts the transaction, the latest block and the rendered admin configuration into a transient fxadmin container that runs fxadmin tx submit.
- name: Submit a transaction with the fxadmin container
vars:
# Defines the fxadmin binary name.
fxadmin_bin_name: fxadmin
# Defines the fxadmin admin configuration filename.
fxadmin_config_file: admin.yaml
# Defines the prepared transaction file to submit, on the host that submits it.
fxadmin_config_tx: "/tmp/fabricx/orderer-consenter-1/config/fxadmin/config_tx.pb"
# Defines the configuration directory mounted inside the fxadmin container.
fxadmin_container_config_dir: /config
# Defines the base container name used by fxadmin workflows, suffixed per host so parallel runs never collide.
fxadmin_container_name: "fxadmin-{{ inventory_hostname }}"
# Defines the fxadmin container image.
fxadmin_image: "{{ fxadmin_registry_endpoint }}/{{ fxadmin_image_name }}:{{ fxadmin_image_tag }}"
# Defines the image name used by the fxadmin container image.
fxadmin_image_name: fabric-x-tools
# Defines the image tag used by the fxadmin container image, which must be at least 1.0.2 because earlier tags do not bundle the fxadmin binary.
fxadmin_image_tag: 1.0.2
# Defines the latest channel configuration block on the host, as written by `ledger/config_latest`, that fxadmin uses for endpoint discovery.
fxadmin_latest_block: "/tmp/fabricx/orderer-consenter-1/config/fxadmin/config.pb"
# Defines the registry endpoint used by the fxadmin container image.
fxadmin_registry_endpoint: "{{ lookup('env', 'FXADMIN_REGISTRY_ENDPOINT') or 'docker.io/hyperledger' }}"
# Defines the fxadmin remote configuration directory.
fxadmin_remote_config_dir: "{{ remote_config_dir }}/fxadmin"
# Provides the base remote configuration directory used by the role.
remote_config_dir: "/opt/hyperledger/fabricx/config"
ansible.builtin.include_role:
name: hyperledger.fabricx.fxadmin
tasks_from: container/tx/submit
decode¶
Decode a configuration block
Dispatches configuration block decoding to either the host binary or a transient container based on fxadmin_use_bin.
- name: Decode a configuration block
vars:
# Defines the output artifact path written by the current fxadmin command, local to the host the task runs on.
fxadmin_output: "/tmp/fabricx/config-build/fxadmin-artifacts/config_update.pb"
# Selects the host-binary workflow instead of the container workflow.
fxadmin_use_bin: false
ansible.builtin.include_role:
name: hyperledger.fabricx.fxadmin
tasks_from: decode
follow¶
Follow the ledger until a configuration update commits
Dispatches ledger following to either the host binary or a transient container based on fxadmin_use_bin, then fetches the committed block back to the control node.
- name: Follow the ledger until a configuration update commits
vars:
# Defines the output artifact path written by the current fxadmin command, local to the host the task runs on.
fxadmin_output: "/tmp/fabricx/config-build/fxadmin-artifacts/config_update.pb"
# Defines the control-node path that `fxadmin_output` is fetched back to once the command completes on a remote host.
fxadmin_output_fetch_dest: "/tmp/fabricx/config-build/fxadmin-artifacts/config_tx.pb"
# Selects the host-binary workflow instead of the container workflow.
fxadmin_use_bin: false
ansible.builtin.include_role:
name: hyperledger.fabricx.fxadmin
tasks_from: follow
ledger/config_latest¶
Fetch the latest channel configuration block
Dispatches fetching the latest channel configuration block to either the host binary or a transient container based on fxadmin_use_bin, then fetches it back to the control node.
- name: Fetch the latest channel configuration block
vars:
# Defines the channel identifier used to derive the genesis block filename.
channel_id: "fabricx-main-channel"
# Defines the control-node directory where configtxgen writes the genesis block.
configtxgen_artifacts_dir: "/tmp/fabricx/config-build/configtxgen-artifacts"
# Defines the control-node reference configuration block fxadmin uses for endpoint discovery, defaulting to the genesis block produced by configtxgen.
fxadmin_current_block: "{{ configtxgen_artifacts_dir }}/{{ channel_id }}_block.pb"
# Defines the output artifact path written by the current fxadmin command, local to the host the task runs on.
fxadmin_output: "/tmp/fabricx/config-build/fxadmin-artifacts/config_update.pb"
# Defines the control-node path that `fxadmin_output` is fetched back to once the command completes on a remote host.
fxadmin_output_fetch_dest: "/tmp/fabricx/config-build/fxadmin-artifacts/config_tx.pb"
# Selects the host-binary workflow instead of the container workflow.
fxadmin_use_bin: false
ansible.builtin.include_role:
name: hyperledger.fabricx.fxadmin
tasks_from: ledger/config_latest
patch_config_value¶
Patch a decoded channel configuration
Applies a caller-supplied jq filter to the decoded current channel configuration JSON on the control node, and writes the resulting modified configuration JSON. Contains no business logic of its own, so the caller supplies the exact change as a jq filter. Requires jq on the control node.
- name: Patch a decoded channel configuration
vars:
# Defines the local decoded current channel configuration JSON file.
fxadmin_current_config_json: "/tmp/fabricx/config-build/fxadmin-artifacts/current_config.json"
# Defines the values passed to `fxadmin_jq_filter`, which reads them as `$args`.
fxadmin_jq_args: {}
# Defines the jq filter applied to the decoded current configuration to produce the modified configuration.
fxadmin_jq_filter: ".channel_group.groups.Orderer.values.ConsensusType.value.metadata.PartiesConfig[0].AssemblerConfig.port = $args.port"
# Defines the local modified channel configuration JSON file produced by `patch_config_value` and consumed by `compute_update`.
fxadmin_modified_config_json: "/tmp/fabricx/config-build/fxadmin-artifacts/modified_config.json"
ansible.builtin.include_role:
name: hyperledger.fabricx.fxadmin
tasks_from: patch_config_value
tx/endorse¶
Endorse a ConfigUpdate
Stages the ConfigUpdate, dispatches its endorsement to either the host binary or a transient container based on fxadmin_use_bin, then fetches the endorsement to the control node.
- name: Endorse a ConfigUpdate
vars:
# Defines the local ConfigUpdate protobuf file to endorse.
fxadmin_config_update: "/tmp/fabricx/config-build/fxadmin-artifacts/config_update.pb"
# Defines the local directory that collects one endorsement file per required organization before merging.
fxadmin_endorsements_dir: "/tmp/fabricx/config-build/fxadmin-artifacts/endorsements"
# Defines the output artifact path written by the current fxadmin command, local to the host the task runs on.
fxadmin_output: "/tmp/fabricx/config-build/fxadmin-artifacts/config_update.pb"
# Selects the host-binary workflow instead of the container workflow.
fxadmin_use_bin: false
ansible.builtin.include_role:
name: hyperledger.fabricx.fxadmin
tasks_from: tx/endorse
tx/merge¶
Merge endorsements
Dispatches endorsement merging to either the host binary or a transient container based on fxadmin_use_bin, then removes the spent endorsement files. Fails when no endorsement was collected, so an empty ConfigUpdateEnvelope is never written.
- name: Merge endorsements
vars:
# Defines the local directory that collects one endorsement file per required organization before merging.
fxadmin_endorsements_dir: "/tmp/fabricx/config-build/fxadmin-artifacts/endorsements"
# Defines the output artifact path written by the current fxadmin command, local to the host the task runs on.
fxadmin_output: "/tmp/fabricx/config-build/fxadmin-artifacts/config_update.pb"
# Selects the host-binary workflow instead of the container workflow.
fxadmin_use_bin: false
ansible.builtin.include_role:
name: hyperledger.fabricx.fxadmin
tasks_from: tx/merge
tx/prepare¶
Prepare a transaction
Stages the merged, endorsed ConfigUpdate, dispatches transaction preparation to either the host binary or a transient container based on fxadmin_use_bin, then fetches the prepared transaction to the control node.
- name: Prepare a transaction
vars:
# Defines the local merged, endorsed ConfigUpdate envelope to prepare into a submittable transaction.
fxadmin_endorsed_config_update: "/tmp/fabricx/config-build/fxadmin-artifacts/merged.pb"
# Defines the output artifact path written by the current fxadmin command, local to the host the task runs on.
fxadmin_output: "/tmp/fabricx/config-build/fxadmin-artifacts/config_update.pb"
# Defines the control-node path that `fxadmin_output` is fetched back to once the command completes on a remote host.
fxadmin_output_fetch_dest: "/tmp/fabricx/config-build/fxadmin-artifacts/config_tx.pb"
# Selects the host-binary workflow instead of the container workflow.
fxadmin_use_bin: false
ansible.builtin.include_role:
name: hyperledger.fabricx.fxadmin
tasks_from: tx/prepare
tx/submit¶
Submit a transaction
Dispatches submission of the prepared transaction to either the host binary or a transient container based on fxadmin_use_bin.
- name: Submit a transaction
vars:
# Selects the host-binary workflow instead of the container workflow.
fxadmin_use_bin: false
ansible.builtin.include_role:
name: hyperledger.fabricx.fxadmin
tasks_from: tx/submit
wipe¶
Remove generated fxadmin files
Removes the fxadmin binary when the host-binary workflow is selected, and the rendered configuration directory.
- name: Remove generated fxadmin files
vars:
# Defines the fxadmin remote configuration directory.
fxadmin_remote_config_dir: "{{ remote_config_dir }}/fxadmin"
# Selects the host-binary workflow instead of the container workflow.
fxadmin_use_bin: false
# Provides the base remote configuration directory used by the role.
remote_config_dir: "/opt/hyperledger/fabricx/config"
ansible.builtin.include_role:
name: hyperledger.fabricx.fxadmin
tasks_from: wipe