Docker Hosts remote mit Portainer verwalten

Ausgangslage

Ich nutzte Portainer um einen grafischen Überblick über mein Container-Dorf zu behalten.

Im Laufe der Zeit sind nicht nur Container, sondern auch Docker-Hosts (Debian 13 / trixie) hinzugekommen.

Beim dritten Host mit eigenem portainer-container stellte ich mir dann die Frage, ob es Alternativen gibt - ein Portainer für alle Hosts. Na sicher, man muß nur wissen wie.

Portainer und Environments

Meine Youtube Recherche brachte mich zum Video “How to manage multiple Hosts in Portainer? “ (siehe: https://youtu.be/kKDoPohpiNk?si=OJN0mzVWo1vdbM2V ) von Christian Lempa.

Man kann in Portainer diverse Environments einbinden und so mit einem Portainer mehrere Hosts managen.
Die Einbindung eines standalone Docker-Hosts über die Docker API erfolgt in folgenden Schritten:

• Zertifikate bereitstellen (Voraussetzung bei TLS Verschlüsselung)
• Docker API auf dem entfernten Server einrichten
• Environment im Portainer erstellen

verschlüsselte Kommunikation mit TLS

Bevor es an die Einrichtung geht, sollte man entscheiden, ob die Kommunikation zwischen Portainer und dem entfernten Docker-Host verschlüsselt oder unverschlüsselt erfolgen soll.
Meine Meinung: Alles verschlüsseln was geht.

Da ich eine eigene CA betreibe, war die Erstellung der erforderlichen Zertifikate in wenigen Minuten erledigt.

Für die Einbindung eines Dockers Hosts in Portainer benötigt man 2 Zertifikate.
Auf der (Server-) Seite des Docker-Hosts ist ein Zertifikat mit der Eigenschaft “serverAuth” notwendig.
Für den zugreifenden Client - der Portainer-Host - ist ein Zertifikat mit der Eigenschaft “clientAuth” erforderlich.

Für die API des Docker-Hosts habe ich also ein dediziertes Zertifikat mit der Eigenschaft “extendedKeyUsage = serverAuth” erstellt. Das Zertifikat muß auf den Docker-Host kopiert werden.

Für den Portainer-Host (=Client) habe ich ein dediziertes Zertifikat mit der Eigenschaft “extendedKeyUsage = clientAuth” erstellt. Das Zertifikat wird im Portainer bei der Einrichtung des Environments benötigt.

Docker API einrichten / Root-Mode

Um die Docker API auf einem rootful Docker-Host zu aktivieren, habe ich die Datei /etc/docker/daemon.json angepasst und die tcp und tls*-Einträge hinzugefügt. Das Ganze ist u.a. auf https://docs.docker.com/engine/security/protect-access/ gut dokumentiert.

{
  "hosts": [
    "unix:///var/run/docker.sock",
    "tcp://192.168.100.200:2376"
  ],
  "tls": true,
  "tlscacert": "/root/certs/my-ca.pem",
  "tlscert": "/root/certs/dckr-server-cert.pem",
  "tlskey": "/root/certs/dckr-server-key.pem",
  "tlsverify": true,
  "data-root": "/data/docker",
  "log-driver": "local",
  "log-opts": {
    "max-size": "15m",
    "max-file": "5"
  },
  "ipv6": true
}

Ein Restart von Docker mit

systemctl restart docker.service

sollte obligatorisch sein

Docker API einrichten / Rootless-Mode

Im rootless Docker wird der daemon im Kontext des Benutzers konfiguriert. Die Datei .config/docker/daemon.json im Home-Verzeichnis des Benutzers muß angepasst werden.</br> Das Ganze ist u.a. auf https://docs.docker.com/engine/security/protect-access/ gut dokumentiert.

{
  "hosts": ["unix:///run/user/1000/docker.sock", "tcp://0.0.0.0:2376"],
  "tls": true,
  "tlscacert": "/home/myuser/.config/cert/my-ca.pem",
  "tlscert": "/home/myuser/.config/cert/dckr-server-cert.pem",
  "tlskey": "/home/myuser/.config/cert/dckr-server-key.pem",
  "tlsverify": true,
  "default-runtime": "runc",
  "data-root": "/data/docker",
  "log-driver": "local",
  "log-opts": {
    "max-size": "15m",
    "max-file": "5"
  }
}

Ein Restart von Docker mit

systemctl --user restart docker.service 

sollte obligatorisch sein

Environment im Portainer einrichten

Nachdem eine laufende Docker-API auf dem Verbindungs-Kandidaten geschaffen ist, kann die Verbindung mit Portainer hergestellt werden.
Erreichbar ist das Portainer-Environment über das Home-Menü links (Administration -> Environment-related -> Environments).
Über “Add environment” gelangt man zu einem Environment Wizard, der der Verbindung zu diversen Umgebungen ermöglicht.
Ich möchte einen “Docker Standalone” verbinden und starte den Wizard.






Der Wizard bietet die Vebindungsmöglichkeiten “Edge Agent Standard”, Agent, API und Socket an.

Mein “Docker Standalone” soll bitte über die Docker API angebunden werden. Diese API funkt entweder unverschlüsselt auf tcp:2375 oder tls-verschlüsselt auf tcp:2376. Für einen ersten Test kann man sicherlich zunächt unverschlüsselt starten, für den Normalbetrieb geht an TLS Verschlüsselung - aus meiner Sicht - kein Weg vorbei.
Im Eingabefeld Name trägt man nun einen Namen ein - bei mir ist es der Servername des Docker-Hosts. Die Docker API URL habe ich als IP im Format tcp://:2376 eingetragen - für einen ersten Test ohne TLS dann entsprechend tcp://:2375.

Wenn man mit Verschlüsselung arbeiten möchte, benötigt man an dieser Stelle 3 Zertifikate aus dem ersten Schritt:

• das Zertifikat der CA
• das Zertifikat des Portainer-Hosts (=Client)
• den Zertifikats-Schlüssel des Portainer-Hosts (=Client)

Die Zertifikate können dann bequem via Browser ausgewählt und eingetragen werden. Ein beherzter Klick auf Connect links unten sollte dann das neue Environent im Portainer anzeigen.

Troubleshooting

Falls es nicht auf Anhieb funktioniert….

Lies das Log.

Wir wollen entfernte Docker-Hosts anbinden. Überprüfe das Routing zum Ziel. Sind Firewalls auf dem Weg sorge für geöffnete Ports.

Wenn die verschlüsselte Kommunikation nicht funktioniert, teste den unverschlüsselten Weg.
Überprüfe, ob deine Zertifikate an der richtigen Stelle gelandet sind und die passende extendedKeyUsage eingetragen ist

Quellen:

Link zu Docker Doku: https://docs.docker.com/engine/security/protect-access/

Youtube Video von Christian Lempa: https://youtu.be/kKDoPohpiNk?si=OJN0mzVWo1vdbM2V