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 primary server (formerly called the 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 primary server 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 primary server. This is a chicken-and-egg situation. How do you install r10k to deploy code when the code is not available on the primary server?

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

1. To install r10k and its dependencies into /tmp, log in to the primary server 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)

2. You need a new SSH key for r10k to download code from the control repo. To add the key to the primary server 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/

3. Configure access to your Git provider to allow the primary server 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 primary server and add the SSH key to that user, or you might need to add the SSH key on the primary server to the Git control repo as a deploy key.

4. On the primary server, 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,
      }

5. Install r10k and its dependencies by running the following on the primary server:

   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 server-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

1. 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.

2. 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 primary server 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

• Deploying code: What the heck is a control repo?
• Deploying code: What is a Puppetfile?