Deploying code: Set up r10k and deploy code from your control repo

r10k uses Puppetfiles to deploy dynamic environments and modules from your control repo. In this article, you’ll use the puppet-r10k module to install and configure r10k onto a Puppet master and then use r10k to deploy code.

Assumptions

puppetserver is installed.
The puppet user exists.
puppet is in your path.
You are running r10k as the puppet user.
The master has access to the Forge (and is not air-gapped).
You’ve set up and configured a control repo.

Version and installation information

Puppet version: 5.5.8 and later
OS: RHEL, Ubuntu, Scientific Linux, CentOS, Oracle Linux, Arch Linux
Installation type: Standard
Modules (required by r10k, installed by steps in this article)

puppet-r10k version 4.0.0 and later
puppetlabs/stdlib version 4.19.0 and later
puppetlabs/ruby version 0.6.0 and later
puppetlabs/inifile version 1.4.1 and later
puppetlabs/vcsrepo version 1.3.1 and later
puppetlabs/git version 0.5.0 and later

Install and configure r10K

The puppet-r10k module can install and configure r10k onto a Puppet master. This is a chicken-and-egg situation. How do you install r10k to deploy code when the code is not available on the master?

Use the following steps to install and configure r10k by installing the required modules in your ${modulepath} and running a puppet apply on the master.

To install r10k and its dependencies into /tmp, log in to the master and run:

puppet module install puppet-r10k --version 8.0.0 --modulepath /tmp

Until you’ve deployed code with r10k, add --modulepath /tmp to the end of all Puppet commands so that you can use these modules.

Example output:

Notice: Preparing to install into /tmp ...
 Notice: Downloading from https://forgeapi.puppet.com ... Notice: Installing -- do not interrupt ... /tmp

 └─┬ puppet-r10k (v8.0.0)
   ├── puppetlabs-git (v0.5.0)
   ├─┬ puppetlabs-inifile (v3.1.0)
   │ └── puppetlabs-translate (v2.1.0)
   ├── puppetlabs-ruby (v1.0.1)
   ├── puppetlabs-stdlib (v6.2.0)
   └── puppetlabs-vcsrepo (v2.4.0)

You need a new SSH key for r10k to download code from the control repo. To add the key to the master with appropriate permissions, follow these steps.
1. Create a directory for the keys:
```
mkdir -p /etc/puppetlabs/puppetserver/ssh/
```
2. Generate a new SSH key:
```
ssh-keygen -t rsa -b 4096 -f /etc/puppetlabs/puppetserver/ssh/control_repo_key
```
3. Change the owner to Puppet:
```
chown -R puppet: /etc/puppetlabs/puppetserver/ssh/
```
Configure access to your Git provider to allow the master to download the code from the control repository. Please consult with your Git provider’s documentation to find the needed steps.

For example, you might need to add a Git user for the master and add the SSH key to that user, or you might need to add the SSH key on the master to the Git control repo as a deploy key.

On the master, create a file at /tmp/install_r10k.pp and copy the code below into it.

/tmp/install_r10k.pp

   $puppet_user_home = '/opt/puppetlabs/server/data/puppetserver'
   $private_key = '/etc/puppetlabs/puppetserver/ssh/control_repo_key'
   $git_server_hostname = 'gitlab.com'
   $git_clone_url = "git@${git_server_hostname}:spidersddd/demo_control_repo.git"
   $ssh_config_content = "Host ${git_server_hostname}
     IdentityFile ${private_key}
     User git
     UserKnownHostsFile /dev/null
     StrictHostKeyChecking no
     PasswordAuthentication no"

   File {
     owner  => 'puppet',
     group  => 'puppet',
   }

   # This is not idempotent, it runs every time `puppet apply` is run
   # and should not be placed in a profile this way.
    exec { 'chown for envs':
     command => 'chown -R puppet: /etc/puppetlabs/code/environments',
     path    => '/bin:/usr/bin:/usr/local/bin'
   }

   include git
   class { 'r10k':
     provider => 'puppet_gem',
     remote   => $git_clone_url,
   }

   file { [ "${puppet_user_home}/.ssh" ]:
     ensure => directory,
   }

   file { "${puppet_user_home}/.ssh/config":
     ensure  => file,
     content => $ssh_config_content,
   }

Install r10k and its dependencies by running the following on the master:

puppet apply /tmp/install_r10k.pp --modulepath /tmp/

Note: You can run this command from any directory as long as puppet is in your path.

Example output:

 Notice: Compiled catalog for master-oss-env.platform9.puppet.net in environment production in 0.10 seconds
 Notice: /Stage[main]/Git/Package[git]/ensure: created
 Notice: /Stage[main]/R10k::Install/Package[r10k]/ensure: created
 Notice: /Stage[main]/R10k::Install::Puppet_gem/File[/usr/bin/r10k]/ensure: created
 Notice: /Stage[main]/R10k::Config/File[/etc/puppetlabs/r10k]/ensure: created
 Notice: /Stage[main]/R10k::Config/File[r10k.yaml]/ensure: defined content as '{md5}ded5ee14b7597ab9d402d9bef07a5fd5'
 Notice: /Stage[main]/Main/File[/opt/puppetlabs/server/data/puppetserver/.ssh]/ensure: created
 Notice: /Stage[main]/Main/File[/opt/puppetlabs/server/data/puppetserver/.ssh/config]/ensure: defined content as '{md5}fdbd11340585d447605061e79e9d623d'
 Notice: Applied catalog in 8.00 seconds

Deploy code with r10k

To deploy code with r10k, you must be in a directory the puppet user can read. Navigate to a directory with the right permissions, such as Puppet’s home directory or /tmp.
Deploy all the environments in the control repo by running:

sudo -H -u puppet r10k deploy command to cd ~puppet && sudo -H -u puppet r10k deploy environment

Conclusion

From a host with a minimal Puppet master installation, you’ve installed and configured your r10k installation and deployed all environments in the control repo.

If you are interested in automating r10k, learn more about using an r10k webhook or using MCollective r10k support.

Additional resources

Articles in this section