Primeros pasos con chainctl

chainctl de Chainguard ofrece acceso desde la línea de comandos para gestionar imágenes de contenedor, recursos de identidad y configuraciones de seguridad en toda su organización. Esta guía presenta los comandos esenciales para empezar a usar chainctl de forma eficaz en sus flujos de trabajo de seguridad y DevOps. Para ver la documentación completa de los comandos, consulte la referencia de chainctl.

Autenticarse y comprobar el estado de la autenticación

Para usar chainctl, lo primero que debe hacer es autenticarse en la plataforma de Chainguard. Para ello, ejecute:

chainctl auth login

Se muestra una lista de proveedores de identidad para que elija uno. Use el que esté vinculado a su cuenta de Chainguard. Cuando seleccione el que quiere usar, por ejemplo Google, chainctl abre una ventana del navegador para que inicie sesión con sus credenciales. Si el inicio de sesión se realiza correctamente, tiene la opción de guardar ese proveedor de identidad como predeterminado para los próximos inicios de sesión. Después se intercambia un token y ya puede usar 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.

Para comprobar el estado de su autenticación en cualquier momento, ejecute:

chainctl auth status

Este comando muestra su identidad y otros atributos vinculados a su cuenta, incluidos los roles y las capacidades asignados a ella.

Para crear un token de pull, use:

chainctl auth pull-token

Un flag importante que puede pasar a este comando es --repository, que permite especificar el tipo de repositorio para el que se crea el token de pull. Por ejemplo, si especifica --repository=apk, la identidad del token de pull se vincula al rol apk.pull, lo que le permite descargar paquetes del repositorio APK privado de la organización principal.

Para configurar un asistente de credenciales de Docker, que usa un token para descargar imágenes cuando usa Docker, use:

chainctl auth configure-docker

Nota:

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.

Actualizar chainctl a la versión más reciente

Para ver qué versión de chainctl tiene instalada, use:

chainctl version

Para actualizar su instalación de chainctl, use:

chainctl update

Como este comando reemplaza el binario instalado, necesita permiso de escritura en el directorio donde se encuentra chainctl. En Linux y macOS, actualizar una instalación para todo el sistema, como /usr/local/bin, requiere privilegios de administrador (por ejemplo, con sudo). El comando también verifica la firma del binario descargado dentro del propio proceso antes de instalarlo; consulte Actualizar chainctl para obtener más detalles.

Configurar chainctl

chainctl incluye una configuración predeterminada, pero algunos de sus aspectos se pueden ajustar. Por ejemplo, puede definir la ubicación del registro que se usa cuando un comando no indica ninguna. Para editar la configuración actual, use:

chainctl config edit

Si comete un error y no recuerda la configuración original, restablezca la configuración predeterminada con:

chainctl config reset

Obtenga más información en Cómo gestionar la configuración de chainctl.

Listar las imágenes disponibles

Para ver qué imágenes de contenedor están disponibles para su cuenta, use:

chainctl images list

Tenga en cuenta que generar esa lista puede tardar un poco y que es probable que se desplace rápidamente en su terminal de línea de comandos.

Comparar dos versiones de una imagen

Supongamos que quiere comparar dos versiones de una imagen del mismo paquete. Necesita conocer la URL de su repositorio, el nombre de la imagen y las dos versiones que quiere comparar. Como versiones, puede usar números de versión como 8.12.0, o bien latest o latest-dev.

Use el siguiente comando, donde mostramos el repositorio que usa nuestro equipo de Chainguard Developer Education y donde ambas instancias de <image_name> son iguales:

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

Si la imagen o la versión solicitada no está disponible en el repositorio que usa, el comando devuelve un error Forbidden, igual que si intentara descargar una imagen a la que no tiene acceso o desde un repositorio que su cuenta no está autorizada a usar.

Obtenga más información en Cómo comparar Chainguard Containers con chainctl.

Listar las versiones de paquetes disponibles

Si quiere obtener detalles sobre las distintas versiones de paquetes disponibles que se pueden usar en las imágenes, use:

chainctl packages versions list $PACKAGENAME

Este comando muestra todas las versiones que Chainguard ha compilado y la fecha de fin de vida de cada versión que tenga una asignada. También muestra las versiones de paquetes más antiguas que ya no están disponibles.

Formatos de salida

Los comandos pueden tener un formato de salida predeterminado, pero eso no significa que tenga que mantenerlo. Existe una opción para indicarle a chainctl qué formato de salida usar, de la siguiente manera:

chainctl $COMMAND -o $FORMAT

Después de -o se indica una de las siguientes cadenas: csv, id, json, none, table, terse, tree o wide.

No todos los formatos de salida tienen sentido para todos los comandos, así que pruébelos bien antes de usar un formato específico en la automatización.