Setup docker (#6396)

* setup-docker: install and run docker inside integration test VMs

* must pip install requests to satisfy community.docker requirements

* add Ubuntu configuration to setup_docker

* Update tests/integration/targets/mssql_script/tasks/main.yml

* Update tests/integration/targets/mssql_script/tasks/main.yml

* docker_pacakges variable non-existent by default

* add setup_docker to keycloak_groups

* add setup_docker to keycloak_groups

* removed unused file tasks/nothing.yml

* add README

* add copyright notice to readme file

* Update tests/integration/targets/setup_docker/README.md

* rolled back the boilerplate disclaimer to mssql_script tasks/main.yml

tests/integration/targets/keycloak_group/meta/main.yml

@@ -0,0 +1,7 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+dependencies:
+  - setup_docker

tests/integration/targets/keycloak_group/tasks/main.yml

@@ -3,6 +3,29 @@
 # GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
 # SPDX-License-Identifier: GPL-3.0-or-later
 
+- name: Start container
+  community.docker.docker_container:
+    name: mykeycloak
+    image: "quay.io/keycloak/keycloak:20.0.2"
+    command: start-dev
+    env:
+      KC_HTTP_RELATIVE_PATH: /auth
+      KEYCLOAK_ADMIN: admin
+      KEYCLOAK_ADMIN_PASSWORD: password
+    ports:
+      - "8080:8080"
+    detach: true
+    auto_remove: true
+    memory: 2200M
+
+- name: Check default ports
+  ansible.builtin.wait_for:
+    host: "localhost"
+    port: "8080"
+    state: started         # Port should be open
+    delay: 30              # Wait before first check
+    timeout: 50            # Stop checking after timeout (sec)
+
 - name: Create a keycloak group
   community.general.keycloak_group:
     auth_keycloak_url: "{{ url }}"
@@ -13,6 +36,9 @@
     name: test-group
     state: present
   register: result
+  retries: 3
+  delay: 20
+  until: result is not failed
 
 - name: Assert group was created
   assert:

tests/integration/targets/mssql_script/aliases

@@ -7,3 +7,4 @@ skip/macos
 skip/freebsd
 skip/rhel
 disabled
+destructive

tests/integration/targets/mssql_script/defaults/main.yml

@@ -4,6 +4,6 @@
 # SPDX-License-Identifier: GPL-3.0-or-later
 
 mssql_host: localhost
-mssql_port: 14330
+mssql_port: 1433
 mssql_login_user: sa
-mssql_login_password: "yourStrong(!)Password"
+mssql_login_password: "Abcd!234"

tests/integration/targets/mssql_script/meta/main.yml

@@ -0,0 +1,7 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+dependencies:
+  - setup_docker

tests/integration/targets/mssql_script/tasks/main.yml

@@ -13,13 +13,33 @@
 # docker run --name mssql-test -e "ACCEPT_EULA=Y" -e 'SA_PASSWORD={{ mssql_login_password }}' -p "{ mssql_port }"0:"{ mssql_port }" -d mcr.microsoft.com/mssql/server:2019-latest
 # ansible-test integration mssql_script  -v --allow-disabled
 
+- name: Install pymssql
+  ansible.builtin.pip:
+    name:
+      - pymssql
+    state: present
+
+- name: Start container
+  community.docker.docker_container:
+    name: mssql-test
+    image: "mcr.microsoft.com/mssql/server:2019-latest"
+    env:
+      ACCEPT_EULA: "Y"
+      SA_PASSWORD: "{{ mssql_login_password }}"
+      MSSQL_PID: Developer
+    ports:
+      - "{{ mssql_port }}:1433"
+    detach: true
+    auto_remove: true
+    memory: 2200M
+
 - name: Check default ports
-  wait_for:
+  ansible.builtin.wait_for:
     host: "{{ mssql_host }}"
     port: "{{ mssql_port }}"
     state: started         # Port should be open
-    delay: 0               # No wait before first check (sec)
+    delay: 10              # Wait 10 secs before first check
-    timeout: 3             # Stop checking after timeout (sec)
+    timeout: 30            # Stop checking after timeout (sec)
 
 - name: Check DB connection
   community.general.mssql_script:
@@ -41,7 +61,7 @@
       GO
       SELECT 'Batch 1 - Select 0'
   register: result_batches
-# "result_batches.query_results": 
+# "result_batches.query_results":
 # [ # batches
 #     [ # selects
 #         [ # Rows
@@ -115,8 +135,6 @@
       - result_batches_dict.query_results_dict[0][0] | length == 1  # one row in first select
       - result_batches_dict.query_results_dict[0][0][0]['b0s0'] == 'Batch 0 - Select 0'  # column 'b0s0' of first row
 
-
-
 - name: Stored procedure may return multiple result sets
   community.general.mssql_script:
     login_user: "{{ mssql_login_user }}"

tests/integration/targets/setup_docker/README.md

@@ -0,0 +1,73 @@
+<!--
+Copyright (c) Ansible Project
+GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+SPDX-License-Identifier: GPL-3.0-or-later
+-->
+
+Setup Docker
+============
+
+This role provides a mechanism to install docker automatically within the context of an integration test.
+
+For the time being (Apr 2023) it has been tested in Fedora 37 and Ubuntu Jammy.
+
+This role was largely based on the `setup_snap` one written by @felixfontein.
+
+
+Quickstart
+----------
+
+Add the file `meta/main.yml` to your integration test target it it does not yet contain one, and add (or update) the `dependencies` block with `setup_docker`, as in:
+
+```yaml
+dependencies:
+  - setup_docker
+```
+
+In your integration test target, add to the beginning of the `tasks/main.yml` something like (example from `mssql_script`):
+
+```yaml
+- name: Start container
+  community.docker.docker_container:
+    name: mssql-test
+    image: "mcr.microsoft.com/mssql/server:2019-latest"
+    env:
+      ACCEPT_EULA: "Y"
+      SA_PASSWORD: "{{ mssql_login_password }}"
+      MSSQL_PID: Developer
+    ports:
+      - "{{ mssql_port }}:1433"
+    detach: true
+    auto_remove: true
+    memory: 2200M
+```
+
+That's it! Your integration test will be using a docker container to support the test.
+
+
+What it does
+------------
+
+The role will install `docker` on the test target, allowing the test to run a container to support its execution.
+
+The installation of the package sends a notification to an Ansible handler that will remove `docker` from the system after the integration test target is done.
+
+This role assumes that developers will use the collection `community.docker` to manage the containers used in the test. To support that assumption, this role will install the `requests` package in the Python runtime environment used, usually a *virtualenv* used for the test. That package is **not removed** from that environment after the test.
+
+The most common use case is to use `community.docker.docker_container` to start a container, as in the example above. It is likely that `community.docker.docker_compose` can be used as well, although this has **not been tested** yet.
+
+
+Recommendations
+---------------
+
+* Don't forget to publish the service ports when starting the container
+* Take into consideration that the services inside the container will take a while to get started. Use both/either `ansible.builtin.wait_for` to check for the availability of the network port and/or `retries` on the first task effectively using those services
+* As a precautionary measure, start using the role in a test that is marked either `disabled` or `unsupported`, and move forward from there.
+
+
+Known Issues & Caveats
+----------------------
+
+* Support only Ubuntu and Fedora, having been tested in Ubuntu Jammy and Fedora 37, respectively
+* Lack mechanism to choose or constraint the `docker` version to be used
+* Lack option to prevent `docker` from being removed at the end of the integration test

tests/integration/targets/setup_docker/aliases

@@ -0,0 +1,5 @@
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+needs/target/setup_epel

tests/integration/targets/setup_docker/defaults/main.yml

@@ -0,0 +1,14 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+distro_lookup_names:
+  - "D-{{ ansible_facts.distribution }}-{{ ansible_facts.distribution_version }}.yml"
+  - "D-{{ ansible_facts.distribution }}-{{ ansible_facts.distribution_major_version }}.yml"
+  - "{{ ansible_facts.os_family }}-{{ ansible_facts.distribution_major_version }}.yml"
+  - "D-{{ ansible_facts.distribution }}.yml"
+  - "{{ ansible_facts.os_family }}.yml"
+  - "default.yml"
+
+has_docker: false

tests/integration/targets/setup_docker/handlers/main.yml

@@ -0,0 +1,19 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+- name: Remove Docker packages
+  package:
+    name: "{{ docker_packages }}"
+    state: absent
+
+- name: "D-Fedora : Remove repository"
+  file:
+    path: /etc/yum.repos.d/docker-ce.repo
+    state: absent
+
+- name: "D-Fedora : Remove dnf-plugins-core"
+  package:
+    name: dnf-plugins-core
+    state: absent

tests/integration/targets/setup_docker/meta/main.yml

@@ -0,0 +1,7 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+dependencies:
+  - setup_pkg_mgr

tests/integration/targets/setup_docker/tasks/D-Fedora.yml

@@ -0,0 +1,33 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# dnf -y install dnf-plugins-core
+# dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo
+# sudo dnf -y install docker-ce docker-ce-cli containerd.io docker-compose-plugin
+
+- name: Install dnf-plugins-core
+  become: true
+  package:
+    name: dnf-plugins-core
+    state: present
+  notify: "D-Fedora : Remove dnf-plugins-core"
+
+- name: Add docker repo
+  become: true
+  ansible.builtin.command:
+    cmd: dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo
+  notify: "D-Fedora : Remove repository"
+
+- name: Install docker
+  become: true
+  package:
+    name: "{{ item }}"
+    state: present
+  loop: "{{ docker_packages }}"
+  notify: Remove Docker packages
+
+- name: Inform that docker is installed
+  set_fact:
+    has_docker: true

tests/integration/targets/setup_docker/tasks/default.yml

@@ -0,0 +1,21 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# dnf -y install dnf-plugins-core
+# dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo
+# sudo dnf -y install docker-ce docker-ce-cli containerd.io docker-compose-plugin
+
+- name: Install docker
+  become: true
+  package:
+    name: "{{ item }}"
+    state: present
+  loop: "{{ docker_packages }}"
+  notify:
+    - Remove Docker packages
+
+- name: Inform that docker is installed
+  set_fact:
+    has_docker: true

tests/integration/targets/setup_docker/tasks/main.yml

@@ -0,0 +1,55 @@
+---
+####################################################################
+# WARNING: These are designed specifically for Ansible tests       #
+# and should not be used as examples of how to write Ansible roles #
+####################################################################
+
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+- name: Print information on which we distinguish
+  debug:
+    msg: "Distribution '{{ ansible_facts.distribution }}', version '{{ ansible_facts.distribution_version }}', OS family '{{ ansible_facts.os_family }}'"
+
+- name: Install EPEL repository (RHEL only)
+  include_role:
+    name: setup_epel
+  when:
+    - ansible_distribution in ['RedHat', 'CentOS']
+    - ansible_distribution_major_version is version('9', '<')
+
+- name: Distribution specific
+  block:
+    - name: Include distribution specific vars
+      include_vars: "{{ lookup('first_found', params) }}"
+      vars:
+        params:
+          files: "{{ distro_lookup_names }}"
+          paths:
+            - "{{ role_path }}/vars"
+    - name: Include distribution specific tasks
+      include_tasks: "{{ lookup('first_found', params) }}"
+      vars:
+        params:
+          files: "{{ distro_lookup_names }}"
+          paths:
+            - "{{ role_path }}/tasks"
+
+- name: Start docker service
+  become: true
+  ansible.builtin.service:
+    name: docker
+    state: started
+
+- name: Cheat on the docker socket permissions
+  become: true
+  ansible.builtin.file:
+    path: /var/run/docker.sock
+    mode: 0666
+
+- name: Install python "requests"
+  ansible.builtin.pip:
+    name:
+      - requests
+    state: present

tests/integration/targets/setup_docker/vars/D-Fedora.yml

@@ -0,0 +1,10 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+docker_packages:
+  - docker-ce
+  - docker-ce-cli
+  - containerd.io
+  - docker-compose-plugin

tests/integration/targets/setup_docker/vars/D-Ubuntu.yml

@@ -0,0 +1,7 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+docker_packages:
+  - docker.io

tests/requirements.yml

@@ -6,5 +6,6 @@
 integration_tests_dependencies:
 - ansible.posix
 - community.crypto
+- community.docker
 unit_tests_dependencies:
 - community.internal_test_tools

tests/utils/shippable/shippable.sh

@@ -85,6 +85,7 @@ if [ "${script}" != "sanity" ] || [ "${test}" == "sanity/extra" ]; then
     # Nothing further should be added to this list.
     # This is to prevent modules or plugins in this collection having a runtime dependency on other collections.
     retry git clone --depth=1 --single-branch https://github.com/ansible-collections/community.internal_test_tools.git "${ANSIBLE_COLLECTIONS_PATHS}/ansible_collections/community/internal_test_tools"
+    retry git clone --depth=1 --single-branch https://github.com/ansible-collections/community.docker.git "${ANSIBLE_COLLECTIONS_PATHS}/ansible_collections/community/docker"
     # NOTE: we're installing with git to work around Galaxy being a huge PITA (https://github.com/ansible/galaxy/issues/2429)
     # retry ansible-galaxy -vvv collection install community.internal_test_tools
 fi