david_igou.armbian.image_build role – Build a custom Armbian image with caller-supplied userpatches via armbian/build (Docker mode)
Note
This role is part of the david_igou.armbian collection (version 0.0.5-alpha).
It is not included in ansible-core.
To check whether it is installed, run ansible-galaxy collection list.
To install it use: ansible-galaxy collection install david_igou.armbian.
To use it in a playbook, specify: david_igou.armbian.image_build.
Entry point main – Build a custom Armbian image with caller-supplied userpatches via armbian/build (Docker mode)
Synopsis
Single-purpose, intent-agnostic role. The caller supplies the board, host, branch, release, and userpatches list; the role enforces the desired output state under armbian_build_output_dir/<host>/.
Workflow playbooks (e.g. playbooks/build_and_publish_from_inventory.yml) pre-resolve armbian_build and armbian_board_config via the resolver primitives in playbooks/tasks/ and inject the resolved armbian_build_userpatches before invoking this role. The role itself is agnostic to the content of those patches.
Parameters
Parameter |
Comments |
|---|---|
Armbian board identifier passed as BOARD= to compile.sh. Must match a supported board in the armbian/build tree at armbian_build_ref. |
|
Armbian kernel branch (current, edge, legacy, vendor). Passed as BRANCH= to compile.sh. Default: |
|
Directory on the builder host for the armbian/build checkout, cache, and userpatches tree. Must be writable by the connecting user — the role does not escalate privileges. The default resolves to the connecting user’s real $HOME (via ansible_facts[‘env’][‘HOME’], so root and non-/home homes work too), which holds with no setup; if you relocate it under a root-owned path like /var/lib, pre-create + chown the path before the first run. Default: |
|
Extra key=value arguments passed verbatim to compile.sh. Not folded into the patch_hash; changing these forces a rebuild only when armbian_build_force is true. Default: |
|
Set to true (e.g. via -e armbian_build_force=true) to bypass the manifest-match skip logic and force a full rebuild. Choices:
|
|
inventory_hostname of the host this build is for. Drives the per-host output path under armbian_build_output_dir/<host>/ and the per-host checkout dir under armbian_build_cache_dir/<host>/. Used so concurrent per-host builds don’t collide and so secret- bearing userpatches in one host’s tree never see another host’s. |
|
Minimum free disk space (GiB) required on the builder before starting the build. Preflight fails if the threshold is not met. Default: |
|
Directory where the final .img.xz and manifest.json are written. Same writability requirement as armbian_build_cache_dir. Default: |
|
armbian/build git ref to checkout. Pinned for reproducibility; bumping is a deliberate role-level change. Default: |
|
Debian/Ubuntu release codename. Passed as RELEASE= to compile.sh. Default: |
|
Hostnames that must be TCP-reachable from the builder before the build starts. Defaults to github.com, apt.armbian.com, ghcr.io, and registry-1.docker.io. Default: |
|
Maximum seconds to wait for compile.sh to complete. 7200 (2 h) covers cold-cache full builds. Default: |
|
List of userpatches to apply before the build. Each entry is a mapping with keys dest (path relative to USERPATCHES_DIR, no leading slash, no ..) and content (raw file text). Patch content MAY contain Jinja referencing the host’s resolved armbian_board_config fact (e.g. armbian_board_config.console); apply_userpatches.yml’s ansible.builtin.copy with `content:` renders these references at the point the file lands on the builder. The role itself is fully agnostic to what the patches do. Default: |