AAP-34017 Add Ansible-lint chapter to Devtools doc

Author: ariordan-redhat

downstream/assemblies/devtools/assembly-devtools-lint.adoc

@@ -11,12 +11,28 @@ endif::[]
 
 = Working with ansible-lint
 
-:context: devtools-lint
-
-// You must move roles into collections if you want to use them in {PlatformNameShort}.
-
-Working with ansible-lint
-
+:context: devtools-ansible-lint
+
+include::devtools/ref-devtools-ansible-lint-about.adoc[leveloffset=+1]
+include::devtools/proc-debugging-playbook.adoc[leveloffset=+1]
+include::devtools/proc-devtools-ansible-lint-rules.adoc[leveloffset=+1]
+include::devtools/proc-devtools-ansible-lint-customize.adoc[leveloffset=+1]
+include::devtools/proc-devtools-ansible-lint-profiles.adoc[leveloffset=+1]
+// include::devtools/ref-devtools-ansible-lint-usage.adoc[leveloffset=+1]
+include::devtools/proc-devtools-ansible-lint-cli.adoc[leveloffset=+1]
+include::devtools/ref-devtools-ansible-lint-switches.adoc[leveloffset=+2]
+include::devtools/proc-devtools-ansible-lint-autofix.adoc[leveloffset=+3]
+include::devtools/proc-devtools-ansible-lint-exclude-rules.adoc[leveloffset=+2]
+include::devtools/proc-devtools-ansible-lint-ci.adoc[leveloffset=+1]
+// Include mute warnings?
+include::devtools/ref-devtools-ansible-lint-muting-warnings.adoc[leveloffset=+2]
+include::devtools/ref-devtools-ansible-lint-cache.adoc[leveloffset=+2]
+include::devtools/ref-devtools-ansible-lint-gradual-adoption.adoc[leveloffset=+2]
+include::devtools/proc-devtools-ansible-lint-vaults.adoc[leveloffset=+1]
+include::devtools/ref-devtools-ansible-lint-dependencies.adoc[leveloffset=+1]
+// Add a section about extending lint.
+// Not includoing the Specifying rules at runtime section because we don't encourage using custom rules.
+// proc-devtools-ansible-lint-all.adoc
 // include::devtools/proc-devtools-zzz.adoc[leveloffset=+1]
 
 ifdef::parent-context-of-devtools-lint[:context: {parent-context-of-devtools-lint}]

downstream/assemblies/devtools/assembly-devtools-lint.html

@@ -130,6 +130,8 @@
 :IDEcollection: Ansible IDE collection explorer
 :IDElanguage: Ansible IDE language server
 :VSCode: VS Code
+:LintName: Ansible Lint
+:LintCmd: ansible-lint
 
 // Content Collections
 :CertifiedName: Ansible Certified Content Collections

downstream/attributes/attributes.adoc

@@ -0,0 +1,31 @@
+[id="debugging-playbook_{context}"]
+
+= Debugging with ansible-lint in {VSCode}
+
+When the Ansible extension is running in {VSCode}, ansible-lint runs in the background.
+Diagnostics information for files whose language is identified as Ansible is displayed in the *Problems* tab of the terminal.
+
+// == Error messages
+
+The following playbook contains multiple errors:
+
+----
+- name:
+  hosts: localhost 
+  tasks:
+   - name: 
+     ansible.builtin.ping:
+----
+
+The errors are indicated with a wavy underline in {VSCode}.
+Hover your mouse over an error to view the details:
+
+image::ansible-lint-errors.png[Popup message explaining a playbook error]
+
+The errors are listed in the *Problems* tab of the {VSCode} terminal.
+Playbook files that contain errors are indicated with a number in the *Explorer* pane:
+
+image::ansible-lint-errors-explorer.png[Playbook errors shown in Problems tab and explorer list]
+
+`$[0].tasks[0].name None is not of type 'string'` indicates that the playbook does not have a label.  
+

downstream/modules/devtools/:wq

@@ -1,8 +1,11 @@
 [id="debugging-playbook_{context}"]
 
-= Debugging your playbook
+= Debugging with ansible-lint in {VSCode}
 
-== Error messages
+When the Ansible extension is running in {VSCode}, ansible-lint runs in the background.
+Diagnostics information for files whose language is identified as Ansible is displayed in the *Problems* tab of the terminal.
+
+// == Error messages
 
 The following playbook contains multiple errors:
 

downstream/modules/devtools/proc-debugging-playbook.adoc

@@ -0,0 +1,58 @@
+[id="devtools-ansible-lint-autofix_{context}"]
+
+= Autofix
+
+Ansible-lint provides an autofix feature that allows auto-fixing of some rule violations in Ansible files.
+
+To reformat YAML files and run transform for the given rules, run the following command:
+
+----
+ansible-lint --fix [<write_list>]
+----
+
+Use the `write-list` to limit the rules that you want to auto-fix
+by passing a keywords `all` or `none` or a comma separated list of rule ids or rule tags.
+
+* `ansible-lint --fix ["all"]` (default) runs all transforms.
+* `ansible-lint --fix ["none"]` disables all auto-fixes.
+* `ansible-lint --fix ["csv-list-of-rules"]` enables a subset of rule transforms by listing rules/tags here.
+
+The following rules allow autofix functionality.
+
+[options="header" cols="30,70"]
+|===
+|Options |Description
+|`command-instead-of-shell`
+|Use shell only when shell functionality is required.
+
+|`deprecated-local-action`
+|Do not use `local_action`, use `delegate_to: localhost`.
+
+|`fqcn`
+|Use FQCN for builtin actions.
+
+|`jinja`
+|Rule that looks inside jinja2 templates.
+
+|`key-order`
+|Ensure specific order of keys in mappings.
+
+|`name`
+|Rule for checking task and play names.
+
+|`no-free-form`
+|Rule for detecting discouraged free-form syntax for action modules.
+                             
+|`no-jinja-when`
+|No Jinja2 in when.
+
+|`no-log-password`
+|Password should not be logged.
+
+|`partial-become`
+|`become_user` should have a corresponding `become` at the play or task level.
+
+|`yaml`
+|Violations reported by yamllint.
+|===
+

downstream/modules/devtools/proc-devtools-ansible-lint-autofix.adoc

@@ -0,0 +1,4 @@
+[id="devtools-ansible-lint-ci_{context}"]
+
+= Using ansible-lint in CI
+

downstream/modules/devtools/proc-devtools-ansible-lint-ci.adoc

@@ -0,0 +1,42 @@
+[id="devtools-ansible-lint-cli_{context}"]
+
+= Running ansible-lint from the command line
+
+Run `ansible-lint --help` to display available commands and their options.
+
+Ansible-lint recommends following the
+https://docs.ansible.com/ansible-core/devel/dev_guide/developing_collections_structure.html#collection-structure[collection
+structure layout] whether you plan to build a collection or not.
+
+Following that layout assures the best integration with all ecosystem
+tools because it helps those tools better distinguish between random
+YAML files and files managed by Ansible. When you call `ansible-lint`
+without arguments, it uses internal heuristics to determine file types.
+
+Pass the *roles* and *playbooks* that you want to lint as arguments to
+the `ansible-lint` command. For example, to lint
+`examples/playbooks/play.yml` and `examples/roles/bobbins`, use the
+following command:
+
+----
+$ ansible-lint examples/playbooks/play.yml examples/roles/bobbins
+----
+
+// == Running example playbooks
+// 
+// Ansible-lint includes an `ansible-lint/examples` folder that contains
+// example playbooks with different rule violations and undesirable
+// characteristics. You can run `ansible-lint` on the example playbooks
+// to observe Ansible-lint in action, as follows:
+// 
+// ----
+// $ ansible-lint --offline -p examples/playbooks/example.yml
+// ----
+
+Ansible-lint also handles playbooks that include other playbooks, tasks,
+handlers, or roles.
+// 
+// ----
+// $ ansible-lint --offline -q -p examples/playbooks/include.yml
+// ----
+

downstream/modules/devtools/proc-devtools-ansible-lint-cli.adoc

@@ -0,0 +1,185 @@
+[id="devtools-ansible-lint-customize_{context}"]
+
+= Customizing {LintName}
+
+You can customize how {LintName} runs against automation content to suit your needs.
+You can ignore certain rules, enable opt-in rules, and control various other settings.
+
+{LintName} loads configuration from the `.ansible-lint.yml` configuration file, or from a file that you specify in the command line.
+This file is not scaffolded when you create a playbook or collection project.
+You must create the file in the `.config` directory of your {VSCode} workspace.
+
+Any configuration option that is passed from the command line will override the one specified inside the configuration file.
+
+The example `.ansible-lint.yml` file below selects the `production` profile.
+The settings are explained in the comments.
+
+----
+---
+# .ansible-lint
+
+profile: production     # min, basic, moderate,safety, shared, production, null
+
+# Allows dumping of results in SARIF format
+# sarif_file: result.sarif
+
+# exclude_paths included in this file are parsed relative to this file's location
+# and not relative to the CWD of execution. CLI arguments passed to the --exclude
+# option are parsed relative to the CWD of execution.
+exclude_paths:
+  - .cache/ # implicit unless exclude_paths is defined in config
+  - test/fixtures/formatting-before/
+  - test/fixtures/formatting-prettier/
+# parseable: true
+# quiet: true
+# strict: true
+# verbosity: 1
+
+# Mock modules or roles in order to pass ansible-playbook --syntax-check
+mock_modules:
+  - zuul_return
+  # note the foo.bar is invalid as being neither a module or a collection
+  - fake_namespace.fake_collection.fake_module
+  - fake_namespace.fake_collection.fake_module.fake_submodule
+mock_roles:
+  - mocked_role
+  - author.role_name # old standalone galaxy role
+  - fake_namespace.fake_collection.fake_role # role within a collection
+
+# Enable checking of loop variable prefixes in roles
+loop_var_prefix: "^(__|{role}_)"
+
+# Enforce variable names to follow pattern below, in addition to Ansible own
+# requirements, like avoiding python identifiers. To disable add `var-naming`
+# to skip_list.
+var_naming_pattern: "^[a-z_][a-z0-9_]*$"
+
+use_default_rules: true
+# Load custom rules from this specific folder
+# rulesdir:
+#   - ./rule/directory/
+
+# Ansible-lint is able to recognize and load skip rules stored inside
+# `.ansible-lint-ignore` (or `.config/ansible-lint-ignore.txt`) files.
+# To skip a rule just enter filename and tag, like "playbook.yml package-latest"
+# on a new line.
+# Optionally you can add comments after the tag, prefixed by "#". 
+# When putting ignores inside the ignore file, they are marked as ignored, but
+# still visible, making it easier to address later.
+
+# Ansible-lint does not automatically load rules that have the 'opt-in' tag.
+# You must enable opt-in rules by listing each rule 'id' below.
+enable_list:
+  - args
+  - empty-string-compare # opt-in
+  - no-log-password # opt-in
+  - no-same-owner # opt-in
+  - name[prefix] # opt-in
+  - galaxy-version-incorrect # opt-in
+  # add yaml here if you want to avoid ignoring yaml checks when yamllint
+  # library is missing. Normally its absence just skips using that rule.
+  - yaml
+# Report only a subset of tags and fully ignore any others
+# tags:
+#   - jinja[spacing]
+
+# Ansible-lint does not fail on warnings from the rules or tags listed below
+warn_list:
+  - skip_this_tag
+  - experimental # experimental is included in the implicit list
+  # - role-name
+  # - yaml[document-start]  # you can also use sub-rule matches
+
+# Some rules can transform files to fix (or make it easier to fix) identified
+# errors. `ansible-lint --fix` will reformat YAML files and run these transforms.
+# By default it will run all transforms (effectively `write_list: ["all"]`).
+# You can disable running transforms by setting `write_list: ["none"]`.
+# Or only enable a subset of rule transforms by listing rules/tags here.
+# write_list:
+#   - all
+
+# Offline mode disables installation of requirements.yml and schema refreshing
+offline: true
+
+# Define required Ansible's variables to satisfy syntax check
+extra_vars:
+  foo: bar
+  multiline_string_variable: |
+    line1
+    line2
+  complex_variable: ":{;\t$()"
+
+# Uncomment to enforce action validation with tasks, usually is not
+# needed as Ansible syntax check also covers it.
+# skip_action_validation: false
+
+# List of additional kind:pattern to be added at the top of the default
+# match list, first match determines the file kind.
+kinds:
+  # - playbook: "**/examples/*.{yml,yaml}"
+  # - galaxy: "**/folder/galaxy.yml"
+  # - tasks: "**/tasks/*.yml"
+  # - vars: "**/vars/*.yml"
+  # - meta: "**/meta/main.yml"
+  - yaml: "**/*.yaml-too"
+
+# List of additional collections to allow in only-builtins rule.
+# only_builtins_allow_collections:
+#   - example_ns.example_collection
+
+# List of additions modules to allow in only-builtins rule.
+# only_builtins_allow_modules:
+#   - example_module
+
+# Allow setting custom prefix for name[prefix] rule
+task_name_prefix: "{stem} | "
+# Complexity related settings
+
+# Limit the depth of the nested blocks:
+# max_block_depth: 20
+----
+
+The following example `.ansible-lint.yml` file excludes the comments.
+It selects the `production` profile and enables fixing of files.
+
+----
+---
+profile: 'production'
+
+loop_var_prefix: '^(__|{role}_)'
+var_naming_pattern: '^[a-z_][a-z0-9_]*$'
+use_default_rules: true
+offline: true
+skip_action_validation: false
+
+kinds:
+  - tasks: 'tasks/*.{yml,yaml}'
+  - vars: 'vars/*.{yml,yaml}'
+  - vars: 'defaults/*.{yml,yaml}'
+  - meta: 'meta/main.{yml,yaml}'
+  - yaml: '.ansible-lint'
+  - yaml: '.github/workflows/*.{yml,yaml}'
+  - yaml: '.pre-commit-config.yaml'
+  - yaml: '.yamllint'
+  - yaml: 'collections/requirements.yml'
+
+task_name_prefix: '{stem} | '
+
+exclude_paths:
+  - '.git/'
+  - 'files/'
+
+max_block_depth: 20
+skip_list: []
+warn_list:
+  - 'experimental'
+write_list:
+  - 'all'
+----
+
+To specify the configuration file, use the `-c <filename>` CLI flag with command line invocations of `{LintCmd}`:
+
+----
+ansible-lint -c path/to/ansible-lint-dev.yml
+----
+

downstream/modules/devtools/proc-devtools-ansible-lint-customize.adoc

@@ -0,0 +1,14 @@
+[id="devtools-ansible-lint-exclude-rules_{context}"]
+
+
+= Excluding ansible-lint rules
+
+To exclude specific rules from being applied when linting a playbook, use the `-x` flag.
+This is useful if you want to temporarily disable certain rules without modifying your configuration file.
+
+The following example lints a file but skips the checks for YAML formatting rules and tabs:
+
+----
+ansible-lint -x no-tabs -x yaml <filename.yml>
+----
+