Nesta página

Registries Privados de Container

Quando você faz deploy de um serviço a partir de uma imagem Docker pré-construída, o Guara Cloud consegue puxar de qualquer registry privado de container — repositórios privados do Docker Hub, GitHub Container Registry, Google Container Registry, Quay.io, GitLab, Harbor self-hosted e qualquer registry compatível com V2.

Você anexa as credenciais direto no serviço. Não existe uma aba global de “credenciais de registry”, e você não precisa embutir tokens na imagem nem passar por variáveis de ambiente.

Onde encontrar

São dois pontos de entrada, dependendo se você está criando um serviço novo ou editando um existente:

Wizard de criação de serviço. Quando você escolhe Imagem Docker como método de build e fornece uma referência de imagem privada, uma seção colapsada Credenciais de Registry Privado aparece logo abaixo do campo de imagem.
Aba Configurações do serviço. Abra o serviço, vá em Configurações e encontre a seção Registry Privado. Se já houver credenciais, a seção aparece expandida com os valores atuais; senão, mostra um único botão ”+ Adicionar credenciais de registry privado”.

As duas superfícies compartilham o mesmo formulário e fluxo de validação.

Adicionando credenciais

URL do Registry. O hostname ou URL completa do registry (por exemplo, gcr.io, ghcr.io, quay.io, docker.io ou seu host self-hosted).
Usuário. O usuário para basic auth, ou o usuário do token para autenticação por token (comumente oauth2accesstoken para GCR, _json_key_base64 para JSON keys do GCR, etc.).
Senha. A senha ou token. O valor em texto puro nunca sai da requisição — veja a seção de segurança abaixo.
Testar conexão. Clique no botão. A plataforma faz um preflight real contra o seu registry.
Salvar. Quando o teste passa, o botão Salvar habilita.

Testar conexão

O botão Testar conexão faz um preflight real contra o registry — não é só um check de URL bem formada. O fluxo:

Sondar o endpoint V2 da API do registry (GET /v2/) para confirmar que ele fala o protocolo OCI.
Trocar tokens de auth se o registry desafiar com WWW-Authenticate: Bearer realm=....
Mandar uma requisição HEAD para o manifest da referência de imagem que você forneceu, para confirmar que ela existe naquele registry com aquelas credenciais.

O preflight inteiro tem timeout de 8 segundos no relógio. Falhas mapeiam para códigos amigáveis:

Código	Significado
`invalid_url`	A URL é inválida ou o host não responde.
`auth_failed`	Usuário ou senha foram rejeitados pelo registry.
`manifest_not_found`	A referência da imagem não existe nesse registry.
`timeout`	O registry levou mais de 8 segundos para responder.
`ssrf_blocked`	O hostname do registry resolve para um endereço bloqueado (loopback, RFC 1918, etc.).
`network_error`	Outra falha de rede (DNS, TLS, etc.).

O Testar conexão tem rate limit de 5 tentativas por minuto por usuário. Se você bater o limite, o dashboard mostra uma mensagem suave e você pode tentar de novo em pouco tempo.

Salvar sem verificar

Se o teste falhar mas você tem certeza que as credenciais estão certas (por exemplo, o registry está em manutenção rápida), marque Salvar sem verificar para pular o preflight obrigatório e persistir as credenciais mesmo assim.

Atualizar e remover

Editar. Clique no grupo de campos para revelar o formulário. Usuário e senha aparecem mascarados; você pode trocar ou manter como estão. Refaça o teste antes de salvar.
Remover. Clique em Remover credenciais. O serviço passa a fazer pulls anônimos. Se a imagem for privada, o próximo deploy vai falhar até as credenciais voltarem.

Segurança

Senhas são criptografadas em repouso com AES-256-GCM, usando uma chave por projeto derivada via HKDF a partir da chave master da plataforma. Cada projeto tem sua própria chave derivada — nada de segredo compartilhado entre projetos.
A senha em texto puro fica em memória apenas durante a requisição que cria ou atualiza as credenciais, a chamada HTTP de preflight e a transação que criptografa e persiste. Ela nunca é logada, cacheada ou escrita em disco.
O preflight do registry está sob a mesma proteção SSRF que protege os destinos HTTP de cron workers. Loopback, RFC 1918, link-local, carrier-grade NAT, IPv4-mapped IPv6 e o endereço não especificado são todos bloqueados.
Todo save é registrado nos seus Audit Logs sob service.create ou service.update, com metadata indicando se o preflight passou ou foi sobrescrito.

Registries suportados

Qualquer coisa que fale a OCI Distribution Spec V2 funciona. Exemplos comuns:

Registry	Exemplo de URL	Notas de usuário
Docker Hub (repo privado)	`docker.io`	Seu usuário do Docker Hub
GitHub Container Registry	`ghcr.io`	Seu usuário do GitHub; senha = personal access token
GitLab Container Registry	`registry.gitlab.com`	Seu usuário do GitLab; senha = personal access token
Google Container Registry	`gcr.io`	`oauth2accesstoken` ou `_json_key_base64`
Quay.io	`quay.io`	Seu usuário do Quay
Harbor self-hosted	`harbor.example.com`	A conta robô ou um usuário