Biblioteca de imagens de SO

Problema e finalidade

Uma máquina virtual pode ser iniciada a partir de uma imagem de SO pronta em segundos, enquanto a instalação a partir de mídia leva dezenas de minutos. Mas o disco da nova máquina é criado como um clone ZFS, e um clone reside no mesmo pool que o seu pai. Portanto, a imagem já precisa estar no pool onde a máquina é criada. Baixar gigabytes de um servidor externo toda vez que uma VM é criada não faz sentido.

A biblioteca de imagens separa esses dois eventos no tempo. Primeiro, o administrador importa a imagem para o cluster uma única vez e a distribui entre os pools. Depois, as máquinas são criadas a partir das cópias locais, sem acessar a rede externa.

Isso divide o modelo em duas partes. Fora do cluster está a fonte da biblioteca: um servidor web comum com um arquivo manifest.json que lista as imagens disponíveis. Dentro do cluster está o catálogo de imagens: imagens que já foram importadas, com um mapa de distribuição entre os pools e o estado de cada cópia. A sincronização lê a primeira parte; a importação preenche a segunda.

A terceira característica do modelo é menos óbvia. O registro de fonte não tem um parâmetro "qual VDC" (data center virtual): o papel Cluster master cria uma fonte compartilhada do cluster, e um administrador de VDC cria uma fonte do seu próprio VDC. A importação tem esse parâmetro, mas quem decide são os direitos. O papel Cluster master importa apenas imagens compartilhadas, e um VDC especificado é ignorado. Um administrador de VDC precisa especificar o seu próprio VDC: sem ele, a importação é rejeitada com o código -49005, e com outro VDC, com o código -49006.

Na interface web do vStack Center, a biblioteca é aberta pela seção «Image library», com as abas «Images» e «Sources»: o catálogo de imagens do cluster, a adição de uma imagem a partir de uma fonte, a remoção de uma imagem e o registro, a sincronização e a remoção de fontes. Todas as operações da biblioteca também estão disponíveis pela API do cluster, por chamadas de API ou por um sistema de automação que faz essas chamadas. As operações estão listadas no final desta página; as estruturas de requisição e resposta estão na referência da API.

Esta página explica o modelo. Para importar uma imagem, consulte Como importar uma imagem de SO para o cluster; para remover uma imagem do cluster, consulte Como remover uma imagem de SO.

Modelo e entidades

Fonte da biblioteca. Um servidor externo com imagens. Uma fonte tem um nome, uma URL raiz da biblioteca e o horário da sua última sincronização, que fica vazio se ela ainda não foi sincronizada. A URL deve usar http ou https; https é obrigatório por padrão. O http não criptografado só é permitido com autorização explícita. A URL é única dentro do cluster: a mesma URL raiz não pode ser registrada duas vezes.

Manifesto. O arquivo manifest.json na raiz da fonte é um catálogo do que a fonte oferece. O proprietário da biblioteca escreve o manifesto, e cada entrada contém os metadados completos da imagem: os campos obrigatórios name, version, format, url_path, size e sha256, e os opcionais description, os_type, net_link_pattern, zero_based_link, default_shell, sector_size_logical, sector_size_physical, guest_customization, uefi, min_size e uuid. O próprio cluster determina se uma imagem pode ser importada: apenas imagens no formato zfs são elegíveis.

O campo uuid é formalmente opcional, mas a importação o usa para localizar a imagem no manifesto: uma entrada sem uuid não pode ser importada. O identificador é globalmente único: o manifesto não pode conter duas entradas com o mesmo uuid.

Imagem no catálogo do cluster. Uma imagem importada é endereçada por um identificador substituto (UUID). Os nomes de imagem não são únicos, então as operações usam o identificador, e não o nome. Uma imagem tem um estágio do ciclo de vida e um mapa da sua distribuição real entre os pools.

Cópia em um par nó → pool. A distribuição é feita por pool, e cada par nó → pool tem o seu próprio resultado. Isso explica o estado "não distribuída em todos os lugares" e a dependência inversa: os discos das VMs em um pool são clones ZFS da cópia da imagem naquele pool específico.

Entidade	Endereçada por	Pertence a
Fonte da biblioteca	Identificador inteiro	Ao cluster (compartilhada) ou a um VDC
Imagem no catálogo	Identificador UUID	Ao VDC proprietário ou ao cluster
Cópia da imagem	Um par nó → pool	Ao pool

Como funciona

O trabalho com a biblioteca envolve oito operações, cada uma com o seu próprio privilégio.

Tarefa	Modo	Privilégio
Registrar ou reconfigurar uma fonte	Síncrono	Manage Image Library
Remover uma fonte	Síncrono	Manage Image Library
Visualizar as fontes disponíveis	Síncrono	View Image Library
Ler o catálogo da fonte	Síncrono	Sync Image Library
Importar uma imagem para o cluster	Assíncrono	Import Golden Image
Visualizar o catálogo de imagens do cluster	Síncrono	View Image Catalog
Obter o mapa de dependências de uma imagem	Síncrono	View Image Dependencies
Remover uma imagem do cluster	Síncrono	Remove OS Image

Todos os privilégios têm como escopo o respectivo VDC; o papel Cluster master tem escopo global. O direito de visualizar dependências é separado do direito de remover imagens: a visualização pode ser concedida amplamente, a remoção não.

A sincronização lê o manifesto, não as imagens

A sincronização baixa apenas o manifest.json e retorna o catálogo de imagens da fonte. Nenhum byte de imagem é transferido, então a operação é barata e segura. Ela também atualiza o horário da última sincronização da fonte. Uma imagem em um formato não suportado não desaparece do catálogo: ela é retornada com um indicador "não elegível para importação", que mostra por que a importação não a aceitará.

As requisições a URLs externas são protegidas contra substituição de destino. O esquema (somente http ou https) e o resultado da resolução de nomes são verificados. O cluster rejeita loopback, link-local, incluindo o endereço do serviço de metadados, as faixas privadas da RFC 1918, o espaço de endereços compartilhado de NAT de nível de operadora (CGNAT), a "rede zero" e o endereço de broadcast. As formas disfarçadas de IPv6 mapeado em IPv4 são reduzidas a IPv4 e verificadas contra a mesma lista; os endereços IPv6 nativos de loopback, link-local e locais únicos (ULA) são bloqueados. O corpo do manifesto é limitado a 100 MB.

A importação distribui a imagem entre os pools

A importação responde imediatamente, confirmando a aceitação do job, e não que a imagem está pronta: o trabalho continua em segundo plano. O serviço de distribuição dedicado vstack-center-image-distributor transfere os bytes usando um protocolo de duas fases; o dispatcher do cluster apenas orquestra o processo. Um único componente grava no catálogo de imagens, então não há gravações concorrentes no estado da imagem.

O progresso e o resultado ficam visíveis no catálogo de imagens do cluster: uma imagem tem um estágio e um mapa de distribuição com uma entrada para cada pool.

Estágio	Significado	Ação
importing	A imagem está sendo baixada e distribuída	Aguarde
active	A imagem foi distribuída para todos os pools selecionados	É possível criar VMs
partial_active	Alguns pools não receberam uma cópia	Conclua a distribuição importando a mesma versão novamente
failed	A tentativa falhou por completo	Investigue a causa e reinicie a importação
deleting	A imagem está sendo removida	Aguarde o resultado; a importação e outra remoção são rejeitadas com o código -48004

Não há novas tentativas automáticas, por design. Qualquer falha (download, soma de verificação, distribuição ou o serviço perder o job) coloca a imagem em failed e cria uma entrada de log. O administrador inicia uma nova tentativa importando novamente. A mesma lógica se aplica após um reinício do dispatcher: as importações incompletas são marcadas como falhas, em vez de repetidas silenciosamente.

O sucesso parcial não é revertido. Os pools que receberam uma cópia a mantêm; importar a mesma versão novamente entrega as cópias restantes.

A criação de VM aguarda um pool pronto

Enquanto a imagem tiver um mapa de distribuição, a sua cópia no pool selecionado para a criação da máquina precisa estar ativa. Caso contrário, a criação da VM é rejeitada com o código -259 antes que qualquer coisa seja criada. Portanto, a ordem das operações inverte a abordagem habitual: primeiro a imagem no pool, depois a máquina nesse pool. Para detalhes sobre a criação, consulte Como criar, remover e migrar uma máquina virtual.

Visibilidade e propriedade

Imagens e fontes têm o mesmo escopo de visibilidade. O Cluster master vê tudo. Um administrador de VDC vê os objetos compartilhados do cluster mais os objetos atribuídos aos seus VDCs. Uma entidade sem VDC vê apenas os objetos compartilhados. A URL da fonte é exibida apenas ao seu proprietário; os demais não a veem.

Visibilidade e propriedade são direitos diferentes. Um administrador de VDC não pode remover uma imagem que se tornou visível para o seu VDC por meio de uma concessão de visibilidade: a remoção exige propriedade. Importar uma nova versão de uma imagem existente também só está disponível ao proprietário ou ao papel Cluster master. Imagens inexistentes e invisíveis retornam a mesma resposta, "não encontrada", de modo que a resposta não pode revelar a existência da imagem restrita de outra pessoa.

Toda alteração é registrada primeiro

O registro e a remoção de fontes, a sincronização, a importação e a remoção de imagens gravam um registro de intenção no log de segurança antes da própria ação. A gravação do registro tem um limite de tempo de dois segundos por padrão. Se o log não aceitar o evento, a operação não é iniciada e retorna o código -503. Nada muda nem no catálogo nem nos nós.

As leituras bem-sucedidas da lista de fontes e do catálogo de imagens não são registradas, mas uma negação de acesso a qualquer operação com imagens deixa uma entrada auth.image_library_access_denied. A visualização de dependências é registrada como um evento config.image_dependencies_viewed. Os estágios da remoção têm as suas próprias entradas: config.image_remove_initiated, config.image_removed, config.image_remove_partial, config.image_remove_failed e config.image_remove_blocked_dependencies. Cada registro contém uma associação a um VDC ou a indicação de que o objeto é compartilhado em todo o cluster, o escopo de acesso de quem fez a chamada e o seu identificador. O log não contém caminhos de armazenamento nem a topologia dos pools, apenas identificadores de nós e contagens agregadas.

Limitações

Apenas o formato zfs pode ser importado. Uma cópia de imagem em um pool é um dataset ZFS a partir do qual os discos das máquinas são clonados, então não há onde distribuir outro formato. Uma imagem em outro formato aparece no catálogo da fonte como não elegível para importação, e a própria importação retorna o código -48005. Solução alternativa: inclua uma variante zfs da imagem no manifesto.

O http não criptografado é bloqueado por padrão. A biblioteca fornece os dados a partir dos quais todas as máquinas do cluster são construídas, então o canal precisa ser verificável. Sem autorização explícita, uma URL http é rejeitada com o código -46011. Solução alternativa: publique a fonte por https; reserve a autorização para um ambiente de teste isolado.

Endereços internos são proibidos. Um host de fonte que resolve para loopback, link-local, o endereço do serviço de metadados, uma faixa privada da RFC 1918, CGNAT, a "rede zero" ou o endereço de broadcast é rejeitado com o código -46012. A restrição não pode ser removida: ela impede que o cluster acesse a si mesmo por ordem de terceiros. Uma biblioteca em uma rede interna se enquadra inteiramente nessa restrição. Solução alternativa: mova a biblioteca para um endereço fora das faixas listadas.

Remover uma fonte mantém as suas imagens. A remoção de uma fonte exclui apenas o registro e os seus vínculos com VDCs; as imagens importadas dela permanecem no catálogo, mas perdem o vínculo com a fonte. Um administrador de VDC remove apenas a fonte do seu VDC; uma fonte compartilhada do cluster é removida pelo papel Cluster master. Para alterar a URL, não é necessário remover a fonte: o registro com um identificador de fonte existente funciona como uma sobrescrita do seu nome e da sua URL.

A importação exige o serviço de distribuição. Sem um vstack-center-image-distributor implantado (e o seu vhost obrigatório imgdistr_vhost), não há o que transfira os bytes. A única solução alternativa é implantar o serviço; a sincronização não envolve o serviço de distribuição e lê apenas o manifesto.

As verificações de dependências podem ser incompletas. O mapa de clones é montado consultando todos os nós, e um nó inacessível não é incluído na resposta; ele é marcado como ignorado. Solução alternativa: aguarde o retorno do nó e obtenha o mapa novamente; a remoção nessa situação ainda terá um resultado parcial.

Leitura adicional

• Como importar uma imagem de SO para o cluster — leitura do catálogo da fonte, início da importação e acompanhamento da distribuição entre os pools.
• Como remover uma imagem de SO — verificação de dependências, remoção irreversível e investigação de um resultado parcial.
• Como criar, remover e migrar uma máquina virtual — seleção de uma imagem e de um pool ao criar uma máquina.

Métodos da API

As operações de API abordadas nesta página são os-library-set, os-library-delete, os-library-list, os-library-sync, os-image-import, os-image-from-vm, golden-images-list, golden-image-clones e golden-image-remove; consulte a referência da API.