From 706a3395663fd870a64cfe3c9a3ce699bcbeaedc Mon Sep 17 00:00:00 2001 From: Simon Baerlocher Date: Mon, 12 Feb 2024 19:29:17 +0100 Subject: [PATCH] feat: add docker compose v2 --- galaxy.yml | 2 +- roles/docker/tasks/main.yml | 1 - roles/docker_compose_v2/README.md | 80 +++++++ roles/docker_compose_v2/defaults/main.yml | 125 ++++++++++ .../docker_compose_v2/meta/argument_specs.yml | 225 ++++++++++++++++++ roles/docker_compose_v2/tasks/main.yml | 69 ++++++ .../etc/docker/compose/docker-compose.yml.j2 | 1 + .../systemd/system/docker-compose@.service.j2 | 14 ++ 8 files changed, 515 insertions(+), 2 deletions(-) create mode 100644 roles/docker_compose_v2/README.md create mode 100644 roles/docker_compose_v2/defaults/main.yml create mode 100644 roles/docker_compose_v2/meta/argument_specs.yml create mode 100644 roles/docker_compose_v2/tasks/main.yml create mode 100644 roles/docker_compose_v2/templates/etc/docker/compose/docker-compose.yml.j2 create mode 100644 roles/docker_compose_v2/templates/etc/systemd/system/docker-compose@.service.j2 diff --git a/galaxy.yml b/galaxy.yml index 6ba4bf4..ecd6679 100644 --- a/galaxy.yml +++ b/galaxy.yml @@ -1,7 +1,7 @@ --- namespace: arillso name: container -version: 0.0.4 +version: 0.0.5 readme: README.md authors: diff --git a/roles/docker/tasks/main.yml b/roles/docker/tasks/main.yml index e5b89d5..33aa776 100644 --- a/roles/docker/tasks/main.yml +++ b/roles/docker/tasks/main.yml @@ -80,7 +80,6 @@ become: true ansible.builtin.systemd: name: "{{ item.name }}" - state: started enabled: true daemon_reload: true loop: "{{ docker_systemd_units }}" diff --git a/roles/docker_compose_v2/README.md b/roles/docker_compose_v2/README.md new file mode 100644 index 0000000..cd4a3ea --- /dev/null +++ b/roles/docker_compose_v2/README.md @@ -0,0 +1,80 @@ +# arillso.container.docker_compose + +This Ansible role is tailored for the configuration and management of Docker Compose environments. +It provides a customizable approach for Docker Compose setups across various systems. + +## Requirements + +- **Ansible Version**: 2.15 or higher +- **Permissions**: Necessary rights to access and manage target systems + +## Role Variables + +Variables are defined in `defaults/main.yml` and can be overridden in your playbook for specific needs. Key variables include: + +### Docker Compose Configuration + +#### Argument Specifications + +- `docker_compose_version`: Specifies Docker Compose version to install (defaults to latest) +- `docker_compose_packages`: List of Docker Compose packages for installation +- `docker_compose_directory_path`: Base directory path for Docker Compose configuration files +- `docker_compose_directory`: Full path for the Docker Compose project directory +- `docker_compose_use_file`: Boolean to choose between file-based or inline configuration +- `docker_compose_config`: Inline Docker Compose configuration as YAML string +- `docker_compose_project`: Name of the Docker Compose project +- `docker_compose_api_version`: Docker API version ('auto' for automatic) +- `docker_compose_build`: Option to build images before starting services +- `docker_compose_ca_cert`: CA certificate path for server verification +- `docker_compose_client_cert`: Client's TLS certificate path +- `docker_compose_client_key`: Client's TLS key path +- `docker_compose_debug`: Toggle for debug mode +- `docker_compose_dependencies`: Include/exclude linked services +- `docker_compose_docker_host`: Docker host URL or Unix socket path +- `docker_compose_env_file`: Custom environment file path +- `docker_compose_files`: Override default `docker-compose.yml` with a list of filenames +- `docker_compose_hostname_check`: Check Docker daemon's hostname against client certificate +- `docker_compose_nocache`: Control cache use during image build +- `docker_compose_profiles`: Profiles to activate when starting services +- `docker_compose_project_name`: Custom name for the Docker Compose project +- `docker_compose_pull`: Always pull images before starting +- `docker_compose_recreate`: Container recreation strategy ('always', 'never', 'smart') +- `docker_compose_remove_images`: Remove images when state is 'absent' +- `docker_compose_remove_orphans`: Remove containers not defined in Compose file +- `docker_compose_remove_volumes`: Remove data volumes when state is 'absent' +- `docker_compose_restarted`: Restart all containers when state is 'present' +- `docker_compose_scale`: Service scaling configuration +- `docker_compose_services`: List of specific services to operate on +- `docker_compose_ssl_version`: SSL version for secure communication +- `docker_compose_state`: Desired state of the Docker Compose project +- `docker_compose_stopped`: Stop all containers when state is 'present' +- `docker_compose_timeout`: Timeout for container shutdown operations (seconds) +- `docker_compose_tls`: Use TLS for API connection without server authenticity verification +- `docker_compose_tls_hostname`: Expected hostname for Docker Host server TLS verification +- `docker_compose_use_ssh_client`: Enable SSH client for Docker API communication +- `docker_compose_validate_certs`: Verify Docker host server authenticity with TLS + +## Documentation + +For detailed information and advanced usage, refer to our comprehensive guide: + +[Arillso Docker Compose Guide](https://guide.arillso.io/collections/arillso/container/docker_compose.html#ansible-collections-arillso-container-docker-compose-role) + +## Dependencies + +This role operates independently without external dependencies. + +## Example Playbook + +Example demonstrating this role's usage: + +```yaml +- hosts: servers + become: true + roles: + - arillso.container.docker_compose + vars: + docker_compose_version: "1.29.2" + docker_compose_use_file: true + docker_compose_project: "my_project" +``` diff --git a/roles/docker_compose_v2/defaults/main.yml b/roles/docker_compose_v2/defaults/main.yml new file mode 100644 index 0000000..f4a3749 --- /dev/null +++ b/roles/docker_compose_v2/defaults/main.yml @@ -0,0 +1,125 @@ +# Specifies the version of Docker Compose to install. Leave blank for the latest version. +# Specify a specific version to install an older or specific release. +docker_compose_v2_version: "" + +# List of Docker Compose packages for installation. Appends the specified version to the package name if docker_compose_v2_version is set. +# Useful for ensuring consistency across environments by locking to a specific version. +docker_compose_v2_packages: + - name: "{{ 'docker-compose-plugin=' + docker_compose_v2_version if docker_compose_v2_version != '' else 'docker-compose-plugin' }}" + +# Base directory path for storing Docker Compose configuration files. +# Ensure the specified path exists and is writable. +docker_compose_v2_directory_path: "/etc/docker/compose" + +# Full path to the Docker Compose project directory, constructed from docker_compose_v2_directory_path and docker_compose_v2_project. +docker_compose_v2_directory: "{{ docker_compose_v2_directory_path }}/{{ docker_compose_v2_project }}" + +# Boolean flag to choose Docker Compose execution method: 'true' for file-based, 'false' for inline configuration. +# 'true' uses a file for configuration, while 'false' utilizes an inline configuration. +docker_compose_v2_use_file: true + +# Inline configuration for Docker Compose, defined as an array of multi-line YAML strings. +docker_compose_v2_config: [] + +# Name of the Docker Compose project, utilized to construct the full Docker Compose directory path. +docker_compose_v2_project: "" + +# Docker API version to use. Set to 'auto' for automatic selection of the latest supported version. +# 'auto' automatically selects the latest supported API version. +docker_compose_v2_api_version: "auto" + +# Path to the CA certificate for server verification. If not set, default CA certificates are used. +docker_compose_v2_ca_cert: "{{ omit }}" + +# Path to the client's TLS certificate for Docker daemon communication. +docker_compose_v2_client_cert: "{{ omit }}" + +# Path to the client's TLS key for Docker daemon communication. +docker_compose_v2_client_key: "{{ omit }}" + +# Enable or disable debug mode. Set to 'true' to activate. +docker_compose_v2_debug: false + +# Include or exclude linked services. Set to 'true' to include. +docker_compose_v2_dependencies: true + +# Docker host URL or Unix socket path for API connection. Defaults to the standard Unix socket. +docker_compose_v2_docker_host: "unix:///var/run/docker.sock" + +# Custom path to an environment file, relative to the project source directory. +docker_compose_v2_env_file: "{{ omit }}" + +# List of Compose file names, relative to project_src, to override default docker-compose.yml. +docker_compose_v2_files: "{{ omit }}" + +# Check Docker daemon's hostname against the name provided in the client certificate. Default is 'false'. +docker_compose_v2_hostname_check: false + +# Control the use of cache during the image build. Set to 'true' to ignore cache. +docker_compose_v2_nocache: false + +# List of profiles to enable when starting services, applicable for docker-compose v1.28.0 or later. +docker_compose_v2_profiles: "{{ omit }}" + +# Custom name for the Docker Compose project. If not set, the default name is derived from the project directory. +docker_compose_v2_project_name: "{{ omit }}" + +# Set 'always' to pull images before starting, 'never' to skip, or 'if_not_present' for pulling if not local. +docker_compose_v2_pull: policy + +# Strategy for container recreation: 'always', 'never', or 'smart' (default). +docker_compose_v2_recreate: "auto" + +# Option to remove images when state is 'absent'. Choices are 'all' or 'local'. +docker_compose_v2_remove_images: all + +# Remove containers for services not defined in the current Compose file. Default is 'false'. +# Useful for cleaning up containers that are no longer needed. +docker_compose_v2_remove_orphans: false + +# Remove data volumes when state is 'absent'. Default is 'false'. +docker_compose_v2_remove_volumes: false + +# Restart all containers when state is 'present'. Default is 'false'. +docker_compose_v2_restarted: false + +# Dictionary defining service scaling: service name as key, number of containers as value. +docker_compose_v2_scale: "{{ omit }}" + +# List of specific services to operate on. If empty, applies to all services in the Compose file. +docker_compose_v2_services: "{{ omit }}" + +# Specify a valid SSL version number for secure communication. Uses the default value determined by the SSL Python module if not set. +docker_compose_v2_ssl_version: "{{ omit }}" + +# Desired state of the Docker Compose project: 'present' (default) or 'absent'. +# 'present' ensures the project is running, 'absent' removes it. +docker_compose_v2_state: "present" + +# Stop all containers when state is 'present'. Default is 'false'. +docker_compose_v2_stopped: false + +# Timeout in seconds for container shutdown operations. Uses default docker-compose timeout if not set. +# Set a specific value to override the default timeout. +docker_compose_v2_timeout: + +# Use TLS for API connection without verifying the Docker host server's authenticity. Default is 'false'. +docker_compose_v2_tls: false + +# Expected hostname of the Docker Host server for TLS verification. No default value. +docker_compose_v2_tls_hostname: "{{ omit }}" + +# Verify the Docker host server's authenticity when using TLS. Default is 'false'. +docker_compose_v2_validate_certs: false + +# Specify the Docker CLI context to use with Docker Compose v2. +docker_compose_v2_cli_context: "{{ omit }}" + +# Path to the Docker CLI executable, if not in standard PATH. +docker_compose_v2_docker_cli: "{{ omit }}" + +# Whether to build images before starting containers. This is used when docker compose up is run. +docker_compose_v2_build: "{{ omit }}" + +# Use a CA certificate when performing server verification by providing the path to a CA certificate file. +docker_compose_v2_ca_path: "{{ omit }}" diff --git a/roles/docker_compose_v2/meta/argument_specs.yml b/roles/docker_compose_v2/meta/argument_specs.yml new file mode 100644 index 0000000..40df61e --- /dev/null +++ b/roles/docker_compose_v2/meta/argument_specs.yml @@ -0,0 +1,225 @@ +--- +argument_specs: + main: + short_description: Configure and manage Docker Compose environment using Ansible + description: + - This spec outlines parameters for configuring Docker Compose with Ansible. + - It includes Docker Compose version, package names, directory paths, configuration methods, and project name. + + options: + docker_compose_v2_version: + type: str + description: + - Specifies the version of Docker Compose to install. Leave blank for the latest version. + - Specify a specific version to install an older or specific release. + default: "" + + docker_compose_v2_packages: + type: list + elements: str + description: + - List of Docker Compose packages for installation. Appends the specified version to the package name if docker_compose_v2_version is set. + - Useful for ensuring consistency across environments by locking to a specific version. + default: + - name: "{{ 'docker-compose-plugin=' + docker_compose_v2_version if docker_compose_v2_version != '' else 'docker-compose-plugin' }}" + + docker_compose_v2_directory_path: + type: str + description: + - Base directory path for storing Docker Compose configuration files. + - Ensure the specified path exists and is writable. + default: "/etc/docker/compose" + + docker_compose_v2_directory: + type: str + description: + - Full path to the Docker Compose project directory, constructed from docker_compose_v2_directory_path and docker_compose_v2_project. + default: "{{ docker_compose_v2_directory_path }}/{{ docker_compose_v2_project }}" + + docker_compose_v2_use_file: + type: bool + description: + - "Boolean flag to choose Docker Compose execution method: 'true' for file-based, 'false' for inline configuration." + - "'true' uses a file for configuration, while 'false' utilizes an inline configuration." + default: true + + docker_compose_v2_config: + type: raw + description: + - Inline configuration for Docker Compose, defined as an array of multi-line YAML strings. + default: [] + + docker_compose_v2_project: + type: str + description: + - Name of the Docker Compose project, utilized to construct the full Docker Compose directory path. + default: "" + + docker_compose_v2_api_version: + type: str + description: + - Docker API version to use. Set to 'auto' for automatic selection of the latest supported version. + - "'auto' automatically selects the latest supported API version." + default: "auto" + + docker_compose_v2_ca_cert: + type: str + description: + - Path to the CA certificate for server verification. + + docker_compose_v2_client_cert: + type: str + description: + - Path to the client's TLS certificate for Docker daemon communication. + + docker_compose_v2_client_key: + type: str + description: + - Path to the client's TLS key for Docker daemon communication. + + docker_compose_v2_debug: + type: bool + description: + - Enable or disable debug mode. + default: false + + docker_compose_v2_dependencies: + type: bool + description: + - Include or exclude linked services. + default: true + + docker_compose_v2_docker_host: + type: str + description: + - Docker host URL or Unix socket path for API connection. Defaults to the standard Unix socket. + default: "unix:///var/run/docker.sock" + + docker_compose_v2_env_file: + type: str + description: + - Custom path to an environment file, relative to the project source directory. + + docker_compose_v2_files: + type: list + elements: str + description: + - List of Compose file names, relative to project_src, to override default docker-compose.yml. + + docker_compose_v2_hostname_check: + type: bool + description: + - Check Docker daemon's hostname against the name provided in the client certificate. Default is 'false'. + default: false + + docker_compose_v2_nocache: + type: bool + description: + - Control the use of cache during the image build. Set to 'true' to ignore cache. + default: false + + docker_compose_v2_profiles: + type: list + elements: str + description: + - List of profiles to enable when starting services, applicable for docker-compose v1.28.0 or later. + + docker_compose_v2_project_name: + type: str + description: + - Custom name for the Docker Compose project. If not set, the default name is derived from the project directory. + + docker_compose_v2_pull: + description: + - Always pull images before starting the application. Set to 'true' to enable. + + docker_compose_v2_recreate: + type: str + description: + - "Strategy for container recreation: 'always', 'never', or 'smart' (default)." + default: "smart" + + docker_compose_v2_remove_images: + type: str + description: + - Option to remove images when state is 'absent'. Choices are 'all' or 'local'. + + docker_compose_v2_remove_orphans: + type: bool + description: + - Remove containers for services not defined in the current Compose file. Default is 'false'. + - Useful for cleaning up containers that are no longer needed. + default: false + + docker_compose_v2_remove_volumes: + type: bool + description: + - Remove data volumes when state is 'absent'. Default is 'false'. + default: false + + docker_compose_v2_restarted: + type: bool + description: + - Restart all containers when state is 'present'. Default is 'false'. + default: false + + docker_compose_v2_scale: + type: dict + description: + - "Dictionary defining service scaling: service name as key, number of containers as value." + + docker_compose_v2_services: + type: list + elements: str + description: + - List of specific services to operate on. If empty, applies to all services in the Compose file. + + docker_compose_v2_ssl_version: + type: str + description: + - Specify a valid SSL version number for secure communication. Uses the default value determined by the SSL Python module if not set. + + docker_compose_v2_state: + type: str + description: + - "Desired state of the Docker Compose project: 'present' (default) or 'absent'." + - "'present' ensures the project is running, 'absent' removes it." + default: "present" + + docker_compose_v2_stopped: + type: bool + description: + - Stop all containers when state is 'present'. Default is 'false'. + default: false + + docker_compose_v2_timeout: + type: int + description: + - Timeout in seconds for container shutdown operations. Set a specific value to override the default timeout. + + docker_compose_v2_tls: + type: bool + description: + - Use TLS for API connection without verifying the Docker host server's authenticity. Default is 'false'. + default: false + + docker_compose_v2_tls_hostname: + type: str + description: + - Expected hostname of the Docker Host server for TLS verification. + + docker_compose_v2_validate_certs: + type: bool + description: + - Verify the Docker host server's authenticity when using TLS. Default is 'false'. + default: false + + docker_compose_v2_cli_context: + type: str + description: + - Specify the Docker CLI context to use with Docker Compose v2. + + docker_compose_v2_docker_cli: + type: str + description: + - Path to the Docker CLI executable, if not in standard PATH. diff --git a/roles/docker_compose_v2/tasks/main.yml b/roles/docker_compose_v2/tasks/main.yml new file mode 100644 index 0000000..87e760c --- /dev/null +++ b/roles/docker_compose_v2/tasks/main.yml @@ -0,0 +1,69 @@ +--- +- name: Install Docker Compose packages + become: true + ansible.builtin.package: + name: "{{ item.name }}" + state: present + loop: "{{ docker_compose_v2_packages }}" + +- name: Ensure Docker Compose directory exists with correct permissions + become: true + ansible.builtin.file: + path: "{{ docker_compose_v2_directory }}" + state: directory + mode: "0755" + +- name: Manage Docker Compose Setup + when: docker_compose_v2_config | length > 0 + block: + - name: Configure Docker Compose environment + when: docker_compose_v2_use_file + block: + - name: Set up Docker Compose systemd service on target host + become: true + ansible.builtin.template: + src: etc/systemd/system/docker-compose@.service.j2 + dest: /etc/systemd/system/docker-compose@.service + owner: root + group: root + mode: "0644" + + - name: Create Docker Compose configuration file from template + become: true + ansible.builtin.template: + src: etc/docker/compose/docker-compose.yml.j2 + dest: "{{ docker_compose_v2_directory_path }}/{{ docker_compose_v2_project }}/docker-compose.yml" + owner: root + group: root + mode: "0644" + + - name: Launch Docker Compose based on specified configuration + become: true + community.docker.docker_compose_v2: + project_src: "{{ docker_compose_v2_directory if docker_compose_v2_use_file else omit }}" + definition: "{{ docker_compose_v2_config if not docker_compose_v2_use_file else omit }}" + api_version: "{{ docker_compose_v2_api_version }}" + dependencies: "{{ docker_compose_v2_dependencies }}" + docker_host: "{{ docker_compose_v2_docker_host }}" + env_files: "{{ docker_compose_v2_env_file }}" + profiles: "{{ docker_compose_v2_profiles }}" + project_name: "{{ docker_compose_v2_project_name }}" + recreate: "{{ docker_compose_v2_recreate }}" + remove_images: "{{ docker_compose_v2_remove_images }}" + remove_orphans: "{{ docker_compose_v2_remove_orphans }}" + remove_volumes: "{{ docker_compose_v2_remove_volumes }}" + state: "{{ docker_compose_v2_state }}" + timeout: "{{ docker_compose_v2_timeout | default(omit, true) }}" + tls: "{{ docker_compose_v2_tls }}" + tls_hostname: "{{ docker_compose_v2_tls_hostname }}" + validate_certs: "{{ docker_compose_v2_validate_certs }}" + cli_context: "{{ docker_compose_v2_cli_context }}" + docker_cli: "{{ docker_compose_v2_docker_cli }}" + build: "{{ docker_compose_v2_build }}" + ca_path: "{{ docker_compose_v2_ca_path }}" + client_cert: "{{ docker_compose_v2_client_cert }}" + client_key: "{{ docker_compose_v2_client_key }}" + files: "{{ docker_compose_v2_files }}" + pull: "{{ docker_compose_v2_pull }}" + scale: "{{ docker_compose_v2_scale }}" + services: "{{ docker_compose_v2_services }}" diff --git a/roles/docker_compose_v2/templates/etc/docker/compose/docker-compose.yml.j2 b/roles/docker_compose_v2/templates/etc/docker/compose/docker-compose.yml.j2 new file mode 100644 index 0000000..2b2f7ba --- /dev/null +++ b/roles/docker_compose_v2/templates/etc/docker/compose/docker-compose.yml.j2 @@ -0,0 +1 @@ +{{ docker_compose_v2_config | to_nice_yaml }} diff --git a/roles/docker_compose_v2/templates/etc/systemd/system/docker-compose@.service.j2 b/roles/docker_compose_v2/templates/etc/systemd/system/docker-compose@.service.j2 new file mode 100644 index 0000000..b404ad9 --- /dev/null +++ b/roles/docker_compose_v2/templates/etc/systemd/system/docker-compose@.service.j2 @@ -0,0 +1,14 @@ +[Unit] +Description=%i service with docker compose +PartOf=docker.service +After=docker.service + +[Service] +Type=oneshot +RemainAfterExit=true +WorkingDirectory={{ docker_compose_v2_directory_path }}/%i +ExecStart=/usr/bin/docker-compose up -d --remove-orphans +ExecStop=/usr/bin/docker-compose down + +[Install] +WantedBy=multi-user.target