Importação de Imagens Customizadas

Visão Geral

A funcionalidade de importação de imagens customizadas permite que você adicione suas próprias imagens de máquinas virtuais Linux à Magalu Cloud. Atualmente, apenas imagens Linux são suportadas, pois o processo de inicialização da plataforma depende do cloud-init, agente nativo para configuração automática de rede, hostname e chaves SSH.

Pré-requisitos​ obrigatórios

Para que o processo de importação funcione corretamente na Magalu Cloud, alguns requisitos são obrigatórios:

PRÉ-REQUISITOS DE ARQUIVO DA IMAGEM:

• Formato QCOW2: Sua imagem deve estar no formato QCOW2 (QEMU Copy-On-Write).

  Esse formato é otimizado para ambientes de virtualização, pois armazena apenas modificações feitas na imagem base, facilitando o gerenciamento e a distribuição.

  Caso sua imagem estiver em outro formato (como .vmdk, .vhd ou .raw), utilize a ferramenta qemu-img para convertê-la:

  qemu-img convert -f <formato-origem> -O qcow2 <arquivo-origem> <arquivo-destino>.qcow2

• Tamanho máximo: A imagem não pode ultrapassar 20GB

• Upload para bucket MGC: Faça o upload da imagem .qcow2 para um bucket no Object Storage da MGC.

• Disponibilidade da URL: Gere uma URL pré-assinada para a imagem.

  • Importante: Configure a URL com prazo de expiração maior que 12 horas, garantindo tempo suficiente para o processo de importação.
  • Esta URL será utilizada durante o processo de importação

• Arquitetura suportada: Atualmente apenas imagens na arquitetura x86/64 podem ser importadas.

PRÉ-REQUISITOS DE CONFIGURAÇÃO DA IMAGEM:

• Agente de inicialização:

  • Instale e habilite o cloud-init.
  • Ele configura automaticamente o hostname, a rede e injeta a chave SSH pública no primeiro boot da VM, permitindo que você se conecte de forma segura à sua nova instância.

• Servidor SSH:

  • Instale e habilite o openssh-server
  • O serviço deve iniciar automaticamente junto com o sistema operacional, garantindo acesso remoto logo após a inicialização da instância.

• Particionamento e redimensionamento de disco:

  • Configure a imagem para permitir expansão automática da partição e do sistema de arquivos.
  Informação

  Na MGC, você pode iniciar uma instância com um disco maior do que a imagem original. Sem essa configuração, apenas o tamanho original será utilizável (ex.:uma imagem de 5GB em um disco de 20GB continua limitada a 5GB). O cloud-init automatiza esse redimensionamento na primeira inicialização da instância.

• Chaves SSH (Keypairs)

  • O acesso inicial à instância deve ser feito exclusivamente via chave SSH.
  • O cloud-init injeta automaticamente a chave pública fornecida durante a criação da VM no arquivo ~/.ssh/authorized_keys do usuário principal da imagem.
  • A chave privada permanece com você, garantindo autenticação segura e sem senha.
  • Se esse processo não estiver configurado corretamente, sua instância ficará inacessível.

• Configuração de rede

  • Evite endereços MAC fixos
    • Remova endereços MAC codificados em arquivos de rede (ex.: ifcfg-eth0).
    • Isso evita conflitos e falhas de inicialização, já que a Magalu Cloud atribui o MAC dinamicamente em cada VM.
  • DHCP obrigatório
    • Configure a imagem para obter endereço IP automaticamente via DHCP.
    • Caso a imagem use configurações de rede estáticas (IP fixo) ou não consiga se comunicar com o servidor DHCP da plataforma, a VM será criada, mas permanecerá inacessível permanentemente.
  • Firewall interno
    • Desabilite o firewall interno da imagem e utilize apenas os grupos de segurança da Magalu Cloud.
  Dica

  Antes de importar, valide se a interface de rede principal da imagem está habilitada para receber as configurações de rede fornecidas pela infraestrutura da Magalu Cloud.

Parâmetros de Configuração

Campos Obrigatórios

Campo	Descrição	Formato	Exemplo
name	Nome da imagem customizada. O nome deve ser único dentro do tenant e não pode conter caracteres especiais (permitidos: letras, números, traços e underscores)	String (1-255 caracteres)	"minha-imagem-nginx"
url	URL HTTPS do arquivo .qcow2	String (URL válida HTTPS)	"https://bucket.mgc.com/imagem.qcow2"
platform	Sistema operacional	"linux"	"linux"
license	Tipo de licença	"unlicensed"	"unlicensed"
architecture	Arquitetura da imagem	"x86/64"	"x86/64"
requirements.vcpu	vCPUs mínimas necessárias	Inteiro > 0	4
requirements.ram	RAM mínima em GB	Inteiro > 0	8
requirements.disk	Espaço em disco mínimo em GB	Inteiro > 0	100

Informação

Como aceitamos somente imagens Linux no momento, use license: "unlicensed".

Campos Opcionais

Campo	Descrição	Formato	Padrão
description	Descrição da imagem	String (1-200 caracteres)	-
version	Versão da imagem	String	-
uefi	Utiliza UEFI para boot	Boolean	false

Status da Imagem

Durante o ciclo de vida da imagem, ela passará pelos seguintes status:

Status	Descrição
importing	A imagem está sendo importada
active	A imagem está ativa e pronta para uso
deleting	A imagem está em processo de deleção
deleted	A imagem foi deletada

Como Usar

Via CLI (Command Line Interface)

mgc vm images custom create \
  --name "minha-imagem-nginx" \
  --url "https://meu-bucket.magalu.cloud/minha-imagem.qcow2" \
  --platform linux \
  --architecture x86/64 \
  --license unlicensed \
  --version 1.0 \
  --description "Imagem customizada com NGINX e PostgreSQL" \
  --uefi \
  --requirements.disk 100 \
  --requirements.ram 8 \
  --requirements.vcpu 4

Exemplo Prático de Importação de Imagem Customizada

Vamos criar uma imagem customizada com as seguintes características:

• Sistema operacional Linux
• 4 vCPUs mínimas
• 8 GB de RAM mínima
• 100 GB de disco mínimo
• Suporte a UEFI

mgc vm images custom create \
  --name "ubuntu-customizada" \
  --url "https://meu-bucket.mgc.com/ubuntu-custom.qcow2" \
  --platform linux \
  --architecture x86/64 \
  --license unlicensed \
  --description "Ubuntu 22.04 com configurações personalizadas" \
  --uefi \
  --requirements.vcpu 4 \
  --requirements.ram 8 \
  --requirements.disk 100

Recursos adicionais

• Consulte nosso tutorial sobre Como Criar sua Imagem de Cloud do Zero manualmente

• Consulte nosso tutorial sobre Como Criar sua Imagem de Cloud do Zero usando Libvirt

• Consulte nosso tutorial sobre Como Importar Imagens de Outras Clouds

• Para recomendações adicionais sobre otimização, segurança e manutenção de imagens, consulte o nosso Guia de Boas Práticas de Imagens Customizadas.

Principais Erros e Como Mitigá-los

Erro comum	Causa provável	Mitigação
Upload falha / timeout	Imagem muito grande / conexão instável	Reduzir imagem, dividir em partes, validar conectividade do bucket.
Formato inválido	Arquivo não está em QCOW2	Converter previamente com qemu-img convert.
Falha no primeiro boot	Drivers faltando, OS "hardenizado" ou config incorreta	Testar em sandbox, manter SO vanilla, garantir suporte a cloud-init.
Imagem muito lenta	Software pesado, dados persistentes incluídos	Reduzir imagem só com SO + pacotes mínimos, mover dados para volumes extras.
Erro de credenciais (falha no ssh - ssh error public key permission denied)	Senhas/chaves incluídas no ~/.ssh/authorized_keys do usuário.	Remover os arquivos ~/.ssh/authorized_keys dos usuários ubuntu, debian, fedora, e outros usuários com nomes semelhantes.
Limite de tamanho excedido	Arquivo maior que o suportado	Reduzir tamanho de disco virtual (shrink), excluir dados desnecessários.
Erros no Cloud-init	Arquivos de configuração apontando para datasources não suportados pela Magalu Cloud	Remover arquivo de configuração antes de gerar a imagem. Geralmente os arquivos de configuração do cloud-init ficam em /etc/cloud/cloud.cfg.d/.
Image name already exists	Nome da imagem duplicado	O nome deve ser único dentro do tenant.
Invalid characters in name	Nome com caracteres especiais	Não use caracteres especiais; use apenas letras, números, traços ou underscores.

Suporte

Caso ainda tenha dúvidas sobre como preparar suas imagens ou resolver problemas durante a importação, entre em contato com o suporte técnico MGC.

Esta documentação está sujeita a atualizações conforme novas funcionalidades são adicionadas à plataforma.