docker_compose - add env_file option (#174)

* Initial commit

* Adding changelog and fixing docs

* Fixing integration tests

* Restricting minimum docker-compose versions for tests

* Applying initial review suggestions

changelogs/fragments/174-docker_compose-env_file.yml

@@ -0,0 +1,4 @@
+---
+minor_changes:
+  - docker_compose - added ``env_file`` option for specifying custom environment files
+    (https://github.com/ansible-collections/community.docker/pull/174).

plugins/modules/docker_compose.py

@@ -36,6 +36,16 @@ options:
       - Provide a project name. If not provided, the project name is taken from the basename of I(project_src).
       - Required when I(definition) is provided.
     type: str
+  env_file:
+    description:
+      - By default environment files are loaded from a C(.env) file located directly under the I(project_src) directory.
+      - I(env_file) can be used to specify the path of a custom environment file instead.
+      - The path is relative to the I(project_src) directory.
+      - Requires C(docker-compose) version 1.25.0 or greater.
+      - "Note: C(docker-compose) versions C(<=1.28) load the env file from the current working directory of the
+          C(docker-compose) command rather than I(project_src)."
+    type: path
+    version_added: 1.9.0
   files:
     description:
       - List of Compose file names relative to I(project_src). Overrides C(docker-compose.yml) or C(docker-compose.yaml).
@@ -637,6 +647,9 @@ class ContainerManager(DockerBaseClass):
         if self.project_name:
             self.options[u'--project-name'] = self.project_name
 
+        if self.env_file:
+            self.options[u'--env-file'] = self.env_file
+
         if self.files:
             self.options[u'--file'] = self.files
 
@@ -1124,6 +1137,7 @@ def main():
     argument_spec = dict(
         project_src=dict(type='path'),
         project_name=dict(type='str',),
+        env_file=dict(type='path'),
         files=dict(type='list', elements='path'),
         profiles=dict(type='list', elements='str'),
         state=dict(type='str', default='present', choices=['absent', 'present']),

tests/integration/targets/docker_compose/tasks/tests/options.yml

@@ -94,4 +94,84 @@
       vars:
         cname_1_name: "{{ pname + '_' + cname_1 + '_1' }}"
         cname_2_name: "{{ pname + '_' + cname_2 + '_1' }}"
-  when: docker_compose_version is version('1.28.0', '>=')
+  when: docker_compose_version is version('1.28.0', '>=')
+
+####################################################################
+## Env_file ########################################################
+####################################################################
+
+- block:
+    - name: Define service and files
+      set_fact:
+        compose_file: "{{ output_dir }}/docker-compose.yml"
+        env_file: "{{ output_dir }}/.env"
+        env_sleep_cmd: sleep 10m
+        new_env_file: "{{ output_dir }}/new.env"
+        new_env_sleep_cmd: sleep 20m
+        test_service: |
+          version: '2'
+          services:
+            {{ cname_1 }}:
+              image: "{{ docker_test_image_alpine }}"
+              command: '/bin/sh -c "${SLEEP_CMD}"'
+              stop_grace_period: 1s
+
+    - name: Define testcases
+      set_fact:
+        test_cases:
+          - test_name: Without env_file option
+          - test_name: With env_file option
+            env_file: "{{ new_env_file }}"
+
+    - name: Generate compose file
+      ansible.builtin.copy:
+        content: "{{ test_service }}"
+        dest: "{{ compose_file }}"
+
+    - name: Generate .env file
+      ansible.builtin.copy:
+        content: |
+          SLEEP_CMD="{{ env_sleep_cmd }}"
+        dest: "{{ env_file }}"
+
+    - name: Generate new.env file
+      ansible.builtin.copy:
+        content: |
+          SLEEP_CMD="{{ new_env_sleep_cmd }}"
+        dest: "{{ new_env_file }}"
+
+    - name: Env_file
+      docker_compose:
+        project_name: "{{ pname }}"
+        project_src: "{{ output_dir }}"
+        env_file: "{{ test_case.env_file | default(omit) }}"
+      register: env_file_outputs
+      loop: "{{ test_cases }}"
+      loop_control:
+        loop_var: test_case
+
+    - name: Cleanup
+      docker_compose:
+        project_name: "{{ pname }}"
+        state: absent
+        definition: "{{ test_service | from_yaml }}"
+
+    - assert:
+        that:
+          - "env_sleep_cmd is in (env_file_outputs.results[0].services[cname_1][cname_1_name].cmd | join(' '))"
+          - "new_env_sleep_cmd is in (env_file_outputs.results[1].services[cname_1][cname_1_name].cmd | join(' '))"
+      vars:
+        cname_1_name: "{{ pname + '_' + cname_1 + '_1' }}"
+        cname_2_name: "{{ pname + '_' + cname_2 + '_1' }}"
+
+    - name: Remove files
+      ansible.builtin.file:
+        path: "{{ file_path }}"
+        state: absent
+      loop_control:
+        loop_var: file_path
+      loop:
+        - "{{ compose_file }}"
+        - "{{ env_file }}"
+        - "{{ new_env_file }}"
+  when: docker_compose_version is version('1.25.0', '>=')