The Puppet Agent

• Overview
• Runtime requirements
• Building puppet-agent
• Building puppet-agent for windows
• Branches in puppet-agent
• Installer plugin for OSX
• License
• Maintainers

Overview

The puppet agent is a collection of software that is required for puppet and its dependencies to run. The full list of software and projects included in the puppet agent can be found in the project definition. This repo is where the puppet-agent vanagon configuration lives. It is used to drive the building of puppet-agent packages for releases.

Runtime Requirements

The Gemfile specifies all of the needed ruby libraries to build a puppet-agent package. Additionally, puppet-agent requires a VM to build within for each desired package.

Environment variables

VANAGON_LOCATION

The location of Vanagon in the Gemfile can be overridden with the environment variable VANAGON_LOCATION. Can be set prior to bundle install or updated with bundle update.

• 0.3.14 - Specific tag from the Vanagon git repo
• git@github.com:puppetlabs/vanagon#master - Remote git location and tag
• file:///workspace/vanagon - Absolute file path
• file://../vanagon - File path relative to the project directory

Building puppet-agent

If you wish to build puppet-agent yourself, it should be relatively easy. First bundle install, followed by bundle exec build puppet-agent <desired platform> <vm hostname>, where the platform is a platform supported by vanagon and vm hostname is the hostname of a vm of the desired platform. The current user must be able to ssh into that vm as root (vanagon has facilities to provide an ssh key beyond what is listed in .ssh/config).

Requirements for building

To build puppet-agent, you'll need the following:

• GCC (>=4.8.0)
• Boost (>=1.57)
• CMake (>= 3.2.3)
• yaml-cpp (>= 0.5.0)

To build puppet-agent on infrastructure outside of Puppet Labs, you'll need to make a few edits in the component and project files. Any references to pl-gcc, pl-cmake, pl-boost, pl-yaml-cpp, etc need to be changed. In many cases, just drop the pl- prefix and ensure that CXX or CC envrionment variables are what they should be.

You also may need to change the source URIs for components. We recognize this is less than ideal at this point, but we wanted to error on the side of getting this work out in public rather than having everything perfect.

If you have your own mirror of the components of puppet-agent, you can also use a rewrite rule. See the Vanagon README for an example.

Building puppet-agent for windows

For the moment, windows is a special case. It can be built using a similar pattern to other platforms. BUILD_TARGET=win-x86 ruby bin/build-windows.rb is the way to do this. The windows build assumes access to Puppet Labs' vm pooler and does not currently accept a hostname override. VANAGON_SSH_KEY is respected for ssh key overrides.

Pre-built packages in S3 are generated by running the Windows build, and using- 7-zip to compress the resulting directories into .7z files of the same name, i.e. 7za a <dirname>.7z <dirname>. The packages are then uploaded to s3://kylo-pl-bucket. Once uploaded these files need to be made public, using something like s3cmd setacl -P s3://kylo-pl-bucket/<file>.

The Windows build currently uses nuget packages hosted at https://www.myget.org/F/puppetlabs. We roll the binaries into the nuget packages to reduce dependencies on external sites, particularly SourceForge. To access myget you'll need to setup a free account and get an existing account holder to add you to the organization; most of RE has access.

To get started creating nuget packages, see

• https://npe.codeplex.com/ - download existing packages from a feed
• Nuget packages are just zip files, use 7-zip to unpack them
• https://github.com/chocolatey/choco/wiki/CreatePackages - create new packages

Branches in puppet-agent

There are two types of branches in puppet-agent

• release branches (e.g. aardwolf)
• tracking branches (e.g. master and stable)

The fundamental difference between the two is their relation with CI pipelines, especially wrt the component configurations:

• on a release branch:
  • all components reference component tags never SHAs
• on a tracking branch:
  • some components may reference tags if they’re slow moving (ruby, openssl)
  • some components reference SHAs promoted by a CI pipeline (generally puppet-agent#master pipelines track components' master branches, and likewise for stable)

Guidelines on Merging Between Branches

• stable should be merged to master regularly (e.g. per commit), as is done for component repos; no PR needed
• master should be merged to stable as-needed; typically this is done when a component merges its master to stable, and there are matching changes needed in puppet-agent
• stable should be merged to aardwolf as-needed; typically this is done when a component is tagged and ready for release, and there are matching changes needed in puppet-agent
• aardwolf should be merged to stable after each tag; this ensures that a 'git describe' on stable always refers to a "later" release than what came off aardwolf; this merge can be accomplished with 'git merge aardwolf -s ours' and should not change the contents of any files (because no content changes should ever originate on aardwolf)

Generally, no PR is needed for routine merges from stable to master or aardwolf, but a PR is advised for other merges. Use your judgment of course, and put up a PR if you want review.

Note that for all merges from master or stable, the merge should pick up:

• changes outside of config/components
• changes that bumped to a tag inside config/components

But never:

• changes that bumped to a SHA inside config/components

Here's a sample snippet used for a stable -> aardwolf merge:

git merge --no-commit --no-ff stable
for i in {hiera,facter,puppet,marionette-collective,pxp-agent,cpp-pcp-client}; do git checkout aardwolf -- configs/components/$i.json;done
git checkout aardwolf -- configs/components/windows_*.json
git commit -m "(maint) Restore promoted components refs after merge from stable"

Installer plugin for OSX

The GUI installer for OSX includes a custom plugin that captures and sets information such as the puppet master and certificate name for the client. The source for this Xcode project can be found here.

Issues

File issues in the Pupept Agent (PA) project on the Puppet Labs Jira site. Issues with individual components should be filed in their respective projects.

License

Puppet agent is licensed under the Apache-2.0 license.

Maintainers

The Release and Client Engineering teams at Puppet Labs