archive module 'exclude_path' documentation is very misleading

[skylerbunny]

ISSUE TYPE

• Documentation Report

COMPONENT NAME

archive

ANSIBLE VERSION

ansible 2.4.2.0
  config file = /Users/rsteinfeldt/Documents/discovery-ansible/ansible.cfg
  configured module search path = [u'/Users/rsteinfeldt/.ansible/plugins/modules', u'/usr/share/ansible/plugins/modules']
  ansible python module location = /Users/rsteinfeldt/Documents/ansible/lib/python2.7/site-packages/ansible
  executable location = /Users/rsteinfeldt/Documents/ansible/bin/ansible
  python version = 2.7.14 (default, Sep 25 2017, 09:53:22) [GCC 4.2.1 Compatible Apple LLVM 9.0.0 (clang-900.0.37)]

CONFIGURATION

OS / ENVIRONMENT

OS X 10.12.x

SUMMARY

STEPS TO REPRODUCE

Suppose I have a directory structure that looks like this, and the following playbook:

/tmp
/tmp/foo
/tmp/bar.txt
/tmp/dir/
/tmp/dir/stuff_in_dir.txt

```yaml
- name: Create archive
  archive:
    path:
        - /tmp
    dest: /myarchive.tar.gz
    exclude_path:
        - /tmp/bar.txt

EXPECTED RESULTS

I would expect bar.txt to be excluded from the created archive, as per http://docs.ansible.com/ansible/latest/archive_module.html : "Remote absolute path, glob, or list of paths or globs for the file or files to exclude from the archive"

ACTUAL RESULTS

bar.txt is included in the archive anyway. From the testing I've done, it appears that the ONLY thing exclude_path entries do is to explicitly remove-after-the-fact top level listings that were declared with wildcards in path.

So I can do this:

- name: Create archive
  archive:
    path:
        - /tmp/*
    dest: /myarchive.tar.gz
    exclude_path:
        - /tmp/bar.txt

NOW bar.txt isn't included in the archive I create, but its top level is not /tmp/*, it simply is 'foo', 'bar.txt', 'dir/', etc.

The way the documentation is written for the archive module, it's very easy for someone to assume that exclude_paths works the way tar cfvz --exclude tmp/bar.txt /tmp would, because it's never explained that exclude_path only operates against the list explicitly provided in path. What it doesn't say is the bigger problem over what it does say: I'd suggest wording more like this.

exclude_path (added in 2.4): One remote absolute path or glob; or a list of absolute paths or globs, to exclude from adding to the archive, tested only against the list expanded in the path variable. File or directory names which do not appear in the list or expanded globs from path will have no effect.

[ansibot]

Files identified in the description:

• lib/ansible/modules/files/archive.py

If these files are inaccurate, please update the component name section of the description or use the !component bot command.

click here for bot help

[ansibot]

cc @bendoh
click here for bot help

[skylerbunny]

It occurs to me of course that the issue may be that exclude_paths is supposed to mimic the behavior of tar --exclude. If that's the case, then the current documentation is essentially correct as worded, and this is a bug against how the archive module actually works. I have no idea which.

[josh-cain]

Just sank some time into this one as well, as I was deceived by the documentation. Would definitely be up for a more clear demonstration of what this does and does not do.

[bendoh]

Thanks for the report.

It looks like it should be fairly straight-forward to add exclusion of files and paths for tar archives using the filter argument to TarFile.add, but there doesn't appear to be any equivalent in the ZipFile object, so the only way to add that sort of support would be to explicitly recurse through the tree in python and exclude at that level, which might as well then be leveraged for adding files individually to the tar archives. This will definitely be less efficient, but lead to a more correct result.

So the simple solution is to add support for tar archives only and perhaps emit a warning when this sort of exclusion is desired in zip archives, but the more complete solution is to bring the filesystem walk into the python level, filter there, and add files individually.

EDIT: Looking into this further, it seems that the filesystem is already being walked at the python level, so this should be pretttty easy to implement.

[kimegede]

I have the same issue / expectations.

[bendoh]

resolved_by_pr 34659

[tishma]

I'm defaulting to shell/tar, as #34659 seems stale for too long...

[belkone]

is there any progress in the subject?

[whereisaaron]

Yes, I too believed the documentation and wasted time trying to work out why this option wasn't working for me.

Given it seems unlikely any of the fixes will be merged, could the documentation be updated to remove the option or to mark it as broken?

https://docs.ansible.com/ansible/latest/modules/archive_module.html

Remote absolute path, glob, or list of paths or globs for the file or files to exclude from the archive.

[ansibot]

Thank you very much for your interest in Ansible. Ansible has migrated much of the content into separate repositories to allow for more rapid, independent development. We are closing this issue/PR because this content has been moved to one or more collection repositories.

• lib/ansible/modules/files/archive.py -> https://galaxy.ansible.com/community/general

For further information, please see:
https://github.com/ansible/ansibullbot/blob/master/docs/collection_migration.md