Premiers pas avec chainctl

L’outil chainctl de Chainguard permet de gérer en ligne de commande les images de conteneur, les ressources d’identité et les configurations de sécurité de toute votre organisation. Ce guide présente les commandes essentielles pour bien démarrer avec chainctl dans vos workflows de sécurité et DevOps. Pour la documentation complète des commandes, consultez la référence de chainctl.

S’authentifier et vérifier l’état de l’authentification

Pour utiliser chainctl, vous devez d’abord vous authentifier auprès de la plateforme Chainguard. Pour cela, exécutez :

chainctl auth login

La commande affiche une liste de fournisseurs d’identité parmi lesquels choisir. Choisissez celui qui est associé à votre compte Chainguard. Une fois votre choix fait, par exemple Google, chainctl ouvre une fenêtre de navigateur pour que vous vous connectiez avec vos identifiants. Une fois la connexion réussie, vous pouvez enregistrer ce fournisseur d’identité comme fournisseur par défaut pour vos prochaines connexions. Un jeton est ensuite échangé et vous pouvez utiliser chainctl.

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.

Pour vérifier à tout moment l’état de votre authentification, exécutez :

chainctl auth status

La commande affiche votre identité et d’autres attributs associés à votre compte, notamment les rôles et les capacités attribués à votre compte.

Pour créer un jeton de pull, exécutez :

chainctl auth pull-token

Un flag important de cette commande est --repository, qui permet d’indiquer le type de dépôt pour lequel créer le jeton de pull. Par exemple, --repository=apk associe l’identité du jeton de pull au rôle apk.pull, ce qui lui permet de télécharger des paquets depuis le dépôt APK privé de l’organisation parente.

Pour configurer un credential helper Docker, qui utilise un jeton pour récupérer les images lorsque vous utilisez Docker, exécutez :

chainctl auth configure-docker

Remarque :

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.

Mettre à jour chainctl vers la dernière version

Pour savoir quelle version de chainctl est installée, exécutez :

chainctl version

Pour mettre à jour votre installation de chainctl, exécutez :

chainctl update

Comme cette commande remplace le binaire installé, vous devez disposer d’un accès en écriture au répertoire où se trouve chainctl. Sous Linux et macOS, la mise à jour d’une installation à l’échelle du système, par exemple dans /usr/local/bin, nécessite des privilèges d’administrateur (par exemple avec sudo). La commande vérifie aussi la signature du binaire téléchargé avant de l’installer ; pour en savoir plus, consultez Mettre à jour chainctl.

Configurer chainctl

chainctl est livré avec une configuration par défaut, mais certains de ses aspects sont modifiables. Vous pouvez par exemple définir l’emplacement du registre utilisé lorsqu’une commande n’en précise aucun. Pour modifier la configuration actuelle, exécutez :

chainctl config edit

Si vous faites une erreur et ne vous souvenez plus des paramètres d’origine, rétablissez la configuration par défaut avec :

chainctl config reset

Pour en savoir plus, consultez Gérer la configuration de chainctl.

Lister les images disponibles

Pour voir quelles images de conteneur sont disponibles pour votre compte, exécutez :

chainctl images list

Attention : la génération de cette liste peut prendre un certain temps, et la liste risque de défiler rapidement dans votre terminal.

Comparer deux versions d’une image

Supposons que vous vouliez comparer deux versions d’une image pour le même paquet. Vous devez connaître l’URL de votre dépôt, le nom de l’image et les deux versions à comparer. Comme versions, vous pouvez utiliser des numéros de version comme 8.12.0, ou bien latest ou latest-dev.

Exécutez la commande suivante. Elle utilise le dépôt de l’équipe Chainguard Developer Education, et les deux occurrences de <image_name> sont identiques :

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

Si l’image ou la version demandée n’est pas disponible dans le dépôt que vous utilisez, la commande renvoie une erreur Forbidden, comme lorsque vous essayez de récupérer une image à laquelle vous n’avez pas accès ou depuis un dépôt que votre compte n’est pas autorisé à utiliser.

Pour en savoir plus, consultez Comparer des images Chainguard Containers avec chainctl.

Lister les versions de paquets disponibles

Pour obtenir des informations sur les différentes versions de paquets disponibles pour les images, exécutez :

chainctl packages versions list $PACKAGENAME

La commande liste toutes les versions que Chainguard a construites, avec la date de fin de vie de chaque version qui en a une. Elle liste aussi les anciennes versions de paquets qui ne sont plus disponibles.

Formats de sortie

Les commandes ont parfois un format de sortie par défaut, mais rien ne vous oblige à le conserver. Une option permet d’indiquer à chainctl le format de sortie à utiliser, comme ceci :

chainctl $COMMAND -o $FORMAT

L’option -o est suivie de l’une des chaînes suivantes : csv, id, json, none, table, terse, tree ou wide.

Tous les formats de sortie ne conviennent pas à toutes les commandes : testez-les soigneusement avant d’utiliser un format précis dans une automatisation.