You are browsing a read-only backup copy of Wikitech. The primary site can be found at


From Wikitech-static
Revision as of 13:10, 20 March 2020 by imported>Jbond (→‎Host variable override)
Jump to navigation Jump to search


You can run puppet-compiler by hand to get the results of a given puppet configuration without having to deploy it to servers.

This page provides a instructions for this process.

Catalog compiler in integration Jenkins

There is a Jenkins job that takes a Gerrit change and runs the compiler.


  1. Push your change to gerrit using git-review
  2. Go to
  3. Go to "Build with parameters"
  4. In the form, fill change number (from Gerrit) and list of nodes
  5. Hit the Build button
  6. Wait for the Jenkins job to end
  7. You can check for results in the Jenkins Console output
  8. You can see the compiled catalogs in a web frontend. The URL structure is, where:
    • compiler_host is the hostname (without domain name) of the compiler node that Jenkins dispatched the build to. A current list of possible compiler nodes is available at
    • build_id is the unique id of the Jenkins build (changes with every run)
    • This link is automatically constructed and can be found at the bottom of the Jenkins console output after each build.

NOTE: this method won't work for CloudVPS instances. See below.

Host variable override

The list_of_nodes supports selecting hosts using the following methods

  • an empty list. In this case pcc attempt to pick one host for each definition in site.pp
  • comma separate list of hosts e.g. example1001.eqiad.wmnet,,example3001.esams.wmnet
  • Regular expression - you can use re: followed by a regular expression to select hosts e.g. to select all puppetmasters use re:puppetmaster.*wmnet
  • Simplified Cumin syntax. you can use the P:, C: and O: cumin prefixes to select hosts based on there profile, class or role e.g.
    • select all hosts with the envoy class: C:envoy
    • select all hosts with the tlsproxy::envoy profile: P:envoy
    • select all hosts with the mediawiki::appserver role: O:envoy

With the simplified cumin syntax we try to select a set of hosts which covers all unique uses cases of the class, profile and role to avoid preforming the same test on multiple nodes. We select this reduced set of hosts based on the host prefix i.e. mw, cp, db etc and they set of puppet tags applied to the host. Check the code for further details

Gerrit integration

There is an experimental feature which allows users to specify the list_of_node in the gerrit commit massage. To do this you need to specify your list_of_nodes using the keyword Hosts: followed by your list of hosts or one of the supported overrides listed above.

Currently there needs to be a space between the Hosts:</code variable and the footer variables like Bug and Change-Id.

Once this is in place you can comment on your change with check experimental and zuul will schedule a PCC using the correct gerrit ID and the hosts specified

Catalog compiler for CloudVPS

The standard Jenkins-hosted catalog compiler can now target VPS instances. Because VMs are frequently created and deleted, it may be necessary to update the facts from whatever puppetmaster is hosting the VM in question. Instructions for doing that can be found at Nova Resource:Puppet-diffs.

Catalog compiler local run (pcc utility)

There is a also a tool called pcc under the operations/puppet/utils repo. You'll need your Jenkins API token to make it work-- retrievable under$YOURUSERNAME/configure.


$ ./utils/pcc GERRIT_CHANGE_NUMBER LIST_OF_NODES --username YOUR_USERNAME --api-token 12312312312312313  
$ ./utils/pcc 282936 oxygen.eqiad.wmnet --username batman --api-token 12312312312312313


Some common errors and mistakes.

  • Catalog for Cloud VPS instances doesn't get any classes/roles.

This happens because $::realm is not set to labs. There are patches in place to fix this, but the puppet-compiler software needs to be released with these patches.

  • ERROR: Unable to find facts for host, skipping

If running locally, collect facts by hand from the corresponding puppetmaster. If running in the Jenkins web service for a production host, follow these instructions.


The puppet-compiler mechanism won't discover all the issues in the resulting catalog. If the catalog was compiled OK by Jenkins, you may still find some issues when running the puppet agent.

Some known limitations:

  • Files sources. When declaring a File { '/my/file':, the path information you specified in the content parameter will be resolved at puppet agent runtime.
  • Private Hiera lookups. The way Hiera fetches data may vary between how it's done in the puppet-compiler process to how it's done in the final puppet master. Specifically, secrets in the private repo.
  • Hiera behavior. Currently, we don't have a way to know in concrete how Hiera is behaving when compiling the catalog. See Phabricator ticket T215507 for more information.

Communication and support

Support and administration of the WMCS resources is provided by the Wikimedia Foundation Cloud Services team and Wikimedia Movement volunteers. Please reach out with questions and join the conversation:

Discuss and receive general support
Receive mail announcements about critical changes
Subscribe to the cloud-announce@ mailing list (all messages are also mirrored to the cloud@ list)
Track work tasks and report bugs
Use the Phabricator workboard #Cloud-Services for bug reports and feature requests about the Cloud VPS infrastructure itself
Learn about major near-term plans
Read the News wiki page
Read news and stories about Wikimedia Cloud Services
Read the Cloud Services Blog (for the broader Wikimedia movement, see the Wikimedia Technical Blog)

See also