File sync cautions

Keep these warnings in mind when working with file sync.

File sync API

Because file sync is part of Code Manager, Code Manager handles communication with the file sync API. Information about the file sync API in this documentation is for informational purposes only.

Do not directly access the file sync API.

Where to edit code

With Code Manager, you only modify code in your control repo. Changes made in invalid locations are overwritten by the next deployment. For more information refer to Understanding file sync and the staging directory.

While extremely uncommon, if you're using file sync without Code Manager, only modify your Puppet code in the staging directory.

By default, the enable-forceful-sync parameter is set to true in Puppet Enterprise (PE). If this is set to false, file sync no longer overwrites changes in the live code directory. Instead, it logs errors to the Puppet Server log (at /var/log/puppetlabs/puppetserver/puppetserver.log).

If you need to set this parameter to false, you must add it with Hiera:

puppet_enterprise::master::file_sync::file_sync_enable_forceful_sync: false

The puppet module command and file sync

The puppet module command doesn't work with file sync. You'll need to specify modules in your environment's Puppetfiles and use Code Manager to handle module code deployments. For information and instructions refer to:

Permissions

File sync runs as the pe-puppet user. To sync files, file sync must have permission to read the staging directory and to write to all files and directories in the live code directories. You can run the following command to make sure the pe-puppet user owns the required directories:

chown -R pe-puppet /etc/puppetlabs/code /etc/puppetlabs/code-staging

Puppet Enterprise chowns the content of the code directory automatically. If users encounter problems while using find and chown, they can disable the behavior by setting the following parameter:


                        puppet_enterprise::master::file_sync::chown_code_to_pe_puppet to false to
                        skip that find/chowns

Environment isolation metadata

File sync generates .pp metadata files in your staging code directory and live code directories. These files provide environment isolation for your resource types, which ensures that each environment uses the correct version of the resource type.

Do not delete or modify the metadata files. Do not use expressions from these files in regular manifests.

For more details about these files and how they isolate resource types in multiple environments, refer to Environment isolation in the Puppet documentation. For information about when these files are generated, refer to Environment isolation metadata and Code Manager.