Erste Schritte mit chainctl

Mit chainctl von Chainguard verwalten Sie Container-Images, Identitätsressourcen und Sicherheitskonfigurationen in Ihrer gesamten Organisation über die Befehlszeile. Dieser Leitfaden stellt die wichtigsten Befehle vor, mit denen Sie chainctl effektiv in Ihren Security- und DevOps-Workflows einsetzen. Die vollständige Befehlsdokumentation finden Sie in der chainctl-Referenz.

Authentifizieren und Authentifizierungsstatus prüfen

Bevor Sie chainctl verwenden können, müssen Sie sich zuerst bei der Chainguard-Plattform authentifizieren. Führen Sie dazu Folgendes aus:

chainctl auth login

Daraufhin erscheint eine Liste von Identitätsanbietern, aus der Sie einen auswählen. Verwenden Sie den Anbieter, der mit Ihrem Chainguard-Konto verknüpft ist. Sobald Sie einen ausgewählt haben, zum Beispiel Google, öffnet chainctl ein Browserfenster, in dem Sie sich mit Ihren Zugangsdaten anmelden. Nach erfolgreicher Anmeldung können Sie diesen Identitätsanbieter als Standard für künftige Anmeldungen speichern. Anschließend wird ein Token ausgetauscht, und Sie können chainctl verwenden.

Note: chainctl auth login supports several login flows, including device-code login for machines without a browser and assumable identities for CI. If the default browser flow doesn't work in your environment, see Authentication options.

Um Ihren Authentifizierungsstatus jederzeit zu prüfen, geben Sie Folgendes ein:

chainctl auth status

Dieser Befehl listet Ihre Identität und weitere mit Ihrem Konto verknüpfte Attribute auf, darunter die Ihrem Konto zugewiesenen Rollen und Capabilities.

Um ein Pull-Token zu erstellen, verwenden Sie:

chainctl auth pull-token

Ein wichtiges Flag für diesen Befehl ist --repository. Damit legen Sie den Repository-Typ fest, für den das Pull-Token erstellt wird. Mit --repository=apk binden Sie die Pull-Token-Identität beispielsweise an die Rolle apk.pull, sodass die Identität Pakete aus dem privaten APK-Repository der übergeordneten Organisation herunterladen kann.

Um einen Docker-Credential-Helper zu konfigurieren, der beim Arbeiten mit Docker ein Token zum Pullen von Images verwendet, nutzen Sie:

chainctl auth configure-docker

Hinweis:

Zscaler, a popular decrypting proxy, may not support encrypted HTTP/2 traffic by default. If you are having connection issues using chainctl behind Zscaler, follow these steps to enable support for HTTP/2.

1. Open a Support Ticket with Zscaler

   Before any UI configuration option appears you may need to contact Zscaler Support (TAC) and request that HTTP/2 support be provisioned/activated for your tenant. This is currently a backend setting only Support can toggle.

   You typically need to provide:

   • Your Company ID
   • Tenant details
   • Reason/use case for enabling HTTP/2 inspection

   This will allow HTTP/2 negotiation to be available in policies.

2. Enable HTTP/2 in SSL Inspection Policies

   Once Support has enabled HTTP/2 on your tenant:

   1. Log in to the Zscaler Admin Portal.
   2. Navigate to Policy → SSL Inspection (or Administration → Advanced Settings depending on UI version).
   3. Edit your relevant SSL Inspection Policy.
   4. Look for the option "Enable HTTP/2" and turn it ON for the required rules/policies.

   This setting ensures Zscaler will maintain HTTP/2 where possible rather than downgrading to HTTP/1.1. You may need to enable it on multiple rules if you use granular SSL policies (for example, by URL category).

3. Check Advanced settings for API/CLI traffic

   Zscaler has an advanced setting under Admin → Advanced that controls how non-browser (API or CLI) HTTP/2 traffic is handled. This setting is disabled by default, which means Zscaler will downgrade non-browser HTTP/2 traffic to HTTP/1.1. For chainctl usage, this must be set to Enabled.

See this Zscaler blog post for more details.

If the above approach is not available to you, you may need to reconfigure Zscaler to disable its "Block Undecryptable Traffic" setting. Another option is to configure direct (proxyless) access to HTTP/2 endpoints and use the no_proxy environment variable, depending on your IT policies. Please consult your proxy software's documentation for guidance on adjusting these settings in order to authenticate.

chainctl auf die neueste Version aktualisieren

Um zu sehen, welche chainctl-Version installiert ist, verwenden Sie:

chainctl version

Um Ihre chainctl-Installation zu aktualisieren, verwenden Sie:

chainctl update

Da dieser Befehl die installierte Binärdatei ersetzt, benötigen Sie Schreibzugriff auf das Verzeichnis, in dem chainctl liegt. Unter Linux und macOS erfordert die Aktualisierung einer systemweiten Installation, etwa in /usr/local/bin, Administratorrechte (zum Beispiel mit sudo). Der Befehl verifiziert außerdem vor der Installation die Signatur der heruntergeladenen Binärdatei im laufenden Prozess. Details finden Sie unter chainctl aktualisieren.

chainctl konfigurieren

chainctl wird mit einer Standardkonfiguration ausgeliefert, von der sich aber einige Aspekte anpassen lassen. Sie können zum Beispiel festlegen, welcher Registry-Standort verwendet wird, wenn ein Befehl keinen angibt. Um die aktuelle Konfiguration zu bearbeiten, verwenden Sie:

chainctl config edit

Wenn Ihnen ein Fehler unterläuft und Sie sich nicht mehr an die ursprünglichen Einstellungen erinnern, setzen Sie die Konfiguration mit folgendem Befehl auf die Standardwerte zurück:

chainctl config reset

Mehr dazu erfahren Sie unter chainctl-Konfiguration verwalten.

Verfügbare Images auflisten

Um zu sehen, welche Container-Images für Ihr Konto verfügbar sind, verwenden Sie:

chainctl images list

Seien Sie gewarnt: Das Erstellen der Liste kann eine Weile dauern, und sie läuft im Terminal vermutlich schnell durch.

Zwei Image-Versionen vergleichen

Angenommen, Sie möchten zwei Versionen eines Images für dasselbe Paket vergleichen. Dafür brauchen Sie die URL Ihres Repositorys, den Image-Namen und die beiden Versionen, die Sie vergleichen möchten. Als Versionen können Sie Release-Nummern wie 8.12.0 oder latest bzw. latest-dev verwenden.

Verwenden Sie den folgenden Befehl. Er zeigt das Repository unseres Chainguard-Developer-Education-Teams, und beide Vorkommen von <image_name> sind identisch:

chainctl images diff cgr.dev/chainguard.edu/$IMAGENAME:latest cgr.dev/chainguard.edu/$IMAGENAME:latest-dev

Ist ein angefordertes Image oder Release in dem von Ihnen verwendeten Repository nicht verfügbar, gibt der Befehl einen Forbidden-Fehler zurück – genau wie beim Versuch, ein Image zu pullen, auf das Sie keinen Zugriff haben, oder aus einem Repository zu pullen, für das Ihr Konto nicht berechtigt ist.

Mehr dazu erfahren Sie unter Chainguard Containers mit chainctl vergleichen.

Verfügbare Paketversionen auflisten

Um Details zu den verschiedenen Paketversionen abzurufen, die in Images verwendet werden können, verwenden Sie:

chainctl packages versions list $PACKAGENAME

Dieser Befehl listet alle Versionen auf, die Chainguard gebaut hat, sowie das End-of-Life-Datum jeder Version, der eines zugewiesen ist. Außerdem listet er ältere Paketversionen auf, die nicht mehr verfügbar sind.

Ausgabeformate

Befehle haben möglicherweise ein Standardformat für die Ausgabe, aber daran müssen Sie sich nicht halten. Mit einer Option teilen Sie chainctl mit, welches Ausgabeformat es verwenden soll:

chainctl $COMMAND -o $FORMAT

Auf -o folgt einer dieser Werte: csv, id, json, none, table, terse, tree oder wide.

Nicht jedes Ausgabeformat ist für jeden Befehl sinnvoll. Testen Sie daher gründlich, bevor Sie ein bestimmtes Format in der Automatisierung einsetzen.