Problem
Roles carry internal variables that users should never set — e.g. *_freshstart,
and register/set_fact state like elasticsearch_role, *_cluster_set_up. Some are
declared in defaults/main.yml and listed in meta/argument_specs.yml (and thus the
README). That is misleading: argument_specs is the role's user-facing contract,
so documenting "do not set" variables is noise.
Convention (proposed)
- Runtime facts (
register: / set_fact): prefix __<role>_<name> (double
underscore). Example: elasticsearch_freshstart → __elasticsearch_freshstart.
- Static role internals (in
vars/): prefix _<role>_<name> (single underscore).
vars/ sits high in variable precedence.
- Keep internals out of
argument_specs.yml, defaults/main.yml, and the docs —
they are not part of the public API.
- Notes: underscores are a signal, not enforcement (Ansible still lets
-e/set_fact
override them). ansible-lint's var-naming allows leading underscores before the role
prefix, so __<role>_* / _<role>_* stay lint-clean.
Also: argument_specs correctness (absorbs #474)
While touching each role's spec, verify required/default are correct:
- Variables with a default must also be defined in
defaults/main.yml (the spec
default must equal the defaults value).
- Variables marked required must not be defined in
defaults/main.yml — the
user provides them.
Scope — one PR per role
Each PR: audit required/default, inventory the role's internal vars, rename per the
convention, remove them from defaults / argument_specs / docs, and guard handlers
where a removed default was a fallback (e.g. __elasticsearch_freshstart.changed | default(false)).
Document the convention in CONTRIBUTING.
Absorbs #474 (argument-spec review). Relates to #396 (refactoring).
Problem
Roles carry internal variables that users should never set — e.g.
*_freshstart,and register/set_fact state like
elasticsearch_role,*_cluster_set_up. Some aredeclared in
defaults/main.ymland listed inmeta/argument_specs.yml(and thus theREADME). That is misleading:
argument_specsis the role's user-facing contract,so documenting "do not set" variables is noise.
Convention (proposed)
register:/set_fact): prefix__<role>_<name>(doubleunderscore). Example:
elasticsearch_freshstart→__elasticsearch_freshstart.vars/): prefix_<role>_<name>(single underscore).vars/sits high in variable precedence.argument_specs.yml,defaults/main.yml, and the docs —they are not part of the public API.
-e/set_factoverride them). ansible-lint's
var-namingallows leading underscores before the roleprefix, so
__<role>_*/_<role>_*stay lint-clean.Also: argument_specs correctness (absorbs #474)
While touching each role's spec, verify
required/defaultare correct:defaults/main.yml(the specdefault must equal the defaults value).
defaults/main.yml— theuser provides them.
Scope — one PR per role
Each PR: audit
required/default, inventory the role's internal vars, rename per theconvention, remove them from
defaults/argument_specs/ docs, and guard handlerswhere a removed default was a fallback (e.g.
__elasticsearch_freshstart.changed | default(false)).Document the convention in CONTRIBUTING.
Absorbs #474 (argument-spec review). Relates to #396 (refactoring).