fabric-x-ansible-collection

Imported from LF-Decentralized-Trust-labs/fabric-x-ansible-collection (AGENTS.md). Install upstream with npx skills add LF-Decentralized-Trust-labs/fabric-x-ansible-collection. Copyright stays with the author.

AGENTS.md — AI Agent Guide for hyperledger.fabricx

hyperledger.fabricx is an Ansible collection that automates deployment and lifecycle management of Hyperledger Fabric-X networks. Namespace/name: hyperledger.fabricx. Authoritative version and deps: galaxy.yml.

Project-local Agent Skills

.agents/skills/ is the source of truth for project-local Agent Skills. Compatible agents discover their metadata from this trusted repository checkout and load the applicable SKILL.md on demand:

• creating-fabricx-inventories: load when creating, adapting, or reviewing a custom operator-owned Fabric-X inventory.
• validating-fabricx-changes: load when checking, validating, reviewing, or preparing repository changes.

Rules — follow before every commit

1. License header — every YAML, shell, and Jinja2 file must begin with:

   #
   # Copyright IBM Corp. All Rights Reserved.
   #
   # SPDX-License-Identifier: Apache-2.0
   #

   CI enforces this via scripts/check_license_header.sh.

2. No trailing spaces in .j2 files — enforced by scripts/check_trailing_spaces.sh.

3. Idempotency — all tasks must be idempotent; use creates:, changed_when:, or appropriate modules.

4. Task names — every ansible.builtin.* task must have a name: field.

5. Code order — first name: field, then vars: (if needed), FQDN name of task and finally when: (if needed). For blocks: name:, then when:, then block:.

6. Templates — Jinja2 templates go in roles/<role>/templates/ with .j2 extension.

Working in isolation

Use git worktrees under .worktrees/ only for multi-agent jobs (i.e. with subagents). For single-agent work, edit the main checkout directly.

git worktree add .worktrees/<3-4-word-slug> -b worktree/<3-4-word-slug>

Do not remove the worktree when done — leave cleanup to the user.

Architecture

Always read the role argument_specs.yaml first

Before modifying any role, read roles/<role>/meta/argument_specs.yaml. It is the authoritative reference for that role: available tasks, variables, and which deployment modes (binary / container / k8s) it supports. Deployment mode support varies per role — do not assume.

Dispatch pattern

Roles that manage multiple sub-components (e.g. orderer: consenter/batcher/assembler/router; committer: validator/verifier/coordinator/sidecar/query-service) use a dispatcher: the top-level task file reads <role>_component_type and delegates to the matching sub-component directory:

ansible.builtin.include_role:
  name: hyperledger.fabricx.<role>
  tasks_from: <sub_component>/start # e.g. coordinator/start, assembler/bin/install

Role layout

roles/<role>/
├── defaults/main.yaml          # auto-generated from meta/argument_specs.yaml
├── meta/argument_specs.yaml    # single source of truth for variables and docs
├── tasks/
│   ├── start.yaml              # top-level dispatcher (reads *_component_type)
│   ├── <sub_component>/
│   │   ├── bin/
│   │   ├── container/
│   │   └── k8s/
└── templates/                  # *.j2 Jinja2 templates

Cross-role dependencies

These connections are not visible from within a single role:

Role reference

Essential commands

make lint                  # full validation; run only when the user explicitly asks
make start / stop / teardown / wipe   # lifecycle
make install-deps          # set up control node (venv + python + ansible deps)
make help                  # full command reference

Agents must use the Makefile targets for repository checks. Do not rewrite or bypass the project check scripts (for example, with ad hoc Python replacements) unless the user explicitly asks for that.

make lint is very time consuming. Do not run it unless the user explicitly asks you to run make lint.

Modifying a role

1. Role variables and documentation are managed exclusively through roles/<role>/meta/argument_specs.yaml. Both defaults/main.yaml and README.md are auto-generated — never edit them directly.

2. When you change argument_specs.yaml, use these Makefile checks in order:

   make check-argument-specs
   make check-trailing-spaces
   make check-license-header

3. Run make lint only if the user explicitly asks for it.

4. Only when all checks pass, regenerate the docs:

   make generate-roles-docs

Adding a role (rare)

1. Create roles/<new_role>/meta/argument_specs.yaml with role options and entrypoints.
2. Create the task files under roles/<new_role>/tasks/.
3. Add the Apache-2.0 license header to every file created.
4. Run make generate-roles-docs to generate defaults/main.yaml and README.md.
5. Register the role in roles/README.md (alphabetical order).
6. Add playbooks under playbooks/<new_role>/ following existing patterns.
7. Run make lint and fix any issues before committing.

Adding a new inventory

When a new inventory is added under examples/inventory/, write a corresponding doc under examples/inventory/docs/ following the structure of existing docs (e.g. examples/inventory/docs/local/fabric-x.md). Then register the new doc in mkdocs.yml under the nav.Inventories section, in the appropriate deployment-type group.

Adding or modifying a tutorial lesson

The tutorial under docs/tutorial/ is hand-written and is the only documentation in the repository that is a learning path rather than reference material. Keep the two roles distinct: reference detail belongs in the inventory/playbook/role docs, and the tutorial links to them.

When adding or renaming a lesson:

1. Follow the existing lesson skeleton: # <N>. <Title>, a framing paragraph, a > [!NOTE] stating the estimated time and the prerequisite lesson, ## Table of Contents <!-- omit in toc -->, ## What You Will Learn, the content sections, ## Exercise, and a ## Next table.
2. Exercises pose the task in a > [!TIP] callout and hide the answer in a <details markdown="1"> block. The markdown="1" attribute is required — without it md_in_html does not render the fenced code inside the block on the MkDocs site.
3. Never place two callouts adjacent with only a blank line between them; markdownlint reports MD028. Put prose between them, or merge them into one callout using a > continuation line.
4. Update the previous/next links in both neighbouring lessons, and the learning-path table in docs/tutorial/index.md.
5. Register the lesson in mkdocs.yml under nav.Tutorial. Pages under docs/tutorial/ are copied to the site by scripts/build_mkdocs_source.py, but only the nav makes them reachable.
6. Verify with npx --yes markdownlint-cli2 "docs/tutorial/**/*.md" (zero issues, using the repo's .markdownlint.yaml) and make mkdocs-build, which runs mkdocs build --strict and fails on any broken internal link.

Markdown files need no license header — scripts/check_license_header.sh only checks *.yaml and *.yml.

Modifying a playbook

When a playbook under playbooks/ is modified, update the corresponding README.md in the same directory. These READMEs are not auto-generated.

WARNING: Never run make install when the repo is cloned directly into the Ansible collections path — it overwrites the live checkout with a built artifact.