> ## Documentation Index > Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt > Use this file to discover all available pages before exploring further. # Imagens > Importe uma imagem de disco e selecione compilações atuais ou com controle de versão para instâncias. 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](/pt/compute/ssh). Como `debian-13` e `debian-13:20260807` diferem, e quando a tag se move abaixo de você. URL pré-signado, conversão em segundo plano e o que a coluna de status diz. 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::platform:image//architecture//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. 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)`. 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: | Referência de Produto | Resolve | | - | - | | `debian-13` | O que for atual **no momento em que a instância é criada**. | | `debian-13:20260807` | Que compilação, enquanto estiver ativo. | | Um UUID | Que compilação, enquanto estiver ativo. | `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. 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. ```bash theme={null} POST https://compute.sa-saopaulo-1.basaltic.sh/v1/images { "name": "app-base", "version": "20260807", "source_url": "https://bucket.s3.example.com/app-base.qcow2?X-Amz-Signature=...", "os": "debian", "os_version": "13", "min_disk_gb": 10 } ``` ```bash theme={null} basaltic compute image create --name app-base --version 20260807 \ --source-url 'https://bucket.s3.example.com/app-base.qcow2?X-Amz-Signature=...' \ --os debian --os-version 13 --min-disk-gb 10 ``` ```go theme={null} img, err := compute.New(cfg).CreateImage(ctx, &compute.ImageCreateRequest{ Name: "app-base", Version: basaltic.String("20260807"), SourceURL: "https://bucket.s3.example.com/app-base.qcow2?X-Amz-Signature=...", OS: basaltic.String("debian"), OSVersion: basaltic.String("13"), MinDiskGB: basaltic.Int(10), }) ``` 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. 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. 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: ```bash theme={null} GET /v1/images/{image_id} ``` `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: ```bash theme={null} PATCH /v1/images/{image_id} { "current": true } ``` 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. ```bash theme={null} DELETE /v1/images/{image_id} ``` ```bash theme={null} basaltic compute image delete ``` ```go theme={null} img, err := compute.New(cfg).DeleteImage(ctx, imageID) ``` 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 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. 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. | Código | Significado e recuperação | | - | - | | `IMAGE_IMPORT_START_FAILED` | A importação não pôde ser agendada. Tente novamente a importação. | | `IMAGE_CONVERSION_FAILED` | O disco baixado não pôde ser convertido. Corrija a fonte e tente novamente. | | `IMAGE_DELETE_FAILED` | A desmontagem da imagem falhou. Tente novamente a exclusão. | 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.