Merge pull request #2 from arillso/feat/docker-login-compose-roles

feat: add new Ansible roles for Docker Login and Docker Compose

galaxy.yml

@@ -18,16 +18,15 @@ tags:
   - apt
   - containerd
   - linux
-  - windows
 
 dependencies:
   arillso.system: ">=0.0.17"
 
 repository: https://github.com/arillso/ansible.container
 
-documentation: https://github.com/arillso/ansible.container
+documentation: https://guide.arillso.io/collections/arillso/container/index.html
 
-# homepage: http://example.com
+homepage: https://arillso.io
 
 issues: https://github.com/arillso/ansible.container/issues
 

roles/docker/README.md

@@ -1,35 +1,43 @@
 # arillso.container.docker
 
-This Ansible role is designed for configuring and managing Docker environments using Ansible. It defines parameters for
-setting up Docker on various distributions, allowing for a customized Docker experience.
+This Ansible role is designed for the configuration and management of Docker environments.
+It offers tailored parameters for setting up Docker across various distributions, enabling a customized Docker experience.
 
 ## Requirements
 
-- Ansible 2.915 or higher.
-- Suitable access to target systems for Docker installation and configuration.
+- **Ansible Version**: 2.15 or higher
+- **Access**: Adequate permissions for Docker installation and configuration on target systems
 
 ## Role Variables
 
-The role uses various variables to customize Docker setup and behavior. These variables are defined in the `defaults/main.yml` file.
-Users can override these default values in their playbook.
+Variables for customizing Docker setup are defined in `defaults/main.yml`. Users can override these in their playbook. Key variables include:
 
 ### Docker Configuration
 
-- `docker_version`: Specifies the Docker version to install (default: latest).
-- `docker_daemon`: A dictionary to define Docker daemon configurations, including options like `log-driver` (default: "journald"),
-  `log-opts` (with options like `max-size`), `live-restore` (default: true), and `registry-mirrors`.
+- `docker_version`: Docker version to install (default: latest)
+- `docker_daemon`: Configuration dictionary for Docker daemon, including:
+  - `log-driver` (default: "journald")
+  - `log-opts` with options like `max-size`
+  - `live-restore` (default: true)
+  - `registry-mirrors`
 
 ### Systemd Units for Docker
 
-- `docker_systemd_units`: A list of systemd units for Docker pruning tasks, with options to specify the unit's name, type, and various systemd options.
+- `docker_systemd_units`: List of systemd units for Docker pruning tasks. Includes options for unit's name, type, and various systemd settings.
+
+## Documentation
+
+For detailed information and advanced usage, refer to our guide:
+
+[Arillso Docker Guide](https://guide.arillso.io/collections/arillso/container/docker.html#ansible-collections-arillso-container-docker-role)
 
 ## Dependencies
 
-No other Ansible roles are required as dependencies.
+This role is standalone and does not require other Ansible roles as dependencies.
 
 ## Example Playbook
 
-An example playbook demonstrating the use of `arillso.container.docker` to set up Docker:
+Example playbook for using `arillso.container.docker`:
 
 ```yaml
 - hosts: all

roles/docker/meta/argument_specs.yml

@@ -8,7 +8,7 @@ argument_specs:
       docker_version:
         type: str
         description: Specifies the version of Docker to be installed. If omitted, the latest version is installed.
-        default: "{{ omit }}"
+        default: ""
 
       docker_daemon:
         type: dict

roles/docker_compose/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_package`: 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"
+```

roles/docker_compose/defaults/main.yml

@@ -0,0 +1,111 @@
+# Specifies the version of Docker Compose to install. Leave blank for the latest version.
+docker_compose_version: ""
+
+# List of Docker Compose packages for installation. Appends the specified version to the package name if docker_compose_version is set.
+docker_compose_package:
+  - "{{ 'docker-compose-plugin=' + docker_compose_version if docker_compose_version != '' else 'docker-compose-plugin' }}"
+
+# Base directory path for storing Docker Compose configuration files.
+docker_compose_directory_path: "/etc/docker/compose"
+
+# Full path to the Docker Compose project directory, constructed from docker_compose_directory_path and docker_compose_project.
+docker_compose_directory: "{{ docker_compose_directory_path }}/{{ docker_compose_project }}"
+
+# Boolean flag to choose Docker Compose execution method: 'true' for file-based, 'false' for inline configuration.
+docker_compose_use_file: true
+
+# Inline configuration for Docker Compose, defined as an array of multi-line YAML strings.
+docker_compose_config: []
+
+# Name of the Docker Compose project, utilized to construct the full Docker Compose directory path.
+docker_compose_project: ""
+
+# Docker API version to use. Set to 'auto' for automatic selection of the latest supported version.
+docker_compose_api_version: "auto"
+
+# Option to build images before starting services. Set to 'true' to enable image building.
+docker_compose_build: false
+
+# Path to the CA certificate for server verification. If not set, default CA certificates are used.
+docker_compose_ca_cert: null
+
+# Path to the client's TLS certificate for Docker daemon communication.
+docker_compose_client_cert: null
+
+# Path to the client's TLS key for Docker daemon communication.
+docker_compose_client_key: null
+
+# Enable or disable debug mode. Set to 'true' to activate.
+docker_compose_debug: false
+
+# Include or exclude linked services. Set to 'true' to include.
+docker_compose_dependencies: true
+
+# Docker host URL or Unix socket path for API connection. Defaults to the standard Unix socket.
+docker_compose_docker_host: "unix://var/run/docker.sock"
+
+# Custom path to an environment file, relative to the project source directory.
+docker_compose_env_file: null
+
+# List of Compose file names, relative to project_src, to override default docker-compose.yml.
+docker_compose_files: null
+
+# Check Docker daemon's hostname against the name provided in the client certificate. Default is 'false'.
+docker_compose_hostname_check: false
+
+# Control the use of cache during the image build. Set to 'true' to ignore cache.
+docker_compose_nocache: false
+
+# List of profiles to enable when starting services, applicable for docker-compose v1.28.0 or later.
+docker_compose_profiles: null
+
+# Custom name for the Docker Compose project. If not set, the default name is derived from the project directory.
+docker_compose_project_name: null
+
+# Always pull images before starting the application. Set to 'true' to enable.
+docker_compose_pull: false
+
+# Strategy for container recreation: 'always', 'never', or 'smart' (default).
+docker_compose_recreate: "smart"
+
+# Option to remove images when state is 'absent'. Choices are 'all' or 'local'.
+docker_compose_remove_images: null
+
+# Remove containers for services not defined in the current Compose file. Default is 'false'.
+docker_compose_remove_orphans: false
+
+# Remove data volumes when state is 'absent'. Default is 'false'.
+docker_compose_remove_volumes: false
+
+# Restart all containers when state is 'present'. Default is 'false'.
+docker_compose_restarted: false
+
+# Dictionary defining service scaling: service name as key, number of containers as value.
+docker_compose_scale: null
+
+# List of specific services to operate on. If empty, applies to all services in the Compose file.
+docker_compose_services: null
+
+# Specify a valid SSL version number for secure communication. Uses the default value determined by the SSL Python module if not set.
+docker_compose_ssl_version: null
+
+# Desired state of the Docker Compose project: 'present' (default) or 'absent'.
+docker_compose_state: "present"
+
+# Stop all containers when state is 'present'. Default is 'false'.
+docker_compose_stopped: false
+
+# Timeout in seconds for container shutdown operations. Uses default docker-compose timeout if not set.
+docker_compose_timeout: null
+
+# Use TLS for API connection without verifying the Docker host server's authenticity. Default is 'false'.
+docker_compose_tls: false
+
+# Expected hostname of the Docker Host server for TLS verification. No default value.
+docker_compose_tls_hostname: null
+
+# Flag to enable SSH client usage for Docker API communication. Currently ignored.
+docker_compose_use_ssh_client: false
+
+# Verify the Docker host server's authenticity when using TLS. Default is 'false'.
+docker_compose_validate_certs: false