Primeiros passos com o chainctl

O chainctl da Chainguard oferece acesso pela linha de comando para gerenciar imagens de contêiner, recursos de identidade e configurações de segurança em toda a sua organização. Este guia apresenta os comandos essenciais para começar a usar o chainctl nos seus fluxos de trabalho de segurança e DevOps. Para a documentação completa dos comandos, consulte a referência do chainctl.

Autenticar e verificar o status da autenticação

Para usar o chainctl, a primeira coisa a fazer é se autenticar na plataforma da Chainguard. Para isso, execute:

chainctl auth login

Será exibida uma lista de provedores de identidade para você escolher. Use o que está vinculado à sua conta da Chainguard. Depois que você escolher o provedor, como o Google, o chainctl abrirá uma janela do navegador para você fazer login com suas credenciais. Após o login, você poderá salvar esse provedor de identidade como padrão para os próximos logins. Em seguida, um token será trocado e você poderá usar o 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 verificar o status da autenticação a qualquer momento, execute:

chainctl auth status

Esse comando mostra sua identidade e outros atributos vinculados à sua conta, incluindo os papéis e as capacidades atribuídos a ela.

Para criar um token de pull, use:

chainctl auth pull-token

Uma flag importante desse comando é --repository, que permite especificar o tipo de repositório para o qual o token de pull será criado. Por exemplo, --repository=apk vincula a identidade do token de pull ao papel apk.pull, o que permite que a identidade baixe pacotes do repositório APK privado da organização pai.

Para configurar um auxiliar de credenciais do Docker, que usará um token para baixar imagens quando você usar o Docker, execute:

chainctl auth configure-docker

Observação:

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.

Atualizar o chainctl para a versão mais recente

Para ver qual versão do chainctl está instalada, use:

chainctl version

Para atualizar sua instalação do chainctl, use:

chainctl update

Como esse comando substitui o binário instalado, você precisa de permissão de gravação no diretório em que o chainctl está. No Linux e no macOS, atualizar uma instalação para todo o sistema, como em /usr/local/bin, exige privilégios de administrador (por exemplo, com sudo). O comando também verifica a assinatura do binário baixado antes de instalá-lo. Para mais detalhes, consulte Atualizar o chainctl.

Configurar o chainctl

O chainctl vem com uma configuração padrão, mas alguns aspectos dela podem ser ajustados. Um exemplo é definir o local do registro usado quando um comando não especifica um. Para editar a configuração atual, use:

chainctl config edit

Se você cometer um erro e não lembrar das configurações originais, restaure a configuração padrão com:

chainctl config reset

Saiba mais em Como gerenciar a configuração do chainctl.

Listar as imagens disponíveis

Para ver quais Chainguard Containers estão disponíveis para sua conta, use:

chainctl images list

Atenção: essa lista pode demorar para ser gerada e provavelmente vai rolar rapidamente no seu terminal.

Comparar duas versões de uma imagem

Digamos que você queira comparar duas versões de uma imagem do mesmo pacote. Você precisa saber a URL do seu repositório, o nome da imagem e as duas versões que quer comparar. Para as versões, você pode usar números de release, como 8.12.0, ou latest e latest-dev.

Use o comando a seguir, que mostra o repositório usado pela equipe de Developer Education da Chainguard. As duas ocorrências de <image_name> são iguais:

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

Se a imagem ou a release solicitada não estiver disponível no repositório que você está usando, o comando retornará um erro Forbidden, da mesma forma que ao tentar baixar uma imagem a que você não tem acesso ou de um repositório que sua conta não tem autorização para usar.

Saiba mais em Como comparar Chainguard Containers com o chainctl.

Listar as versões de pacotes disponíveis

Para ver detalhes sobre as versões de pacotes disponíveis para uso em imagens, use:

chainctl packages versions list $PACKAGENAME

Esse comando lista todas as versões que a Chainguard compilou e a data de fim de vida útil de cada versão que tiver uma. Ele também lista versões mais antigas de pacotes que não estão mais disponíveis.

Formatos de saída

Os comandos podem ter um formato de saída padrão, mas você não precisa se limitar a ele. Há uma opção para informar ao chainctl qual formato de saída usar:

chainctl $COMMAND -o $FORMAT

O -o deve ser seguido por uma destas strings: csv, id, json, none, table, terse, tree ou wide.

Nem todos os formatos de saída fazem sentido para todos os comandos, então teste bem antes de usar um formato específico em automações.