Forge API

Puppet Forge implements a basic API that prior to Puppet 3.6 was not documented. After version 3.6 the documentation for the Forge API can be found at https://forgeapi.puppetlabs.com/.

The challenging aspect of re-implementing the API is that prior to puppet version 3.3, the puppet module tool used hard-coded absolute paths, so the API must exist at the root of the web server. This also prevents the inclusion of a repository ID in the URL. After puppet version 3.5 the use of hard-coded paths was reintroduced so the methods of specifying the repository or consumer outlined here apply.

Dependency

When the puppet module tool needs to know what the dependencies are for a particular module (such as at install time), it queries the dependency API. For a module named puppetlabs/java, the following request would be made against the Puppet Forge repository.

http://forge.puppetlabs.com/api/v1/releases.json?module=puppetlabs/java

Because of the URL namespace limitation described above, Pulp had to take a creative approach to identifing which repositories should be considered when determining the dependencies for a module.

Basic Auth

For puppet versions prior to 3.3, basic authentication credentials included in the URL are used to specify either a repository ID or a consumer ID. When a consumer ID is specified, all repositories to which it is bound are searched for the specified module. If a version was not specified, the repository with the newest version is then queried for dependency information.

This is an example request with a consumer ID:

http://consumer1:.@localhost/api/v1/releases.json?module=puppetlabs/java

This is an example with a repository ID and a version:

http://.:repo1@localhost/api/v1/releases.json?module=puppetlabs/java&version=0.2.0

When specifying a repository ID or a consumer ID, use a single “.” in place of the other value.

Under the Hood

When a Puppet repository is published by Pulp, a small gdbm database is generated and placed at the root of the repository containing all of the data necessary to respond to dependency queries. This ensures that when dependency data is returned, it corresponds to the state of the repository at the time it was published, and does not reflect any changes made in the database since. The name of this file is .dependency_db, and it is not visible when accessing the repository over HTTP because Apache excludes files whose names begin with “.”.