Skip to main content

Harbor na Prática — Parte 1 Instalação via Helm no Kubernetes

Esta é a primeira parte de uma série de artigos em português sobre o Harbor, o registry de imagens open source da CNCF. O objetivo é ajudar a comunidade a implementar e operar o Harbor do zero, com exemplos práticos e explicações claras.

Pré-requisitos​

Antes de começar, você precisa ter:

  • Um cluster Kubernetes funcionando (kubeadm, k3s, EKS, GKE, etc.)
  • kubectl configurado e com acesso ao cluster
  • helm instalado (v3+)
  • Uma StorageClass disponível no cluster (ex: longhorn, local-path, gp2)
  • Um domínio ou IP para acesso externo

O que vamos instalar​

O Harbor será instalado via Helm chart oficial, com as seguintes configurações:

  • Acesso via NodePort (simples para começar)
  • TLS desabilitado (ideal para ambiente de desenvolvimento)
  • Storage local via StorageClass
  • Banco de dados PostgreSQL interno
  • Redis interno

Passo 1 — Adicionar o repositório Helm do Harbor​

helm repo add harbor https://helm.goharbor.io
helm repo update

Verifique se o repositório foi adicionado corretamente:

helm search repo harbor/harbor

Você deverá ver a versão mais recente do chart disponível.

Passo 2 — Criar o namespace​

kubectl create namespace harbor

Passo 3 — Criar o arquivo values.yaml​

O values.yaml é onde você personaliza toda a instalação. Crie o arquivo com o conteúdo abaixo:

expose:
  type: nodePort
  tls:
    enabled: false
  nodePort:
    name: harbor
    ports:
      http:
        port: 80
        nodePort: 32000
      https:
        port: 443
        nodePort: 32001

# URL externa que o Harbor vai usar para gerar links e tokens
# Substitua pelo IP ou domínio do seu cluster
externalURL: http://harbor.empresa.com:32000

# Senha do administrador — Eu inserir aqui para ficar mais pratico
harborAdminPassword: "Harbor12345"

persistence:
  resourcePolicy: "keep"
  persistentVolumeClaim:
    registry:
      storageClass: "longhorn"   # substitua pela sua StorageClass
      accessMode: ReadWriteOnce
      size: 50Gi
    jobservice:
      jobLog:
        storageClass: "longhorn"
        size: 5Gi
    database:
      storageClass: "longhorn"
      size: 10Gi
    redis:
      storageClass: "longhorn"
      size: 2Gi
    trivy:
      storageClass: "longhorn"
      size: 5Gi

Dica: O campo externalURL é crítico. Ele define a URL base que o Harbor usa para gerar tokens de autenticação e links internos. Se estiver errado, o docker login e o docker push vão falhar com erros de autenticação.

Passo 4 — Instalar o Harbor​

helm install harbor harbor/harbor \
  --namespace harbor \
  --values values.yaml

Acompanhe a criação dos pods:

kubectl get pods -n harbor -w

A instalação completa leva entre 2 e 5 minutos. Todos os pods devem estar em estado Running antes de prosseguir.

Passo 5 — Verificar a instalação​

kubectl get pods -n harbor

Você deverá ver algo parecido com:

NAME                                READY   STATUS    RESTARTS   AGE
harbor-core-xxx                     1/1     Running   0          3m
harbor-database-0                   1/1     Running   0          3m
harbor-jobservice-xxx               1/1     Running   0          3m
harbor-nginx-xxx                    1/1     Running   0          3m
harbor-portal-xxx                   1/1     Running   0          3m
harbor-redis-0                      1/1     Running   0          3m
harbor-registry-xxx                 2/2     Running   0          3m
harbor-trivy-0                      1/1     Running   0          3m

Verifique também os serviços:

kubectl get svc -n harbor

Passo 6 — Acessar a interface web​

Abra o browser e acesse:

http://<IP-DO-SEU-NODE>:32000

Use as credenciais:

  • Usuário: admin
  • Senha: o valor que você definiu em harborAdminPassword

Você verá o dashboard do Harbor com o projeto library já criado por padrão.

Explorando a interface​

Ao acessar o Harbor pela primeira vez, vale conhecer os menus principais:

  • Projects — onde ficam os repositórios de imagens, organizados por projeto
  • Registries — para configurar endpoints de replicação e proxy cache
  • Administration — gestão de usuários, configurações LDAP, quotas globais
  • Logs — auditoria de todas as operações realizadas

Solução de problemas comuns​

Pod harbor-core reiniciando constantemente

Verifique se o banco de dados já está pronto antes do core tentar conectar:

kubectl logs -n harbor harbor-core-xxx
kubectl logs -n harbor harbor-database-0

Erro de autenticação ao fazer docker login

Confirme que o externalURL no values.yaml corresponde exatamente ao endereço que você está usando para acessar o Harbor. Qualquer diferença (HTTP vs HTTPS, porta, domínio) causa falha na geração de tokens.

PVCs em estado Pending

Verifique se a StorageClass informada existe no cluster:

kubectl get storageclass
kubectl describe pvc -n harbor

Atualizando a instalação​

Se precisar alterar alguma configuração após a instalação, edite o values.yaml e execute:

helm upgrade harbor harbor/harbor \
  --namespace harbor \
  --values values.yaml

Próximo artigo​

Na Parte 2, vamos criar projetos e repositórios no Harbor — via interface web, via API REST e via Terraform — e entender como organizar suas imagens de forma eficiente.