Reuse work with roles
Who acts: you, or your coding agent, in your MMX project on your
controller machine: the computer where you run mmx. No command on this
page asks a question, so a coding agent can run every command as written.
When to use this page: several playbooks or fleet stages need the same node tasks, such as setting up the same website, or one playbook has grown long and you want to give a group of node tasks a name and a short list of settings.
What this page does: you move the nginx work of
Write a playbook into a role named shop_website,
with the port as a declared input, and call the role from the playbook. The
servers do not change, as mmx dryrun shows. Then the role learns to
run on servers with different distributions.
Terms:
- A node is a Linux server that MMX manages. A playbook lists fleet stages. Each fleet stage picks nodes, and each of those nodes runs the fleet stage's node tasks, in order.
- A role is a list of node tasks in its own file,
roles/<name>/main.yml, with declared inputs: the values that the role needs, each with a type, such asportof typeinteger. - A role call is a node task that names the role and gives values for
the role's inputs:
role: shop_websitewithinputs: {port: 8080}. The role's node tasks run where the role call stands. A role is a way to organize your files: a role does not run as a separate program or in another place.
| What you need | Where |
|---|---|
| Put node tasks in a role, and call the role | Steps |
| One role for Debian, Ubuntu, Fedora, and other distributions | One role for several distributions |
| The input types, defaults, and required inputs | Inputs |
| Template files and other files that belong to a role | Files inside a role |
| A value that the role works out, for the node tasks after the role call | Outputs |
| A role that calls another role | Role calls within roles |
| A file or a value that two roles need | A file or a value that two roles share |
| Roles that other people wrote | What MMX does not have |
Before you start
playbooks/set_up_web_servers.ymlis the playbook from Write a playbook, andmmx run set_up_web_serverssucceeds. The serversweb01andweb02are in the groupweb_serversininventories/example.yml.- The group
web_serverssets the variablehttp_port: 8080, as in Describe your servers, step 3. Step 6 uses the variable. - Find the fields of a role call with
mmx describe-module role.
The line numbers in the output of mmx explain depend on your files, so
your numbers may differ from the numbers on this page.
Steps
-
Create the role's file. Create the directory
roles/shop_website/and the fileroles/shop_website/main.yml. The directory's name is the role's name. The file holds the node tasks of the fleet stageset_up_nginx, with three changes: the port and the page heading come from inputs, and the two files come from template files.# roles/shop_website/main.yml inputs: port: {type: integer, required: true} # an input name you choose heading: {type: string, default: Shop} node_tasks: - id: install_nginx apt_package: packages: - {name: nginx, version: newest_when_first_installed} - id: create_site_directory directory: path: /srv/shop/public create_missing_parent_directories: true - id: write_home_page file: path: /srv/shop/public/index.html permissions_mode: "0644" template: files/index.html.tmpl # roles/shop_website/files/index.html.tmpl - task_block: id: shop_site changes: - id: write_site_file file: path: /etc/nginx/conf.d/shop.conf permissions_mode: "0644" template: files/shop.conf.tmpl # roles/shop_website/files/shop.conf.tmpl activate: - id: reload_nginx systemd_service: name: nginx start_at_boot: true state: running refresh: reload verify: - id: check_home_page wait_for: url_responds: "http://127.0.0.1:{{ .inputs.port }}/" response_body_contains: "{{ .inputs.heading }}"inputsdeclares the role's inputs.portis a whole number, and each role call must giveport.headingis text, and a role call that leaves outheadinggetsShop. Node tasks in the role read an input as{{ .inputs.port }}.Check: none yet:
mmx validatereads a role only when a playbook calls the role, in step 3. -
Create the role's template files. Inside a role, a
templatepath starts at the role's directory, sofiles/index.html.tmplisroles/shop_website/files/index.html.tmpl. Createroles/shop_website/files/index.html.tmpl:<h1>{{ .inputs.heading }}</h1>Create
roles/shop_website/files/shop.conf.tmpl:server { listen {{ .inputs.port }}; root /srv/shop/public; }A template in a role reads the role's inputs, as the role's node tasks do. The role's directory now holds:
roles/shop_website/files/index.html.tmpl roles/shop_website/files/shop.conf.tmpl roles/shop_website/main.ymlCheck: none yet: step 3 checks the files.
-
Call the role from the playbook. Replace the contents of
playbooks/set_up_web_servers.yml:# playbooks/set_up_web_servers.yml fleet_stages: - id: set_up_nginx nodes: web_servers node_tasks: - id: shop_website # a node task ID you choose role: shop_website # the directory name under roles/ inputs: port: 8080The role file's
inputsdeclares which inputs exist. The role call'sinputsgives their values.Check:
mmx validate set_up_web_serversprintsValid:and the project's name. If the role call leaves outport, the message isrole shop_website: missing input port. See If something is different for the other messages. -
See what the role call gives each server.
mmx explain set_up_web_servers --limit web01Check: the role call lists each input's value and where the value came from: the role call, or the role's
default. Then each node task of the role follows, with the role's file and line:set_up_nginx → web01 web01 / set_up_nginx/shop_website: role (ready) at playbooks/set_up_web_servers.yml:5:9 (fleet_stages[0].node_tasks[0]) inputs.heading = "Shop" from roles/shop_website/main.yml:3:36 (inputs.heading.default) inputs.port = 8080 from playbooks/set_up_web_servers.yml:8:17 (fleet_stages[0].node_tasks[0].inputs.port) web01 / set_up_nginx/shop_website/install_nginx: apt_package (ready) at roles/shop_website/main.yml:6:5 (node_tasks[0]) -
Preview the playbook.
mmx dryrun set_up_web_servers --limit web01 echo "exit code $?"Check: every node task says
unchanged, and the exit code is 0. The role writes the same files that the playbook wrote before, so moving work into a role changes nothing on the servers. The output names each node task with the role call's ID first:set_up_nginx / web01: succeeded set_up_nginx / web01 / shop_website/install_nginx: succeeded, unchanged set_up_nginx / web01 / shop_website/create_site_directory: succeeded, unchanged set_up_nginx / web01 / shop_website/create_site_directory: directory "/srv/shop/public" checked 1 directories and 0 files; 0 metadata updates set_up_nginx / web01 / shop_website/write_home_page: succeeded, unchanged set_up_nginx / web01 / shop_website/shop_site/changes/write_site_file: succeeded, unchanged set_up_nginx / web01 / shop_website/shop_site/activate/reload_nginx: succeeded, unchanged set_up_nginx / web01 / shop_website/shop_site/verify/check_home_page: succeeded, unchanged set_up_nginx / web01 / shop_website/shop_site: succeeded, unchanged set_up_nginx / web01 / shop_website: succeeded, unchanged Run b72f70dd: succeededIf a node task says
would_change, the role's file differs from the old playbook's file.mmx dryrun set_up_web_servers --diffshows the difference. A role call without aniduses the role's name in the output. -
Give the role the port from a variable. A role reads no variable of the project, the inventory, a group, a node, or the command line, so the playbook passes the variable to the role as an input. In
playbooks/set_up_web_servers.yml, change theportline:inputs: port: "{{ .vars.http_port }}"portkeeps its type, a whole number, because the value is exactly one reference.Check:
mmx explain set_up_web_servers --limit web01shows the value and the inventory line that set the value:inputs.port = 8080 from playbooks/set_up_web_servers.yml:8:17 (fleet_stages[0].node_tasks[0].inputs.port) value from inventories/example.yml:16:18 (groups.web_servers.vars.http_port)Then
mmx run set_up_web_serverssaysunchangedfor every node task and ends withRun ...: succeeded.
One role for several distributions
MMX has a module for each package manager, such as apt_package for apt on
Debian and Ubuntu and dnf_package for dnf on Fedora, Rocky Linux, and
AlmaLinux. MMX does not choose the module for you. A role that runs on
several distributions has one node task for each package manager, each
with a when on the fact .node.package_manager. A fact is a value
that the node reports about itself. These steps continue from step 6 and
add web03, an Ubuntu 26.04 server at 203.0.113.13.
-
Add the server. In
inventories/example.yml, addweb03belowweb02, and addweb03to the group:# inventories/example.yml nodes: web01: address: 203.0.113.11 ssh_user: root web02: address: 203.0.113.12 ssh_user: root web03: address: 203.0.113.13 ssh_user: root groups: web_servers: nodes: [web01, web02, web03] vars: http_port: 8080Check:
mmx nodeslistsweb03inweb_servers. Your computer must trustweb03's SSH host key, as Connect to your servers explains. -
Give each package manager its own node task. In
roles/shop_website/main.yml, replaceinstall_nginxwith two node tasks:- id: install_nginx_with_apt when: equals: ["{{ .node.package_manager }}", apt] apt_package: packages: - {name: nginx, version: newest_when_first_installed} - id: install_nginx_with_dnf when: equals: ["{{ .node.package_manager }}", dnf] dnf_package: packages: - {name: nginx, version: newest_when_first_installed}Each node runs the node task for its own package manager, and skips the other node task.
-
Look up a value that differs by distribution. nginx's workers run as the account
www-dataon Debian and Ubuntu, and asnginxon Fedora and Rocky Linux. A mapping input holds both names, and a node task looks up its own. Add the input belowheading:nginx_account: # the account nginx's workers run as type: mapping default: {apt: www-data, dnf: nginx}Add a directory that nginx's workers can write to, below
create_site_directory:- id: create_upload_directory directory: path: /srv/shop/uploads owner: "{{ .inputs.nginx_account[.node.package_manager] }}"[.node.package_manager]looks up the keyaptordnfin the mapping. A missing key is an error that stops the node task, never an empty value.Check:
mmx validate set_up_web_serversprintsValid:. -
Preview and run.
mmx dryrun set_up_web_servers mmx run set_up_web_serversCheck: on every server,
install_nginx_with_dnfsaysskipped, unchanged — when is false, because Debian and Ubuntu use apt. Onweb03, the first run installs nginx:set_up_nginx / web03 / shop_website/install_nginx_with_apt: succeeded, changed [{"name":"nginx-common","to":"1.28.3-2ubuntu1.12"},{"name":"nginx","to":"1.28.3-2ubuntu1.12"}] set_up_nginx / web03 / shop_website/install_nginx_with_dnf: skipped, unchanged — when is falseOn the first run on
web03,reload_nginxsayssucceeded, changed — service is not running, because MMX installs a package without starting its services, so MMX starts nginx (Reload or restart). Onweb01andweb02, onlycreate_upload_directorychanges. The run ends withRun ...: succeeded, and on each server/srv/shop/uploadsbelongs towww-data.
The dryrun's exit code is 3 on a run that adds web03: on a server without
nginx, a dryrun cannot check the site file in /etc/nginx/conf.d, which
the nginx package creates.
Preview and run changes
explains not_checked.
Use variables and templates
lists the other facts about the distribution, such as
.node.distribution.id and .node.distribution.family. A package node task on a server with another package manager
fails, and the message says what to do:
dnf_package installs with dnf, but this node's package manager is apt (the node fact package_manager); give the node task a condition so that it runs only on nodes that use dnf
The module pages say how each package module installs, upgrades, and
removes packages, and how to add a package source, such as
apt_package,
dnf_package,
apt_repository, and
dnf_repository. Arch Linux and openSUSE
use the official extra modules pacman_package and zypper_package;
mmx describe-module pacman_package shows the inputs.
Limits on each distribution says what
is limited where.
The whole role
roles/shop_website/main.yml after the steps:
# roles/shop_website/main.yml
inputs:
port: {type: integer, required: true} # an input name you choose
heading: {type: string, default: Shop}
nginx_account: # the account nginx's workers run as
type: mapping
default: {apt: www-data, dnf: nginx}
node_tasks:
- id: install_nginx_with_apt
when:
equals: ["{{ .node.package_manager }}", apt]
apt_package:
packages:
- {name: nginx, version: newest_when_first_installed}
- id: install_nginx_with_dnf
when:
equals: ["{{ .node.package_manager }}", dnf]
dnf_package:
packages:
- {name: nginx, version: newest_when_first_installed}
- id: create_site_directory
directory:
path: /srv/shop/public
create_missing_parent_directories: true
- id: create_upload_directory
directory:
path: /srv/shop/uploads
owner: "{{ .inputs.nginx_account[.node.package_manager] }}"
- id: write_home_page
file:
path: /srv/shop/public/index.html
permissions_mode: "0644"
template: files/index.html.tmpl # roles/shop_website/files/index.html.tmpl
- task_block:
id: shop_site
changes:
- id: write_site_file
file:
path: /etc/nginx/conf.d/shop.conf
permissions_mode: "0644"
template: files/shop.conf.tmpl # roles/shop_website/files/shop.conf.tmpl
activate:
- id: reload_nginx
systemd_service:
name: nginx
start_at_boot: true
state: running
refresh: reload
verify:
- id: check_home_page
wait_for:
url_responds: "http://127.0.0.1:{{ .inputs.port }}/"
response_body_contains: "{{ .inputs.heading }}"
playbooks/set_up_web_servers.yml:
# playbooks/set_up_web_servers.yml
fleet_stages:
- id: set_up_nginx
nodes: web_servers
node_tasks:
- id: shop_website # a node task ID you choose
role: shop_website # the directory name under roles/
inputs:
port: "{{ .vars.http_port }}"
Inputs
Each input under the role file's inputs has a type. Give an input
required: true when each role call must give the input, or a default
for a role call that leaves the input out:
type |
A value such as |
|---|---|
string |
Shop |
integer |
8080 |
boolean |
true or false |
list |
[alice, bob] |
mapping |
{apt: www-data, dnf: nginx} |
- A role call must give each input that has
required: true. A role call may leave out an input that has adefault. - An input without
requiredand without adefaulthas no value when the role call leaves the input out. A node task that reads the input then fails withvalue is unavailable. - A
defaultis a value as written, never a reference. A role call passes a variable to the role, as in step 6.default: "{{ .vars.site_name }}"fails withrole shop_website: input heading default must be a literal value; pass references through the role call's inputs mapping. - MMX checks a written value's type when MMX reads the playbook:
port: "8080"is text, and fails withinput port must be integer. A value from a reference is checked where the reference gets its value; A number, a boolean, a list, or a mapping from a reference says where. - An input with
secret: trueholds a secret, such as a password, and takes nodefault. Declaresecret: trueon an input that receives a secret; Secrets in files, output, and history gives the error of a role call that does not. Keep secrets explains secrets. - A role call's
inputscan read the same values as any node task in its fleet stage: variables, facts,{{ .secrets.payment_key }}, and an earlier fleet stage's output, such as{{ .outputs.prepare_database.db01.api_token }}(Use a result from one server on another).
Files inside a role
Inside a role, a relative path in template and source, and in the
other fields that name files on your computer, starts at the role's
directory. Keep a role's files in the role's directory, such as
roles/shop_website/files/, so that the role works when you copy the
directory. A relative path may leave the role's directory but must stay
inside the project, and an absolute path may name any file on your
computer. The file module page
lists the fields that name files on your computer and says more.
What a role reads
A role reads its inputs, its node's facts (.node), the results of its
own earlier node tasks (.node_tasks), and the variables that its own
set_vars node tasks set. A role reads a secret only through an input
with secret: true. The variables of the project, the inventory, the
groups, the nodes, and the command line reach a role only through the role
call's inputs. {{ .vars.http_port }} inside a role fails
with
reference .vars.http_port is not available in a role: a role reads only its inputs and the variables its own set_vars set earlier; declare an input in the role file and pass the value in the role call's inputs.
The reason: a role that reads only its inputs works the same in each
playbook and each project, and mmx explain shows every value that the
role gets at the role call.
Outputs
A role can give values back to the node tasks after the role call. The
role declares the values in outputs, beside inputs:
# roles/shop_website/main.yml, below inputs
outputs:
home_page_url: "http://127.0.0.1:{{ .inputs.port }}/"
A later node task in the same fleet stage reads the value through the role call's ID:
- show: "Home page: {{ .node_tasks.shop_website.outputs.home_page_url }}"
The run prints "Home page: http://127.0.0.1:8080/". MMX works out the
outputs after the role's node tasks succeed. The rest of the playbook sees
only the declared outputs, not the role's own node tasks.
Role calls within roles
By default, a role cannot call another role. The playbook then lists every role call, in the order that the role calls run, so you read the whole order in one file. MMX does not work out an order between roles: put a role that another role needs first in the playbook. A role call inside a role fails with:
role calls within roles require allow_role_calls_within_roles: true
To let roles call roles, add the setting to mmx_project_settings.yml:
# mmx_project_settings.yml
allow_role_calls_within_roles: true
The output then names each node task with each role call's name, such as
shop_website/nginx/install_nginx_with_apt for a role nginx that
shop_website calls. A role that calls itself, directly or through
another role, is an error even with the setting:
recursive role call: shop_website.
A file or a value that two roles share
| Situation | What to do |
|---|---|
| Two kinds of server need the same setup, and neither server's role owns the setup | Put the shared setup in a role of its own. Call the shared role from one fleet stage that selects both groups, such as nodes: [web_servers, database_servers]. A node in both groups runs the shared role once. |
| Two roles are the same role for two environments | Keep one role. Each environment's inventory sets the values that differ, and the playbook passes the values to the role as inputs. |
| Two roles read the same value, such as a list of Redis instances | Set the value once in the project's or the inventory's vars. The playbook passes the value to each role as an input. |
| One role needs a value that only another role's work finds out | The first role declares an output, and the playbook passes the output to the second role as an input. |
What MMX does not have
MMX has no shared collection of roles to download, and no search path for
roles. A role is a directory in your project's roles/, written for your
project. To use a role in a second project, copy the role's directory to
the second project's roles/. The modules are the shared part: the core
modules, such as apt_package and file, come with MMX, and
mmx describe-module lists every module.
If something is different
| What you see | What it means and what to do |
|---|---|
role shop_website: missing input port |
The role call leaves out an input with required: true. Add the input under the role call's inputs. |
role shop_website: unknown input title |
The role call gives an input that the role file does not declare. Check the name, or declare the input in the role file. |
input port must be integer |
A written value has the wrong type, such as port: "8080", which is text. Write port: 8080. |
open /home/you/shop/roles/shop_site/main.yml: no such file or directory |
No role has this name. A role's name is its directory under roles/. |
role shop_website: input heading needs type string, integer, boolean, list, or mapping |
The input's type is not one of the five types. |
reference .vars.http_port is not available in a role: ... |
A role reads .vars. Declare an input, and pass the variable in the role call, as in step 6. |
invalid reference ".inputs.heading | title" |
A function call in the role's YAML. Use the value as it is, or move the text to a template file; Functions in templates explains why. |
role calls within roles require allow_role_calls_within_roles: true |
See Role calls within roles. |
dnf_package installs with dnf, but this node's package manager is apt |
A package node task runs on a server with another package manager. Add a when, as in One role for several distributions. |
Where to go next
- Use variables and templates: the values a role call can pass, facts, and functions in templates.
- Change a configuration and reload its service: node task blocks in full, inside a role or outside one.
- A small whole project with one role that runs on apt and dnf servers:
examples/nginx-role/. - How roles fit with the other parts of a playbook: How MMX works.
This page is docs/how-to/reuse-work-with-roles.md in the MMX repository.