About file sync

File sync helps Code Manager keep your Puppet code synchronized across your primary server and compilers.

When a code deployment is triggered, Code Manager uses r10k to fetch code (over HTTPS or SSH) from the Git server and places the code into the staging directory on the primary server (at /etc/puppetlabs/code-staging), which is an internal Git server.

Next, the file sync storage service on the primary server detects the change in the staging directory, and the file sync clients pause Puppet Server to avoid conflicts during synchronization. Finally, the file sync clients synchronize the new code to the live code directories on the primary server and compilers (usually at /etc/puppetlabs/code).

File sync only deploys Puppet code when an agent is ready to receive the new code. This ensures that your agents' code doesn't change during a Puppet run. File sync triggers an environment cache flush when the deployment is finished, which ensures that new Puppet agent runs use the newly-deployed Puppet code.

Important:

File sync is part of Code Manager, and you usually don't need to directly configure or trigger file sync.

Directly accessing the file sync API is unsupported and not recommended.

For information about how code deployments are triggered, refer to How Code Manager works.

Tip: If you want code deployments to run uninterrupted while Orchestrator plans are running, you can enable Running plans alongside code deployments.

File sync terms

Understanding these terms is helpful for understanding file sync.

Control repository
Used for storing your Puppet code and maintaining separate code for different environments (such as production, development, or testing). Each environment is represented by a branch of the control repo. For more information, refer to Managing environments with a control repository.
Each environment branch has a Puppetfile specifying exactly which modules to install in each environment. You can learn more About Environments in the Puppet documentation.
Live code directory
This directory contains all your Puppet manifests and modules for each environment (Code Manager creates directory environments based on the branches you've set up in your control repo). Puppet Server uses this directory for catalog compilation. This directory is present on your primary server and all compilers.
The directory's location is specified in the Puppet Server master-code-dir setting and the Puppet$codedir setting. The default value is /etc/puppetlabs/code, which is also the default location for the live code directory.
In file sync configuration settings, the live code directory is sometimes abbreviated as live-dir.
Staging code directory
Code Manager detects code changes that you make in your control repository, and then Code Manager stages the updated code in the staging code directory. From there, file sync moves the updated code to the live code directories.
While the primary server and all compilers have their own live code directories, the staging code directory is only present on the primary server. The default location is /etc/puppetlabs/code-staging.

How file sync works

File sync helps distribute your Puppet code to your primary server, compilers, and agents.

By default, file sync is disabled and there is no staging directory on the primary server. If you're upgrading from Puppet Enterprise (PE) 2015.2 or earlier, file sync is automatically disabled after the upgrade. When you Set up Code Manager, you also enable file sync. This creates the staging directory on the primary server, which Code Manager can then populate with Puppet code it detects in your control repo.

Once Code Manager pulls code from your control repo and places it in the staging directory, file sync synchronizes the code to the primary server's live code directory, and then to the live code directories on all compilers. Once deployed to compilers, the new code is available to agents that check in to those compilers.

Usually, code deployments are handled by Code Manager, but, only if absolutely necessary, you could use the POST file-sync/v1/commit endpoint to manually trigger a file sync deployment.
Important:

File sync is part of Code Manager, and you usually don't need to directly configure or trigger file sync.

File sync endpoint documentation is for informational purposes only. Directly accessing the file sync API is unsupported and not recommended.

You can call the endpoint from the primary server, and your request must contain:
  • A content type specification in the header: Content-Type: application/json
  • Authentication. Namely, the primary server's SSL certificate and private key, and the Puppet CA's certificate.
  • The POST action.
  • A URI made up of:
    • The primary server's fully qualified domain name, which you can call with puppet config print server or the literal domain name.
    • The port the endpoint listens on. The default is 8140.
    • The endpoint identifier: file-sync/v1/commit
  • A JSON body containing {"commit-all" : true}
For example:
type_header='Content-Type: application/json'
cert="$(puppet config print hostcert)"
cacert="$(puppet config print localcacert)"
key="$(puppet config print hostprivkey)"
uri="https://$(puppet config print server):8140/file-sync/v1/commit"
data='{"commit-all": true}'

curl --header "$type_header" --cert "$cert" --cacert "$cacert" --key "$key" --request POST "$uri" --data "$data"

For general information about forming curl commands, authentication in commands, and Windows modifications, go to Using example commands.

A successful request triggers file sync to commit the latest changes from the staging directory to the primary server's live code directory. The next time the compilers poll the file sync service for code changes, they receive the newly-committed code and deploy it into their own live code directories, where it is available for agents checking in to those compilers. By default, compilers poll for changes every 5 seconds.

Code commits can be restricted to a specific environment and can include details, such as a message or information about the commit author.

Enabling or disabling file sync

File sync is normally enabled or disabled automatically along with Code Manager.

File sync's behavior is linked to Code Manager. Because Code Manager is disabled by default, file sync is also disabled by default. To enable file sync, you must Set up Code Manager. You can enable and configure Code Manager either during or after you install Puppet Enterprise (PE).

In the PE console, the file_sync_enabled parameter, in the puppet_enterprise::profile::master class, defaults to automatic, which means that file sync is enabled and disabled automatically when Code Manager is enabled or disabled. If you set the file_sync_enabled parameter to true, it forces file sync to be enabled even if Code Manager is disabled. The file_sync_enabled parameter doesn't appear in the puppet_enterprise::profile::master class definitions – you must add the parameter to the class if you want to set it.

Resetting file sync

You'll need to reset the file sync service if file sync enters a failure state, if file sync consumes all available disk space, or a repository becomes irreparably corrupted.

Resetting the file sync service deletes the commit history for all repositories that file sync tracks. This frees up disk space and returns the service to a fresh state while preserving code in the staging directory.
  1. On your primary server:
    • If you use Code Manager: Make sure the code you want to deploy is present in the staging directory at /etc/puppetlabs/code-staging, and make sure that your most-recently deployed code is present in your control repository (so you can re-sync it).
    • If you use r10k: Trigger and r10k code deployment, and make sure your most-recently deployed code is present in your control repository (so you can re-sync it).
    • If you use file sync by itself: Make sure the code you want to deploy is present in the staging directory at /etc/puppetlabs/code-staging.
  2. Stop the Puppet Server service by running: 
    puppet resource service pe-puppetserver ensure=stopped
  3. Delete the data directory located at: 
    /opt/puppetlabs/server/data/puppetserver/filesync/storage
  4. Restart the Puppet Server service by running: 
    puppet resource service pe-puppetserver ensure=running
  5. Take the appropriate action to redeploy your code:
Results
When you reset the file sync service, it creates fresh repositories on each client and on the storage server for the code it manages.

Checking your deployments

If necessary, you can retrieve information about file sync deployments by calling the status/v1/services/file-sync-storage-service endpoint.

Important:

File sync is part of Code Manager, and you usually don't need to directly configure or trigger file sync.

File sync endpoint documentation is for informational purposes only. Directly accessing the file sync API is unsupported and not recommended.

To call the status/v1/services/file-sync-storage-service endpoint, use this curl command:
curl --insecure "https://$(puppet config print server):8140/status/v1/services/file-sync-storage-service?level=debug"

For general information about forming curl commands, authentication in commands, and Windows modifications, go to Using example commands.

A successful request returns a JSON-formatted list of:
  • All clients that file sync is aware of.
  • When those clients last checked in.
  • Which commit the clients currently have deployed.
Tip: For pretty printing, pipe the response to: python -m json.tool

To check if a specific commit was deployed, review the latest_commit in the response. The latest_commit SHA, in this endpoint's response, is specific to file sync. This SHA does not correspond to a commit from your control repository.

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.

Important: 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

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.

CAUTION: 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.