Add code and set up Code Manager
Set up your control repo, create a Puppetfile, and configure Code Manager so you can start adding content to your Puppet Enterprise (PE) environments.
The control repo is where you store your code. Code in your control repo is usually bundled in modules.
The Puppetfile specifies detailed information about each environment's Puppet code and data, including where to get that code and data from, where to install it, and whether to update it.
Code Manager automates the management and deployment of your Puppet code. PE doesn't require Code Manager, but it is helpful for ensuring Puppet syncs code to your primary server and all your servers run new code at the same time.
Create a control repository from the Puppet template
To create a control repository (or control repo) that has the recommended structure, code examples, and configuration scripts, base your control repo on the Puppet control repo template. This template covers most customer situations.
- Basic code examples for setting up roles and profiles.
- A Puppetfile that references modules to manage content in your environments.
- An example Hiera configuration file and
config_versionscript that tells you which version of code from your control repo was applied to your agents.
environment.conffile that implements the
config_versionscript and a
site-modulesdirectory for roles, profiles, and custom modules.
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.
To use the template, you must set up a private SSH key, copy the control repo template to your development workstation, set your own remote Git repository as the default source, and then push the template contents to that source.
To allow access to the control repo, generate a private SSH key without a
To generate the key pair, run:
ssh-keygen -t ed25519 -P '' -f /etc/puppetlabs/puppetserver/ssh/id-control_repo.ed25519
To allow the
pe-puppetuser to access the key, run:
puppet infrastructure configureYour private key is located at
/etc/puppetlabs/puppetserver/ssh/id-control_repo.ed25519, and your public key is at
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).
Important: Code management needs read access to your control repository, as well as any module repositories referenced in the Puppetfile.
- To generate the key pair, run:
In your Git user account or organization, create
a repository named
control-repo, and make sure a README is not automatically generated when you create the repo. Take note of the repo's SSH URL.Important: Do not use an existing repo. The template requires a new, empty repo named
If you haven't already installed Git, run
yum install git.
To clone the Puppet
git clone https://github.com/puppetlabs/control-repo.git
Change to the
Remove the template repo as the origin:
git remote remove origin
Set your control repo as the origin:
git remote add origin <SSH_URL_FOR_YOUR_CONTROL_REPO>
Push the contents of the
productionbranch of the cloned control repo to your remote control repo:
git push origin production
You now have a control repository based on the Puppet
control-repo template. After configuring Code Manager, 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 Manager
detects and deploys your infrastructure changes.
By using the
control-repo template, you now also have
a Puppetfile to which you can add and manage content,
like module code.
Configure Code Manager
Code Manager stages, commits, and synchronizes your code, automatically managing your environments and modules when you make changes.
Enable Code Manager
Set parameters in the console to enable Code Manager and connect your primary server to your Git repository.
pe-puppetuser to access your Git repositories. The SSH key must be:
- Owned by the
- Located on the primary server.
- Located in a directory the
pe-puppetuser has permission to view, such as
These steps use the
puppet job command. To use this
command, you must have permission to run jobs and have access to the primary
In the console, click Node groups, locate the
PE Master node group, and set these parameters for
trueto enable Code Manager.
r10k_remote, enter a string that is a valid SSH URL for your Git control repository, such as
git@<YOUR.GIT.SERVER.COM>:puppet/control.git.Important: Some Git providers have additional requirements for enabling SSH access. For example, BitBucket requires
ssh://at the beginning of the SSH URL (such as
ssh://git@<YOUR.GIT.SERVER.COM>:puppet/control.git). See your provider's documentation for this information.
r10k_private_key, enter a string specifying the path to the SSH private key that permits the
pe-puppetuser to access your Git repositories, such as
- Click Commit.
On the command line, run
puppet job run --nodes <NODE NAME>where
<NODE NAME>is the name of your primary server. For example:
puppet job run --nodes small-doubt.delivery.puppetlabs.net
Set up authentication for Code Manager
To securely deploy environments, Code Manager needs an authentication token for both authentication and authorization.
Before requesting an authentication token, you must assign a user to the deployment role.
In the Puppet Enterprise (PE) console, create a deployment
Tip: Create a dedicated deployment user for Code Manager to use.
Add the deployment user to the Code Deployers
When you install PE, this role is automatically created with default permissions for code deployment and token lifetime management.
- Click Generate Password to create a password for the deployment user.
Request an authentication token for deployments
To securely deploy your code, request an authentication token for the deployment user.
The default lifetime for authentication tokens is one hour. You can use the
default expiry permission set to change the token lifetime to a
duration better suited for a long-running, automated process.
puppet-access command to generate the authentication token.
From the command line on the primary server, run
puppet-access login --lifetime 180d. This command requests the token and sets the token lifetime to 180 days.Tip: You can specify additional settings in this command, such as the token file's location or your RBAC API URL, as explained in Configuration file settings for puppet-access.
- Enter the deployment user's username and password when prompted.
The generated token is stored in a file for later use. The default token storage location is
~/.puppetlabs/token. You can run
show to view the token.
Test the connection and deploy your code
Make sure Code Manager can connect to your control repository, make a test deployment to a single environment,and then deploy code to all environments.
To test the connection to the control repo, run:
puppet-code deploy --dry-run
If the control repo is set up properly, this command fetches and displays a list of environments in the control repo as well as the total number of environments.
If an environment is not set up properly or causes an error, it does not appear in the returned list. Check the Puppet Server log for details about the errors.
If the control repo connection works, test Code Manager by deploying a single environment. From the command line, run:
puppet-code deploy my_test_environment --waitThe
--waitflag returns results after the deployment is finished.
If Code Manager is configured correctly, this command deploys the test environment and returns deployment results with the SHA (a checksum for the content stored) for the control repo commit.
If the deployment does not work, review the Code Manager configuration steps or refer to Troubleshooting for help.
After enabling and testing Code Manager, you can
trigger Code Manager to deploy all environments. SSH
into your primary server and run:
puppet-code deploy --all --waitYou can also use
puppet-code deploy <ENVIRONMENT> --waitto deploy a specific environment.