A imagem

O RootPilot Agent é entregue como imagem de container. Esta página descreve o que ela contém — é o material de uma revisão de segurança antes de dar credenciais a ela.

Obter

# AWS (ECR)
docker pull <conta-rootpilot>.dkr.ecr.<região>.amazonaws.com/rootpilot-agent:<versão>

# GCP (Artifact Registry)
docker pull <região>-docker.pkg.dev/<projeto-rootpilot>/rootpilot/rootpilot-agent:<versão>

O acesso é concedido à sua conta AWS ou projeto GCP: o pull usa a identidade da sua nuvem, e não há credencial do RootPilot para você guardar ou rotacionar.

Autenticar antes do pull

O registry é privado, então um docker pull sem autenticação falha com no basic auth credentials. Autentique com as suas credenciais — é a autorização que concedemos a elas que libera o pull.

AWS (ECR) — o token vem da sua conta; o login aponta para o registry do RootPilot:

aws ecr get-login-password --region <região> \
  | docker login --username AWS --password-stdin <conta-rootpilot>.dkr.ecr.<região>.amazonaws.com

Use a mesma <região> do endereço da imagem. O seu principal precisa de ecr:GetAuthorizationToken; as permissões de leitura no repositório já foram concedidas à sua conta do nosso lado.

GCP (Artifact Registry) — registre o credential helper uma vez:

gcloud auth configure-docker <região>-docker.pkg.dev

O seu principal precisa de roles/artifactregistry.reader no repositório, que já foi concedido ao projeto que você informou.

Em orquestrador não existe docker login

Em ECS, EKS, GKE ou Cloud Run quem puxa a imagem é a plataforma, não você — e ela usa a identidade dela, não a sua. Garanta que a identidade responsável pelo pull tenha a mesma permissão de leitura:

• ECS: a task execution role.
• EKS: a role do node group (ou um imagePullSecret, se você não puder alterar a role).
• GKE / Cloud Run: a service account do node pool ou do serviço.

Nos informe qual conta ou projeto é, se for diferente do que já autorizamos — a concessão é por conta/projeto, e um pull de uma identidade não autorizada falha com o mesmo erro de credencial.

Propriedade	Valor
Arquiteturas	linux/amd64 e linux/arm64
Base	node:22-alpine
Usuário	node (uid 1000) — não-root
Entrypoint	carrega os PEMs de /certs e executa o processo do Agent
Portas expostas	nenhuma

O que a imagem contém

Só o que o processo abre em execução: os artefatos JavaScript compilados (dist/), os manifests dos pacotes e as dependências de produção.

O que a imagem não contém

Por construção, o estágio final do build não copia a árvore de desenvolvimento:

• nenhum código-fonte (src/);
• nenhum teste nem fixture de teste;
• nenhum toolchain de compilação — python3, make e g++ existem só num estágio intermediário e não chegam ao runtime;
• nenhum segredo. A imagem é idêntica para todos os clientes; o que varia é o certificado e as credenciais que você monta em runtime.

A exclusão de fixtures é deliberada e importa a você: sem ela, dado de teste de um cliente viajaria para dentro da infraestrutura de outro.

Fixe por digest

Em produção, referencie a imagem pelo digest, não pela tag:

<endereço>/rootpilot-agent@sha256:<digest>

O Agent é efêmero e puxa a imagem com frequência. Uma tag móvel permite que réplicas diferentes rodem builds diferentes sem que ninguém perceba. O digest é imutável.

Para descobrir o digest de uma tag:

docker buildx imagetools inspect <endereço>/rootpilot-agent:<versão>

O mesmo comando lista as arquiteturas presentes no índice multi-plataforma.

Verifique a assinatura

A imagem é assinada no momento da publicação, sem chave: o workflow que a constrói troca a própria identidade por um certificado efêmero, e a assinatura fica registrada num log público de transparência. O que isso prova não é “alguém com uma chave assinou” — é qual workflow, de qual repositório, em qual tag produziu aquele digest.

Precisa do cosign:

cosign verify \
  --certificate-identity https://github.com/sunnysystems/rootpilot-edge/.github/workflows/release-image.yml@refs/tags/v<versão> \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  <endereço>/rootpilot-agent@sha256:<digest>

O --certificate-identity é a parte que importa, e é por isso que ele carrega a versão: sem fixar a identidade, cosign verify aceitaria qualquer assinatura válida do ecossistema Sigstore, inclusive de um repositório que não é o nosso. Verificar sem essa flag é quase o mesmo que não verificar.

Versões anteriores à 1.0.2 não são assinadas

A assinatura entrou depois da primeira imagem publicada. Um cosign verify numa versão anterior falha por ausência de assinatura, não por assinatura inválida — são coisas diferentes, e a mensagem do cosign não é óbvia nesse ponto.

Se você aplica política de admissão no cluster (Kyverno, policy-controller), é essa mesma identidade que entra na regra. Recomendado, mas é decisão sua: nós publicamos a assinatura, não exigimos a verificação.

Requisitos de execução

Nenhum privilégio especial: sem --privileged, sem capability adicional, sem acesso ao socket do Docker, sem montagem do sistema de arquivos do host. O único volume necessário é o /certs, somente leitura.

Isto vale para o Agent. O Profiler é outro artefato, e a postura dele é o oposto

O RootPilot Profiler — o segundo artefato, opcional — é uma imagem diferente (rootpilot-profiler), e ele exige privilégio: cinco capabilities de kernel, visão dos processos do host e um perfil AppArmor próprio. Uma delas, CAP_SYS_ADMIN, é root-equivalente num container com hostPID.

Elas não são negociáveis e o Profiler recusa subir sem alguma delas — não existe modo reduzido. A razão está em Segurança → RootPilot Profiler, junto do que sai da sua infraestrutura e do que fazer se a sua resposta for não.

Esta distinção é o motivo de serem dois artefatos e não uma flag: a página que você está lendo descreve o que todo cliente instala, e ela continua verdadeira. Quem nunca instalar o Profiler nunca concede nada disso.

Memória e CPU: 0,5 vCPU e 512 MB atendem a maioria das instalações. O RUNNER_LEARNED_STORE_PATH padrão é :memory:, então não há escrita em disco — se você apontá-lo para um volume, o container passa a escrever lá e você é dono das permissões.