read_file
read_file reads one file on the node, so that a later node task, or through
a fleet stage output another node, can use its content. It changes nothing on
the node. To copy a file from the node to the controller machine, use
read_file and a fleet stage's
save_on_controller_machine;
MMX has no separate fetch module.
Inputs
path(string; required): absolute path of a regular file up to 1 MiB; links are followedcontent_is_secret(boolean; required): true when the file holds a secret, such as a token or a key: the content is never printed or saved, an output made from it is secret too, and mmx resume reads the file again from this node when later work needs it; false otherwise
Outputs
The node task's result holds these fields. A later node task reads them as .node_tasks.<id>.<field>, where <id> is the node task's id.
statuschangecontent
What a dryrun reports
Runs; changes nothing and reports unchanged; a missing file reports not_checked, since an earlier node task may still create it.
Retries and time limits
Runs once unless the task sets retry.
The node task takes the time limits time_limit and time_limit_per_try; without them, the project's node_task_defaults apply. mmx describe-module task describes the settings every node task accepts.
Examples
Pass a cluster's join token to the other servers
A k3s cluster's first server writes a join token that the other servers need:
# playbooks/cluster.yml
fleet_stages:
- id: start_first_server
nodes: server01
node_tasks:
- id: join_token
read_file:
path: /var/lib/rancher/k3s/server/token
content_is_secret: true
outputs:
join_token: "{{ .node_tasks.join_token.content }}"
On the node server01, the node task reads the token file. The node task's
result field content holds the file's text, and the fleet stage passes it
on as its output join_token. Both fields are required:
content_is_secret makes every such node task say whether the content may
appear in output and saved results. With true, the content is a secret that
started on a node;
Secrets that start on a node
shows how the token reaches nodes joining the cluster and how mmx resume
handles the secret content.
How it works
read_file changes nothing and reports unchanged, so it also runs during
mmx dryrun.
pathis an absolute path of a regular file of at most 1 MiB. Links are followed. A directory, a device, or a larger file fails the node task.- A missing file fails the node task. During dryrun, the
read_filenode task reportsnot_checked, because an earlier node task of the run may still create the missing file. - A file that is not UTF-8 text gives binary content. Binary content can only
be passed on whole: as a file's
content: "{{ .node_tasks.key.content }}", an output, a role input, or a file saved on the controller machine. A reference to it inside other text, or in a template, fails and says so, because text cannot hold it. read_filetries once unless the node task setsretry. To wait for a file that a program creates a little later, put await_forwithpath_existsbefore theread_filenode task.
Tested on
Distributions: Debian 12 and 13, Ubuntu 24.04 and 26.04, Arch Linux, openSUSE Leap 16.1, Rocky Linux 9, AlmaLinux 10, Fedora 45.
The base suite covers this module (task_secrets.py) and runs on every tested distribution.
Why it works this way
- The content is limited to 1 MiB. It travels inside the node job and is saved with the playbook run; large files belong in streamed file transfers.
This page is docs/reference/modules/read_file.md in the MMX repository.