nickjj.docker

Was ist ansible-docker?

Es ist eine Ansible Rolle, um:

• Docker zu installieren (Versionen, Kanäle und Versionierungs-Pinning werden unterstützt)
• Docker Compose v2 und / oder Docker Compose v1 zu installieren (Versionierungs-Pinning wird unterstützt)
• Das docker PIP-Paket zu installieren, damit die Ansible docker_* Module funktionieren
• Docker-Registry-Anmeldedaten zu verwalten
• 1 oder mehrere Benutzer zu konfigurieren, die Docker ohne Root-Zugriff ausführen können
• Die Optionen und Umgebungsvariablen des Docker-Daemons zu konfigurieren
• Einen Cron-Job zu konfigurieren, um Docker-Bereinigungsbefehle auszuführen

Warum sollten Sie diese Rolle verwenden?

Wenn Sie wie ich sind, lieben Sie wahrscheinlich Docker. Diese Rolle bietet alles, was Sie benötigen, um einen produktionsbereiten Docker-Host einzurichten.

Falls Sie nicht wissen, was Docker ist oder Experte darin werden möchten, schauen Sie sich Dive into Docker: The Complete Docker Course for Developers an.

Unterstützte Plattformen

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

Frühere Versionen funktionieren möglicherweise, werden jedoch nicht offiziell unterstützt.

Sie sehen die Dokumentation des Master-Branchs, die möglicherweise aktueller ist als die neueste Version. Wechseln Sie zur neuesten Version.

Schnellstart

Die Philosophie für all meine Rollen ist es, es einfach zu machen, aber dennoch eine Art der Anpassung für fast alles zu bieten.

Was ist standardmäßig konfiguriert?

Die neueste stabile Version von Docker CE und Docker Compose v2 wird installiert, die Docker-Datenträgerbereinigung erfolgt einmal pro Woche und die Docker-Container-Logs werden an journald gesendet.

Beispiel-Playbook

---

# docker.yml

- name: Beispiel
  hosts: "all"
  become: true

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

Verwendung: ansible-playbook docker.yml

Installation

$ ansible-galaxy install nickjj.docker

Standard Rollenvariablen

Docker installieren

Kanal

Möchten Sie den "stabilen" oder "Test"-Kanal verwenden? Sie können mehr als einen hinzufügen (die Reihenfolge ist wichtig).

docker__channel: ["stable"]

Version

• Wenn auf "" gesetzt, wird die aktuelle neueste Version von Docker installiert
• Wenn auf eine spezifische Version gesetzt, wird diese Version von Docker installiert und festgelegt

docker__version: ""

# Zum Beispiel auf 25.0 festlegen.
docker__version: "25.0"

# Zum Beispiel auf eine genauere Version von 25.0 festlegen.
docker__version: "25.0.5"

Festlegungen werden mit * am Ende der Paketversion gesetzt, sodass Sie kleinere und Sicherheits-Patches erhalten, es sei denn, Sie legen eine genaue Version fest.

Upgrade-Strategie

• Wenn auf "present" gesetzt, wird beim zukünftigen Ausführen dieser Rolle keine neueren Versionen installiert (wenn verfügbar)
• Wenn auf "latest" gesetzt, wird beim zukünftigen Ausführen dieser Rolle neuere Versionen installiert (wenn verfügbar)

docker__state: "present"

Downgrade-Strategie

Der einfachste Weg, um ein Downgrade durchzuführen, besteht darin, das Docker-Paket manuell zu deinstallieren und dann diese Rolle auszuführen, während Sie eine beliebige spezifische Docker-Version festlegen, die Sie möchten.

# Ein ad-hoc Ansible-Befehl zum Stoppen und Entfernen des Docker CE-Pakets auf allen Hosts.
ansible all -m systemd -a "name=docker-ce state=stopped" \
  -m apt -a "name=docker-ce autoremove=true purge=true state=absent" -b

Docker Compose v2 installieren

Docker Compose v2 wird über das offizielle docker-compose-plugin, das von Docker verwaltet wird, installiert.

Version

• Wenn auf "" gesetzt, wird die aktuelle neueste Version von Docker Compose v2 installiert
• Wenn auf eine spezifische Version gesetzt, wird diese Version von Docker Compose v2 installiert und festgelegt

docker__compose_v2_version: ""

# Zum Beispiel auf 2.29 festlegen.
docker__compose_v2_version: "2.29"

# Zum Beispiel auf eine genauere Version von 2.29.1 festlegen.
docker__compose_v2_version: "2.29.1"

Upgrade-Strategie

Es wird die Variable docker__state wiederverwendet, die im Abschnitt Docker oben erklärt wird, mit denselben Regeln.

Downgrade-Strategie

Wie bei Docker selbst ist der einfachste Weg, Docker Compose v2 zu deinstallieren, das manuelle Ausführen des folgenden Befehls und dann eine spezifische Version von Docker Compose v2 festzulegen.

# Ein ad-hoc Ansible-Befehl zum Entfernen des Docker Compose Plugin-Pakets auf allen Hosts.
ansible all -m apt -a "name=docker-compose-plugin autoremove=true purge=true state=absent" -b

Docker Compose v1 installieren

Standardmäßig installiert diese Rolle Docker Compose v1 nicht, da es offiziell veraltet ist und von Docker keine weiteren Updates erhält. Diese Rolle kann es jedoch installieren. Alles, was Sie tun müssen, ist, docker__pip_docker_compose_state: "present" festzulegen, da diese Rolle standardmäßig auf absent für diesen Wert eingestellt ist.

Technisch können beide Versionen gleichzeitig installiert werden, da v1 mit docker-compose und v2 mit docker compose (ohne Bindestrich) aufgerufen wird.

Ich empfehle, v1 nicht zu installieren, es sei denn, Sie benötigen es wirklich aus Gründen der Abwärtskompatibilität. Wenn Sie sich entscheiden, es zu installieren, können Sie unten festlegen, welche Version installiert wird. Wenn es nicht zum Installieren festgelegt ist, bleiben diese Versionen ungenutzt:

Version

• Wenn auf "" gesetzt, wird die aktuelle neueste Version von Docker Compose v1 installiert
• Wenn auf eine spezifische Version gesetzt, wird diese Version von Docker Compose v1 installiert und festgelegt

docker__compose_version: ""

# Zum Beispiel auf 1.29 festlegen.
docker__compose_version: "1.29"

# Zum Beispiel auf eine genauere Version von 1.29 festlegen.
docker__compose_version: "1.29.2"

Upgrade- und Downgrade-Strategien werden im anderen Abschnitt dieses Dokuments erklärt.

Benutzer konfigurieren, die Docker ohne Root ausführen

Eine Liste von Benutzern, die zur docker Gruppe hinzugefügt werden sollen.

Bitte beachten Sie, dass dieser Benutzer bereits existieren muss, diese Rolle wird ihn nicht erstellen. Wenn Sie Benutzer erstellen möchten, schauen Sie sich meine Benutzerrolle an.

Diese Rolle konfiguriert standardmäßig keine Benutzernamenräume oder Sicherheitsfunktionen. Wenn der Benutzer, den Sie hier hinzufügen, SSH-Zugriff auf Ihren Server hat, gewähren Sie ihm effektiv Root-Zugriff auf den Server, da er Docker ohne sudo ausführen und in jedem Verzeichnis Ihres Dateisystems Volumes einhängen kann.

In einer kontrollierten Umgebung ist dies sicher, aber wie immer in Bezug auf Sicherheit ist es wichtig, dies im Voraus zu wissen. Sie können Benutzernamenräume und andere Optionen mit der Variable docker__daemon_json aktivieren, die später erklärt wird.

# Versuchen, den Sudo-Benutzer standardmäßig zu verwenden, andernfalls auf root zurückgreifen.
docker__users: ["{{ ansible_env.SUDO_USER | d('root') }}"]

# Zum Beispiel, wenn der zu setzende Benutzer anders als der Sudo-Benutzer ist.
docker__users: ["admin"]

Konfigurieren der Docker-Registry-Anmeldungen

Anmeldung bei 1 oder mehreren Docker-Registrierungen (z. B. dem Docker Hub).

# Ihre Anmeldedaten landen im Home-Verzeichnis dieses Benutzers.
docker__login_become_user: "{{ docker__users | first | d('root') }}"

# 0 oder mehr Registrierungen, bei denen Sie sich einloggen möchten.
docker__registries:
  - #registry_url: "https://index.docker.io/v1/"
    username: "Ihr_Docker_Hub_Benutzername"
    password: "Ihr_Docker_Hub_Passwort"
    #email: "[email protected]"
    #reauthorize: false
    #config_path: "$HOME/.docker/config.json"
    #state: "present"
docker__registries: []

Eigenschaften, die mit * beginnen, sind erforderlich.

• registry_url hat den Standardwert https://index.docker.io/v1/
• *username ist Ihr Docker-Registrierungs-Benutzername
• *password ist Ihr Docker-Registrierungs-Passwort
• email wird standardmäßig nicht verwendet (nicht alle Registrierungen verwenden es)
• reauthorize ist standardmäßig false, wenn true, wird Ihre Anmeldeinformation aktualisiert
• config_path hat den Standardwert des $HOME-Verzeichnisses Ihres docker__login_become_user
• state hat den Standardwert "present", wenn "absent" wird die Anmeldung entfernt

Konfigurieren der Docker-Daemon-Optionen (json)

Standardoptionen für den Docker-Daemon, wie sie in /etc/docker/daemon.json erscheinen würden.

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

# Fügen Sie Ihre eigenen zusätzlichen Daemon-Optionen hinzu, ohne die Standardoptionen zu überschreiben.
# Es folgt dem gleichen Format wie die Standardoptionen, und keine Sorge,
# dass Sie es nicht mit einem Komma beginnen. Die Vorlage fügt das Komma hinzu, falls erforderlich.
docker__daemon_json: ""

Konfigurieren der Docker-Daemon-Optionen (Flags)

Flags, die beim Starten des Docker-Daemons festgelegt werden, können nicht in der daemon.json-Datei geändert werden. Standardmäßig setzt Docker -H unix://, was bedeutet, dass diese Option nicht mit den JSON-Optionen geändert werden kann.

Fügen Sie die Startflags des Docker-Daemons hinzu oder ändern Sie sie, indem Sie sie genau so angeben, wie sie in der Befehlszeile erscheinen würden.

# Jeder Befehlzeilen-Flag sollte ein eigenes Element in der Liste sein.
#
# Verwenden Sie eine Docker-Version vor 18.09?
#   Sie müssen `-H fd://` anstelle von `-H unix://` setzen.
docker__daemon_flags:
  - "-H unix://"

Wenn Sie hier keinen Typ von -H-Flag angeben, wird Docker nicht starten.

Konfigurieren der Docker-Daemon-Umgebungsvariablen

docker__daemon_environment: []

# Zum Beispiel, so setzen Sie einige Proxy-Umgebungsvariablen.
docker__daemon_environment:
  - "HTTP_PROXY=http://proxy.example.com:80"
  - "HTTPS_PROXY=https://proxy.example.com:443"

Konfigurieren von erweiterten systemd-Direktiven

Diese Rolle lässt das Docker-Paket seine eigene systemd-Einheitendatei verwalten und passt Dinge wie die Flags und Umgebungsvariablen des Docker-Daemons durch Verwendung des systemd-Überschreibungsverfahrens an.

Wenn Sie wissen, was Sie tun, können Sie eine beliebige der systemd-Direktiven von Docker überschreiben oder hinzufügen, indem Sie diese Variable festlegen. Alles, was Sie in diese Zeichenfolge einfügen, wird so geschrieben, wie es ist, in /etc/systemd/system/docker.service.d/custom.conf.

docker__systemd_override: ""

Konfigurieren von Docker-bezogenen Cron-Jobs

Standardmäßig wird dieser Job jeden Sonntag um Mitternacht sicher den Speicherplatz bereinigen, der von Docker verwendet wird.

# `a` entfernt ungenutzte Bilder (nützlich in der Produktion).
# `f` zwingt dazu, dass es ohne Aufforderung zur Bestätigung geschieht.
docker__cron_jobs_prune_flags: "af"

# Steuern Sie den Zeitplan für die Docker-Systembereinigung.
docker__cron_jobs_prune_schedule: ["0", "0", "*", "*", "0"]

docker__cron_jobs:
  - name: "Docker-Datenträgerbereinigung"
    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"

Eigenschaften, die mit * beginnen, sind erforderlich.

• *name ist die Beschreibung des Cron-Jobs
• *job ist der Befehl, der im Cron-Job ausgeführt wird
• *schedule ist das Standardformat für Cron-Jobs für jeden Sonntag um Mitternacht
• *cron_file schreibt eine Cron-Datei nach /etc/cron.d anstelle des individuellen Crontabs eines Benutzers
• user hat den Standardwert den ersten docker__users Benutzer oder root, wenn das nicht vorhanden ist
• state hat den Standardwert "present", wenn "absent", wird die Cron-Datei entfernt

Konfigurieren des APT-Paketmanagers

Docker benötigt einige Abhängigkeiten, um zu funktionieren. Sie sollten keine dieser Variablen bearbeiten müssen.

# Liste der Pakete, die installiert werden sollen.
docker__package_dependencies:
  - "apt-transport-https"
  - "ca-certificates"
  - "cron"
  - "gnupg2"
  - "software-properties-common"

# Ansible identifiziert CPU-Architekturen anders als Docker.
docker__architecture_map:
  "x86_64": "amd64"
  "aarch64": "arm64"
  "aarch": "arm64"
  "armhf": "armhf"
  "armv7l": "armhf"

# Die Docker GPG-Schlüssel-URL.
docker__apt_repository_url: "https://download.docker.com/linux/{{ ansible_distribution | lower }}"

# Der GPG-Schlüssel-Checksum-Wert für Docker.
docker__apt_key_checksum: "sha256:1500c1f56fa9e26b9b8f42452a553675796ade0807cdce11975eb98170b3a570"

# Das upstream APT-Repository von 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(' ') }}

Installieren von Python-Paketen mit Virtualenv und PIP

Virtualenv konfigurieren

Statt die Python-Version Ihres Servers zu belasten, werden alle PIP-Pakete in einem Virtualenv Ihrer Wahl installiert.

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

PIP und seine Abhängigkeiten installieren

Diese Rolle installiert PIP, weil Docker Compose v1 mit dem PIP-Paket docker-compose installiert wird und die Ansible docker_* Module das PIP-Paket docker verwenden.

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

PIP-Pakete installieren

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 }}"

# Fügen Sie Ihre eigenen PIP-Pakete mit den gleichen Eigenschaften wie oben hinzu.
docker__pip_packages: []

Eigenschaften, die mit * beginnen, sind erforderlich.

• *name ist der Paketname
• version ist die zu installierende Paketversion (oder "" wenn dies nicht definiert ist)
• path ist der Zielpfad des Symlinks
• src ist der Quellpfad, der verlinkt werden soll
• state hat den Standardwert "present", andere Werte können "forcereinstall" oder "absent" sein

PIP-Paketstatus

• Wenn auf "present" gesetzt, wird das Paket installiert, aber nicht bei zukünftigen Ausführungen aktualisiert
• Wenn auf "forcereinstall" gesetzt, wird das Paket immer (neu)installiert und bei zukünftigen Ausführungen aktualisiert
• Wenn auf "absent" gesetzt, wird das Paket übersprungen oder entfernt

docker__pip_docker_state: "present"
docker__pip_docker_compose_state: "absent"

Arbeiten mit Ansible's docker_* Modulen

Diese Rolle nutzt docker_login, um sich bei einer Docker-Registry anzumelden, aber Sie können auch die anderen docker_* Module in Ihren eigenen Rollen verwenden. Sie werden nicht funktionieren, es sei denn, Sie geben Ansible an, das Virtualenv dieser Rolle zu verwenden.

Auf entweder der Inventar-, Playbook- oder Task-Ebene müssen Sie ansible_python_interpreter: "/usr/local/bin/python3-docker" setzen. Dies funktioniert, weil diese Rolle ein Proxy-Skript vom Python-Binary des Virtualenvs zu python3-docker erstellt.

Sie können sich die docker_login-Aufgabe dieser Rolle ansehen, um ein Beispiel zu erhalten, wie es auf Task-Ebene funktioniert.

Lizenz

MIT