Skip to content

Adopt an internal-variable naming convention (_ / __) and keep internals out of argument_specs #495

Description

@afeefghannam89

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

  • elasticsearch
  • kibana
  • logstash
  • beats
  • repos
  • elasticstack

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).

Metadata

Metadata

Assignees

No one assigned

    Labels

    breaking-changePR / Issue / Fix that will implement a breaking change!qualityChanges that will not affect the technical details, but add some more quality to the code, docs, ...

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions