From 9377d6733eb93bb8ab2ffda705f14934bf56e06c Mon Sep 17 00:00:00 2001
From: Felix Fontein <felix@fontein.de>
Date: Sat, 1 Aug 2026 08:14:48 +0200
Subject: [PATCH] Fix environment variable fallbacks for plugins. (#1299)

---
 changelogs/fragments/1299-env.yml      |  3 +++
 plugins/connection/docker_api.py       |  1 +
 plugins/doc_fragments/_docker.py       | 22 ++++++++++++++++++++++
 plugins/inventory/docker_containers.py |  1 +
 4 files changed, 27 insertions(+)
 create mode 100644 changelogs/fragments/1299-env.yml

diff --git a/changelogs/fragments/1299-env.yml b/changelogs/fragments/1299-env.yml
new file mode 100644
index 00000000..265012e4
--- /dev/null
+++ b/changelogs/fragments/1299-env.yml
@@ -0,0 +1,3 @@
+bugfixes:
+  - "docker_api connection plugin - the environment fallbacks for ``docker_host``, ``tls_hostname``, ``api_version``, ``timeout``, ``tls``, and ``validate_certs`` now finally work (https://github.com/ansible-collections/community.docker/issues/1298, https://github.com/ansible-collections/community.docker/pull/1299)."
+  - "docker_containers inventory plugin - the environment fallbacks for ``docker_host``, ``tls_hostname``, ``api_version``, ``timeout``, ``tls``, and ``validate_certs`` now finally work (https://github.com/ansible-collections/community.docker/issues/1298, https://github.com/ansible-collections/community.docker/pull/1299)."
diff --git a/plugins/connection/docker_api.py b/plugins/connection/docker_api.py
index 879b013b..ad946c3f 100644
--- a/plugins/connection/docker_api.py
+++ b/plugins/connection/docker_api.py
@@ -19,6 +19,7 @@ notes:
     with Python's C(SSLSocket)s. See U(https://github.com/ansible-collections/community.docker/issues/605) for more information.
 extends_documentation_fragment:
   - community.docker._docker.api_documentation
+  - community.docker._docker.api_environment_documentation
   - community.docker._docker.var_names
 options:
   remote_user:
diff --git a/plugins/doc_fragments/_docker.py b/plugins/doc_fragments/_docker.py
index c3e8fdbc..8acbfe14 100644
--- a/plugins/doc_fragments/_docker.py
+++ b/plugins/doc_fragments/_docker.py
@@ -387,3 +387,25 @@ notes:
   - This module does B(not) use the L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) to
     communicate with the Docker daemon. It directly calls the Docker CLI program.
 """
+
+    API_ENVIRONMENT_DOCUMENTATION = r"""
+options:
+  docker_host:
+    env:
+      - name: DOCKER_HOST
+  tls_hostname:
+    env:
+      - name: DOCKER_TLS_HOSTNAME
+  api_version:
+    env:
+      - name: DOCKER_API_VERSION
+  timeout:
+    env:
+      - name: DOCKER_TIMEOUT
+  tls:
+    env:
+      - name: DOCKER_TLS
+  validate_certs:
+    env:
+      - name: DOCKER_TLS_VERIFY
+"""
diff --git a/plugins/inventory/docker_containers.py b/plugins/inventory/docker_containers.py
index b22d4e36..99039754 100644
--- a/plugins/inventory/docker_containers.py
+++ b/plugins/inventory/docker_containers.py
@@ -17,6 +17,7 @@ author:
 extends_documentation_fragment:
   - ansible.builtin.constructed
   - community.docker._docker.api_documentation
+  - community.docker._docker.api_environment_documentation
   - community.library_inventory_filtering_v1.inventory_filter
 description:
   - Reads inventories from the Docker API.