Skip to main content
Uma imagem é o disco do qual um volume de inicialização de instância é clonado. As imagens são recursos regionais no serviço de computação. Gerencie o login da instância por meio do acesso SSH com IAM.

Os nomes são tags móveis

Como debian-13 e debian-13:20260807 diferem, e quando a tag se move abaixo de você.

Importação

URL pré-signado, conversão em segundo plano e o que a coluna de status diz.

O que o anúncio mostra

Por que uma compilação que você publicou ontem está faltando e o sinalizador que a traz de volta.

​
Imagens

​
Suas imagens e o catálogo da plataforma

GET /v1/images retorna somente imagens pertencentes à sua conta selecionada. Suas imagens permanecem privadas para essa conta; publicar em outras contas não é suportado. Imagens não têm campo ou filtro de visibility. Use GET /v1/image-catalog para escolher uma imagem para uma nova instância. Sua matriz de categories agrupa imagens sob platform e account. Cada entrada descreve a compilação ativa atual de um nome de imagem e arquitetura, com seu ID, CRN, SO, tamanhos mínimos de disco e memória e data de fim de vida, quando conhecida. O catálogo omite tags e metadados operacionais. Ele aceita filtros name, os e architecture e pagina com limit e marker em ambas as categorias. As imagens de plataforma são imagens de SO mantidas disponíveis para todas as contas. Seus CRNs pertencem à conta da platform (crn:compute:<region>:platform:image/<name>/architecture/<arch>/version/<version>). Selecionar uma imagem de plataforma não lhe dá permissão para alterá-la ou excluí-la.

​
Um nome é uma tag, uma versão é uma compilação

Cada linha de imagem tem um name e uma version, e eles fazem trabalhos diferentes.

nome

Uma tag móvel, compartilhada por cada compilação por trás dela. debian-13 aponta para qualquer compilação que seja atual para seu (name, architecture).

versão

Identifica uma compilação dentro desse nome e deve ser exclusivo lá. Omita-o na importação e o servidor carimba um timestamp UTC, então cada compilação é endereçável, independentemente de você ter rotulado uma ou não.
Isso dá três maneiras de nomear uma imagem no lançamento, e a escolha é uma escolha sobre reprodutibilidade: is_current na imagem diz se é o alvo atual do nome. Versões ativas mais antigas permanecem inicializáveis por id e por name:version. A promoção move um ponteiro; a retirada ou exclusão torna uma compilação indisponível para novos lançamentos.
Publicar uma versão que o nome já carrega retorna 409. Ele não substitui a compilação existente ou move o ponteiro atual. Publique uma nova versão; não exclua a compilação existente para fazer uma nova tentativa de substituí-la.

​
Importar uma imagem

Nenhum byte de imagem flui através da API. Você carrega o disco para um bucket que você controla — o armazenamento de objetos do Basaltic, S3, MinIO, qualquer coisa — com um cliente S3 multiparte real e, em seguida, entrega um URL GET pré-assinado. Importe uma imagem Linux AMD64 (x86-64). O campo architecture aceita apenas amd64, que também é o padrão; imagens ARM não são suportadas. Defina os para almalinux, alpine, arch, centos, debian, fedora, opensuse, rhel, rocky ou ubuntu. Para outra distribuição Linux, use linux (o padrão). Mantenha a versão no campo separado os_version. Arquitetura não suportada ou valores de SO retornam 400 INVALID_INPUT antes que uma importação seja criada.
1

Registrar a importação

Vá para Compute → Images na região de destino e escolha Import image. Digite Name e uma Version opcional. Cole o URL HTTPS GET pré-assinado em Source URL. Escolha um Operating system e, opcionalmente, insira OS version. Escolha Other / generic Linux para outra distribuição. Architecture é corrigida para AMD64 (x86-64). Deixe Versão em branco para um timestamp UTC gerado pelo servidor.Escolha Import image. Import accepted informa o status de importação retornado e abre a página de imagem. A imagem é privada para sua conta. Uma vez ativo, ele se torna a compilação atual para seu nome e arquitetura, mudando lançamentos futuros que usam o nome nu.
A resposta é 202 com status: "importing". A plataforma detecta automaticamente qcow2, raw, vmdk, vhd, vhdx e vdi do disco baixado e converte-o em uma base bruta. Você não fornece um formato.
2

Aguarde a busca e conversão

Um worker obtém o URL uma vez, converte o disco e o importa. O URL não é retido depois, então ele só precisa permanecer válido o tempo suficiente para ser lido.
3

Poll até ativo

No console, use Refresh na página da imagem ou Compute → Images. A coluna Status mostra o erro da última tentativa de importação ao tentar novamente, ou a falha do terminal quando o status atinge erro. O mesmo erro é visível na página de imagem.Através da API:
active significa inicializável, e size_bytes é preenchido a partir do que foi realmente escrito. error significa que a importação desistiu; leia faults para o motivo.
source_url deve ser https, e não deve resolver para um endereço privado. Loopback, RFC 1918 e intervalos privados ULA, endereços de metadados e link-local são todos recusados — na URL original e novamente em cada redirecionamento, contra o endereço que ele realmente resolve. Um intervalo acessível apenas dentro da VPC não pode ser importado de; presign de algo publicamente resolvível.
Uma entrada em faults não significa que a importação foi interrompida. Cada tentativa falhada do mesmo código atualiza essa linha e incrementa occurrences em vez de adicionar outra, e a importação é re-tentada. A linha que chega a error é a que diz que nada mais será tentado.

​
Publicar sem alternar a tag

current padrão para true: uma importação concluída se torna a versão atual do nome e lançamentos futuros desse nome nu inicializam os novos bits. Envie "current": false para estagiar uma compilação sem alternar, e depois promova-a mais tarde:
A promoção é atômica — qualquer coisa que fosse atual para esse (name, architecture) é rebaixado na mesma operação. A mesma chamada é como você roll back: aponte o nome para a compilação mais antiga e os lançamentos seguem imediatamente.
A troca acontece quando a importação completa, não quando é aceite. Uma nova compilação é importing por tanto tempo quanto a conversão levar, e a tag continua apontando para a compilação anterior por toda ela — então publicar sobre um nome em uso nunca deixa a resolução para algo que não pode inicializar.Apenas uma imagem active pode ser atualizada; pedir para promover uma que ainda está importando é um 400.
A promoção e o rollback são apenas APIs. A página de uma imagem no console edita sua Description, Tags e Atributos quando pertence à conta selecionada e não é excluída. Name é somente leitura. Não há controle de console que move a tag. A lista mostra onde a tag aponta, como um atual emblema na construção que ele resolve, mas movê-lo é este PATCH.

​
O que List images retorna

GET /v1/images lista as compilações e imagens atuais da sua conta que precisam de atenção. Um nome normalmente contribui com uma entrada; use o ponto de extremidade do catálogo acima para incluir imagens de plataforma. Uma compilação ativa é descartada quando uma compilação mais recente mantém seu nome. As compilações retiradas também são excluídas por padrão:
Qualquer que seja a sua idade. Essas são linhas com as quais você tem que lidar — uma importação que você está esperando, ou uma que falhou e ainda está segurando um slot de imagem até que você a exclua.
“Não atual” é o teste errado por si só. Uma versão que você preparou deliberadamente, e uma versão que você reverteu de, não são atuais e ainda são suas para agir. Só sendo substituído por algo mais novo leva uma construção fora da lista.
Use status=withdrawn ou all_versions=true para inspecionar imagens retiradas. Eles permanecem legíveis por ID e retêm seus dados, mas não podem ser lançados. No console, escolha Withdrawn em Compute → Images; Catalog restaura a exibição padrão. As imagens excluídas permanecem legíveis até que a limpeza seja concluída.
Passe all_versions=true para todo o histórico de uma tag, incluindo compilações retiradas. Os resultados são ordenados por nome, e paginados através de meta.marker como qualquer outra listagem. Os outros filtros são os, architecture, status e name. O filtro name é uma correspondência exata.

​
Fim da vida

eol_date registra o dia em que uma versão do sistema operacional deixa de receber atualizações de segurança gratuitas para uma instalação padrão. Ausente significa ninguém gravou um, o que não é o mesmo que suportado indefinidamente. Omita eol_date em uma nova compilação e ela herda a data que a versão atual do nome carrega, então a republicação de uma tag não pode silenciosamente parar de rastrear seu lançamento. Um null explícito em PATCH o limpa; omitir o campo o deixa sozinho.
As imagens da plataforma são retiradas do catálogo após um período de carência. eol_date. Eles permanecem inicializáveis por id até então, e a data é publicada bem antes para que você possa planejar a mudança.Após a retirada, a resolução do nome nu falha com uma mensagem nomeando o lançamento e a data em que ele terminou — então um lançamento que de repente não consegue encontrar some-distro-11 diz o porquê, ao invés de parecer um erro de digitação. Qualquer coisa que pinning name:version ou um id de uma imagem de plataforma retirada também pára de lançar. Você ainda pode inspecionar a imagem retirada por ID.
Imagens retiradas carregam withdrawal_reason. end_of_life identifica uma retirada de lançamento de plataforma; inspecione eol_date para sua data. legacy significa que a imagem já foi retirada e a razão original é desconhecida. O console mostra essa explicação ao lado do status. Um eol_date em sua própria imagem é armazenado e mostrado. A retirada automática de fim de vida útil se aplica apenas às imagens da plataforma; ela não retira suas próprias imagens.

​
Excluir uma imagem

Abra a imagem de Compute → Images e escolha Delete. A confirmação requer o nome da imagem. Remova as referências das instâncias e dos pools de instâncias primeiro. Após Image deletion accepted, use Refresh para seguir a limpeza até que a página mostre Image not found.Os controles de edição e exclusão exigem propriedade da conta selecionada e desaparecem durante a exclusão. As imagens do catálogo da plataforma são somente de leitura fora da conta da plataforma.
Uma imagem não utilizada retorna 202 com a imagem em status: "deleting". A limpeza é executada de forma assíncrona. GET /v1/images/{image_id} retorna esse recurso até que a limpeza termine, então retorna 404. Uma imagem de exclusão não pode ser iniciada ou alterada. Um DELETE repetido retorna 404, inclusive enquanto a limpeza está em execução. Se as instâncias ou pools de instâncias ainda fizerem referência à imagem, a exclusão retornará 409 e a deixará inalterada. A mensagem do servidor inclui ambas as contagens, incluindo zero: image is in use by 2 instances and 0 pools. Remova essas referências antes de tentar novamente. As imagens retiradas têm as mesmas verificações. Uma imagem já marcada para exclusão ainda pode ser mantida para instâncias ou pools de instâncias existentes. Nesse caso, a lista do proprietário e as respostas de detalhes incluem deletion_retention com reason: "in_use", instances e contagens de instance_pools. O console explica quais referências estão segurando a imagem. Isso significa que os dados de backup estão sendo preservados para esses recursos; isso não significa que o worker de exclusão tenha parado. A limpeza pode terminar depois que as referências forem removidas. O campo é omitido quando não há mais tais referências.
As compilações substituídas de suas próprias imagens nunca são recuperadas para você. Cada compilação que você publica mantém um slot images e seus bytes contra image_storage_gb até que você o exclua — então um pipeline que publica em cada commit precisa de uma etapa de exclusão, ou a quota se torna a etapa de exclusão.
Uma imagem retirada mantém seus dados até que a conta proprietária a exclua. Ler uma imagem de plataforma pública não concede permissão para excluí-la.

​
Tamanhos

​
enforced floor
O menor volume de inicialização que pode conter a imagem. Padrões na importação para o tamanho virtual da imagem arredondado para cima. Um lançamento ou reinstalação pedindo menos é recusado.
​
recorded, not enforced
O que a imagem está documentada para precisar. Ele é armazenado e retornado para você ler; nada impede que uma instância inicialize em um flavor abaixo dele.

​
Solução de problemas

Verifique se uma compilação mais recente tem o mesmo nome. A listagem padrão mostra uma entrada por tag, e a construção de drops substitui uma mais recente. Adicione ?all_versions=true para ver o histórico — a compilação ainda está lá e inicializável por name:version ou por id se o seu status for active.
Um name nu segue a tag, e a tag se move quando uma nova compilação é publicada como atual. Pin name:version ou um id em qualquer coisa que tem que ser reproduzível; manter o nome nu para “sempre o mais recente”.
Duas causas. Uma versão da plataforma que passou do fim de vida foi retirada — o erro nomeia a versão e a data. Ou o nome não tem versão atual, o que acontece após um PATCH com current: false na única compilação atual: a tag então aponta para nada, embora as compilações ativas por trás dela ainda sejam iniciadas por name:version. Promova um para consertá-lo.
Ler faults — uma tentativa falhada registra o motivo na linha enquanto retenta, e uma falha repetida do mesmo código gera occurrences ao invés de adicionar uma linha. As causas usuais são um URL pré-assinado que expirou antes da busca, um disco cujo formato não pode ser detectado ou não é suportado, um disco que faz referência a um arquivo de backup externo ou um host que resolve para um endereço privado e é recusado. A detecção e as verificações de arquivo de backup acontecem de forma assíncrona após o download; a aceitação não significa que o disco é válido.Note que uma importação que termina mas excede a sua quota image_storage_gb é recusada e não re-tentada: reconstruir os mesmos bytes custaria um download completo e conversão para chegar à mesma resposta.
Esse nome já carrega essa versão. Um nome é compartilhado por cada compilação por trás dele de propósito, então publique sob uma nova version ao invés de um novo nome.
Esse é o design. Apenas o catálogo da plataforma cruza contas; visibility: "public" em sua própria imagem não a compartilha, e um id de imagem pertencente a outra conta responde 404 em vez de 403, então a API nunca confirma que ela existe.

​
Próximo

Lançamento de instâncias

Variações, volumes de inicialização, cloud-init e o ciclo de vida da instância.

Pools de instâncias

Onde uma referência de imagem é resolvida uma vez, na criação, e cada réplica inicializa a mesma compilação.