voxpupuli/container-puppetserver
will be deprecated in 2025-02 and might be removed in the future. Please use voxpupuli/puppetserver
instead.
This project hosts the Dockerfile and the required scripts to build a Puppet Server container image.
You can run a copy of Puppet Server with the following Docker command:
docker run --name puppet --hostname puppet ghcr.io/voxpupuli/puppetserver:8.6.1-latest
Although it is not strictly necessary to name the container puppet
, this is
useful when working with the other Puppet images, as they will look for a server
on that hostname by default.
If you would like to start the Puppet Server with your own Puppet code, you can
mount your own directory at /etc/puppetlabs/code
:
docker run --name puppet --hostname puppet -v ./code:/etc/puppetlabs/code ghcr.io/voxpupuli/puppetserver:8.6.1-latest
For compose file see: CRAFTY
You can find out more about Puppet Server in the official documentation.
curl
example below.
curl -i --cert $(puppet config print hostcert) \
--key $(puppet config print hostprivkey) \
--cacert $(puppet config print cacert) \
-X DELETE \
https://$(puppet config print server):8140/puppet-admin-api/v1/environment-cache?environment=production
Another option is to disable the environment caching by setting the PUPPETSERVER_ENVIRONMENT_TIMEOUT
environment variable to zero (0
).
The new version schema has the following layout:
<puppet.major>.<puppet.minor>.<puppet.patch>-v<container.major>.<container.minor>.<container.patch>
Example usage:
docker run --name puppet --hostname puppet -v ./code:/etc/puppetlabs/code/ ghcr.io/voxpupuli/puppetserver:8.6.1-v1.6.0
Name | Description |
---|---|
puppet.major | Describes the contained major Puppet version (7 or 8) |
puppet.minor | Describes the contained minor Puppet version |
puppet.patch | Describes the contained patchlevel Puppet version |
container.major | Describes the major version of the base container (Ubunutu 22.04) or incompatible changes |
container.minor | Describes new features or refactoring with backward compatibility |
container.patch | Describes if minor changes or bugfixes have been implemented |
The following environment variables are supported:
Name | Usage / Default |
---|---|
PUPPETSERVER_HOSTNAME | The DNS name used on the servers SSL certificate - sets the server in puppet.confDefaults to unset. |
CERTNAME | The DNS name used on the servers SSL certificate - sets the certname in puppet.confDefaults to unset. |
DNS_ALT_NAMES | Additional DNS names to add to the servers SSL certificate Note only effective on initial run when certificates are generated |
PUPPETSERVER_PORT | The port of the puppetserver8140 |
AUTOSIGN | Whether or not to enable autosigning on the puppetserver instance. Valid values are true , false , and /path/to/autosign.conf .Defaults to true . |
CA_ENABLED | Whether or not this puppetserver instance has a running CA (Certificate Authority)true |
CA_HOSTNAME | The DNS hostname for the puppetserver running the CA. Does nothing unless CA_ENABLED=false puppet |
CA_PORT | The listening port of the CA. Does nothing unless CA_ENABLED=false 8140 |
CA_ALLOW_SUBJECT_ALT_NAMES | Whether or not SSL certificates containing Subject Alternative Names should be signed by the CA. Does nothing unless CA_ENABLED=true .false |
PUPPET_REPORTS | Sets reports in puppet.confpuppetdb |
PUPPET_STORECONFIGS | Sets storeconfigs in puppet.conftrue |
PUPPET_STORECONFIGS_BACKEND | Sets storeconfigs_backend in puppet.confpuppetdb |
PUPPETSERVER_MAX_ACTIVE_INSTANCES | The maximum number of JRuby instances allowed1 |
PUPPETSERVER_MAX_REQUESTS_PER_INSTANCE | The maximum HTTP requests a JRuby instance will handle in its lifetime (disable instance flushing)0 |
PUPPETSERVER_JAVA_ARGS | Arguments passed directly to the JVM when starting the service-Xms512m -Xmx512m |
USE_PUPPETDB | Whether to connect to puppetdb Sets PUPPET_REPORTS to log and PUPPET_STORECONFIGS to false if those unsettrue |
PUPPETDB_SERVER_URLS | The server_urls to set in /etc/puppetlabs/puppet/puppetdb.conf https://puppetdb:8081 |
PUPPETDB_HOSTNAME | The DNS name of the puppetdb Defaults to puppetdb |
PUPPETDB_SSL_PORT | The TLS port of the puppetdb Defaults to 8081 |
PUPPETSERVER_GRAPHITE_EXPORTER_ENABLED | Activate the graphite exporter. Also needs PUPPETSERVER_GRAPHITE_HOST and PUPPETSERVER_GRAPHITE_PORT Defaults to false |
PUPPETSERVER_GRAPHITE_HOST | Only used if PUPPETSERVER_GRAPHITE_EXPORTER_ENABLED is set to true . FQDN or Hostname of the graphite server where puppet should push metrics to. Defaults to exporter |
PUPPETSERVER_GRAPHITE_PORT | Only used if PUPPETSERVER_GRAPHITE_EXPORTER_ENABLED is set to true . Port of the graphite server where puppet should push metrics to. Default to 9109 |
PUPPETSERVER_ENVIRONMENT_TIMEOUT | Configure the environment timeout Defaults to unlimited |
PUPPETSERVER_ENABLE_ENV_CACHE_DEL_API | Enable the puppet admin api endpoint via certificates to allow clearing environment caches Defaults to true |
ENVIRONMENTPATH | Set an environmentpath Defaults to /etc/puppetlabs/code/environments |
HIERACONFIG | Set a hiera_config entry in puppet.conf file Defaults to $confdir/hiera.yaml |
CSR_ATTRIBUTES | Provide a JSON string of the csr_attributes.yaml content. e.g. CSR_ATTRIBUTES='{"custom_attributes": { "challengePassword": "foobar" }, "extension_requests": { "pp_project": "foo" } }' Defaults to empty JSON object {} Please note that within a compose file, you must provide all environment variables as Hash and not as Array! environment: CSR_ATTRIBUTES: '{"extension_request": {...}}' |
If you would like to do additional initialization, add a directory called /docker-custom-entrypoint.d/
and fill it with .sh
scripts.
These scripts will be executed at the end of the entrypoint script, before the service is ran.
If you plan to use the in-server CA, restarting the container can cause the server's keys and certificates to change, causing agents and the server to stop trusting each other.
To prevent this, you can persist the default cadir, /etc/puppetlabs/puppetserver/ca
.
For example:
docker run -v $PWD/ca-ssl:/etc/puppetlabs/puppetserver/ca ghcr.io/voxpupuli/puppetserver:8.6.1-latest
or in compose:
services:
puppet:
image: ghcr.io/voxpupuli/puppetserver:8.6.1-latest
# ...
volumes:
- ./ca-ssl:/etc/puppetlabs/puppetserver/ca
This project was originally authored by Puppet. The maintainer preferred that Vox Pupuli take ownership of the project for future improvement and maintenance. Existing pull requests and issues were transferred over, please fork and continue to contribute here.