Skip to content

jig.md

Latest commit

 

History

History
161 lines (128 loc) · 6.37 KB

jig.md

File metadata and controls

161 lines (128 loc) · 6.37 KB
layout default
title Scaffolding New Content with Jig

Puppet modules have a defined standard structure; the directories and filenames have to match their contents. In other words, the directory name should match the module name, and each class or defined type should be a matching filename under the manifests directory, and so on. This structure allows the OpenVox compiler to locate and load the proper files when including various classes and such.

{% include alert.html type="warning" title="Historical Note" content="You may stumble into very old Puppet code that doesn't maintain the 'one thing per file' convention. These are vestigial remnants of the times before the module structure was finalized. While OpenVox can technically load content this way in some cases, it's best to just avoid that style since it leads to undefined behaviour." %}

It's possible to create files and maintain the proper directory structure by hand and nothing prevents you from doing so. However, many people today prefer to use a scaffolding tool to maintain proper structure and consistency. The tool we recommend for this today is Jig.

Installing Jig

Download the latest release for your platform from the releases page. Uncompress it and move the jig binary to a path like /usr/local/bin.

{% include alert.html type="tip" title="macOS Security Alert" content="The packages are unsigned, so macOS won't open them by default. Run it once and cancel the warning dialog that tells you to trash it. Then go to System Settings -> Privacy & Security and scroll to the bottom of the pane. You'll see the option to allow jig to run." %}

Jig is one of the few tools in the Vox Pupuli ecosystem implemented in Go. If you have Go installed, then you can choose to install via the Go package manager instead. This will place the compiled binary into $GOPATH/bin, which is likely to be ~/go/bin. Ensure that location is in your $PATH.

go install github.com/avitacco/jig@latest

Creating a new module

Jig has built-in templates to create a complete Puppet module with all the standard directory structure and metadata. It will walk you through an interactive interview to collect module metadata.

$ jig new module demo
Forge username [ben.ford]: binford2k
Author name [Ben Ford]:
License type [Apache-2.0]:
Summary of the module []: This is not a real module; it just demonstrates the Jig new module interview.
Source URL for the module []: https://http.cat/status/404
Created new module demo in /Users/ben.ford/Projects/demo

Jig will create the full directory structure with starter files for the main class, Hiera data, rspec initialization helpers, etc.

$ tree demo
demo
├── CHANGELOG.md
├── data
│   └── common.yaml
├── examples
├── files
├── Gemfile
├── hiera.yaml
├── manifests
│   └── init.pp
├── metadata.json
├── Rakefile
├── README.md
├── spec
│   ├── classes
│   │   └── init_spec.rb
│   ├── default_facts.yml
│   └── spec_helper.rb
├── tasks
└── templates

9 directories, 11 files

Adding content to a module

Jig knows how to add other content to your module. For example, to add a demo::foo class you can type the following (omitting the module name):

$ jig new class foo
creating class demo::foo...

You can create more deeply nested classes by just specifying the name. The required directory structure will be created for you.

$ jig new class foo::bar::baz
creating class demo::foo::bar::baz...
$ tree manifests
manifests
├── foo
│   └── bar
│       └── baz.pp
├── foo.pp
└── init.pp

Jig can create other types of content for your module:

  • class
    • Creates a class manifest and associated spec file.
  • defined_type
    • Creates a defined type manifest and associated spec file.
  • fact
    • Creates a standard Ruby fact and associated spec file.
    • This does not know how to do external facts or structured data facts.
  • function
    • Creates a new Puppet language function and associated spec file.
    • This does not currently know how to create Ruby functions.
  • provider
    • Creates a new type and provider using the Resource API and associated spec files for each.
    • If you want to add a provider for an existing type, you should create the files manually.
    • If you prefer the legacy type and provider interface, you should create those manually.
  • task
    • Creates a new OpenBolt task and its associated metadata file.
  • test
    • Creates a basic spec test for an existing class or defined type.
  • transport (uncommon)
    • Creates a new Resource API transport and its associated files.

See Jig's GitHub page for full documentation.

Configuring Jig

Jig looks for a config file at ~/.config/jig/config.toml. All fields are optional. If the file does not exist, it will fall back to sensible defaults.

forge_username = "avitacco"
author         = "John Doe"
license        = "Apache-2.0"
forge_token    = "your-forge-token"
template_dir   = "~/.config/jig/templates"

Maintaining your own content templates

Jig embeds templates for all the kinds of content that it knows how to scaffold. To customize them, you'd dump them to disk and then edit as you like.

jig templates dump ~/.config/jig/templates

To use your new templates, add this directory to your Jig config file.

Alternative scaffolding solutions

Jig is the only scaffolding tool we have currently tested. If you'd like to experiment, there are other options available.

  • Regent is a high-performance, modern implementation of PDK features in Rust. It uses the embedded Artichoke Ruby runtime for all Ruby execution.
  • PCT is an experimental pluggable content templating system. It's designed so that rather than a single set of templates, each component is a separate template. This means that you could choose to use one author's module template, but a different author's class template, and yet another author's template for adding GitLab CI pipelines.