nickjj.docker

¿Qué es ansible-docker?

Es un rol de Ansible para:

• Instalar Docker (soporta ediciones, canales y fijación de versiones)
• Instalar Docker Compose v2 y/o Docker Compose v1 (se permite fijar versiones)
• Instalar el paquete PIP docker para que los módulos docker_* de Ansible funcionen
• Gestionar las credenciales de inicio de sesión del registro de Docker
• Configurar 1 o más usuarios para ejecutar Docker sin necesidad de acceso root
• Configurar las opciones y variables de entorno del daemon de Docker
• Configurar un trabajo cron para ejecutar comandos de limpieza de Docker

¿Por qué querrías usar este rol?

Si eres como yo, probablemente ames Docker. Este rol ofrece todo lo que necesitas para comenzar con un host de Docker listo para producción.

Por cierto, si no sabes qué es Docker, o si buscas convertirte en un experto en ello, consulta Dive into Docker: The Complete Docker Course for Developers.

Plataformas soportadas

• Ubuntu 20.04 LTS (Focal Fossa)
• Ubuntu 22.04 LTS (Jammy Jellyfish)
• Debian 11 (Bullseye)
• Debian 12 (Bookworm)

Las versiones anteriores pueden funcionar o no, pero no están oficialmente soportadas.

Estás viendo la documentación de la rama principal, que podría estar adelantada a la última versión. Cambia a la última versión.

Inicio rápido

La filosofía de todos mis roles es facilitar el inicio, pero proporcionar una forma de personalizar casi todo.

¿Qué se configura por defecto?

Se instalará la última versión estable de Docker CE y Docker Compose v2, la limpieza de disco de Docker se realizará una vez por semana y los registros de contenedores de Docker se enviarán a journald.

Ejemplo de playbook

---

# docker.yml

- name: Ejemplo
  hosts: "todos"
  become: true

  roles:
    - role: "nickjj.docker"
      tags: ["docker"]

Uso: ansible-playbook docker.yml

Instalación

$ ansible-galaxy install nickjj.docker

Variables de rol por defecto

Instalando Docker

Canal

¿Quieres usar el canal "estable" o "prueba"? Puedes agregar más de uno (el orden importa).

docker__channel: ["stable"]

Versión

• Cuando se establece en "", se instalará la última versión de Docker.
• Cuando se establece en una versión específica, se instalará y fijará esa versión de Docker.

docker__version: ""

# Por ejemplo, fijarlo a 25.0.
docker__version: "25.0"

# Por ejemplo, fijarlo a una versión más precisa de 25.0.
docker__version: "25.0.5"

Las fijaciones se colocan con * al final de la versión del paquete, por lo que recibirás parches menores y de seguridad a menos que fijes una versión exacta.

Estrategia de actualización

• Cuando se establece en "present", ejecutar este rol en el futuro no instalará versiones nuevas (si están disponibles)
• Cuando se establece en "latest", ejecutar este rol en el futuro instalará versiones nuevas (si están disponibles)

docker__state: "present"

Estrategia de degradado

La manera más fácil de degradar sería desinstalar el paquete Docker manualmente y luego ejecutar este rol fijando la versión específica de Docker que deseas.

# Un comando Ansible ad-hoc para detener y eliminar el paquete Docker CE en todos los hosts.
ansible all -m systemd -a "name=docker-ce state=stopped" \
  -m apt -a "name=docker-ce autoremove=true purge=true state=absent" -b

Instalando Docker Compose v2

Docker Compose v2 se instalará mediante apt usando el oficial docker-compose-plugin que gestiona Docker.

Versión

• Cuando se establece en "", se instalará la última versión de Docker Compose v2.
• Cuando se establece en una versión específica, se instalará y fijará esa versión de Docker Compose v2.

docker__compose_v2_version: ""

# Por ejemplo, fijarlo a 2.29.
docker__compose_v2_version: "2.29"

# Por ejemplo, fijarlo a una versión más precisa de 2.29.1.
docker__compose_v2_version: "2.29.1"

Estrategia de actualización

Usará la variable docker__state explicada anteriormente en la sección de Docker con las mismas reglas.

Estrategia de degradado

Al igual que Docker, la forma más fácil de desinstalar Docker Compose v2 es ejecutar manualmente el siguiente comando y luego fijar una versión específica de Docker Compose v2.

# Un comando Ansible ad-hoc para eliminar el paquete Docker Compose Plugin en todos los hosts.
ansible all -m apt -a "name=docker-compose-plugin autoremove=true purge=true state=absent" -b

Instalando Docker Compose v1

Por defecto, este rol no instala Docker Compose v1, ya que ha sido oficialmente desaprobado y ya no recibe actualizaciones de Docker. Sin embargo, este rol puede instalarlo. Todo lo que necesitas hacer es configurar docker__pip_docker_compose_state: "present" ya que este rol tiene como valor predeterminado absent para este valor.

Técnicamente, ambas versiones pueden instalarse juntas, ya que v1 se accede con docker-compose y v2 se accede con docker compose (observa la falta de guion).

Te sugeriría no instalar v1 a menos que realmente lo necesites por razones de legado. Si decides instalarlo, puedes configurar qué versión se instala a continuación. Si no se establece para ser instalado, estas versiones no se usarán:

Versión

• Cuando se establece en "", se instalará la última versión de Docker Compose v1.
• Cuando se establece en una versión específica, se instalará y fijará esa versión de Docker Compose v1.

docker__compose_version: ""

# Por ejemplo, fijarlo a 1.29.
docker__compose_version: "1.29"

# Por ejemplo, fijarlo a una versión más precisa de 1.29.
docker__compose_version: "1.29.2"

Las estrategias de actualización y degradado se explicarán en la otra sección de este README.

Configurando usuarios para ejecutar Docker sin root

Una lista de usuarios que se agregarán al grupo docker.

Ten en cuenta que este usuario debe existir previamente, este rol no lo creará. Si deseas crear usuarios, consulta mi rol de usuario.

Este rol no configura espacios de nombres de usuario ni ninguna otra característica de seguridad de forma predeterminada. Si el usuario que agregas aquí tiene acceso SSH a tu servidor, entonces efectivamente le estás dando acceso root al servidor, ya que puede ejecutar Docker sin sudo y montar volúmenes en cualquier ruta de tu sistema de archivos.

En un entorno controlado, esto es seguro, pero como todo lo relacionado con la seguridad, vale la pena saberlo de antemano. Puedes habilitar espacios de nombres de usuario y cualquier otra opción con la variable docker__daemon_json, que se explica más adelante.

# Intenta usar el usuario sudo de forma predeterminada, pero recae en root.
docker__users: ["{{ ansible_env.SUDO_USER | d('root') }}"]

# Por ejemplo, si el usuario que deseas establecer es diferente del usuario sudo.
docker__users: ["admin"]

Configurando inicios de sesión en el registro de Docker

Inicia sesión en 1 o más registros de Docker (como el Docker Hub).

# Tus credenciales de inicio de sesión terminarán en el directorio home de este usuario.
docker__login_become_user: "{{ docker__users | first | d('root') }}"

# 0 o más registros para iniciar sesión.
docker__registries:
  - #registry_url: "https://index.docker.io/v1/"
    username: "tu_usuario_de_docker_hub"
    password: "tu_contraseña_de_docker_hub"
    #email: "[email protected]"
    #reauthorize: false
    #config_path: "$HOME/.docker/config.json"
    #state: "present"
docker__registries: []

Las propiedades precedidas por * son requeridas.

• registry_url se establece de manera predeterminada en https://index.docker.io/v1/
• *username es tu nombre de usuario en el registro de Docker
• *password es tu contraseña en el registro de Docker
• email no se utiliza de forma predeterminada (no todos los registros lo utilizan)
• reauthorize es falso de forma predeterminada, cuando es verdadero, actualiza tus credenciales
• config_path se establece de forma predeterminada en el directorio home de docker__login_become_user
• state se establece de forma predeterminada en "present"; cuando es "absent", se eliminará el inicio de sesión

Configurando las opciones del daemon de Docker (json)

Opciones predeterminadas del daemon de Docker como aparecerían en /etc/docker/daemon.json.

docker__default_daemon_json: |
  "log-driver": "journald",
  "features": {
    "buildkit": true
  }

# Agrega tus propias opciones adicionales del daemon sin sobrescribir las opciones predeterminadas.
# Sigue el mismo formato que las opciones predeterminadas, y no te preocupes por
# comenzarlo con una coma. La plantilla añadirá la coma si es necesario.
docker__daemon_json: ""

Configurando las opciones del daemon de Docker (flags)

Los flags que se establecen al iniciar el daemon de Docker no se pueden cambiar en el archivo daemon.json. Por defecto, Docker establece -H unix://, lo que significa que esta opción no se puede cambiar con las opciones json.

Agrega o cambia los flags de inicio del daemon de Docker suministrándolos exactamente como aparecerían en la línea de comandos.

# Cada flag de la línea de comandos debe ser su propio elemento en la lista.
#
# ¿Usas una versión de Docker anterior a 18.09?
#   Debes establecer `-H fd://` en lugar de `-H unix://`.
docker__daemon_flags:
  - "-H unix://"

Si no proporcionas algún tipo de flag -H aquí, Docker no podrá iniciar.

Configurando las variables de entorno del daemon de Docker

docker__daemon_environment: []

# Por ejemplo, aquí se muestra cómo establecer un par de variables de entorno para proxy.
docker__daemon_environment:
  - "HTTP_PROXY=http://proxy.ejemplo.com:80"
  - "HTTPS_PROXY=https://proxy.ejemplo.com:443"

Configurando directivas avanzadas de systemd

Este rol permite que el paquete Docker gestione su propio archivo de unidad systemd y ajusta cosas como los flags y las variables de entorno del daemon de Docker utilizando el patrón de anulación de systemd.

Si sabes lo que estás haciendo, puedes anular o agregar a cualquiera de las directivas de systemd de Docker configurando esta variable. Cualquier cosa que coloques en esta cadena se escribirá en /etc/systemd/system/docker.service.d/custom.conf tal como está.

docker__systemd_override: ""

Configurando trabajos cron relacionados con Docker

Por defecto, esto limpiará de manera segura el espacio en disco utilizado por Docker cada domingo a medianoche.

# `a` elimina imágenes no utilizadas (útil en producción).
# `f` fuerza que ocurra sin solicitar tu acuerdo.
docker__cron_jobs_prune_flags: "af"

# Controla el horario de la limpieza del sistema docker.
docker__cron_jobs_prune_schedule: ["0", "0", "*", "*", "0"]

docker__cron_jobs:
  - name: "Limpieza de disco de Docker"
    job: "docker system prune -{{ docker__cron_jobs_prune_flags }} > /dev/null 2>&1"
    schedule: "{{ docker__cron_jobs_prune_schedule }}"
    cron_file: "docker-disk-clean-up"
    #user: "{{ (docker__users | first) | d('root') }}"
    #state: "present"

Las propiedades precedidas por * son requeridas.

• *name es la descripción del trabajo cron
• *job es el comando a ejecutar en el trabajo cron
• *schedule es el formato estándar de trabajo cron para cada domingo a medianoche
• *cron_file escribe un archivo cron en /etc/cron.d en lugar del crontab individual de un usuario
• user se establece de forma predeterminada en el primer usuario docker__users o root si no está disponible
• state se establece de forma predeterminada en "present", cuando es "absent", el archivo cron será eliminado

Configurando el gestor de paquetes APT

Docker requiere que se instalen algunas dependencias para funcionar. No deberías tener que editar ninguna de estas variables.

# Lista de paquetes a instalar.
docker__package_dependencies:
  - "apt-transport-https"
  - "ca-certificates"
  - "cron"
  - "gnupg2"
  - "software-properties-common"

# Ansible identifica las arquitecturas de CPU de manera diferente a Docker.
docker__architecture_map:
  "x86_64": "amd64"
  "aarch64": "arm64"
  "aarch": "arm64"
  "armhf": "armhf"
  "armv7l": "armhf"

# La URL de la clave GPG de Docker.
docker__apt_repository_url: "https://download.docker.com/linux/{{ ansible_distribution | lower }}"

# El valor de la suma de verificación de la clave GPG de Docker.
docker__apt_key_checksum: "sha256:1500c1f56fa9e26b9b8f42452a553675796ade0807cdce11975eb98170b3a570"

# El repositorio APT upstream de Docker.
docker__apt_repository: >
  deb [arch={{ docker__architecture_map[ansible_architecture] }}
  signed-by=/etc/apt/keyrings/docker.asc]
  {{ docker__apt_repository_url }}
  {{ ansible_distribution_release }} {{ docker__channel | join(' ') }}

Instalando paquetes de Python con Virtualenv y PIP

Configurando Virtualenv

Más bien que contaminar la versión de Python de tu servidor, todos los paquetes PIP se instalan en un Virtualenv de tu elección.

docker__pip_virtualenv: "/usr/local/lib/docker/virtualenv"

Instalando PIP y sus dependencias

Este rol instala PIP porque Docker Compose v1 se instala con el paquete PIP docker-compose, y los módulos docker_* de Ansible utilizan el paquete PIP docker.

docker__pip_dependencies:
  - "gcc"
  - "python3-setuptools"
  - "python3-dev"
  - "python3-pip"
  - "virtualenv"

Instalando paquetes PIP

docker__default_pip_packages:
  - name: "docker"
    state: "{{ docker__pip_docker_state }}"
  - name: "docker-compose"
    version: "{{ docker__compose_version }}"
    path: "/usr/local/bin/docker-compose"
    src: "{{ docker__pip_virtualenv + '/bin/docker-compose' }}"
    state: "{{ docker__pip_docker_compose_state }}"

# Agrega tus propios paquetes PIP con las mismas propiedades que arriba.
docker__pip_packages: []

Las propiedades precedidas por * son requeridas.

• *name es el nombre del paquete
• version es la versión del paquete a instalar (o "" si esto no está definido)
• path es la ruta de destino del enlace simbólico
• src es la ruta de origen a la que se vinculará
• state se establece de forma predeterminada en "present", otros valores pueden ser "forcereinstall" o "absent"

Estado de los paquetes PIP

• Cuando se establece en "present", el paquete se instalará pero no se actualizará en futuras ejecuciones
• Cuando se establece en "forcereinstall", el paquete siempre se (re)instalará y actualizará en futuras ejecuciones
• Cuando se establece en "absent", el paquete se pasará por alto o se eliminará

docker__pip_docker_state: "present"
docker__pip_docker_compose_state: "absent"

Trabajando con los módulos docker_* de Ansible

Este rol utiliza docker_login para iniciar sesión en un registro de Docker, pero también puedes utilizar otros módulos docker_* en tus propios roles. No funcionarán a menos que indiques a Ansible que use el Virtualenv de este rol.

A nivel de inventario, playbook o tarea, necesitarás establecer ansible_python_interpreter: "/usr/local/bin/python3-docker". Esto funciona porque este rol crea un script proxy desde el binario de Python del Virtualenv hasta python3-docker.

Puedes mirar la tarea docker_login de este rol como un ejemplo de cómo hacerlo a nivel de tarea.

Licencia

MIT