Harbor — Conceitos, Componentes e Casos de Uso
O que é o Harbor?
Harbor é um registry de imagens de containers open source, desenvolvido pela VMware e doado à CNCF (Cloud Native Computing Foundation) em 2018, onde alcançou o status de projeto graduated em 2020.
Vai além de um simples registry compatível com a especificação OCI — o Harbor adiciona uma camada de governança, segurança e gestão empresarial em cima do armazenamento de imagens. É a escolha natural para organizações que precisam de controlo sobre os artefactos que correm nos seus clusters Kubernetes.
Por que utilizar o Harbor?
Um registry público como o Docker Hub tem limitações importantes em contextos empresariais: rate limits, ausência de controlo de acesso granular, sem scanning de vulnerabilidades integrado e dependência de infraestrutura externa. O Harbor resolve todos estes problemas.
Principais razões de adoção
Controlo total sobre os artefactos As imagens ficam na tua infraestrutura. Não há dependência de serviços externos, sem rate limits, sem risco de imagens serem removidas ou alteradas por terceiros.
Segurança integrada Scanning automático de vulnerabilidades com o Trivy antes de qualquer imagem ser usada em produção. É possível bloquear o deploy de imagens com vulnerabilidades acima de um determinado nível de severidade (política de CVE).
Controlo de acesso granular Integração nativa com LDAP/Active Directory e suporte a OIDC. Permissões definidas por projeto, com roles distintos para cada equipa ou squad.
Proxy cache de registries externos O Harbor pode funcionar como proxy cache para Docker Hub, GCR, ECR, GHCR e outros — os pulls passam pelo Harbor, que guarda uma cópia local. Reduz latência, elimina rate limits e mantém disponibilidade mesmo sem acesso à internet.
Replicação entre registries Suporta replicação de imagens entre instâncias Harbor ou para/de outros registries compatíveis com OCI. Útil para estratégias multi-região ou promoção de imagens entre ambientes (dev → staging → prod).
Gestão de artefactos OCI Além de imagens Docker, suporta Helm charts, OPA policies, CNAB bundles e qualquer artefacto compatível com a especificação OCI.
Imutabilidade de tags
Permite configurar tags imutáveis por projeto — impede que uma tag existente (como latest ou v1.0.0) seja sobrescrita acidentalmente.
Audit log completo Registo de todas as operações: quem fez push, quem fez pull, quando e de onde.
Arquitetura e Componentes
O Harbor é composto por vários serviços independentes que correm como containers. Em instalações Kubernetes via Helm, cada componente é um Deployment ou StatefulSet separado.
Core
O componente central do Harbor. É a API principal que coordena todos os outros serviços. Expõe a API REST v2.0 consumida pela UI, pelo CLI (docker login/push/pull) e por ferramentas externas. Responsável por autenticação, autorização, gestão de projetos, utilizadores, webhooks e quotas.
harbor-core → porta 80 (ClusterIP interno)
Portal
O frontend web do Harbor — a interface gráfica acessível pelo browser. É uma aplicação Angular que comunica exclusivamente com o Core via API. Stateless, escala facilmente.
harbor-portal → porta 80 (ClusterIP interno)
Registry
O motor de armazenamento de imagens, baseado no projeto distribution. É aqui que os blobs e manifests das imagens são efetivamente guardados. Comunica com o backend de storage configurado (filesystem local, S3, Azure Blob, GCS, etc.).
harbor-registry → porta 5000 (pull/push) + 8080 (registryctl)
⚠️ Para escalar o registry para múltiplas réplicas, o backend de storage tem de ser partilhado (S3/MinIO ou PVC com accessMode ReadWriteMany). Com filesystem local e RWO, apenas uma réplica é possível.
Jobservice
Responsável pela execução de tarefas assíncronas em background: replicação de imagens, scanning de vulnerabilidades, garbage collection e outros jobs agendados. Comunica com o Core e usa Redis como queue de trabalho.
harbor-jobservice → porta 80 (ClusterIP interno)
Nginx (Proxy)
Proxy reverso que recebe todo o tráfego externo (HTTP/HTTPS) e encaminha para o Portal ou para o Core/Registry conforme o path. É o único componente exposto externamente — todos os outros são ClusterIP internos.
harbor-nginx → portas 80/443 (NodePort ou LoadBalancer)
Redis
Cache e sistema de filas utilizado pelo Core e pelo Jobservice. Guarda sessões de utilizador, cache de dados frequentes e a fila de jobs do Jobservice. Em instalações padrão corre como StatefulSet interno.
harbor-redis → porta 6379 (ClusterIP interno)
PostgreSQL (Database)
Base de dados relacional que persiste todo o estado do Harbor: utilizadores, projetos, permissões, repositórios, tags, resultados de scanning, logs de auditoria, configurações de replicação, etc.
É o componente mais crítico para disponibilidade — se a base de dados ficar indisponível, o Harbor fica completamente inoperacional.
PostgreSQL → porta 5432
Pode ser interno (StatefulSet gerido pelo Helm) ou externo (instância existente). Para produção, recomenda-se sempre uma instância externa em HA.
Trivy
Scanner de vulnerabilidades integrado. Analisa as imagens presentes no registry e identifica CVEs conhecidas nas dependências e pacotes do sistema operativo. Os resultados ficam visíveis na UI e podem ser usados para bloquear imagens vulneráveis via políticas de projeto.
harbor-trivy → porta 8080 (ClusterIP interno)
Modos de Autenticação
| Modo | Descrição |
|---|---|
| Database | Utilizadores criados e geridos localmente no Harbor |
| LDAP / Active Directory | Autenticação delegada ao LDAP/AD da organização |
| OIDC | Integração com providers como Keycloak, Dex, Azure AD |
| HTTP Basic | Para robots/service accounts via credenciais simples |
Em ambientes empresariais, o modo LDAP é o mais comum — os utilizadores autenticam com as credenciais corporativas e são importados automaticamente no primeiro login.
Tipos de Utilizadores
| Tipo | Origem | Identificação na DB |
|---|---|---|
| Local | Criado diretamente no Harbor | Campo password preenchido |
| LDAP | Importado do LDAP/AD | Campo password vazio |
| Robot Account | Service account para CI/CD | Prefixo robot$ no username |
Roles por Projeto
O Harbor usa um modelo de controlo de acesso baseado em roles (RBAC) ao nível do projeto:
| Role | Permissões |
|---|---|
| Project Admin | Gestão completa do projeto, membros, webhooks, políticas |
| Maintainer | Push, pull, delete de imagens e Helm charts |
| Developer | Push e pull de imagens |
| Guest | Pull apenas (read-only) |
| Limited Guest | Pull apenas de repositórios públicos |
Tipos de Projetos
Privado — apenas membros com acesso explícito conseguem fazer pull das imagens.
Público — qualquer utilizador autenticado (ou anónimo, se configurado) consegue fazer pull. Útil para imagens base partilhadas entre equipas.
Fluxo típico de uma pipeline CI/CD com Harbor
1. Developer faz push de código para o GitLab
2. GitLab CI executa o build da imagem (Kaniko ou Docker)
3. Pipeline faz push da imagem para o Harbor
harbor.empresa.com/projeto/app:branch-sha
4. Trivy faz scan automático da imagem
5. Se vulnerabilidades críticas → pipeline falha (política de CVE)
6. ArgoCD (ou outro tool GitOps) detecta nova imagem
7. Deploy no cluster Kubernetes
Funcionalidades Avançadas
Garbage Collection Remove blobs órfãos do storage (layers de imagens sem manifests associados). Deve ser agendado regularmente para evitar crescimento indefinido do storage.
Imutabilidade de Tags
Regras configuráveis por projeto que impedem a sobrescrita de tags específicas. Exemplo: bloquear qualquer push para tags que correspondam ao padrão v*.*.*.
Retenção de Imagens Políticas automáticas de limpeza: manter apenas as últimas N tags, remover imagens sem pulls há mais de X dias, etc.
Webhooks Notificações para sistemas externos (Slack, CI/CD, ferramentas de ITSM) quando ocorrem eventos: push de imagem, scan concluído, download, etc.
Proxy Cache Configuração de um projeto como proxy transparente para um registry externo. O Harbor guarda uma cópia local na primeira vez que a imagem é pedida, reduzindo latência e eliminando dependência externa nos pulls subsequentes.
Replicação Sincronização automática de imagens entre instâncias Harbor ou para registries externos (ECR, GCR, Docker Hub, etc.). Útil para estratégias de promoção entre ambientes ou distribuição geográfica.
Considerações para Alta Disponibilidade
Para um setup Harbor em produção com HA, os seguintes componentes precisam de atenção especial:
| Componente | Requisito para HA |
|---|---|
| Core, Portal, Jobservice, Nginx | replicas: 2+ (stateless, sem requisitos especiais) |
| Registry | replicas: 2+ + storage com ReadWriteMany (S3, MinIO ou NFS/Longhorn RWX) |
| Redis | Redis Sentinel com 3+ nós |
| PostgreSQL | Cluster externo em HA (CloudNativePG, Patroni, Bitnami HA) |
O PostgreSQL é o único ponto de falha que derruba o Harbor completamente. Os outros componentes degradam a funcionalidade mas não necessariamente tornam o sistema inacessível.