feat: add Docker API TLS client-certificate support (#1265)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: JamBalaya56562

.github/workflows/test.yml

@@ -121,6 +121,9 @@ jobs:
           - test-name: standalone_ipv6
             setup: 2containers
             pebble-config: pebble-config.json
+          - test-name: docker_api_tls
+            setup: 2containers
+            pebble-config: pebble-config.json
     runs-on: ubuntu-latest
 
     steps:

app/entrypoint.sh

@@ -23,6 +23,21 @@ function check_docker_socket {
             echo "Typically you should run your container with: '-v /var/run/docker.sock:$socket_file:ro'" >&2
             exit 1
         fi
+    elif parse_true "${DOCKER_TLS_VERIFY:-}"; then
+        if [[ -z "${DOCKER_CERT_PATH:-}" ]]; then
+            echo "Error: DOCKER_TLS_VERIFY is enabled but DOCKER_CERT_PATH is not set." >&2
+            echo "Set DOCKER_CERT_PATH to the in-container directory holding ca.pem, cert.pem and key.pem." >&2
+            exit 1
+        fi
+        local cert_file
+        for cert_file in ca.pem cert.pem key.pem; do
+            if [[ ! -r "${DOCKER_CERT_PATH}/${cert_file}" ]]; then
+                echo "Error: TLS certificate file ${DOCKER_CERT_PATH}/${cert_file} is missing or not readable." >&2
+                echo "DOCKER_CERT_PATH must point to an in-container directory containing readable ca.pem, cert.pem and key.pem files." >&2
+                echo "Typically you should mount your Docker client certificate directory, e.g.: '-v /path/to/docker/certs:${DOCKER_CERT_PATH}:ro'" >&2
+                exit 1
+            fi
+        done
     fi
 }
 

app/functions.sh

@@ -232,6 +232,11 @@ function docker_api {
     if [[ $DOCKER_HOST == unix://* ]]; then
         curl_opts+=(--unix-socket "${DOCKER_HOST#unix://}")
         scheme='http://localhost'
+    elif parse_true "${DOCKER_TLS_VERIFY:-}"; then
+        curl_opts+=(--cert "${DOCKER_CERT_PATH}/cert.pem")
+        curl_opts+=(--key "${DOCKER_CERT_PATH}/key.pem")
+        curl_opts+=(--cacert "${DOCKER_CERT_PATH}/ca.pem")
+        scheme="https://${DOCKER_HOST#*://}"
     else
         scheme="http://${DOCKER_HOST#*://}"
     fi

docs/Container-configuration.md

@@ -45,3 +45,24 @@ You can also create test certificates per container (see [Test certificates](./L
 * `RELOAD_NGINX_ONLY_ONCE` - The companion reload nginx configuration after every new or renewed certificate. Previously this was done only once per service loop, at the end of the loop (this was causing delayed availability of HTTPS enabled application when multiple new certificates where requested at once, see [issue #1147](https://github.com/nginx-proxy/acme-companion/issues/1147)). You can restore the previous behaviour if needed by setting the environment variable `RELOAD_NGINX_ONLY_ONCE` to `true`.
 
 * `DOCKER_CONTAINER_FILTERS` -  You can filter which containers are considered by acme-companion by using the `DOCKER_CONTAINER_FILTERS` environment variable (by default, acme-companion will consider all running containers). It takes a comma separated list of `key=value` pairs. For example, setting `DOCKER_CONTAINER_FILTERS` environment variable to `network=mynetwork` will cause acme-companion to consider only containers connected to the `mynetwork` network. See the [Docker CLI documentation](https://docs.docker.com/reference/cli/docker/container/ls/#filter) for details on available filters.
+
+* `DOCKER_HOST` - The Docker API endpoint acme-companion talks to. Defaults to `unix:///var/run/docker.sock` (the mounted Docker socket). To connect to a remote or TLS-protected Docker daemon over TCP, set it to `tcp://<host>:<port>` (the conventional Docker TLS port is `2376`).
+
+* `DOCKER_TLS_VERIFY` and `DOCKER_CERT_PATH` - Enable TLS client-certificate authentication when connecting to the Docker daemon over `tcp://`. Set `DOCKER_TLS_VERIFY` to `true` and `DOCKER_CERT_PATH` to the **in-container** path of a directory containing `ca.pem`, `cert.pem` and `key.pem`. These variable names and file names match the [Docker CLI convention](https://docs.docker.com/engine/security/protect-access/) and the ones used by **docker-gen**, so the same certificate directory can be shared across containers.
+
+    > **Important:** `DOCKER_CERT_PATH` is a path **inside the container**. You must mount your certificate directory into the container with a volume, otherwise the files will not be found and the container will exit on startup with an error.
+
+    For example, connecting to a TLS-protected Docker daemon over TCP (note that the Docker socket is **not** mounted in this case):
+
+    ```bash
+    $ docker run --detach \
+        --name nginx-proxy-acme \
+        --volumes-from nginx-proxy \
+        --volume certs:/etc/nginx/certs:rw \
+        --volume acme:/etc/acme.sh \
+        --volume /path/to/docker/certs:/docker-certs:ro \
+        --env "DOCKER_HOST=tcp://docker-host.example.com:2376" \
+        --env "DOCKER_TLS_VERIFY=true" \
+        --env "DOCKER_CERT_PATH=/docker-certs" \
+        nginxproxy/acme-companion
+    ```

test/config.sh

@@ -4,6 +4,7 @@ set -e
 globalTests+=(
 	docker_api
 	docker_api_legacy
+	docker_api_tls
 	location_config
 	debug_acmesh_log
 	certs_single

test/tests/docker_api_tls/expected-std-out.txt

@@ -0,0 +1,8 @@
+## tls-verify-true-get
+-s --cert /docker-certs/cert.pem --key /docker-certs/key.pem --cacert /docker-certs/ca.pem -X GET https://docker:2376/version
+## tls-verify-true-post
+-s --cert /docker-certs/cert.pem --key /docker-certs/key.pem --cacert /docker-certs/ca.pem -H Content-Type: application/json -X POST https://docker:2376/containers/test/restart
+## tls-verify-false-get
+-s -X GET http://docker:2376/version
+## unix-socket-get
+-s --unix-socket /var/run/docker.sock -X GET http://localhost/version

test/tests/docker_api_tls/run.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+
+## Test for Docker API TLS client-certificate support (DOCKER_TLS_VERIFY / DOCKER_CERT_PATH).
+##
+## Deterministic verification that docker_api builds the expected curl invocation for
+## each transport, by stubbing curl. This needs no external TLS daemon and is therefore
+## stable on CI runners.
+##
+## This test is transport-focused and produces identical output regardless of the
+## SETUP (2containers / 3containers); it is registered to run once via the CI matrix.
+
+# Replace curl with a stub that prints the arguments it would have received, then
+# exercise docker_api over each transport in an isolated subshell (to avoid the
+# bash quirk where `VAR=x function_call` leaks VAR into the calling shell).
+commands="$(cat <<'EOF'
+curl() { printf '%s\n' "$*"; }
+source /app/functions.sh
+echo '## tls-verify-true-get'
+( export DOCKER_HOST='tcp://docker:2376' DOCKER_TLS_VERIFY='true' DOCKER_CERT_PATH='/docker-certs'; docker_api '/version' )
+echo '## tls-verify-true-post'
+( export DOCKER_HOST='tcp://docker:2376' DOCKER_TLS_VERIFY='true' DOCKER_CERT_PATH='/docker-certs'; docker_api '/containers/test/restart' 'POST' )
+echo '## tls-verify-false-get'
+( export DOCKER_HOST='tcp://docker:2376' DOCKER_TLS_VERIFY='false' DOCKER_CERT_PATH='/docker-certs'; docker_api '/version' )
+echo '## unix-socket-get'
+( export DOCKER_HOST='unix:///var/run/docker.sock'; docker_api '/version' )
+EOF
+)"
+
+docker run --rm "$1" bash -c "$commands" 2>&1