> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/artifact-registry/3.0/setup/puppet.md).

# Puppet

Puppet - host Puppet modules in Harness Artifacts

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 guide, you will know how to:

* Create a registry in Harness Artifacts.
* Publish a package to the registry.
* Install the package from the registry and confirm that it works.

## 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:

1. In Artifact Registry, select **Registries**.
2. Select **+ Create Registry**.
3. Specify the **Registry name**.

{% hint style="info" %}
**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.
{% endhint %}

4. Optionally, add a **Description**.
5. Choose visibility between **Public** and **Private**. The default is *Private*.
6. Select **Puppet** as the **Registry type**.
7. Click **Save**.
8. Select **Create** to finalize.

{% hint style="info" %}
**Private Puppet registry**

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

## 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:

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.

{% hint style="info" %}
**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 [Configure metadata cache TTL](https://developer.harness.io/artifact-registry/3.0/registries/create-an-upstream-proxy.md#configure-metadata-cache-ttl).
{% endhint %}

### Configure the upstream proxy in your registry

To configure the upstream proxy in your registry:

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.

{% hint style="info" %}
**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.
{% endhint %}

## Puppet client setup

In your Puppet Artifact, select the registry, then select **Setup 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 **Setup 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>`.

{% hint style="info" %}
**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.
{% endhint %}

### 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.

{% tabs %}
{% tab title="Puppet CLI" %}
**1. Configure puppet.conf**

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

```ini
[main]
module_repository = https://<USERNAME>:<IDENTITY_TOKEN>@pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/puppet
```

**2. Publish the module**

Upload the module tarball to the registry:

```bash
hc artifact push puppet <REGISTRY_NAME> <FILE_PATH>
```

**3. Use the module**

Install the module using the Puppet CLI:

```bash
puppet module install <ARTIFACT_NAME> --version <VERSION>
```

{% endtab %}

{% tab title="r10k" %}
**1. Configure r10k.yaml**

Edit `r10k.yaml`:

```yaml
forge:
  baseurl: 'https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/puppet'
  authorization_token: 'Bearer <IDENTITY_TOKEN>'
```

**2. Publish the module**

Upload the module tarball to the registry:

```bash
hc artifact push puppet <REGISTRY_NAME> <FILE_PATH>
```

**3. Use the module**

Add the module to your Puppetfile:

```ruby
mod '<ARTIFACT_NAME>', '<VERSION>'
```

Resolve the Puppetfile:

```bash
r10k puppetfile install
```

{% endtab %}
{% endtabs %}

## Setup verification

Confirm that your registry serves the module you published. To verify your setup:

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 **Setup 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](#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.

```yaml
- step:
    type: Run
    name: Publish package
    identifier: publish_package
    spec:
      shell: Sh
      envVariables:
        PACKAGE_VERSION: <+codebase.tag>
      command: |
        hc artifact push puppet <REGISTRY_NAME> build/<MODULE_NAME>-"$PACKAGE_VERSION".tar.gz
```

## Troubleshooting

<details>

<summary>`puppet module install` or `r10k puppetfile install` fails with `401` or `403`</summary>

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

</details>

<details>

<summary>`hc artifact push puppet` returns `409 Conflict`</summary>

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.

</details>

<details>

<summary>`puppet module install` cannot find the module, or resolves an older version</summary>

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.

</details>

<details>

<summary>`r10k puppetfile install` resolves a stale module version</summary>

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.

</details>

<details>

<summary>Setup Client omits upload instructions for a Puppet upstream proxy</summary>

An upstream proxy registry is pull-only, so **Setup 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.

</details>

## Next steps

* To add a pipeline that publishes a new version for every release tag, go to [Harness CI](https://developer.harness.io/artifact-registry/3.0/platform-integrations/harness-ci.md).
* To control who can publish and consume packages in your registry, go to [RBAC and permissions](https://developer.harness.io/artifact-registry/3.0/reference/rbac-and-permissions.md).
* To set retention and lifecycle rules for old versions, go to [Lifecycle Management overview](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/overview.md).

{% @harness-feedback/feedback %}
