title: "Readme"
draft: false
Puppet Content Templates
Overview
Puppet Content Templates (PCT) codify a structure to produce content for any Puppet Product that can be authored by Puppet Product Teams or external users without direct help of the PDK team.
PCT can create any type of a Puppet Product project: Puppet control repo, Puppet Module, Bolt project, etc. It can create one or more independent files, such as CI files or gitignores. This can be as simple as a name for a Puppet Class, a set of CI files to add to a Puppet Module, or as complex as a complete Puppet Control repo with roles and profiles.
These are meant to be ready-to-run, which means they put everything needed for a user to run the project from the moment after creation. This solves the 'blank page' problem, where a few files are in place but the user does not know what the next steps are.
β PCT is currently in an EXPERIMENTAL phase and feedback is encouraged via pct/discussions and starting a feedback
post.
Installing
While the PCT is in early release, we provide an archive and a simple script to unpack it. When we move closer to a full release we will add a platform specific installer. Use the install.[ps1|sh]
script, depending upon your OS:
Unix Systems
curl -L https://pup.pt/pct/install.sh | sh
Windows Systems
iex "&{ $(irm https://pup.pt/pct/install.ps1); Install-Pct }"
This will install the latest release of PCT to ~/.puppetlabs/pct
.
β If you do not use the install script and are extracting the archive yourself, be sure to use the fully qualified path to ~/.puppetlabs/pct
on *nix or $HOME/.puppetlabs/pct
on Windows when you set your PATH
environment variable.
A version of the product, with telemetry functionality disabled, is available too.
See here for instructions on how to install it.
Setting up Tab Completion
After installation, we'd highly recommend setting up tab completion for your shell to ensure the best possible experience.
PCT has built in tab completion support for the following shells: bash
, zsh
, fish
and powershell
.
To view the install instructions, access the --help
menu in pct completion
and follow the instructions for your shell:
Quick Start Guide
This quick start guide will show you how to:
- Create a "bare bones" Puppet module from the
puppet-module-base
project template
- Add a Puppet Class to the module
- Add a Github Actions Workflow to test the module against the currently supported Puppet versions
STEP 1: Create a Puppet Module
Let's name our module test_module
using the -n
flag:
STEP 2: Add a New Class
If we cd
in to the module root dir, everything will get deployed with the correct layout:
STEP 3: Add a Github Actions Workflow
Want to know what configurable parameters are availble for a template and their defaults?
Run pct new --info <TEMPLATE_AUTHOR>/<TEMPLATE_ID>
:
We're happy with those defaults, so let's deploy this item.
Since we're outside the module root dir, we'll use the -o
option to point at the root dir:
Getting Started
The $INSTALLATION_ROOT/templates
directory will be subsequently referred to as the Default Template Location.
Templates currently come in 2 flavours: project
and item
.
- A
project
is a template containing many files in a particular structure. They create a ready-to-run structure to start using a Puppet product. These are great starting points. You can create a boilerplate empty starter Puppet Module or a fully customized Puppet Module with specialized CI files and RSAPI providers.
- An
item
is a template that will supplement a project or existing content. These could be language features like a Puppet class or single files like a Git ignore file.
pct new
PCT is available through the pct new
command.
The --list
or -l
flag displays a list of locally available templates located in the Default Template Location. The list of templates is also available by calling pct new
without flags.
pct new
pct new --list
Example output:
DISPLAYNAME | AUTHOR | NAME | TYPE
--------------------------------+------------+-------------------------+------
| | |
Bolt Plan | puppetlabs | bolt-plan | item
Bolt Project | puppetlabs | bolt-project | project
Bolt PowerShell Task | puppetlabs | bolt-pwsh-task | item
Bolt YAML Plan | puppetlabs | bolt-yaml-plan | item
Puppet Module Managed Gemfile | puppetlabs | git-attributes | item
Puppet Class | puppetlabs | puppet-class | item
Puppet Content Template | puppetlabs | puppet-content-template | project
Puppet Defined Type | puppetlabs | puppet-defined-type | item
Puppet Fact | puppetlabs | puppet-fact | item
Puppet Module | puppetlabs | puppet-module | project
Puppet Resource API Provider | puppetlabs | rsapi-provider | item
Puppet Resource API Transport | puppetlabs | puppet-transport | item
Using the available templates above, its time to generate some content.
pct new <author>/<template>
Replace <author>
and <template>
with the author
and name
of the template containing the content you want.
By default the new <author>/<template>
function will use the directory name of your current working directory to "name" your new content.
To override this behaviour use the --name
or -n
flag.
pct new <author>/<template> --name MyProject
By default the new <author>/<template>
function will output the template content to the current working directory.
To override this behavour use the --output
or -o
flag.
pct new <author>/<template> --output /path/to/your/project
π Not all templates require a name
. If a template doesn't require one, providing a value to the --name
parameter will have no effect on the generated content.
Example workflows
> cd /home/me/projects/MyBoltProject
> pct new puppetlabs/bolt-project
> pct new puppet-module -n MyNewProject -o /home/me/projects/
> cd /home/me/projects/MyNewProject
> pct new puppetlabs/puppet-fact -n ApplicationVersion
> pct new puppetlabs/rsapi-provider -n Awesomething
> pct new puppetlabs/puppet-transport -n AwesomethingApi
Template Updates
At this time pct new
will NOT update existing code to a newer version of a template.
If you run a pct new
command using a project
template, the project will replace the content within the output directory with the template code.
If you run a pct new
command using an item
template, the item will suppliment the content within the output directory with the template code. If files / folders that are named the same as the template content already exist, it will overwite this content.
Writing Templates
Structure
A PCT is an archive containing a templated set of files and folders that represent a completed set of content. Files and folders stored in the template aren't limited to formal Puppet project types. Source files and folders may consist of any content that you wish to create when the template is used, even if the template engine produces just one file as its output.
Location
You can specify the location of your templates using the --templatepath
option:
pct new my-name/my-custom-project --templatepath /home/me/templates
Composition
A PCT must contain a pct-config.yml
in the root directory, alongside a content
directory.
The content
directory contains the files and folders required to produce the project
or item
.
To mark a file as a template, use the .tmpl
extension. Templated files can also use the global variable of {{pct_name}}
to access the input from the --name
cli argument.
π Folders within the content
directory can also use the {{pct_name}}
variable
Example template file names:
myConfig.json.tmpl
{{pct_name}}_spec.rb
π One, all or none of the files can be templated.
pct-config.yml
Format of pct-config.yml
---
template:
id: <a unique name>
author: <name|username|orgname|handle|etc>
type: <'item' or 'project'>
display: <a human readable name>
version: <semver>
url: <url to project repo>
<template parameters>
π Template id
and author
must not contain spaces or special characters. We recommend using a hyphen to break up the identifier.
Example pct-config.yml:
---
template:
id: example-template
author: myorgname
type: project
display: Example
version: 0.1.0
url: https://github.com/puppetlabs/example-template
Example structure for example-template
:
> tree ~/templates/example-template
/Users/me/templates/example-template
βββ content
β βββ example.txt.tmpl
βββ pct-config.yml
Templating Language
PCT uses Go's templating language.
Example pct-config.yml with parameters:
---
template:
id: example-template-with-params
author: myorgname
type: project
display: Example with Parameters
version: 0.1.0
url: https://github.com/puppetlabs/pct-example-with-params
example_params:
foo: "bar"
isPuppet: true
colours:
- "Red"
- "Blue"
- "Green"
In the above template example-template-with-params
the parameters can be accessed in a .tmpl
file like so:
{{.example_params.foo}}
{{.example_params.isPuppet}}
{{.example_params.colours}}
outputs:
bar
<no value>
[Red Blue Green]
As a template author you can chose your own parameters and parameter structure so long as it is valid YAML. Then utilise the GO templating language to display or iterate over these.
For most templates, we believe that you can do most of the things you would want with these common template controls:
// Outputs the value of `foo` defined within pct.yml
{{.example_template.foo}}
// A conditional
{{if .example_template.isPuppet}}
"boo :("
{{else}}
"yay!"
{{end}}
// Loops over all "colours" and renders each using {{.}}
{{range .example_template.colours}} {{.}} {{end}}
For more examples look at the existing templates provided in the Default Template Location.
Dos and Don'ts
project
templates should provide all the code necessary to create a project from scratch and no more.
- Do not include configuration files that can be added via an
item
template later by an end user, for example, CI job configuration.
- Templates should be self documenting to help guide new users on how to use the file that has been created.
Overriding Template Defaults
Perhaps you use a template often and find that you set the same values over and over?
As a template user, you can choose to override the default values specified by a template author.
π To view the default parameters for a template run pct new --info <TEMPLATE_ID>
.
To override these defaults you need to create a pct.yml
containing the template id along with the values you wish to override.
Example:
example_template:
foo: "wibble"
isPuppet: false
colours:
- "Red"
- "Blue"
another_template:
key: "value"
π You don't need to override everything
example_template:
isPuppet: false
User level configuration
Placing a pct.yml
within $HOME/.pdk/
allows you to create global overrides. Everytime you generate content from a template the configuration will be used.
Workspace configuration
You may also place a pct.yml
within a workspace.
Running pct new
within a directory makes the current working directory your workspace.
If you specify an --outputdir
that location is your workspace.
The configuration specified in a workspace pct.yml
will override any configuration found within the user level configuration at $HOME/.pdk/pct.yml
Sharing Templates
After you've written your own template you may wish to share it with other members of your team or the wider Puppet community. Work is underway to improve this initial functionality.
pct build
This command will attempt to package the current working directory. You can change the directory to pack by providing --sourcedir
.
pct build [--sourcedir <dir>][--targetdir <dir>]
The build
command will ensure that the directory that you are attempting to package will produce a valid Puppet Content Template by looking for a pct-config.yml
and a content
directory.
The resulting tar.gz
package will be created by default in $cwd/pkg
. You can change the directory the package is created in by providing --targetdir
.
Installing template packages
Packages created using the build
command can be installed by extracting the tar.gz
into the Default Template Location.
Local archive
Packages created using the build
command can also be installed with the pct install
command.
For example, this command:
pct install ~/my-template-1.2.3.tar.gz
Will install the template contained in my-template-1.2.3.tar.gz
to the default template location.
Remote archive
Packages created using the build
command can be automatically downloaded and extracted with pct install
so long as you know the URL to where the archive is.
For example, this command:
pct install https://packages.mycompany.com/pct/my-template-1.2.3.tar.gz
Will attempt to download the PCT template from the specified url and then afterward install it like any other locally available PCT template archive.
Remote Git Repository
Git must be installed for this feature to work. The git repository must contain only one template and must be structured with the pct-config.yml
file and the content
directory in the root directory of the repository.
For more information on template structures see the Writing Templates section in the README
.
For example, this command:
pct install --git-uri https://github.com/myorg/myawesometemplate
This will attempt to clone the PCT template from the git repository at the specified URI and install to the default template location.
Locally host documentation site
The DevX documentation site can be locally hosted and changes made to the markdown files inside of the docs/md/content
directory will
be visible on the site.
Prerequisites
Essential software that will need to be installed to run the documentation site locally:
- Git version control
- Hugo extended version
- Nodejs and NPM
Install site
To install the documentation site run the following command from the root of this project:
./docs.sh
This will install and run the documentation site. The site can be found at http://localhost:1313
. All updates will to the
docs/md/content
directory will hot reload the site.
To stop the running ctrl + c
in the terminal window in which it is running.
Run site
Commands to run the site locally:
# Run without draft pages being displayed
./docs.sh
or
# Run with draft pages being displayed
./docs.sh -D
Requesting a feature
Open a new feature request in our Github discussion page.
Reporting Problems
If you're having trouble with the experimental PCT tool, please follow these instructions
to file an issue on our GitHub repository: https://github.com/puppetlabs/pct/issues/new
Make sure to fill in the information that is requested in the issue template as it
will help us investigate the problem more quickly.
Installing Telemetry Free Version
As of 0.5.0
, we have been gathering telemetry data to provide insights in to how our products are being used.
The following data is collected:
- Version of application in use
- OS / platform of the device
- What commands have been invoked (including command args)
- Any errors that occurred when running the application
We understand that there will be some users who prefer to have no telemetry data sent.
For those users, we offer a version of PCT with the telemetry functionality disabled.
To install:
Unix Systems
curl -L https://pup.pt/pct/install.sh | sh -s -- --no-telemetry
Windows Systems
iex "&{ $(irm https://pup.pt/pct/install.ps1); Install-Pct -NoTelemetry }"
This will install the latest release of PCT, without telemetry functionality, to ~/.puppetlabs/pct
.