Create an empty control repo

In situations where you can't access the internet, or where organizational security policies prevent downloading modules from the Forge, you can create an empty control repo and add the necessary files to it.

When you can't use the Puppet control repo template, you must create a new repo on your Git host, clone it to your workstation, make changes to the repo (such as adding a configuration file to allow code management tools to find modules in your module directories), and push your changes to the remote repo on your Git host.

  1. To allow access to the control repo, generate a private SSH key without a password:
    1. To generate the key pair, run:
      ssh-keygen -t ed25519 -P '' -f /etc/puppetlabs/puppetserver/ssh/id-control_repo.ed25519
    2. To allow the pe-puppet user to access the key, run:
      puppet infrastructure configure

      Your private key is located at /etc/puppetlabs/puppetserver/ssh/id-control_repo.ed25519, and your public key is at /etc/puppetlabs/puppetserver/ssh/id-control_repo.ed25519.pub.

    3. Configure your Git host to use the SSH public key you generated. Usually, this involves creating a user or service account and assigning the SSH public key to it, but the exact process varies for each Git host. For instructions on adding SSH keys to your Git server, check your Git host's documentation (such as GitHub, BitBucket Server, or GitLab).
      Code management needs read access to your control repository, as well as any module repositories referenced in the Puppetfile.
  2. In your Git account, create a repository with the name you want your control repo to have (we recommend control-repo), and take note of the repo's SSH URL.

    Check your Git host's documentation for exact instructions, because this process varies for each host. For example, to create a new repo on GitHub:

    1. Click + at the top of the page, and choose New repository.
    2. Select the account Owner for the repository.
    3. Name the repository (for example, control-repo).
    4. Note the repository's SSH URL for later use.
      While you can use an existing repo as your control repo, we recommend starting with a new repo to avoid possible unexpected changes to existing files and directories once you enable code management.
  3. Clone the new repo to your workstation: git clone <REPOSITORY_URL>
  4. In the control repo's main directory, create a configuration file named environment.

    The environment.conf file allows code management tools to find modules in your site- and environment-specific module directories. You can learn more about this file and its contents in the Puppet environment.conf documentation.

  5. To set the module path, open the environment.conf file in a text editor, add the following line, and then save and close the file.
    modulepath=site-modules:modules:$basemodulepath
  6. Add the new file to the index and commit your change by running git add environment.conf and then git commit -m "add environment.conf"
  7. Rename the master branch to production by running git branch -m master production
    Puppet Enterprise (PE) requires the control repo's default branch to be production.
  8. Push your repository's production branch from your workstation to your Git host by running: git push -u origin production
Results
After configuring the Puppetfile and code management, when you make changes to your control repo on your workstation and push the changes to the remote control repo on your Git host, code management detects and deploys your infrastructure changes.
What to do next

After creating your control repo, you must create a Puppetfile to manage your environment content with code management. Then, you must configure either Code Manager (recommended) or r10k.

Related information