Abbreviated collection of release notes, doc updates, test plan for Chef 11.6's file provider updates

chef-11-6-file-refactor-notes.md

Release Notes

Changes to Previously Undefined Behaviors

Prior to this patch, Chef did not have a defined behavior for some situations. Users relying on these undefined behaviors may need to make changes to cookbooks when upgrading to 11.6+

• Chef previously did not have a defined behavior if a file provider encountered something other than a file when attempting to update content. In particular, chef would follow symlinks and overwrite the symlink target's content; other dir entry types (such as devices, named pipes, etc.) would fail in strange ways. Chef will now raise an error instead of overwriting the content of a symlink. If you wish to delete whatever's in your way, set force_unlink true on your resource.

• Chef previously did not define what file permissions it would set if a file resource did not specify them, and was inconsistent between different providers and in some cases differed based on the version of ruby used. All file providers will now create files with default permissions determined by the OS and filesystem default behavior. In general this is governed by your umask setting, but may also be affected by filesystem type or mount options.

  This can be a problem when depending on the default file mode when managing ssh keys or config with cookbook_file or template resources. In previous chef versions, cookbook_file would set the mode of a file to 0600 if not explicitly specified, and template resources would set the mode to 0600 if not specified when running on ruby 1.9.3. In Chef 11.6, these are likely to be created with 0644 permissions (assuming a defualt umask), which can cause SSH operations to error out.

New Features and Enhancements

• SELinux support: Chef will restorecon files after modifying them.

• Configurable atomic file updates. Chef lets you choose between atomic (mv-based) or non-atomic (cp-based) file updates. Defaults to atomic. Atomic:

  • will not fail updating important file when out of disk space
  • will not fail updating a running binary
  • may alter file permissions when running as non-root user in some cases
  • files will temporarily have incorrect selinux permissions (until restorecon runs) or windows ACLs (until an ACL restore step runs)

  Non atomic is basically converse of the above.

  Global config: file_atomic_update, per-resource: atomic_update

  NOTE: At the moment, we don't know if this will automatically make community cookbooks work with selinux enabled; it's possible that the debian style file hierarchies used by some community cookbooks conflict with default selinux policy. There is a task to do some testing of this use case so we will know how to set expectations at release time.

• File providers have been significantly refactored, many methods deprecated. Beware if you have custom providers that subclass a file provider.

• Templates can now have custom per-resource methods. CHEF-4220. TODO: examples.

• Remote file can automatically send HTTP conditional GET requests, using ETags and If-Modified-Since. This is enabled by default, use use_conditional_get false to disable, or use_etags false or use_last_modified false to disable individual headers.

• Remote file now supports FTP and local files, using "ftp://" and "file://" URIs, respectively.

• Remote file supports custom headers.

Doc Updates

Config Parameters

• enable_selinux_file_permission_fixup
• file_atomic_update
• file_staging_uses_destdir

All File Resources

• force_unlink parameter
• atomic_update parameter

Template Resource

• helper methods

Remote File Resource

• FTP
• local file
• conditional_get, use_etags, use_last_modified
• headers

Test Plan:

• Run community apache2 recipe with selinux enforcing. We want to learn if (1) chef correctly sets selinux labels and (2) if community cookbooks work with selinux enforcing. Our testing of selinux support is pretty good, but community cookbooks tend to use debian/ubuntu file layouts everywhere and this might not work with default selinux configuration. We need to know how to set expectations around selinux support.
• remote file w/ FTP: create/update a file via remote_file w/ ftp source.
• remote file w/ local file: create/update a file via remote_file w/ file:// source.
• remote file HTTP conditional GET. First fetch should get the file, re-run of recipe should not fetch anything.
• template with helpers (pretty well tested already, but worth a full integration pass).