Connecting Visual Studio Team Services to Code Manager in Puppet Enterprise

As a Sales Engineer at Puppet, I hear about large scale Microsoft Windows-centric environments all the time. Many of these teams use Microsoft Team Foundation Server (TFS) for their source control. There is a hosted version of TFS called Microsoft Visual Studio Team Services (VSTS) that is a great alternative to Github or Gitlab. Luckily, Puppet Enterprise (PE) will work with either.

While these tools operate just like Github & Gitlab, their user interface can seem a little unfamiliar. The following is a guide for setting VSTS with an existing Puppet Control repository, and then connecting it to freshly installed Puppet Enterprise that doesn’t have Code Manager configured. If you’re unfamiliar with Puppet Control repos read our Puppet documentation. While the guide is explictly for VSTS the steps should be very similar in TFS.

Create a VSTS account

1. Create a free account on visualstudio.com.
2. Create a new project. For Version Control choose Git.

3. Select or import a repository on the Dashboard.

4. Enter https://github.com/puppetlabs/control-repo.git. Leave Requires Authorization turned off.

5. Click Clone in the upper right corner and select Create Git Credentials. Create an user name, alias, and password.

Install Code Manager in Puppet Enterprise

The easiest way to set up Code Manager is via the verbosely named pe_code_manager_easy_setup task. It automates all the steps required to connect your VSTS repo with PE.

1. Log into your puppet master. Run the following command as a root user:
   puppet module install beersy-pe_code_manager_easy_setup
2. Open the PE Console and click on the Tasks link on the left navigation, and select the pe_code_manager_easy_setup task.
3. Specify HTTPS url from step 5 above (ex. https://alias:password@abirpuppet.visualstudio.com/MyFirstProject/_git/control-repo). You will need to put the username and password in the URL unless it’s a public repo.†

4. Run the task on the master node. It can take 3–5 minutes to complete. The Puppet server may be restarted when the task is running so we recommend not doing anything on the master until the task finishes. If the task is successful, you will see output like the following:

You should be all set up now!

High Five!

Doing a code deploy

Obtain an access token

Before doing the code deploy you will need to log into the PE master as the root user and create an access token. To do so, you must execute the following from the command line:
puppet access login --lifetime <timeframe>
<timeframe> is the length of time you want the token to last. For example "1y" would make the token valid for a year. It will then ask you for your PE console username and password.

To verify things are working as expected you can simulate a code deploy by doing a “dry run” by executing the following from the command line:
puppet code deploy --dry-run

Deploying code from the command line:

If the dry run succeeds you can execute the following from the command line on the master to kick off the build:
puppet code deploy <environment> --wait
<environment> is the Puppet environment you want to deploy. The --wait parameter tells the command to return after the deploy has completed (instead of right away).

Deploying code from the PE Console:

Once you’ve got the code deploying successfully from the command line, you can use the code_deploy task to perform code deploys directly from the PE console. To install the task, just add the following to your control repo’s Puppetfile and then do a code deploy from the command line again:
mod 'tspy-code_deploy'

Then open the Tasks view in the PE Console and select the code_deploy task. Under environments, specify production.

Run the task on the master node. It can take a minute to complete. If the task is successful, you will see output like the following:

Congratulations! You’ve set up your PE instance to work with VSTS!

If you’re having issues, check out Troubleshooting Code Manager in the Puppet Documentation.

† You can also use the ssh URL (ssh://abirpuppet@vs-ssh.visualstudio.com:22/MyFirstProject/_ssh/control-repo). However there are some known issues with SSH for some VSTS customers, and you may see an Unsupported Protocol error. If you do decide to use the SSH url you will need to grab the generated Public SSH key from the pe_code_manager_easy_setup output (Step 4) add it to the “Manage SSH keys” setting in VSTS.