nathan/homelab
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Releases Wiki Activity
homelab/ansible/archive/documentation/standards/naming-conventions.md

5.6 KiB
Raw Blame History

Naming conventions

Date: 2026-01-10
Status: Approved
Author: Chester + FrankGPT

Purpose

Consistent naming reduces cognitive load, prevents errors, and makes the codebase navigable for future contributors (including future-you).

General principles

  1. Be descriptive: Names should explain what something is or what it does.
  2. Be consistent: Once you pick a pattern, stick to it everywhere.
  3. Avoid abbreviations: Write network not net, manager not mgr — unless the abbreviation is industry-standard (e.g., vm, ip, ssh).
  4. Use English: All identifiers, comments, and documentation in English.

Files and folders

Element Convention Example
Folders lowercase, singular noun docker/, proxmox/, onboarding/
Playbooks snake_case.yml provision_swarm_vms.yml
Roles snake_case proxmox_post_install
Templates filename.ext.j2 docker-compose.yml.j2
Variable files snake_case.yml swarm_defaults.yml

Playbook naming pattern

Use verb + object format:

Verb Use when Example
provision_ Creating infrastructure provision_swarm_vms.yml
configure_ Modifying settings configure_nas.yml
deploy_ Pushing applications deploy_portainer.yml
init_ First-time setup init_cluster.yml
update_ Applying updates update_containers.yml
validate_ Checking correctness validate_karakeep.yml
test_ Running tests test_ollama.yml
enforce_ Ensuring compliance enforce_access.yml
remove_ Deleting resources remove_old_images.yml

Exceptions: Master/orchestrator playbooks may be named after their target scope:

  • proxmox_host.yml — orchestrates full PVE onboarding
  • ai_workstation.yml — orchestrates AI host setup

Inventory

Element Convention Example
Group names snake_case proxmox_cluster, swarm_managers
Hostnames kebab-case pve-01, swarm-manager-1
Child groups parent:children syntax ubuntu_lab:children

Hostname pattern

<role>-<index>
Role Pattern Examples
Proxmox hosts pve-0X pve-01, pve-02
Swarm managers swarm-manager-X swarm-manager-1
Swarm workers swarm-worker-X swarm-worker-1
AI workstations ai-<name> ai-lenovo, ai-surface1
Docker hosts <name> or docker-0X waldorf, docker-01
Storage <product> synology, terramaster

Variables

Element Convention Example
All variables snake_case vm_disk_size
Role defaults Prefix with role name proxmox_post_install_enabled
Boolean vars Use positive names enable_ha (not disable_ha)
List vars Plural nouns required_packages, allowed_users
Dict vars Singular noun vm_config, network_settings

Variable prefixes by scope

Scope Prefix Example
Role-specific <role>_ proxmox_post_install_enabled
Playbook-local _ (single underscore) _temp_file
Global/shared none ansible_user, ssh_key_path

Reserved variable names

Never override these Ansible built-ins:

  • inventory_hostname, ansible_host, ansible_user
  • ansible_become, ansible_become_pass
  • hostvars, groups, group_names

Tasks and handlers

Element Convention Example
Task names Sentence case, descriptive Install required packages
Handler names Restart <service> or Reload <service> Restart docker
Block names <Action> <scope> Configure SSH access
Tags snake_case, short install, configure, test

Task naming rules

  1. Start with a verb: Install, Configure, Create, Remove, Ensure, Check
  2. Be specific: Install Docker CE not Install Docker
  3. No trailing punctuation: Install packages not Install packages.
  4. Use present tense: Create user not Created user

Tags

Use tags to allow selective execution:

Tag Purpose Example usage
install Package installation --tags install
configure Configuration changes --tags configure
test Validation/testing --tags test
cleanup Removal/pruning --tags cleanup
never Skip unless explicit --tags never,dangerous_task

Secrets and sensitive data

Element Convention Example
Vault files vault_<scope>.yml vault_production.yml
Secret vars Suffix with _secret or _pass db_password, api_key_secret
Encrypted strings Use !vault tag `password: !vault

Git branches (if applicable)

Branch Purpose
main Production-ready playbooks
develop Integration branch
feature/<name> New features
fix/<name> Bug fixes
docs/<name> Documentation updates

Quick reference card

Files:         snake_case.yml
Folders:       lowercase/
Roles:         snake_case
Hostnames:     kebab-case
Groups:        snake_case
Variables:     snake_case
Tasks:         Sentence case, verb first
Tags:          snake_case

References