Setting Up a Productive Puppet Dev Environment with VS Code

Introduction

As a Puppet Professional Services Engineer, I've had the opportunity to observe the development workflows and code editing practices of dozens of teams. One of the most consistent issues I’ve seen is a lack of consistency in Puppet codebases: code that’s hard to read, maintain, or reason about. This isn’t just an aesthetic problem. Inconsistent code makes upgrades harder, contributes to technical debt, and makes new team members less confident when contributing.

I believe many of these issues stem from the development environment, or more often, the lack of one. Few teams have clear standards for how engineers should work with Puppet day to day. Even when they do, those standards are rarely enforced or adopted consistently. Most engineers just bring their existing habits into Puppet development: a beloved Vim config, a long-standing reliance on Notepad++, or maybe even no real tooling at all.

VS Code has emerged as a powerful and approachable editor for Puppet development. But many engineers don’t realize how much better their experience can be with the right setup. This post walks through how to build a productive Puppet dev environment with VS Code, PDK, Git, and the Puppet VS Code extension. These tools are cross-platform, modern, and battle-tested.

Prerequisites

This guide assumes some basic familiarity with Puppet concepts like modules, manifests, and Git repositories. You should already have:

• Visual Studio Code installed


• Git installed

Everything in this guide—VS Code, Git, PDK, and the Puppet extension—is fully supported on Windows, macOS, and Linux, including ARM-based systems. This makes it a solid choice for teams working across platforms.

Installing the Essentials

Assuming you already have VS Code and Git installed, the next step is to install Puppet Development Kit (PDK). Do this before installing the VS Code extension. PDK provides the managed Ruby environment, core Puppet libraries, testing tools, and CLI helpers that power the extension.

Starting with PDK 3.5.0, packages are stored in protected repositories but remain free for development use. You can read more about how to install PDK and its licensing model.

Once PDK is installed, install the Puppet VS Code extension from its homepage or directly from the VS Code Marketplace.

To verify everything is working:

1. Open a .pp file.


2. Look for the Puppet version in the status bar (lower right), showing the version provided by PDK.


3. Confirm syntax highlighting, warnings, and linting are active.

Setting Up Your Workspace

Puppet environments often involve multiple Git repositories:

• A control repo
  


• Repos for custom modules


• Possibly third-party modules or separate Hiera data

To get started, open a terminal in VS Code (Ctrl+` or from the menu: Terminal → New Terminal) and clone the repositories you work on. For example:

git clone https://github.com/my-org/control-repo.git

git clone https://github.com/my-org/my_custom_module.git

After cloning, use the VS Code GUI to create your workspace:

1. Open the control-repo directory in VS Code.


2. Go to File → Add Folder to Workspace... and select your module or Hiera directories.


3. Go to File → Save Workspace As... and save your workspace file somewhere convenient.

This setup creates a multi-root workspace, which lets you:

• Track changes to each repo independently in the Source Control panel


• Apply consistent settings across the workspace


• Quickly navigate between files in different repos

Compared to opening a single directory that contains all your projects, this approach avoids Git confusion, lets you commit changes per repo, and helps VS Code keep things organized.

Using PDK in Practice

Once your environment is set up, it’s time to put PDK to work. PDK streamlines many common development tasks:

• 
  Creating new modules:
  

  pdk new module my_module

• 
  Validating code:
  Run static analysis and syntax checks with:
  

  pdk validate

• 
  Running unit tests:
  If your module includes RSpec tests:
  

  pdk test unit

• 
  Managing Ruby dependencies:
  Use pdk bundle to run tools like rspec, rubocop, or rake:
  

  pdk bundle exec rake spec

PDK helps standardize development practices across your team. It ensures that everyone is using the same tools, settings, and code structure, even if they’re working on different operating systems.

Powering Up with the VS Code Extension

The Puppet extension adds rich language support for .pp, .epp, and .yaml files used in Puppet development. Features include:

• Syntax highlighting and automatic formatting


• Autocompletion and hover info for Puppet types and functions


• Inline linting and error diagnostics


• "Go to definition" and "Find all references" support


• Built-in tasks for running pdk validate, pdk test, etc.

The extension integrates tightly with PDK and uses the Puppet Language Server under the hood. It’s especially useful for surfacing errors as you type and for learning available parameters and types.

Git Integration and Development Workflow

VS Code’s built-in Git support works seamlessly with Puppet projects. Some tips:

• Commit changes per repo directly from the Source Control panel


• View diffs, stage changes, and create branches in the UI


• Use extensions like GitLens to view commit history and annotations

You can also configure .gitignore and .editorconfig files to enforce consistency across your team’s repos. This ensures that everyone’s editor behaves the same and avoids committing untracked build files or system-specific configs.

Tips and Best Practices

Here are a few additional recommendations to get the most out of your environment:

• 
  Enable autosave in VS Code to avoid losing changes between test runs


• 
  Use workspace settings to enforce tab width, line endings, and trimming of trailing whitespace


• 
  Add an .editorconfig file to your repos to standardize formatting across editors


• 
  Install recommended extensions like YAML support, GitLens, and Markdown Preview for working on docs. Migrating from Vim? Check out the Vim extension.


• 
  Leverage command palette shortcuts like Ctrl+Shift+P → PDK: Validate to run tasks without switching to terminal

Troubleshooting and Gotchas

Even with a solid setup, things can go sideways. Here are a few common issues and how to fix them:

• Puppet version not showing in the status bar?
  
  Make sure PDK was installed before the VS Code extension.




• Syntax highlighting not working?
  
  Check that you're editing a .pp file in a workspace with PDK configured.




• pdk validate complains about missing gems or dependencies?
  
  Run pdk bundle install in the module directory to refresh the environment.




• Puppet Language Server crashes or stops responding?
  
  Try reloading the VS Code window (Ctrl+Shift+P → Reload Window) or reinstalling the extension.




• Working with legacy modules?
  
  Use pdk convert to migrate older modules into a PDK-managed structure.

Conclusion

With the right environment, Puppet development becomes faster, safer, and more collaborative. VS Code, PDK, and the Puppet extension together offer a powerful toolkit that works across platforms and team sizes.

Whether you're working solo or collaborating across a large team, investing a little time in your setup can pay big dividends in confidence, clarity, and maintainability.

Give it a try, and let me know how it goes! If you’ve got questions, tips, or feedback, feel free to drop them in the comments.