179 lines
5.6 KiB
Markdown
179 lines
5.6 KiB
Markdown
# 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
|
|
|
|
- [Ansible Best Practices — Variable Naming](https://docs.ansible.com/ansible/latest/tips_tricks/ansible_tips_tricks.html)
|
|
- [Ansible Lint — Naming Rules](https://ansible.readthedocs.io/projects/lint/rules/name/)
|
|
- [Google Shell Style Guide](https://google.github.io/styleguide/shellguide.html) — for script naming inspiration
|