ansible-lint 5.0 upgrade guidelines

[ssbarnea]

This post aims to document what changes you should expect when upgrading ansible-lint to 5.0.

Assure you install the linter correctly

• Read updated installation instructions. You will have to manually specify which version of ansible you want to be used as none will be installed implicitly. Same applies for yamllint, which is a new extra.
• You will likely have to do git ignore .cache as linter may create a cache folder in multiple situations: standalone roles, mocking and requirements installation are all using it.
• If you are running ansible-lint as a pre-commit hook, update the configuration like below:

#  .pre-commit-config.yaml
  - repo: https://github.com/ansible/ansible-lint.git
    rev: v5.0.0
    hooks:
      - id: ansible-lint
        # add lines below:
        additional_dependencies:
          - ansible>=2.10,<2.11  # or use ansible-base if you want the slim version
          - yamllint>=1.25.0,<2.0. # this enables YAML support

If you have custom rules you will have to update them as base class methods changed.

• Rule.match() signatured changed by Refactor Rule.match to enforce stable signature #1153
• Rule.matchtask() signature changed by Consolidate signature of matchtask() #1247
• Rule.matchyaml() signature changed by Add rule violations from Yamllint #955

Other notable changes

• You need to install yamllint package yourself to activate this rule as this is not listed as a direct dependency.
• removed rules E201 and E204 that are already covered by yamllint were removed. We now use yamllint to perform style checks. If you skipped these rules you now need to use their new tags: yamllint-trailing-spaces instead of 201 and yamllint-trailing-spaces instead of 204

Known bugs or limitations

• if you do not want to get yamllint errors reported but you already have yamllint module installed, you need to add yaml to the skip_list.

[MarkusTeufelberger]

Is it really necessary to install ansible or is ansible-base (soon ansible-core) already enough?

I also recommend to pin versions a bit tighter than just "whatever is newest".

[ssbarnea]

@MarkusTeufelberger I updated the example to mention that ansible-base can be used. The installation instructions already do that.

Shortly: the linter works fine with the base/core version of Ansible and it will also raise errors if user is trying to use missing community collections.

I know that this made installation bit more complex, but it was the only way possible to empower the users to pick their own poison.

I also included some safe ranges in the examples, ones that should avoid surprises from major releases.

[sean-m-sullivan]

Been testing this today, with two collections, both had their issues in previous versions of 5.0. This is how I've set it to run.

  - repo: 'https://github.com/ansible-community/ansible-lint.git'
    rev: v5.0.0rc1
    hooks:
      - id: ansible-lint
        pass_filenames: false
        always_run: true
        entry: >-
          ansible-lint -vp -c .github/workflow-config/.ansiblelint.yml

and this is the config

parseable: true
use_default_rules: true

Everything is looking good from the testing.

[geerlingguy]

My roles seem to be failing now, due to the role not being found :/ Opened #1329 for that.

[ssbarnea]

If you would install your role before running the linter it would work. I find quite hard to invest time in investing time in standalone-roles because they are unofficially deprecated and I know for sure that they do not have a future (i have a blog post in review about the subject).

Still, I will try to do something for 5.0.1 as I recognize that there is an important number of users still linting old roles.

[soinu]

I find quite hard to invest time in investing time in standalone-roles because they are unofficially deprecated

Who says that? O.o

[geerlingguy]

Agreed, so far I have only heard that the official "Automation Hub" system will not be supporting roles by themselves (only in collections), but that Galaxy and Ansible itself will continue to work with roles... pretty much forever.

The day that changes is the day I take a second look at Puppet or Chef.

[decentral1se]

Does Ansible-lint now run Yamllint when it is installed with this new version? Because I can't see how to pass it my yamllint configuration file when it does. I run yamllint separately normally. I will just disable this for now via https://ansible-lint.readthedocs.io/en/latest/default_rules.html#yaml

[decentral1se]

Disabling Yamllint doesn't seem to work when it is run under Molecule?

[ssbarnea]

Yep yamllint is run by default if installed as some of its rules used to be implemented by ansible-lint too.

If you want to ignore it, just add yaml to skip list and it will ignore violations reported by yamllint.

Regarding which yamllint configuration is used: we use and internal default config which is very close to the default one used by yamllint but if you have a local .yamllint config, that one will take precedence. Shortly results from running yamllint directly or via ansible-lint should be consistent when a config file is present. If that does not happen file a bug and I will try to take care of it.

Based on my tests with pre-releases on various repositories, I did not encounter YAML issues but that is probably because all of them already run it and had a config file.

[sean-m-sullivan]

We disabled it as you stated due to some specific rules around line length and truthy, Think the features useful for an all in one, but am not using Molecule, so not sure what to change for that.

[decentral1se]

Thanks for the explanation. In the case of the local `.yamllint`, I do have that in the root of my repository. Normally, in my Molecule configs, I do `yamllint -c ../../.yamllint.yml .` but I can't pass that `-c` to `ansible-lint` because it has its own configuration file. Can I specify `yamllint` configuration in the `ansible-lint` configuration file? If `ansible-lint` is going to automatically run `yamllint` under the hood, then it needs to accept an option to point to a `yamllint` configuration file IMHO. Thanks for all the efforts.

…

On 0, Sorin Sbarnea ***@***.***> wrote: Yep yamllint is run by default if installed as some of its rules used to be implemented by ansible-lint too. If you want to ignore it, just add yaml to skip list and it will ignore violations reported by yamllint. Regarding which yamllint configuration is used: we use and internal default config which is very close to the default one used by yamllint but if you have a local .yamllint config, that one will take precedence. Shortly results from running yamllint directly or via ansible-lint should be consistent when a config file is present. If that does not happen file a bug and I will try to take care of it. Based on my tests with pre-releases on various repositories, I did not encounter YAML issues but that is probably because all of them already run it and had a config file. — You are receiving this because you commented. Reply to this email directly, [1]view it on GitHub, or [2]unsubscribe. References Visible links 1. #1150 (reply in thread) 2. https://github.com/notifications/unsubscribe-auth/AAPGFUPZKO2BWWZDSSDRASTS6KGG3ANCNFSM4VIITIAQ

[ssbarnea]

There is a reason why I do not think this would help: ansible-lint could be executed from various subfolders inside the project, which would mean that you will be forced to pass it an absolute path in order to find the file.

Keeping a single .yamllint file at the root of your repository should work fine and avoid the need to pass any config anywhere. Is there something that prevents you from doing this?

TBH, Having more than one config file per-repository was not really on my watch list ;)

My personal view is that custom config files on linters are prone to generate problems because other tools will fail to find them. Imagine that your editor/idea would start reporting other kind of issues because it failed to detect in-repo config of your linter. This happens with flake8/pylint/... and the only way I found it to work decently was to always stick to standard config filenames, those that are discovered naturally by the tools.

[geerlingguy]

@ssbarnea ansible-lint doesn't seem to be using the .yamllint file at the root of my repo :(

See: https://github.com/geerlingguy/pi-webcam/runs/1896095171

Yamllint file is in the root: https://github.com/geerlingguy/pi-webcam

Edit: Opened bug: #1344

[geerlingguy]

custom config files on linters are prone to generate problems because other tools will fail to find them

This is why I'd argue ansible-lint shouldn't be automagically running yamllint.

[hawksight]

Has something changed in the way that ansible-lint reads role directories? on the lat 4.X version it would respect my ansible.cfg and find roles installed in any of the directories listed such as:

roles_path = ~/.ansible/roles:roles

But every time I'm running ansible-lint now, it is always just looking in the local directory (my second option)

❯ ansible-lint -c .ansible-lint.yaml

Running ansible-galaxy install --roles-path .cache/roles -vr requirements.yml
Running ansible-galaxy collection install -p .cache/collections -vr requirements.yml
Added ANSIBLE_COLLECTIONS_PATH=.cache/collections
Added ANSIBLE_ROLES_PATH=roles

Is roles path respected from ansible.cfg? only I keep getting this internal-error on a playbook:

internal-error: the role 'geerlingguy.nodejs' was not found in /home/peter/projects/sopost/gcloud-infrastructure/ansible/playbooks/roles:/home/peter/projects/sopost/gcloud-infrastructure/ansible/roles:/home/peter/projects/sopost/gcloud-infrastructure/ansible/playbooks

The offending line appears to be:

  roles:
    - geerlingguy.nodejs
      ^ here

If I set that env var whilst running then I'm sorted, but I think by default the ansible.cfg file should be respected if found?

ANSIBLE_ROLES_PATH=~/.ansible/roles:roles ansible-lint -c .ansible-lint.yaml 

Actually I have managed to work around this by using the ANSIBLE_CONFIG env var and moving to the repository root.
I am getting issues loading vault files and cannot skip them with the skip_list option. They always appear.

[elgalu]

Same issue, I had to downgrade to v4.3.7, does someone knows why ansible-lint>=5 is not reading ansible.cfg ?

[aminvakil]

You will likely have to do git ignore .cache as linter may create a cache folder in multiple situations: standalone roles, mocking and requirements installation are all using it.

Although .cache is necessary in multiple situations as stated, this behaviour is unexpected in my opinion and it's not something I expect from I run ansible-lint . in my standalone role.

I'm suggesting it gets removed after it has been created or at least provide an option, so that if gets passed to ansible-lint, .cache folder gets removed.

Also @felixfontein had another solution: "maybe it would be better to create that symlink in /tmp and clean up on exit".

I've brought this up in #ansible-lint IRC channel before and for the record adding this here too.

[ssbarnea]

@aminvakil @hawksight Take a look at #1419 which is a first step towards addressing .cache concerns, at least it will create only one folder per repository, regardless the current cwd.

[aminvakil]

@ssbarnea Thank you very much for this.

[perlun]

Worth mentioning: the skip_list syntax changed from older versions to 5.0. Here's the diff for our particular config. The command-instead-of-shell etc. names are displayed when you run ansible-lint, so it's fairly easy to cobble the updated config together based on your code base.

diff --git .ansible-lint .ansible-lint
index da3211b..76f3b68 100644
--- .ansible-lint
+++ .ansible-lint
@@ -1,8 +1,8 @@
 skip_list:
-  - 204   # Lines should be no longer than 160 chars
-  - 305   # Use shell only when shell functionality is required
-  - 503   # Tasks that run when changed should likely be handlers
-  - 701   # No 'galaxy_info' found
+  - command-instead-of-shell  # Use shell only when shell functionality is required
+  - no-handler                # Tasks that run when changed should likely be handlers
+  - meta-no-info              # No 'galaxy_info' found
+  - unnamed-task              # All tasks should be named