Docs Puppet Enterprise Getting started with Puppet Enterprise Add code and set up Code Manager

Add code and set up Code Manager

Sections

Create a control repository from the Puppet template

Enable Code Manager
Set up authentication for Code Manager

Test the connection and deploy your code

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 (repo) that includes a standard recommended structure, code examples, and configuration scripts, base your control repo on the Puppet control repo template. This template covers most customer situations.

To base your control repo on the Puppet control repository template, you must set up a private SSH key (so your primary server can identify itself to your Git host), 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.

The control repo template contains the files needed to get you started with a functioning control repo, including:

An environment.conf file to implement a site-modules/ directory for roles, profiles, and custom modules.
config_version scripts to notify you which control repo version was applied to the agents.
Basic code examples for setting up roles and profiles.
An example hieradata directory that matches the default hierarchy .
A Puppetfile to manage content maintained in your environment.

Generate a private SSH key to allow access to the control repository.

This SSH key cannot require a password.
1. Generate the key pair:
```
ssh-keygen -t ed25519 -P '' -f /etc/puppetlabs/puppetserver/ssh/id-control_repo.ed25519Copied!
```
2. Set appropriate permissions so that the pe-puppet user can access the key:
```
puppet infrastructure configureCopied!
```
Your keys are now located in /etc/puppetlabs/puppetserver/ssh:
- Private key: /etc/puppetlabs/puppetserver/ssh/id-control_repo.ed25519
- Public key: /etc/puppetlabs/puppetserver/ssh/id-control_repo.ed25519.pub
Configure your Git host to use the SSH public key you generated. The process to do this is different for every Git host. Usually, you create a user or service account, and then assign the SSH public key to it.

Code management needs read access to your control repository, as well as any module repositories referenced in the Puppetfile.

See the your Git host docs for detailed instructions on adding SSH keys to your Git server. Commonly used Git hosts include:
Create a repository in your Git account, with the name you want your control repo to have.

Steps for creating a repository vary, depending on what Git host you are using (GitHub, GitLab, Bitbucket, or another provider). See your Git host's documentation for complete instructions.

For example, 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.
If you don't already have Git installed, run the following command on your primary server:
```
yum install gitCopied!
```

From the command line, clone the Puppet control-repo template.

git clone https://github.com/puppetlabs/control-repo.gitCopied!

Change directory into your contro repo.
```
cd <NAME OF YOUR CONTROL REPO>Copied!
```
Remove the template repository as your default source.
```
git remote remove originCopied!
```
Add the control repository you created as the default source.
```
git remote add origin <URL OF YOUR GIT REPOSITORY>Copied!
```
Push the contents of the cloned control repo to your remote copy of the control repo:
```
git push origin productionCopied!
```

Results

You now have a control repository based on the Puppet control-repo template. When you make changes to this repo on your workstation and push those changes to the remote copy of the control repo on your Git server, Code Manager deploys your infrastructure changes.

You also now have a Puppetfile available for you to start adding and managing 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.

Before you begin

Set up an SSH key to permit the pe-puppet user to access your Git repositories. The SSH key must be:

Owned by the pe-puppet user.
Located on the primary server.
Located in a directory the pe-puppet user has permission to view, such as /etc/puppetlabs/puppetserver/ssh/id-control_repo.ed25519.

These steps use the puppet job command. To use this command, you must have permission to run jobs and have access to the primary server.

In the console, click Node groups, locate the PE Master node group, and set these parameters for the puppet_enterprise::profile::master class:
1. Set code_manager_auto_configure to true to enable Code Manager.
2. For 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.
3. For r10k_private_key, enter a string specifying the path to the SSH private key that permits the pe-puppet user to access your Git repositories, such as "/etc/puppetlabs/puppetserver/ssh/id-control_repo.ed25519".
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.netCopied!
```

What to do next

Set up authentication for Code Manager.

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

Tip: Create a dedicated deployment user for Code Manager to use.
Add the deployment user to the Code Deployers role.
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.

What to do next

Request an authentication token for deployments.

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 Override default expiry permission set to change the token lifetime to a duration better suited for a long-running, automated process.

Use the 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.

Results

The generated token is stored in a file for later use. The default token storage location is ~/.puppetlabs/token. You can run puppet-access show to view the token.

What to do next

Test the connection to the control repo.

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 --wait
The --wait flag 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 --wait
You can also use puppet-code deploy <ENVIRONMENT> --wait to deploy a specific environment.

What to do next

After making changes to your Puppetfile, such as adding a new module or creating a repo, you must deploy your code so Code Manager can recognize and start managing the content. You can trigger deployments from the command line, webhooks, or custom scripts.