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

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions