Artifact Hub: o guia completo do repositório central de pacotes Kubernetes

Quem trabalha com Kubernetes conhece o ritual: precisa de um ingress controller, um operador de banco, uma política de segurança ou um plugin do kubectl, e começa a busca no GitHub, em blogs e em READMEs. Cada projeto publica de um jeito, em um lugar diferente, com níveis variados de documentação e de cuidado com segurança.

O Artifact Hub centraliza essa descoberta. Ele indexa pacotes de centenas de repositórios e mostra, numa interface única, documentação, versões, licença, mantenedores, vulnerabilidades conhecidas e o comando de instalação. Este artigo explica o que ele é, como funciona por dentro, como consumir e publicar pacotes e quais cuidados de segurança e governança times de plataforma devem ter.

O que é o Artifact Hub

O Artifact Hub é uma aplicação web de código aberto, hospedada pela CNCF em artifacthub.io, para descobrir, instalar e publicar pacotes e configurações de projetos cloud native. Ele nasceu a partir do antigo Helm Hub, que foi incorporado a ele, e hoje é um projeto da CNCF (confira o nível de maturidade atual na página do projeto na CNCF, pois ele muda com o tempo).

O ponto mais importante: o Artifact Hub é um catálogo, não um registry. Ele não armazena seus charts nem suas imagens. Quem publica continua hospedando os artefatos onde já hospeda (um repositório Helm em GitHub Pages, um registry OCI, um repositório Git) e o Artifact Hub apenas indexa os metadados e os apresenta.

Na prática, isso traz três consequências:

• Você não depende dele para instalar: helm install continua apontando para o repositório de origem.
• Se um repositório sai do ar, o pacote some da fonte, mesmo que a página continue listada por um tempo.
• A confiança vem dos sinais que ele exibe (publisher verificado, status oficial, scan de segurança, assinatura), e não do simples fato de o pacote estar listado.

Tipos de artefatos suportados

Helm charts são a maior parte do catálogo, mas o Artifact Hub cobre muito mais do que isso. A lista abaixo mostra os tipos mais usados; ela cresce conforme projetos da CNCF adotam a plataforma, então vale conferir a documentação para o conjunto atual.

Para times de plataforma, essa diversidade é a vantagem real: um único lugar para procurar tanto o chart do cert-manager quanto a política Kyverno que impõe limites de recursos.

Arquitetura: como o catálogo é montado

O Artifact Hub é composto por poucos serviços em torno de um banco PostgreSQL: o hub (API e interface), o tracker, o scanner e o notifier.

[embedded content: arquitetura do Artifact Hub · 5 serviços e os repositórios de origem]

O tracker lê os repositórios de origem e grava os metadados no banco; o scanner analisa as imagens com o Trivy; o notifier envia alertas por e-mail e webhook. O hub serve a interface e a API a partir do banco, enquanto a instalação com helm install vai sempre direto à origem.

Como usar: buscar, avaliar e instalar

O fluxo de consumo tem três passos: buscar, avaliar o pacote e instalar a partir do repositório de origem.

1. Buscar. Use a busca em artifacthub.io e filtre por tipo (por exemplo, apenas Helm charts), por publisher verificado, por status oficial ou por licença.
2. Avaliar. Abra a página do pacote e olhe, nessa ordem: quem publica (selos de Verified publisher e Official), data da última versão, changelog, relatório de segurança, licença, links de documentação e o values.yaml com seu schema.
3. Instalar. O botão Install mostra os comandos exatos. Para um chart Helm, o formato é este (exemplo com o cert-manager):

helm repo add jetstack https://charts.jetstack.io
helm repo update
helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager --create-namespace \
  --set crds.enabled=true

Use sempre os comandos da página do pacote, porque flags como a que habilita os CRDs mudam entre versões. Para inspecionar antes de instalar, helm show values jetstack/cert-manager e helm template ajudam a revisar o que será aplicado.

O Artifact Hub também tem uma API REST pública, útil para automação. Um exemplo de busca por charts (confirme os parâmetros na documentação da API):

curl -s "https://artifacthub.io/api/v1/packages/search?ts_query_web=cert-manager&kind=0&limit=5"

Com uma conta gratuita você também pode seguir pacotes, receber notificações de novas versões e de alertas de segurança por e-mail ou webhook, e dar star nos pacotes que sua equipe usa.

Publicando seus pacotes

Publicar no Artifact Hub é registrar um repositório que você já mantém, não subir arquivos. O processo tem quatro etapas.

1. Hospede o chart em um repositório Helm (GitHub Pages com o chart-releaser, por exemplo) ou em um registry OCI.
2. Adicione o repositório no painel de controle do Artifact Hub (conta necessária), informando tipo, nome e URL.
3. Comprove a propriedade com o arquivo artifacthub-repo.yml, publicado na raiz do repositório (ou como tag especial em registries OCI), contendo o repositoryID gerado pela plataforma e o e-mail do dono. Isso concede o selo Verified publisher.
4. Enriqueça os metadados com annotations no Chart.yaml.

Exemplo de artifacthub-repo.yml:

repositoryID: 00000000-0000-0000-0000-000000000000
owners:
  - name: Time de Plataforma
    email: plataforma@exemplo.com.br

E de annotations no Chart.yaml, que melhoram a página do pacote:

annotations:
  artifacthub.io/license: Apache-2.0
  artifacthub.io/images: |
    - name: minha-app
      image: ghcr.io/minha-org/minha-app:1.4.2
  artifacthub.io/changes: |
    - kind: added
      description: Suporte a ServiceMonitor
    - kind: fixed
      description: Probe de readiness com timeout incorreto
  artifacthub.io/links: |
    - name: Documentação
      url: https://exemplo.com.br/docs

A annotation artifacthub.io/images é a mais importante para segurança: é por ela que o scanner sabe quais imagens analisar. Outras annotations úteis cobrem mantenedores, CRDs com exemplos, recomendações e marcação de versões prerelease ou com correções de segurança.

O selo Official é diferente: indica que o publicador é o dono do software empacotado, e é concedido pela equipe do Artifact Hub após solicitação.

No CI (GitHub Actions, por exemplo), rode o ah lint (CLI do projeto) sobre o chart antes de cada release para pegar annotations malformadas antes que o tracker as rejeite.

Segurança: o que o Artifact Hub verifica e o que não verifica

O Artifact Hub oferece sinais úteis de segurança, mas nenhum deles substitui a revisão do seu próprio time. Entender o limite de cada sinal evita falsa sensação de proteção.

Boas práticas para quem consome:

• Trate o security report como triagem, não como aprovação. Reescaneie as imagens no seu pipeline com o scanner que sua empresa adota.
• Fixe versões de chart e de imagem (de preferência por digest) e revise o helm template antes de atualizar.
• Prefira publishers verificados e oficiais, e desconfie de pacotes sem manutenção recente.
• Verifique assinaturas quando disponíveis e imponha isso por política (Kyverno ou Gatekeeper no cluster).
• Mantenha um mirror interno para charts críticos, para não depender da disponibilidade do repositório de origem.

Self-hosting e API

Como o projeto é de código aberto, você pode rodar sua própria instância do Artifact Hub, por exemplo para catalogar apenas charts internos e aprovados. O repositório oficial inclui um chart Helm para instalar a aplicação.

O que você precisa preparar:

• PostgreSQL como banco de dados principal, com as migrações aplicadas pelo próprio chart.
• Servidor SMTP, se quiser notificações por e-mail.
• Autenticação: contas locais ou provedores OAuth/OIDC, conforme a configuração.
• Repositórios privados: repositórios com autenticação podem ser registrados informando credenciais, o que torna a instância útil como portal interno.

A configuração fica em um arquivo de valores do chart; consulte o guia de instalação na documentação oficial, porque as opções mudam entre versões.

A API REST (pública em artifacthub.io e idêntica na instância própria) permite integrar o catálogo a outras ferramentas: buscar pacotes, obter detalhes de uma versão, ler o security report e listar repositórios. Alguns usos comuns em plataformas internas:

• Um bot que avisa no Slack quando um chart usado pela empresa publica versão com correção de segurança.
• Um job de CI que consulta a última versão estável de um chart e abre um pull request de atualização.
• Um portal de desenvolvedores (como o Backstage) que mostra o catálogo aprovado da empresa.

Limitações, alternativas e boas práticas

O Artifact Hub é excelente para descoberta, mas não resolve sozinho a governança de pacotes de uma empresa.

Limitações a ter em mente

• Qualidade desigual: qualquer pessoa pode registrar um repositório, e a listagem não implica revisão.
• Metadados dependem do publisher: sem annotations, a página fica pobre e o scan de segurança pode ficar incompleto.
• Há atraso entre a publicação de uma versão e sua aparição no catálogo, porque o tracker roda periodicamente.
• É um catálogo: disponibilidade e integridade dos artefatos continuam sendo responsabilidade do repositório de origem.

Alternativas e complementos

Boas práticas para times de plataforma

1. Use o Artifact Hub público para descobrir e avaliar, e um registry interno para consumir.
2. Defina critérios mínimos de aceite: publisher verificado, manutenção recente, licença compatível e scan sem vulnerabilidades críticas sem correção.
3. Faça o mirror dos charts aprovados e aponte o GitOps (Argo CD ou Flux) para o mirror.
4. Assine seus próprios charts e imagens e verifique as assinaturas no admission controller.
5. Se publica pacotes, mantenha changelog, annotations e ah lint no CI, tratando a página do Artifact Hub como a vitrine do seu produto.

Conclusão

O Artifact Hub é a porta de entrada mais prática para o ecossistema de pacotes do Kubernetes: reúne Helm charts, operadores, políticas e plugins num só lugar, com sinais de confiança e segurança visíveis. O cuidado essencial é lembrar que ele cataloga e não garante: a decisão de adotar um pacote continua sendo do seu time.

Como próximos passos, escolha um chart que sua equipe já usa e avalie a página dele pelos critérios deste artigo. Se você publica pacotes, registre seu repositório, adicione o artifacthub-repo.yml e as annotations, e rode o ah lint no CI. Para plataformas internas, considere uma instância própria combinada a um registry privado como fonte de verdade.