NETWAYS / NETWAYS/ansible-collection-elasticstack

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

Open
#495 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

breaking-change component:all quality
Dominant language
Jinja
Stars
14
Forks
11
Avg merge
1d 47m
Merged PRs (30d)
6

Description

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.

Scope — one PR per role

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

Each PR: 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)).

The naming rules themselves are defined in #542. Relates to #474 (argument-spec
correctness, split back out) and #396 (refactoring). Part of #545.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by inventorying internal variables in each listed role, checking defaults/main.yml, meta/argument_specs.yml, vars/, and the documentation. Use the naming rules from #542, then verify each role's internal variables are renamed, removed from the public contract, and that handlers retain fallbacks such as the documented default(false) guard.

Written by the indexing model from the issue text.

Assessment

Domain
devops
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.