Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.
ArtifactsRegistry TypesGetting Started

Puppet

Create a Puppet registry, generate an identity token, then publish and install private Puppet modules using the Puppet CLI or r10k.

Use a Puppet registry to host private Puppet modules. The registry works with both the Puppet CLI and r10k.

What you will learn from this topic

By the end of this quickstart guide, you will be able to:

  • Create a registry in Harness Artifacts.

  • Publish a package to the registry.

  • Install the package from the registry, and confirm the working.

Before you begin

  • Install the Puppet CLI (puppet) or r10k (r10k) on your local machine.

  • Install the Harness CLI (hc). You use it to publish packages to your registry.

  • Make sure you have access to a Harness account with permission to create registries and connectors.

Create a Puppet registry

To create a Puppet registry, perform the following steps:

  1. In Artifact Registry, select Registries.

  2. Select + Create Registry.

  3. Specify the Registry name.

Registry name criteria

The registry name must start with a letter, can only contain lowercase alphanumerics, _, ., and -, and must be unique to your Harness account.

  1. Optionally, add a Description.

  2. Choose visibility between Public and Private. The default is Private.

  3. Select Puppet as the Registry type.

  4. Click Save.

  5. Select Create to finalize.

Private Puppet registry

A Private registry serves Puppet modules only to clients that authenticate with an identity token from your Harness account.

Configure an upstream proxy (optional)

An upstream proxy allows your registry to fetch Puppet modules from external sources, such as the Puppet Forge, when they are not available locally. The default upstream is https://forgeapi.puppet.com.

Create upstream proxy

To create an upstream proxy, perform the following steps:

  1. In Artifact Registry, select Registries.

  2. Select the drop-down next to + Create Registry and select Upstream Proxy.

  3. Specify the Registry name.

  4. Optionally, add a Description.

  5. Choose visibility between Public and Private. The default is Private.

  6. Select Puppet as the Registry type.

  7. Select the Source: Puppet Forge or Custom.

    • If you select Custom, specify the Remote registry URL (for example, https://forgeapi.puppet.com).

  8. Select the Authentication method.

    • Username and password: Specify the username and password. Use an existing secret, or create a new secret by specifying the Name and entering the Secret text.

    • Anonymous: No credentials required. This works for the public Puppet Forge.

  9. Optionally, configure Metadata configuration:

    • Metadata cache TTL (seconds)

    • Negative cache TTL (seconds)

  10. Select Create to finalize.

Metadata configuration

Metadata cache TTL controls how long Harness caches Puppet module metadata from the upstream before refreshing it. Negative cache TTL controls how long Harness caches a not-found lookup before it retries the upstream. For guidance on setting these values for your use case, go to Metadata configuration.

Configure the upstream proxy in your registry

To configure the upstream proxy in your registry, perform the following steps:

  1. In Artifact Registry, select an existing Puppet Artifact.

  2. Navigate to the Configuration tab.

  3. Select Edit in the Upstream proxy section.

  4. Click + Add upstream proxy.

  5. Select the required proxy from the list.

  6. Click Apply.

  7. Select Update to finalize.

Upstream proxy caching

If a module is not found in your Harness registry, the upstream proxy fetches it from the remote registry and caches it.

Puppet client setup

In your Puppet Artifact, select the registry, then select Set Up Client. The dialog gives you an identity token, then setup instructions for the Puppet CLI or r10k.

Generate an identity token

An identity token serves as the password for authenticating with the registry.

  1. In your Puppet Artifact Registry, select Set Up Client.

  2. Select Generate Token.

  3. Select an Expiration for the token:

    • 30 Days

    • 90 Days

    • 180 Days

    • Custom

  4. Copy the token. You use it in the following steps in place of <IDENTITY_TOKEN>.

Token expiration

The identity token stops working after the expiration you select. Generate a new token and update your client configuration before the current token expires.

Configure the client

Select Puppet CLI or r10k for your client. In the code samples, replace the values in angle brackets with your own values.

1. Configure puppet.conf

Edit /etc/puppetlabs/puppet/puppet.conf:

2. Publish the module

Upload the module tarball to the registry:

3. Use the module

Install the module using the Puppet CLI:

1. Configure r10k.yaml

Edit r10k.yaml:

2. Publish the module

Upload the module tarball to the registry:

3. Use the module

Add the module to your Puppetfile:

Resolve the Puppetfile:

Setup verification

Confirm that your registry serves the module you published. To verify your setup, perform the following steps:

  1. In a new directory with no cached Puppet modules and no existing Puppetfile.lock, use the Puppet CLI or r10k to install or resolve the module you published.

  2. Confirm that the client downloaded the module from your Harness registry address, which is shown in Set Up Client.

  3. In Harness, open your registry and confirm that the module and version appear in the package list.

If a step fails, go to Troubleshooting to resolve common authentication and resolution issues before you retry.

Pipeline automation (optional)

Publishing from a pipeline gives you a repeatable release process. Run the publish step when you create a version tag, so each release maps to one version in the registry.

The following Run step shows the shape of a publish step. Store the identity token as a Harness secret, and do not write it into the pipeline YAML.

Troubleshooting

`puppet module install` or `r10k puppetfile install` fails with `401` or `403`

Check that the username and identity token in puppet.conf, or the authorization_token in r10k.yaml, match the active identity token shown in Set Up Client. If the token expired or was revoked, generate a new one and update your client configuration.

`hc artifact push puppet` returns `409 Conflict`

Module versions are immutable after publish. Increment the version in metadata.json, rebuild the tarball, and push again, or delete the existing version only if your registry retention and lifecycle policies allow it.

`puppet module install` cannot find the module, or resolves an older version

Check that the module name (in <NAMESPACE>-<MODULE_NAME> format, from metadata.json) and the version you request match what you published. Also, check that the registry name and account ID in puppet.conf or r10k.yaml are correct.

`r10k puppetfile install` resolves a stale module version

Clear the local r10k module cache and your Puppetfile.lock, then run r10k puppetfile install again to re-resolve the versions pinned in your Puppetfile.

Set Up Client omits upload instructions for a Puppet upstream proxy

An upstream proxy registry is pull-only, so Set Up Client does not show publish instructions for it. Publish your module to a standard Puppet registry instead, or let the upstream proxy cache modules fetched from the Puppet Forge.

Next steps

Last updated

Was this helpful?