Skip to content

Best Practices

  • Use Data annotations for all variables touched by role consumer See example.
  • Prefix role variables with {ROLE}_role_.
  • Prefix service variables (required to setup service, not configure it) with {ROLE}_srv_.
  • Prefix config variables (required for configuring service) with {ROLE}_cfg_.
  • Always create roles explicitly designed for bare-metal installations.
  • Flag protect container specific options requiring explicit enablement:
    • Use a collection level flag {COLLECTION}_container_enable.
    • Use a role level flag {ROLE}_container_enable.
    • As the first step in main.yml override role level option if collection value is set (See example).

  • Handle local and remote mounted data storage possibilities:

    • Provide option for executing task as 'root' or specified user.
    • Use UID/GID for those locations for remote filesystem accommodation.
    • See existing roles.

  • Use the style guide.

  • Always include last update date, version, and OS release in vars/main.yml: 
    # Last time {ROLE} options were validated against a default configuration.
{ROLE}_role_validate_date: '2024-06-14'
{ROLE}_role_validate_release: 'bookworm'

# Default packages for {ROLE}.
{ROLE}_role_packages:
  - 'ssh'  # meta package provides both ssh and sshd.

# Default random data.
{ROLE}_role_generated_api_key: '{{
    lookup("ansible.builtin.password",
           "/dev/null",
           chars=["ascii_letters", "digits"],
           length=32)
  }}'

Reference: