Use image-syncer to migrate container images - Container Service for Kubernetes: Central de Documentação do Alibaba Cloud

Ao migrar workloads do Kubernetes para o ACK, a transferência de um grande volume de imagens de contêiner costuma ser o principal gargalo. Scripts baseados em docker pull e docker push exigem espaço em disco proporcional ao tamanho da imagem, dependem do daemon do Docker e tornam-se complexos quando é necessário filtrar tags ou sincronizar para múltiplos destinos. O image-syncer elimina essas restrições: ele copia imagens diretamente entre registradores usando apenas memória e largura de banda de rede, sem depender do daemon do Docker nem de armazenamento em disco no host. O servidor que executa o image-syncer aproveita integralmente a largura de banda disponível, sem exigir capacidade de disco específica. A ferramenta oferece suporte a repositórios de imagens com capacidade superior a 3 TB.

Como funciona

O image-syncer lê um arquivo de configuração JSON que define credenciais de autenticação e regras de sincronização e, em seguida, transfere as imagens diretamente entre os registradores. Um único arquivo de configuração pode definir regras para sincronizar imagens de vários repositórios de source para vários repositórios de destino simultaneamente. A cada execução, a ferramenta verifica quais imagens já existem no destino e as ignora, o que torna seguro executá-la novamente. Ela gerencia transferências simultâneas com paralelismo configurável e retenta automaticamente tarefas com falha para lidar com instabilidades de rede.

O image-syncer é compatível com qualquer serviço que ofereça suporte ao Docker Registry V2, incluindo Alibaba Cloud Container Registry (ACR), Docker Hub, Quay.io e Harbor. Essa solução é utilizada para migração de imagens na escala de terabytes em ambientes de produção.

Limitações

Antes de configurar as regras de sincronização, observe as seguintes restrições:

Cada regra de sincronização mapeia um repositório de source para um repositório de destino. Não é possível sincronizar um namespace ou registrador inteiro com uma única regra.
A URL do repositório de source não pode estar vazia.
Se a URL de source especificar várias tags (separadas por vírgula), a URL de destino não deve incluir nenhuma tag.

Pré-requisitos

Antes de começar, verifique se você possui:

Conectividade de rede entre a máquina host e todos os registradores de source e destino
Permissões de pull e listagem de tags em todos os repositórios de source
Permissões de push e criação de repositórios em todos os registradores de destino

Configure o image-syncer

O image-syncer utiliza um arquivo de configuração JSON com dois campos de nível superior: auth e images.

Autenticação (`auth`)

O campo auth associa a URL de cada registrador às suas respectivas credenciais. Caso um registrador não exija autenticação, omita-o do campo auth — o image-syncer fará acesso anônimo.

A URL do registrador no campo auth deve corresponder exatamente ao hostname do registrador usado nas URLs das imagens.

Campo	Obrigatório	Tipo	Padrão	Descrição
`username`	Não	String	—	Nome de usuário do registrador
`password`	Não	String	—	Senha do registrador
`insecure`	Não	Boolean	`false`	Defina como `true` para conectar via HTTP em vez de HTTPS. Compatível a partir da versão V1.0.1.

Regras de sincronização (`images`)

O campo images define as regras de sincronização como pares chave-valor. A chave representa a URL da imagem de source; o valor, a URL da imagem de destino. Ambas seguem o formato registry/namespace/repository:tag.

O comportamento das tags varia conforme a especificação da URL de source:

URL de source	URL de destino	Comportamento
Sem tag	Sem tag	Todas as tags do repositório de source são sincronizadas, mantendo os nomes originais
Tag única, ex.: `:v1`	Sem tag	Apenas a imagem com essa tag é sincronizada, preservando o nome original da tag
Tag única, ex.: `:v1`	Com tag, ex.: `:stable`	Somente essa imagem é sincronizada e renomeada para a tag de destino
Múltiplas tags, ex.: `:v1,v2,v3`	Sem tag (obrigatório)	Apenas as tags especificadas são sincronizadas, mantendo os nomes originais
Sem tag	String vazia `""`	Todas as tags são sincronizadas para o repositório de mesmo nome no namespace padrão do registrador padrão

Exemplo de arquivo de configuração

{
    "auth": {
        "quay.io": {
            "username": "xxx",
            "password": "xxxxxxxxx",
            "insecure": true
        },
        "registry.cn-beijing.aliyuncs.com": {
            "username": "xxx",
            "password": "xxxxxxxxx"
        },
        "registry.hub.docker.com": {
            "username": "xxx",
            "password": "xxxxxxxxxx"
        }
    },
    "images": {
        "quay.io/coreos/kube-rbac-proxy": "quay.io/ruohe/kube-rbac-proxy",
        "xxxx": "xxxxx",
        "xxx/xxx/xx:tag1,tag2,tag3": "xxx/xxx/xx"
    }
}

Substitua os valores de exemplo pelas URLs reais dos seus registradores, credenciais e caminhos das imagens.

Execute o image-syncer

Após preparar o arquivo de configuração, execute o image-syncer apontando para esse arquivo. A ferramenta registra a quantidade de imagens que falharam na sincronização e fornece logs de erro detalhados para auxiliar no diagnóstico de problemas.

Para consultar um exemplo funcional completo, veja Synchronize images from a self-managed Harbor project to Container Registry Enterprise Edition.

Próximos passos

image-syncer no GitHub