From a80ef24072ebbc705561057a3cc97c11e54f8dea Mon Sep 17 00:00:00 2001 From: Robert Waffen Date: Thu, 19 Oct 2023 11:16:50 +0200 Subject: [PATCH] updates to documentation and variable naming - remove offensive wording in variables where possible - sync documentation from subfolder into main folder --- README.md | 54 +++++++++++++ puppetserver/Dockerfile | 8 +- puppetserver/README.md | 77 ------------------- .../docker-entrypoint.d/55-set-masterport.sh | 4 +- puppetserver/docker-entrypoint.d/80-ca.sh | 4 +- .../docker-entrypoint.d/90-log-config.sh | 2 +- puppetserver/healthcheck.sh | 4 +- 7 files changed, 65 insertions(+), 88 deletions(-) delete mode 100644 puppetserver/README.md diff --git a/README.md b/README.md index f1723f750..039c689f3 100644 --- a/README.md +++ b/README.md @@ -6,8 +6,62 @@ 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: + +```bash +docker run --name puppet --hostname puppet voxpupuli/container-puppetserver:7.13.0 +``` + +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/ voxpupuli/container-puppetserver:7.13.0 + For compose file see: [CRAFTY](https://github.com/voxpupuli/crafty/tree/main/puppet/oss) +You can find out more about Puppet Server in the [official documentation](https://www.puppet.com/docs/puppet/7/server/about_server.html). + + +## Configuration + +The following environment variables are supported: + +| Name | Usage / Default | +|--------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **PUPPETSERVER_HOSTNAME** | The DNS name used on the servers SSL certificate - sets the `certname` and `server` in puppet.conf

Defaults 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 puppetserver

`8140` | +| **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.conf

`puppetdb` | +| **PUPPET_STORECONFIGS** | Sets `storeconfigs` in puppet.conf

`true` | +| **PUPPET_STORECONFIGS_BACKEND** | Sets `storeconfigs_backend` in puppet.conf

`puppetdb` | +| **PUPPETSERVER_MAX_ACTIVE_INSTANCES** | The maximum number of JRuby instances allowed

`1` | +| **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 unset

`true` | +| **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` | + +## Initialization Scripts + +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. + +## Persistance + +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 voxpupuli/container-puppetserver:7.13.0`. + ## How to build the container [see here](https://github.com/voxpupuli/crafty/blob/main/docs/how-to-build.md) diff --git a/puppetserver/Dockerfile b/puppetserver/Dockerfile index 95fb4cc7d..51ef299cb 100644 --- a/puppetserver/Dockerfile +++ b/puppetserver/Dockerfile @@ -23,15 +23,15 @@ ENV PUPPETSERVER_JAVA_ARGS="-Xms1024m -Xmx1024m" \ PATH=/opt/puppetlabs/server/bin:/opt/puppetlabs/puppet/bin:/opt/puppetlabs/bin:$PATH \ SSLDIR=/etc/puppetlabs/puppet/ssl \ LOGDIR=/var/log/puppetlabs/puppetserver \ - PUPPETSERVER_HOSTNAME="" \ + PUPPETSERVER_HOSTNAME="puppet" \ DNS_ALT_NAMES="" \ - PUPPET_MASTERPORT=8140 \ - AUTOSIGN="" \ + PUPPETSERVER_PORT=8140 \ + AUTOSIGN=true \ PUPPETSERVER_MAX_ACTIVE_INSTANCES=1 \ PUPPETSERVER_MAX_REQUESTS_PER_INSTANCE=0 \ CA_ENABLED=true \ CA_HOSTNAME=puppet \ - CA_MASTERPORT=8140 \ + CA_PORT=8140 \ CA_ALLOW_SUBJECT_ALT_NAMES=false \ USE_PUPPETDB=true \ PUPPETDB_SERVER_URLS=https://puppetdb:8081 \ diff --git a/puppetserver/README.md b/puppetserver/README.md deleted file mode 100644 index cf2da64d2..000000000 --- a/puppetserver/README.md +++ /dev/null @@ -1,77 +0,0 @@ -# [puppetlabs/puppetserver](https://github.com/puppetlabs/puppetserver) - -The Dockerfile for this image is available in the Puppetserver repository -[here][1]. - -You can run a copy of Puppet Server with the following Docker command: - - docker run --name puppet --hostname puppet puppet/puppetserver - -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 master -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/ puppet/puppetserver - -You can find out more about Puppet Server in the [official documentation][2]. - -See the [pupperware repository][3] for running a full Puppet stack using Docker -Compose. - -## Configuration - -The following environment variables are supported: - -| Name | Usage / Default | -|--------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **PUPPETSERVER_HOSTNAME** | The DNS name used on the masters SSL certificate - sets the `certname` and `server` in puppet.conf

Defaults to unset. | -| **DNS_ALT_NAMES** | Additional DNS names to add to the masters SSL certificate
**Note** only effective on initial run when certificates are generated | -| **PUPPET_MASTERPORT** | The port of the puppet master

`8140` | -| **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_MASTERPORT** | 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.conf

`puppetdb` | -| **PUPPET_STORECONFIGS** | Sets `storeconfigs` in puppet.conf

`true` | -| **PUPPET_STORECONFIGS_BACKEND** | Sets `storeconfigs_backend` in puppet.conf

`puppetdb` | -| **PUPPETDB_SERVER_URLS** | The `server_urls` to set in `/etc/puppetlabs/puppet/puppetdb.conf`

`https://puppetdb:8081` | -| **USE_PUPPETDB** | Whether to connect to puppetdb
Sets `PUPPET_REPORTS` to `log` and `PUPPET_STORECONFIGS` to `false` if those unset

`true` | -| **PUPPETSERVER_MAX_ACTIVE_INSTANCES** | The maximum number of JRuby instances allowed

`1` | -| **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` | -| **PUPPERWARE_ANALYTICS_ENABLED** | Set to `true` to enable Google Analytics

`false` | - -## Initialization Scripts - -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. - -## Persistance - -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 puppetlabs/puppetserver:latest`. - -## Analytics Data Collection - -The puppetserver container collects usage data. This is disabled by default. You can enable it by passing `--env PUPPERWARE_ANALYTICS_ENABLED=true` -to your `docker run` command. - -### What data is collected? -* Version of the puppetserver container. -* Anonymized IP address is used by Google Analytics for Geolocation data, but the IP address is not collected. - -### Why does the puppetserver container collect data? - -We collect data to help us understand how the containers are used and make decisions about upcoming changes. - -### How can I opt out of puppetserver container data collection? - -This is disabled by default. - - -[1]: https://github.com/puppetlabs/puppetserver/blob/master/docker/puppetserver/Dockerfile -[2]: https://puppet.com/docs/puppetserver/latest/services_master_puppetserver.html -[3]: https://github.com/puppetlabs/pupperware diff --git a/puppetserver/docker-entrypoint.d/55-set-masterport.sh b/puppetserver/docker-entrypoint.d/55-set-masterport.sh index 7af0f6ce5..197bd5e27 100755 --- a/puppetserver/docker-entrypoint.d/55-set-masterport.sh +++ b/puppetserver/docker-entrypoint.d/55-set-masterport.sh @@ -4,8 +4,8 @@ hocon() { /opt/puppetlabs/puppet/lib/ruby/vendor_gems/bin/hocon "$@" } -if test -n "$PUPPET_MASTERPORT"; then +if test -n "$PUPPETSERVER_PORT"; then cd /etc/puppetlabs/puppetserver/conf.d/ - hocon -f webserver.conf set webserver.ssl-port $PUPPET_MASTERPORT + hocon -f webserver.conf set webserver.ssl-port $PUPPETSERVER_PORT cd / fi diff --git a/puppetserver/docker-entrypoint.d/80-ca.sh b/puppetserver/docker-entrypoint.d/80-ca.sh index 840f748be..11f7b45b4 100755 --- a/puppetserver/docker-entrypoint.d/80-ca.sh +++ b/puppetserver/docker-entrypoint.d/80-ca.sh @@ -1,7 +1,7 @@ #!/bin/bash ca_running() { - status=$(curl --silent --fail --insecure "https://${CA_HOSTNAME}:${CA_MASTERPORT}/status/v1/simple") + status=$(curl --silent --fail --insecure "https://${CA_HOSTNAME}:${CA_PORT:-8140}/status/v1/simple") test "$status" = "running" } @@ -36,7 +36,7 @@ EOF sleep 1 done - puppet ssl bootstrap --server="${CA_HOSTNAME}" --masterport="${CA_MASTERPORT}" + puppet ssl bootstrap --server="${CA_HOSTNAME}" --masterport="${CA_PORT:-8140}" fi else # we are the CA diff --git a/puppetserver/docker-entrypoint.d/90-log-config.sh b/puppetserver/docker-entrypoint.d/90-log-config.sh index 0a7fcf850..ca41093e6 100755 --- a/puppetserver/docker-entrypoint.d/90-log-config.sh +++ b/puppetserver/docker-entrypoint.d/90-log-config.sh @@ -12,7 +12,7 @@ else echo "* PUPPETSERVER_HOSTNAME: unset" certname=$(cd "${SSLDIR}/certs" && ls *.pem | grep --invert-match ca.pem) fi -echo "* PUPPET_MASTERPORT: '${PUPPET_MASTERPORT}'" +echo "* PUPPETSERVER_PORT: '${PUPPETSERVER_PORT:-8140}'" echo "* Certname: '${certname}'" echo "* DNS_ALT_NAMES: '${DNS_ALT_NAMES}'" echo "* SSLDIR: '${SSLDIR}'" diff --git a/puppetserver/healthcheck.sh b/puppetserver/healthcheck.sh index 1fea2702f..07b54e91a 100755 --- a/puppetserver/healthcheck.sh +++ b/puppetserver/healthcheck.sh @@ -13,10 +13,10 @@ certname=$(cd "${SSLDIR}/certs" && ls *.pem | grep --invert-match ca.pem) curl --fail \ --no-progress-meter \ --max-time ${timeout} \ - --resolve "${HOSTNAME}:${PUPPET_MASTERPORT}:127.0.0.1" \ + --resolve "${HOSTNAME}:${PUPPETSERVER_PORT:-8140}:127.0.0.1" \ --cert "${SSLDIR}/certs/$certname" \ --key "${SSLDIR}/private_keys/$certname" \ --cacert "${SSLDIR}/certs/ca.pem" \ - "https://${HOSTNAME}:${PUPPET_MASTERPORT}/status/v1/simple" \ + "https://${HOSTNAME}:${PUPPETSERVER_PORT:-8140}/status/v1/simple" \ | grep -q '^running$' \ || exit 1