Ich habe ein Docker-Image, das eine Reihe von Umgebungsvariablen empfängt, um seine Ausführung anzupassen.

Ein einfaches Beispiel wäre ein Webserver, der Dinge wie Client-Geheimnis für OAuth2, ein Geheimnis zum Signieren von Cookies usw. enthält.

Die gesamte App ist in einem Docker-Image enthalten, das Umgebungsvariablen (zur Laufzeit) empfängt.

Ich verteile dieses Docker-Image in einer privaten Registrierung und möchte dieses Image dokumentieren, damit Benutzer verstehen, wie sie das Image anpassen können.

Ist es möglich, als Teil des Docker-Images Anmerkungen zu versenden, die z. B. mithilfe des docker describe my_imageAusgabe-Markdowns an die Standardausgabe gesendet werden?

Ich könnte natürlich eine statische Seite im Web für die Dokumentation verwenden, aber der Benutzer müsste immer noch wissen, wo diese Dokumentation zu finden ist, und die gesamte Distribution wäre auf diese Weise komplexer (z. B. Änderungen der Dokumentation mit Image-Tag).

Irgendwelche Ideen?

Soweit ich weiß, gibt es hier keine Silberkugel. Alle unten aufgeführten Lösungen funktionieren, der Benutzer muss jedoch darüber informiert werden, wie die Dokumentation abgerufen werden kann. Es gibt keine Standardmethode .

Die Open-Container-Initiative hat eine Annotation für Bildspezifikationen erstellt, die dies nahe legt

• Ein Link zu weiteren Informationen über das Bild sollte in einem Etikett mit dem Namen bereitgestellt werden org.opencontainers.image.documentation.
• Eine Beschreibung der im Container enthaltenen Software sollte auf einem Etikett mit dem Namen angegeben werden org.opencontainers.image.description

Laut OCI ist eine der folgenden Varianten von Option 1 korrekt.

Option 1: Bereitstellen eines Links in einem Label (bevorzugt von OCI )

Angenommen, die Docker-Datei und die zugehörigen Assets werden in einem öffentlich zugänglichen Git-Repository (z. B. auf Github) versioniert, dann könnte dieses Git-Repository auch eine README.md-Datei enthalten. Wenn Sie eine Pipeline mit dem Repo verbunden haben, das das Docker-Image automatisch erstellt und in einer Registrierung veröffentlicht, können Sie den Docker-Build-Befehl so einrichten, dass eine Beschriftung mit einem Link zur Dokumentation wie folgt hinzugefügt wird

# Get the current commit id
commit=$(git rev-parse HEAD)

# Build docker image and attach a link to the Readme as a label
docker build -t myimagename:myversion \
--label "org.opencontainers.image.documentation=https://github.com/<user>/<repo>/blob/$commit/README.md"

Diese Lösung enthält Links zu einer bestimmten Commit-Dokumentation für das jeweilige Commit, die neben Ihrer Docker-Datei versioniert ist. Der Benutzer muss jedoch Zugang zum Internet haben, um die Dokumentation lesen zu können

Option 1b: Bereitstellung einer vollständigen Dokumentation auf einem Etikett (bevorzugt von OCI )

Eine Variante von Option 1, bei der die vollständige Dokumentation serialisiert und in das Etikett eingefügt wird (es gibt keine Längenbeschränkungen für Etiketten). Auf diese Weise wird die Dokumentation mit dem Bild selbst gebündelt

Wie Jorge Leitao in den Kommentaren hervorhob, gibt die Bildanmerkungsspezifikation von OCI den Namen eines Etiketts wie anorg.opencontainers.image.description

Option 2: Bündeln der Dokumentation im Bild

Wenn Sie es vorziehen, die Readme.md-Datei tatsächlich im Bild zu bündeln, um sie von einer externen Webseite unabhängig zu machen, beachten Sie Folgendes

Stellen Sie beim Erstellen sicher, dass Sie die Datei Readme.md in das Docker-Image kopieren. Erstellen Sie außerdem ein einfaches Shell-Skript describe, das Readme.md enthält

beschreiben

#!/usr/bin/env sh
cat /docs/Readme.md

Dockerfile-Ergänzungen

...
COPY Readme.md /docs/Readme.md
COPY describe /opt/bin/describe
RUN chmod +x /opt/bin/describe
ENV PATH="/opt/bin:${PATH}"
...

Ein Benutzer, der über ein Docker-Image verfügt, führt jetzt den folgenden Befehl aus, um den Markdown an stdout zu senden

docker run myimage:version describe

Diese Lösung bündelt die Dokumentation für diese bestimmte Version des Bildes im Bild und kann ohne externe Abhängigkeiten abgerufen werden