Help:Puppet

From Wikitech

This document helps people understand what Puppet is and how it is used in Wikimedia Cloud VPS.

Puppet is a complex tool, and the Wikimedia Puppet repository is very large, constantly changing and mostly designed for the needs of the various WMF SRE teams. Using Puppet to fully manage your applications on Cloud VPS tends to be unnecessarily complicated unless you're an SRE or closely working with them.

What is Puppet?

Puppet is an open-source software configuration management tool. It provides a domain specific language for writing declarative rules that describe how to configure operating system and application software.

What can I use it for on Wikimedia Cloud VPS?

All Cloud VPS VMs are created with an initial Puppet configuration ("manifest") that sets up the default software and configuration needed to connect the VM to the core services provided by Wikimedia Cloud VPS. Additional "roles" can be applied to your instances to enable additional functionality such as LAMP stack services or a MediaWiki-Vagrant managed virtual machine. When you need additional custom configuration beyond the roles and classes provided by the default Wikimedia Puppet repository, you can configure a standalone puppetmaster in your project and use it to provide custom configuration to one or more VMs.

How do I ...?

Most of these are done using Horizon. You need to be logged in and a member of the project you are trying to apply puppet roles to.

Apply a puppet role to or change hiera config of an individual instance

Individual instance Puppet screen
  1. Find the instance in "Instances" screen linked from the "Compute" section of Horizon's side menu.
  2. Click on the instance name to load the instance details screen.
  3. Click on the "Puppet Configuration" tab.

Apply role

  1. Browse available roles in the "project", "common", and "all" sub-pages.
  2. Click the "Apply Class" button for the role you are interested in applying.

Change hiera config

  1. Click the "Edit" button below the "Hiera Config" section.
  2. Add or edit YAML formatted data in the pop-up dialog.
  3. Click the "Apply Changes" button to save your changes.

Apply a puppet role to or change hiera config of all instances in a project

All instances Puppet screen
  1. Go to the "Project Puppet" screen linked from the "Puppet" section of Horizon's side menu.

Apply role

  1. Browse available roles in the "project", "common", and "all" sub-pages.
  2. Click the "Apply Class" button for the role you are interested in applying.

Change hiera config

  1. Click the "Edit" button below the "Hiera Config" section.
  2. Add or edit YAML formatted data in the pop-up dialog.
  3. Click the "Apply Changes" button to save your changes.

Apply a puppet role to or change hiera config for a specific set of instances in a project

Prefix Puppet screen
  1. Go to the "Prefix Puppet" screen linked from the "Puppet" section of Horizon's side menu.
  2. Choose an existing hostname prefix or create a new prefix using the tabs at the top of the screen.
    • Using a naming convention like "<project name>-<instance type><number>" for your instances will make using prefix configuration easier (e.g. "deployment-mediawiki03", "striker-uwsgi01").

Apply role

  1. Browse available roles in the "project", "common", and "all" sub-pages.
  2. Click the "Apply Class" button for the role you are interested in applying.

Change hiera config

  1. Click the "Edit" button below the "Hiera Config" section.
  2. Add or edit YAML formatted data in the pop-up dialog.
  3. Click the "Apply Changes" button to save your changes.

Apply a puppet role that has not been merged into operations/puppet.git yet

If you are using a Standalone puppetmaster for your project you can add custom puppet classes and roles with local commits to the /var/lib/git/operations/puppet checkout of the operations/puppet.git repository on your puppetmaster.

A popular workflow for this if you are hoping the new classes will eventually be included in the operations/puppet.git repository for all users is to create a patch for the change in Gerrit and then cherry-pick the latest version of it on your local puppetmaster. To cherry-pick your change, open your change in Gerrit, open the ⋮ menu on the right and choose Download patch. Use the command provided for cherry-picking the change over https (HTTP tab on the top).

Navigate to your local puppetmaster repository: 

root@instance$ cd /var/lib/git/operations/puppet/

Use the cherry pick command provided by the Gerrit "Download Patch" menu (and make sure to select "Anonymous HTTP" as type in the pop-up). For example: 

root@instance$ git fetch https://gerrit.wikimedia.org/r/a/operations/puppet refs/changes/30/887330/4 && git cherry-pick FETCH_HEAD

Local commits will be automatically rebased on to the latest upstream HEAD by a periodic cron job. This allows you to have local customizations and still keep up with upstream changes which may be required to keep your instance working properly with the services provided by Wikimedia Cloud VPS.

  1. Navigate to the individual instance, all instances, or prefix Puppet configuration screen.
  2. Click the "Edit" button under the "Other Classes" section
  3. Enter the fully qualified name of the class you wish to apply (e.g. "apache::mod::alias", "ores::web", etc)
    • Use YAML's list syntax (each element on it's own line with a leading - ) to add multiple classes.
  4. Click the "Apply Changes" button to save your changes.

To revert the change on a local puppetmaster, run git reset --hard origin/production.

See also

Retrieved from "https://wikitech.wikimedia.org/w/index.php?title=Help:Puppet&oldid=2136160"