| title | draft |
|---|---|
Readme |
false |
- Overview
- Installing
- Setting up Tab Completion
- Quick Start Guide
- Getting Started
- Writing Your Own Templates
- Overriding Template Defaults
- Sharing Templates
- Locally host documentation site
- Request a feature
- Reporting Problems
- Installing Telemetry Free Version
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 afeedbackpost.
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:
curl -L https://pup.pt/pct/install.sh | shiex "&{ $(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/pcton *nix or$HOME/.puppetlabs/pcton Windows when you set yourPATHenvironment variable.
A version of the product, with telemetry functionality disabled, is available too. See here for instructions on how to install it.
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:
This quick start guide will show you how to:
- Create a "bare bones" Puppet module from the
puppet-module-baseproject template - Add a Puppet Class to the module
- Add a Github Actions Workflow to test the module against the currently supported Puppet versions
Let's name our module test_module using the -n flag:
If we cd in to the module root dir, everything will get deployed with the correct layout:
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:
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
projectis 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
itemis 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 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 --listExample 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 | itemUsing 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 MyProjectBy 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--nameparameter will have no effect on the generated content.
> 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 AwesomethingApiAt 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.
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.
You can specify the location of your templates using the --templatepath option:
pct new my-name/my-custom-project --templatepath /home/me/templatesA 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
contentdirectory 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.
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
idandauthormust 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-templateExample structure for example-template:
> tree ~/templates/example-template
/Users/me/templates/example-template
├── content
│ └── example.txt.tmpl
└── pct-config.ymlPCT 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.
projecttemplates 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
itemtemplate 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.
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
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.
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
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.
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.
Packages created using the build command can be installed by extracting the tar.gz into the Default Template Location.
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.gzWill install the template contained in my-template-1.2.3.tar.gz to the default template location.
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.gzWill attempt to download the PCT template from the specified url and then afterward install it like any other locally available PCT template archive.
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/myawesometemplateThis will attempt to clone the PCT template from the git repository at the specified URI and install to the default template location.
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.
Essential software that will need to be installed to run the documentation site locally:
- Git version control
- Hugo extended version
- Nodejs and NPM
To install the documentation site run the following command from the root of this project:
./docs.shThis 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.
Commands to run the site locally:
# Run without draft pages being displayed
./docs.shor
# Run with draft pages being displayed
./docs.sh -DOpen a new feature request in our Github discussion page.
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.
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:
curl -L https://pup.pt/pct/install.sh | sh -s -- --no-telemetryiex "&{ $(irm https://pup.pt/pct/install.ps1); Install-Pct -NoTelemetry }"This will install the latest release of PCT, without telemetry functionality, to ~/.puppetlabs/pct.