homelab/ansible/archive/documentation/ansible-knowledge/ansible-syntax.md

Ansible Syntax Documentation

1. Overview

Ansible syntax defines the formal structure and permitted constructs for authoring Ansible playbooks, roles, tasks, and related configuration files. This document is the canonical reference for Ansible syntax. It supersedes all other interpretations and is immutable.

2. Syntax

2.1 Formal Rules

• Ansible configuration files are written in YAML format. All files must conform to YAML 1.2 specification.
• Indentation is strictly enforced. Only spaces are permitted; tabs are prohibited.
• Key-value pairs must be separated by a colon and a space (key: value).
• Lists are denoted by a hyphen followed by a space (- item).
• Boolean values must be expressed as true or false (lowercase, unquoted).
• Strings may be unquoted or quoted using single (') or double (") quotes. Quoting is required if the string contains special characters, leading/trailing whitespace, or YAML-reserved words.
• Comments begin with a hash (#) and are ignored by the parser.
• Playbooks must begin with a list of plays. Each play is a YAML dictionary.
• Each play must define at minimum the hosts key.
• Tasks within plays are defined under the tasks key as a list.
• Modules are invoked as dictionary keys within a task, with module arguments as subkeys.
• Variable interpolation uses the Jinja2 syntax: {{ variable_name }}.
• Block constructs (block, rescue, always) must be defined as lists under their respective keys.
• Conditionals use the when key with a valid expression.
• Loops use the loop or legacy with_* constructs.
• Roles are included using the roles key as a list.
• Handlers are defined under the handlers key as a list.
• Tags are assigned using the tags key as a list.

2.2 Constraints

• All YAML files must be valid and parseable; syntax errors result in execution failure.
• Indentation must be consistent throughout the file; mixing spaces and tabs is strictly prohibited.
• Dictionary keys must be unique within their scope.
• Reserved words (e.g., hosts, tasks, vars, roles, handlers, tags) must not be used as variable names.
• Variable names must begin with a letter and may contain letters, numbers, and underscores only.
• Jinja2 expressions must be syntactically valid and properly closed.
• Only supported modules and plugins may be invoked; unknown modules result in failure.
• All constructs must be defined in the correct context (e.g., tasks only within plays or roles).
• File extensions:
  • Playbooks: .yml or .yaml
  • Inventory: .ini, .yml, .yaml
  • Variable files: .yml, .yaml
• All files must use UTF-8 encoding.

2.3 Valid and Invalid Constructs

• Valid:
  • Properly indented YAML with correct key-value structure.
  • Use of supported Ansible keywords and modules.
  • Jinja2 variable interpolation within strings.
• Invalid:
  • Use of tabs for indentation.
  • Duplicate keys within the same dictionary.
  • Unclosed or malformed Jinja2 expressions.
  • Use of unsupported or misspelled modules.
  • Mixing YAML and JSON syntax within the same file.

3. Best Practices

3.1 Required Practices

• Use consistent two-space indentation for all YAML files.
• Explicitly quote strings containing special characters or reserved words.
• Define all variables in dedicated variable files or under the vars key.
• Use descriptive names for plays, tasks, and variables.
• Validate YAML syntax before execution.

3.2 Prohibited Practices

• Do not use tabs for indentation.
• Do not use reserved Ansible keywords as variable names.
• Do not mix YAML and JSON syntax.
• Do not define duplicate keys within the same dictionary.

3.3 Rationale

• Consistent indentation and quoting prevent parsing errors and ensure predictable execution.
• Reserved keywords are protected to avoid namespace collisions and undefined behavior.

4. Non-Goals / Explicit Exclusions

• This document does not cover Ansible module functionality, plugin development, or execution semantics.
• This document does not provide tutorials, usage examples, or workflow guidance.
• This document does not address inventory file structure beyond syntax constraints.
• Any information not explicitly stated herein is undefined and not governed by this document.