mcdonaldseanp / puppet-vscode

Puppet Visual Studio Code Extension

Puppet extension for Visual Studio Code

Table of Contents

• Quick Start
• Features
• Requirements
• Platform Support
• Usage
  • Syntax highlighting
  • Auto completion
  • Hover Support
  • Outline View
  • Breadcrumbs
  • Go to Symbol Open Symbol by Name
  • Code Snippets
  • Linting
  • Live Workspace Intellisense
  • Puppet Commands
    • Puppet Resource
    • Puppet Node Graph
  • Puppet Development Kit Support
    • PDK Supported Versions
    • PDK New Module
    • PDK New Class
    • PDK Validate
    • PDK Test Unit
  • Debugging Puppet manifests
  • Docker Language Server Support
• Installing the Extension
• Configuration
• Experience a Problem?
  • Puppet Agent Install
  • Reloading the Puppet VSCode extension
• Reporting Problems
• Maintainers
• Telemetry
• License

Quick start

• Step 1: Install a supported version of the Puppet Development Kit on your system (see Requirements for more information).
• Step 2: Install the Puppet extension for Visual Studio Code.
• Step 3: Open or create a Puppet manifest file (a file with a .pp or .epp extension or named Puppetfile) and start automating!

Features

A Visual Studio Code extension that provides rich support for the Puppet language, including features such as syntax highlighting, linting, debugging, IntelliSense and more.

This extension provides full Puppet Language support for Visual Studio Code.

• Syntax highlighting
• IntelliSense for resources, parameters and more
• Outline View
• Breadcrumbs
• Go to Symbol
• Open Symbol by Name
• Linting
• Live Workspace Intellisense
• Code snippets
• Go to Definition of functions, types and classes
• Validation of metadata.json files
• Import from puppet resource directly into manifests
• Node graph preview
• Puppet Development Kit integration
• (Experimental) Local debugging of Puppet manifests
• (Experimental) Docker Language Server support

It is currently in technical preview, so that we can gather bug reports and find out what new features to add.

Requirements

You will need to have the Puppet Agent or Puppet Development Kit (PDK) installed in order to fully use this extension.

Note: PDK version 1.5.0 or higher is required.

You can find instructions and installation links here:

PDK

• Download page

Puppet-Agent

• Windows
• MacOSX
• Linux

Platform support

• Microsoft Windows
• MacOSX
• Linux

Usage

Loading indicator

The Puppet extension includes additional information in the form of a tooltip which describes the features that are loaded and still loading during startup.

Syntax Highlighting

Syntax highlighting recognizes all versions of Puppet and displays as you type.

• Puppet DSL
• Puppet Grammar
• Module metadata files

Auto Completion

Auto complete Puppet types and classes and their parameter sets as you type. Tab completion works as you would expect.

Hover Support

Hovering over any resource, class declaration or other Puppet symbol provides instant contextual information. For example, hovering over the resource declaration lists the type name and parameter list, with all relevant help text.

Outline View

The new Outline View shows the symbol tree of the currently selected Puppet manifest.

Supported symbols:

• Class
• Defined Type
• Attribute
• Variable

More symbols are planned to be added.

Note: Puppet 4 is not supported for symbols

Breadcrumbs

When the breadcrumbs.enabled setting is set to true, both the file path and the symbol tree hierarchy are shown in the Breadcrumb view.

Note: Puppet 4 is not supported for symbols

Go to Symbol

Opening the Command Palette and typing the @ symbol initiates the Go to Symbol view which allows you to navigate around inside a Puppet manifest more quickly.

Note: Puppet 4 is not supported for symbols

Open Symbol by Name

Pressing Ctrl+T (or ⌘T on OSX) will list all Puppet Custom Types, Functions, Classes and Defined Types in the workspace. You can then navigate to the symbol by pressing Enter.

Code Snippets

As part of IntelliSense and Snippets, you can quickly create templates to automate repetitive series of code.

Linting

Linting is automatically applied to the document as you edit, without having to save the file first. The validation uses puppet-lint to validate the Puppet syntax in all open puppet files. Errors and warnings appear in the Problems window in VSCode.

Live Workspace Intellisense

If you are editing a module, or a Control Repository, you will now get live intellisense of the Puppet Custom Types, Functions, Classes and Defined Types. For example if you are editing the puppetlabs-apache module you will be able to get auto-complete for resources like apache::vhost or apache::mod::php.

Note: Workspace Intellisense is only updated when you save a file, instead of features like linting which update as you type

Puppet Commands

Puppet Resource

You can import existing resources directly using puppet resource

1. Open the command palette (Ctrl+Shift+P) or right click on a puppet file and select the menu entry

2. Type puppet resource and press enter

3. Enter the resource type you want to import, for example user

The information returned will be pasted into the open editor window where your cursor is resting, or at the begining of an empty file.

Puppet Node Graph preview

You can preview the node graph of a manifest while you edit your Puppet Code.

1. Open the command palette (Ctrl+Shift+P) or right click on a puppet file and select the menu entry

2. Type puppet open node.. and press enter

The node graph will appear next to the manifest

Puppet Development Kit Support

You can use the Puppet Development Kit inside VS Code from the command palette. To use any of the above commands, open the command palette and start typing a command. You can also use the right-click context menu or the editor menu to reach these commands.

Note: The PDK must be installed prior to using these commands

Note: pdk convert is not available in the command palette as it is a complicated command that requires user input to succeed. It is better to use it from the builtin terminal.

PDK Supported Versions

The Puppet VSCode Extension supports the current PDK version, and one older version. This is currently 1.8.0 and 1.7.1.

PDK new module

PDK New Module is available even if the extension isn't loaded, the rest of the commands are only available when the extension is loaded.

PDK new class

You can create new classes using PDK using the VS Code command palette. This functionality is only available when a Puppet file has already been opened, to trigger the extension.

PDK validate

You can initiate a valiadtion of your module using PDK using the VS Code command palette. This functionality is only available when a Puppet file has already been opened, to trigger the extension.

PDK test unit

You can run the test suite of your module using PDK using the VS Code command palette. This functionality is only available when a Puppet file has already been opened, to trigger the extension.

Debugging Puppet manifests

Note - This is an experimental feature

The Puppet extension is able to debug the compilation of a Puppet manifest; much like the Go, PowerShell, and C# languages. The debugger supports:

• Line breakpoints but not conditions on those breakpoints
• Function breakpoints
• Exception breakpoints
• Call stack
• Variables, but only at the top stack frame
• Limited interactive debug console. For example, you can assign a variable a value, but just as in regular Puppet you can't change its value later
• Step In, Out, and Over

The debugging features in the extension are based on the excellent ideas in puppet-debugger by Corey Osman.

Configuring the debug session

To debug a simple manifest in VS Code, press F5 and VS Code will try to debug your currently active manifest by running the equivalent of puppet apply. Note that by default No Operation (--noop) is enabled so that your local computer will not be modified.

The VSCode Debugging - Launch Configurations website has instructions on how to configure the debug session with more advanced options.

Settings

• manifest - The manifest to apply. By default this is the currently open file in the editor

• noop - Whether the puppet apply sets No Operation (Noop) mode. By default, this is set to true. This means when running the debugger it will not make changes to your system. The documentation about the puppet agent has more information about puppet apply and and the noop option.

• args - Additional arguements to pass to puppet apply, for example ['--debug'] will output debug information

Docker Language Server Support

Note - This is an experimental feature

The Puppet VSCode extension bundles the Puppet Language Server inside the extension, and loads the language server on demaned and communicates it with either STDIO or TCP. Another option is to communicate via TCP pointed towards a docker container running the Puppet Language Server. The Lingua-Pupuli organization maintains a Puppet Language Server docker container here: https://github.com/lingua-pupuli/images. Using this docker image, we can run the Puppet Language Server without having Puppet Agent or the Puppet Development Kit installed locally, all that is needed is a working docker installation.

Enable using docker by adding the following configuration:

{
  "puppet.editorService.protocol":"docker",
  "puppet.editorService.docker.imageName":"linguapupuli/puppet-language-server:latest"
}

This will cause the Puppet Extension to instruct docker to start the linguapupuli/puppet-language-server container, then wait for it to start. After starting, the Puppet Extension will use the docker container to perform the same functionality as if it was running locally.

Installing the Extension

You can install the official release of the Puppet extension by following the steps in the Visual Studio Code documentation. In the Extensions pane, search for "puppet-vscode" extension and install it there. You will get notified automatically about any future extension updates!

You can also install the extension without access to the internet by following these instructions

Configuration

The Puppet VSCode extension can use the PDK or the Puppet Agent to provide advanced features, which can be set using two configuration options: puppet.installType and puppet.installDirectory.

• By default the puppet.installType is set to agent, and allows you to choose to use pdk or agent.
• The puppet.installDirectory allows you to choose a custom path to either a PDK install or a Puppet-Agent install, and must match the correct setting in puppet.installType.

If no settings are chosen, the extension will attempt to use the Puppet Agent, to force it to use the PDK you have to select pdk for puppet.installType.

Note: The puppet.installDirectory setting name will be changed in the 0.12.0 release to puppet.installDirectory

Note: Only PDK v1.5.0 and above are supported.

Configure extension to use PDK

To ensure that the extension uses the PDK, set the puppet.installType setting to the pdk value like so:

{
  "puppet.installType":"pdk"
}

The default installation paths stored in the extension are:

Windows:

{
  "puppet.installDirectory":"C:\\Program Files\\Puppet Labs\\DevelopmentKit"
}

OSX:

{
  "puppet.installDirectory":"/opt/puppetlabs/pdk"
}

Linux:

{
  "puppet.installDirectory":"/opt/puppetlabs/pdk"
}

To use a custom install path for the PDK, set the puppet.installDirectory setting to the path you installed the PDK to:

{
  "puppet.installDirectory":"D:/programs/pdk"
}

Configure extension to use Puppet-Agent

To ensure that the extension uses the Puppet-Agent, set the puppet.installType setting to the puppet value like so:

{
  "puppet.installType":"puppet"
}

The default installation paths stored in the extension are:

Windows:

{
  "puppet.installDirectory":"C:\\Program Files\\Puppet Labs\\Puppet",
}

OSX

{
  "puppet.installDirectory":"/opt/puppetlabs"
}

Linux:

{
  "puppet.installDirectory":"/opt/puppetlabs"
}

To use a custom install path for the Puppet-Agent, set the puppet.installDirectory setting to the path you installed the Puppet-Agent to:

{
  "puppet.installDirectory":"D:/programs/puppet"
}

Experience a Problem?

Puppet Agent Install

A commonly encountered problem is not having the PDK or Puppet Agent installed on the computer you are running VSCode on. As noted in the Requirements section, you will need to have the PDK or Puppet Agent installed in order to fully use this extension, as the extension uses the Puppet binaries and the Ruby language bundled into the PDK or agent install in order to function.

If you are receiving an error right after opening a Puppet file saying that a Puppet Agent install could not be found, ensure that Puppet is installed on the system. The VSCode extension attempts to find a valid Puppet install if a path is not configured in puppet.installDirectory in User Settings, so if Puppet is installed but not in a default path please check that your setting points to the correct path.

Reloading the Puppet VSCode extension

If you haven't see the Problems Pane update in awhile, or hover and intellisense doesn't seem to showing up, and you might not know what to do. Sometimes the Puppet extension can experience problems which cause the language server to crash or not respond. The extension has a way of logging the crash, but there is something you can do to get right back to working: reload the Puppet Language Server.

You can reload the Puppet Lanuguage Server by opening the command palette and starting to type Reload. A list of commands will appear, select Reload Window. This will reload the Visual Studio Code window without closing down the enitre edtior, and without losing any work currently open in the editor.

Reporting Problems

If you're having trouble with the Puppet extension, please follow these instructions to file an issue on our GitHub repository:

1. File an issue on our Issues Page

Make sure to fill in the information that is requested in the issue template as it will help us investigate the problem more quickly.

2. Capture verbose logs and send them to us

If you're having an issue with crashing or other erratic behavior, add the following line to your User Settings in Visual Studio Code:

    "puppet.editorService.debugFilePath": "C:\\Some\\file\\path.txt"

Restart Visual Studio Code and try to reproduce the problem, then examine the log. If the issue persists please open an issue.

Maintainers

• James Pogran - @ender2025
• Glenn Sarti - @glennsarti
• Michael T Lombardi - @barbariankb
• Austin Blatt

Telemetry

This extension collects telemetry data to help us build a better experience for writing manifest and modules with Puppet and VS Code. We only collect data on which commands are executed. We do not collect any information about files, paths, etc. The extension respects the telemetry.enableTelemetry setting which you can learn more about in our FAQ.

License

This extension is licensed under the Apache-2.0 License.