summaryrefslogtreecommitdiffstats
path: root/src/ansiblelint/rules/var_naming.md
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-13 12:06:49 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-13 12:06:49 +0000
commit2fe34b6444502079dc0b84365ce82dbc92de308e (patch)
tree8fedcab52bbbc3db6c5aa909a88a7a7b81685018 /src/ansiblelint/rules/var_naming.md
parentInitial commit. (diff)
downloadansible-lint-1f847810e1dcffeab102ff853e50a09833fad025.tar.xz
ansible-lint-1f847810e1dcffeab102ff853e50a09833fad025.zip
Adding upstream version 6.17.2.upstream/6.17.2
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'src/ansiblelint/rules/var_naming.md')
-rw-r--r--src/ansiblelint/rules/var_naming.md77
1 files changed, 77 insertions, 0 deletions
diff --git a/src/ansiblelint/rules/var_naming.md b/src/ansiblelint/rules/var_naming.md
new file mode 100644
index 0000000..3386a0c
--- /dev/null
+++ b/src/ansiblelint/rules/var_naming.md
@@ -0,0 +1,77 @@
+# var-naming
+
+This rule checks variable names to ensure they conform with requirements.
+
+Variable names must contain only lowercase alphanumeric characters and the
+underscore `_` character. Variable names must also start with either an
+alphabetic or underscore `_` character.
+
+For more information see the [creating valid variable names][var-names] topic in
+Ansible documentation and [Naming things (Good Practices for Ansible)][cop].
+
+You should also be fully aware of [special variables][magic-vars], also known as
+magic variables, especially as most of them can only be read. While Ansible will
+just ignore any attempt to set them, the linter will notify the user, so they
+would not be confused about a line that does not effectively do anything.
+
+Possible errors messages:
+
+- `var-naming[non-string]`: Variables names must be strings.
+- `var-naming[non-ascii]`: Variables names must be ASCII.
+- `var-naming[no-keyword]`: Variables names must not be Python keywords.
+- `var-naming[no-jinja]`: Variables names must not contain jinja2 templating.
+- `var-naming[pattern]`: Variables names should match ... regex.
+- `var-naming[no-role-prefix]`: Variables names from within roles should use
+ `role_name_` as a prefix.
+- `var-naming[no-reserved]`: Variables names must not be Ansible reserved names.
+- `var-naming[read-only]`: This special variable is read-only.
+
+!!! note
+
+ When using `include_role` or `import_role` with `vars`, vars should start
+ with included role name prefix. As this role might not be compliant
+ with this rule yet, you might need to temporarily disable this rule using
+ a `# noqa: var-naming[no-role-prefix]` comment.
+
+## Settings
+
+This rule behavior can be changed by altering the below settings:
+
+```yaml
+# .ansible-lint
+var_naming_pattern: "^[a-z_][a-z0-9_]*$"
+```
+
+## Problematic Code
+
+```yaml
+---
+- name: Example playbook
+ hosts: localhost
+ vars:
+ CamelCase: true # <- Contains a mix of lowercase and uppercase characters.
+ ALL_CAPS: bar # <- Contains only uppercase characters.
+ v@r!able: baz # <- Contains special characters.
+ hosts: [] # <- hosts is an Ansible reserved name
+ role_name: boo # <-- invalid as being Ansible special magic variable
+```
+
+## Correct Code
+
+```yaml
+---
+- name: Example playbook
+ hosts: localhost
+ vars:
+ lowercase: true # <- Contains only lowercase characters.
+ no_caps: bar # <- Does not contains uppercase characters.
+ variable: baz # <- Does not contain special characters.
+ my_hosts: [] # <- Does not use a reserved names.
+ my_role_name: boo
+```
+
+[cop]: https://redhat-cop.github.io/automation-good-practices/#_naming_things
+[var-names]:
+ https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_variables.html#creating-valid-variable-names
+[magic-vars]:
+ https://docs.ansible.com/ansible/latest/reference_appendices/special_variables.html