Como importar uma imagem de SO para o cluster

Quando usar

Quando o cluster precisa de uma nova imagem de SO ou de uma nova versão de uma imagem já importada. A importação baixa a imagem de uma fonte de biblioteca registrada e a distribui entre os pools de armazenamento. Só então é possível criar máquinas virtuais a partir da imagem.

Este procedimento também se aplica à conclusão da distribuição. Se uma importação anterior não distribuiu a imagem para todos os pools, importar a mesma versão novamente entrega as cópias que faltam.

Este procedimento não se aplica se a imagem da fonte estiver em um formato diferente de zfs: a importação não aceita essas imagens. Ele também não se aplica à alteração do proprietário da imagem: importar novamente não reescreve a propriedade da imagem pelo VDC (data center virtual).

Pré-requisitos

• O privilégio Import Golden Image com escopo no VDC de destino; o papel Cluster master tem escopo global;
• O privilégio Sync Image Library: sem ele, não é possível ler o catálogo da fonte nem obter o identificador da imagem;
• O serviço de distribuição vstack-center-image-distributor está implantado no cluster com o vhost obrigatório imgdistr_vhost; sem ele, nada pode transferir os bytes durante a importação;
• A fonte da biblioteca está registrada, e o seu identificador é conhecido a partir da lista de fontes;
• A fonte está acessível a quem faz a chamada: um administrador de VDC pode acessar uma fonte atribuída ao seu VDC, enquanto uma fonte compartilhada do cluster está disponível apenas para o papel Cluster master. Essa verificação ocorre antes da leitura do catálogo e antes da importação, então sem acesso à fonte a resposta é -403, mesmo quando todos os privilégios necessários foram concedidos;
• O cluster tem pelo menos um pool de armazenamento com proprietário;
• vStack Center versão 4.0.0.

Etapas

Na interface web, a importação começa na seção «Image library», aba «Images». As etapas abaixo são para o papel Cluster master. Um administrador de VDC importa uma imagem para o seu próprio VDC por meio de uma chamada de API, especificando esse VDC na requisição de importação. As estruturas de requisição e os detalhes completos das respostas estão na referência da API.

1. Clique em «Add image» e abra a aba «Source»: a aba «File» ainda não está disponível. Escolha uma fonte na lista «Source». O cluster lê apenas o seu manifest.json e exibe a «Image showcase» com cartões das imagens da fonte. A leitura do catálogo é rápida e não altera nada no cluster.

2. Selecione uma imagem. Um cartão em um formato diferente de zfs fica inativo com a legenda «The platform cannot import this format»; uma imagem já importada é marcada como «Already in the cluster catalog». O identificador de importação é o campo uuid da entrada do manifesto: ele identifica de forma única tanto a imagem quanto a sua versão. Uma entrada sem uuid não pode ser importada — primeiro adicione o campo ao manifesto da fonte.

3. Clique em «Next» e escolha os pools: todos ficam selecionados por padrão. Para distribuir a imagem apenas para alguns pools, desmarque os demais — as cópias restantes podem ser entregues importando a mesma versão novamente. Clique em «Add».

   A importação é assíncrona: a notificação «Image import has started» confirma o job, e não que a imagem está pronta. A distribuição continua em segundo plano.

   A mesma importação pode ser iniciada pela aba «Sources»: painel da fonte → cartão da imagem → «Import image» → «Import».

4. Aguarde a conclusão da distribuição. Na coluna «Status», a imagem passa de «Importing» para «Available»; «Partially available» e «Failure» são tratados abaixo. A coluna «Availability» mostra quantos pools têm uma cópia, e o painel da imagem mostra o resultado por pool.

Verificar o resultado

Encontre a imagem importada em «Image library» e verifique duas coisas:

O que verificar	Valor esperado
Status da imagem	«Available» (active na API): a imagem foi distribuída para todos os pools selecionados
Resultado por pool	Uma entrada para cada pool da etapa 3

O status «Importing» (importing) significa que a distribuição ainda está em andamento. Os status «Partially available» (partial_active) e «Failure» (failed) são discutidos abaixo.

A verificação final é a criação de uma máquina. A cópia da imagem no pool selecionado para a criação da VM precisa estar ativa; caso contrário, a criação é rejeitada com o código -259.

Solução de problemas

A importação faz uma única tentativa, sem novas tentativas automáticas. Qualquer falha, seja no download, na soma de verificação, na distribuição ou no serviço de distribuição perdendo o job, coloca a imagem em failed e cria uma entrada no log de segurança. O administrador inicia uma nova tentativa com a mesma operação de importação. Reiniciar o dispatcher no meio da operação não repete uma importação incompleta; ele a marca como falha.

Um resultado parcial (partial_active) não é revertido: os pools que têm uma cópia a mantêm. Verifique o mapa de distribuição para ver quais pools não receberam uma cópia e importe a mesma versão novamente para entregar as cópias que faltam.

Código de falha	Significado	Ação
-48005	O formato da imagem não é elegível para importação; zfs é obrigatório	Selecione uma imagem elegível para importação no catálogo da fonte
-48002	O catálogo da fonte não contém nenhuma imagem com esse identificador	Obtenha o catálogo da fonte novamente: o manifesto pode ter mudado
-48003	A imagem já está sendo importada	Aguarde o resultado da importação atual; não é necessário reiniciá-la
-48004	A imagem está sendo removida	Aguarde a conclusão da remoção
-48006	A entrada do manifesto falha na validação: versão, tamanho mínimo, tamanho, tamanhos de setor, soma de verificação, caminho do arquivo, um tipo de SO ou de personalização do convidado desconhecido, um uuid repetido	Corrija o manifesto na fonte
-48007	Um pool especificado não existe, ou o cluster não tem pools com proprietário	Verifique a lista de pools; confirme que o cluster tem um pool com proprietário
-48008	Já existe no catálogo uma imagem com esse identificador sob uma fonte ou versão diferente	O identificador da imagem é globalmente único: atribua à imagem o seu próprio uuid no manifesto
-46002	Não existe nenhuma fonte com esse identificador	Use um identificador atual da lista de fontes
-46012	O host da fonte resolve para uma faixa proibida	Mova a biblioteca para um endereço fora de loopback, link-local, faixas privadas da RFC 1918, CGNAT, a "rede zero" e o endereço de broadcast
-46020	A fonte está indisponível: falha de rede, tempo limite ou uma resposta diferente de 2xx	Verifique se a URL da biblioteca é acessível a partir da rede do cluster
-46021	O manifest.json não pode ser interpretado como JSON	Corrija a sintaxe do manifesto
-46022	A versão do esquema do manifesto é maior que a versão suportada	Atualize o manifesto para uma versão de esquema suportada
-46023	O manifesto falha na validação do esquema: uma entrada não tem campos obrigatórios	Adicione name, version, format, url_path, size, sha256
-49005	Um administrador de VDC não especificou um VDC: apenas o papel Cluster master importa uma imagem compartilhada do cluster	Especifique o seu VDC na requisição de importação
-49006	O VDC especificado está fora do escopo de quem faz a chamada	Especifique um VDC no qual você tenha um papel
-403	Acesso negado	Verifique o acesso à fonte, o privilégio e a propriedade: uma fonte compartilhada do cluster está disponível apenas para o papel Cluster master; um administrador de VDC precisa de uma fonte atribuída ao seu VDC; apenas o proprietário da imagem ou o papel Cluster master pode importar uma nova versão de uma imagem existente
-503	O log de segurança não aceitou o registro de intenção	A importação não foi iniciada e nada mudou; restaure a disponibilidade do log e tente novamente
-48001	Erro de banco de dados	Tente a importação novamente; se o erro se repetir, entre em contato com o suporte

Veja também

• Biblioteca de imagens de SO — o modelo da fonte, do catálogo e da distribuição entre os pools.
• Como remover uma imagem de SO — a operação inversa, com verificação de dependências.
• Como criar, remover e migrar uma máquina virtual — criação de uma VM a partir de uma imagem importada.

Métodos da API

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