> ## 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. # Imágenes > Importe una imagen de disco y seleccione compilaciones actuales o con versiones para las instancias. Una imagen es el disco desde el que se clona el volumen de arranque de una instancia. Las imágenes son recursos regionales en el servicio de cómputo. Administre el inicio de sesión de la instancia a través de [SSH access with IAM](/es/compute/ssh). Cómo difieren `debian-13` y `debian-13:20260807`, y cuando la etiqueta se mueve debajo de usted. URL pre-signada, conversión en segundo plano y lo que la columna de estado te dice. Por qué falta una compilación que publicaste ayer y el indicador que la devuelve. ## Imágenes ### Tus imágenes y el catálogo de la plataforma `GET /v1/images` devuelve solo las imágenes que pertenecen a la cuenta seleccionada. Las imágenes permanecen privadas para esa cuenta; no se admite publicarlas en otras cuentas. Las imágenes no tienen campo de `visibility` o filtro. Use `GET /v1/image-catalog` para elegir una imagen para una nueva instancia. Su matriz de `categories` agrupa imágenes bajo `platform` y `account`. Cada entrada describe la compilación activa actual de un nombre de imagen y arquitectura, con su ID, CRN, SO, tamaños mínimos de disco y memoria, y fecha de fin de vida cuando se conoce. El catálogo omite las etiquetas y los metadatos operativos. Acepta filtros `name`, `os` y `architecture` y pagina con `limit` y `marker` en ambas categorías. Las imágenes de plataforma son imágenes de SO mantenidas disponibles para cada cuenta. Sus CRN pertenecen a la cuenta de la `platform` (`crn:compute::platform:image//architecture//version/`). La selección de una imagen de plataforma no le da permiso para cambiarla o eliminarla. ### Un nombre es una etiqueta, una versión es una compilación Cada fila de imagen tiene un `name` y una `version`, y hacen diferentes trabajos. Una **etiqueta móvil**, compartida por cada compilación detrás de ella. `debian-13` apunta a la compilación actual para su `(name, architecture)`. Identifica **una compilación** dentro de ese nombre, y debe ser única allí. Omita esto en la importación y el servidor marcará una marca de tiempo UTC, de modo que cada compilación sea direccionable, independientemente de si usted la ha etiquetado o no. Esto da tres maneras de nombrar una imagen al lanzamiento, y la elección es una elección sobre la reproducibilidad: | Referencia de producto | Resuelve | | - | - | | `debian-13` | Lo que sea actual **en el momento en que se crea la instancia**. | | `debian-13:20260807` | Que compila, mientras está activa. | | Un UUID | Que compila, mientras está activa. | `is_current` en la imagen dice si es el objetivo actual del nombre. Las versiones activas más antiguas permanecen arrancables por id y por `name:version`. La promoción mueve un puntero; la retirada o eliminación hace que una compilación no esté disponible para nuevos lanzamientos. Publicar una versión cuyo nombre ya lleva devuelve `409`. No reemplaza la compilación existente ni mueve el puntero actual. Publica una nueva **versión**; no elimines la compilación existente para que un nuevo intento la sobrescriba. ### Importar una imagen No hay bytes de imagen que fluyan a través de la API. Cargas el disco a un bucket que controlas (el almacén de objetos de Basaltic, S3, MinIO, cualquiera) con un cliente S3 multiparte real y, a continuación, entregas una URL GET prefirmada. Importe una imagen de Linux AMD64 (x86-64). El campo `architecture` solo acepta `amd64`, que también es su valor predeterminado; las imágenes ARM no son soportadas. Establezca `os` a `almalinux`, `alpine`, `arch`, `centos`, `debian`, `fedora`, `opensuse`, `rhel`, `rocky` o `ubuntu`. Para otra distribución de Linux, use `linux` (el valor predeterminado). Mantenga la versión en el campo separado `os_version`. Los valores de arquitectura o sistema operativo no compatibles devuelven `400 INVALID_INPUT` antes de que se cree una importación. Vaya a **Compute → Images** en la región de destino y elija **Import image**. Ingrese **Name** y una **Version** opcional. Pegue la URL HTTPS GET prefirmada en **Source URL**. Elija un **Operating system** y opcionalmente ingrese **OS version**. Elija **Other / generic Linux** para otra distribución. **Architecture** se fija en AMD64 (x86-64). Deja Versión en blanco para una marca de tiempo UTC generada por el servidor. Elija **Import image**. **Import accepted** informa el estado de importación devuelto y abre la página de imagen. La imagen es privada para su cuenta. Una vez activa, se convierte en la compilación actual para su nombre y arquitectura, cambiando los lanzamientos futuros que usan el nombre desnudo. ```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), }) ``` La respuesta es **`202`** con `status: "importing"`. La plataforma detecta automáticamente `qcow2`, `raw`, `vmdk`, `vhd`, `vhdx` y `vdi` del disco descargado y lo convierte a una base raw. No proporciona un formato. Un worker obtiene la URL una vez, convierte el disco e importa. La URL no se conserva después, por lo que solo tiene que permanecer válida el tiempo suficiente para ser leída. En la consola, utilice **Refresh** en la página de la imagen o **Compute → Images**. La columna Estado muestra el error del último intento de importación al volver a intentarlo, o el error del terminal cuando el estado alcanza error. El mismo error es visible en la página de imagen. A través de la API: ```bash theme={null} GET /v1/images/{image_id} ``` `active` significa arrancable, y `size_bytes` se rellena de lo que se escribió realmente. `error` significa que la importación se ha dado por terminada; lea `faults` para saber la razón. **`source_url` debe ser `https`, y no debe resolverse a una dirección privada.** Los bucles, los rangos privados de RFC 1918 y ULA, las direcciones locales de enlace y de metadatos son todos rechazados — en la URL original y de nuevo en cada redirección, contra la dirección a la que realmente se resuelve. Un bucket al que solo se puede acceder desde tu VPC no se puede importar desde; presign de algo públicamente resoluble. Una entrada en `faults` no significa que la importación se ha detenido. Cada intento fallido del mismo código actualiza esa fila e incrementa las `occurrences` en lugar de agregar otra, y la importación se reintenta. La fila que llega a `error` es la que dice que no se intentará nada más. #### Publicación sin cambiar la etiqueta `current` por defecto es `true`: una importación completada se convierte en la versión actual del nombre y los lanzamientos futuros de ese nombre desnudo arrancan los nuevos bits. Enviar `"current": false` para poner en espera una compilación sin cambiar, y luego promoverla más tarde: ```bash theme={null} PATCH /v1/images/{image_id} { "current": true } ``` La promoción es atómica — cualquier otra cosa que fuera actual para ese `(name, architecture)` es degradada en la misma operación. La misma llamada es cómo **retroceder**: apunta el nombre a la compilación más antigua y los lanzamientos la siguen inmediatamente. El cambio ocurre cuando la importación **completas**, no cuando se acepta. Una nueva compilación es `importing` La etiqueta permanecerá apuntando a la compilación anterior durante todo el tiempo que dure la conversión, por lo que publicar sobre un nombre en uso nunca deja que se resuelva a algo que no se pueda arrancar. Solo una imagen `active` puede ser actualizada; pedir que se promueva una que todavía está importando es un `400`. **La promoción y la devolución son solo API.** La página de una imagen en la consola edita su **Description**, **Tags** y **Atributos** cuando es propiedad de la cuenta seleccionada y no se elimina. **Name** es de solo lectura. No hay control de consola que mueva la etiqueta. La lista muestra dónde apunta la etiqueta, como una insignia **actual** en la compilación a la que se resuelve, pero moverla es este `PATCH`. ### Lo que devuelve `List images` `GET /v1/images` muestra las compilaciones e imágenes actuales de tu cuenta que necesitan atención. Un nombre normalmente aporta una entrada; use el punto final del catálogo anterior para incluir imágenes de plataforma. Una compilación activa se elimina cuando una compilación **más reciente** mantiene su nombre. Las compilaciones retiradas también se excluyen de forma predeterminada: Sea cual sea su edad. Estas son filas con las que tienes que lidiar: una importación que estás esperando, o una que falló y todavía tiene un espacio de imagen hasta que la elimines. "No actual" es la prueba equivocada por sí misma. Una versión que has puesto en escena deliberadamente, y una versión que has revertido *de*, ambas no son actuales y ambas siguen siendo tuyas para actuar. Solo ser reemplazado por algo más nuevo toma una construcción fuera de la lista. Utilice `status=withdrawn` o `all_versions=true` para inspeccionar las imágenes retiradas. Permanecen legibles por ID y conservan sus datos, pero no pueden ser lanzados. En la consola, elija **Retirado** en **Compute → Images**; **Catálogo** restablece la vista predeterminada. Las imágenes eliminadas permanecen legibles hasta que finaliza la limpieza. Pase `all_versions=true` para el historial completo de una etiqueta, incluyendo las compilaciones retiradas. Los resultados se ordenan por nombre, y se paginan a través de `meta.marker` como cualquier otro listado. Los otros filtros son `os`, `architecture`, `status` y `name`. El filtro `name` es una coincidencia exacta. ### Fin de vida `eol_date` registra el día en que una versión del sistema operativo deja de recibir actualizaciones de seguridad gratuitas para una instalación predeterminada. Ausente significa que **nadie ha grabado uno**, lo cual no es lo mismo que soportado indefinidamente. Omita `eol_date` en una nueva compilación y hereda la fecha que lleva la versión actual del nombre, por lo que volver a publicar una etiqueta no puede detener silenciosamente el seguimiento de su lanzamiento. Un `null` explícito en `PATCH` lo borra; omitir el campo lo deja solo. **Las imágenes de la plataforma se retiran del catálogo un período de gracia después de su `eol_date`.** Se mantienen arrancables por id hasta entonces, y la fecha se publica con bastante antelación para que puedas planificar el movimiento. Después de retirar, la resolución del nombre nulo falla con un mensaje que nombra la versión y la fecha en que terminó — así que un lanzamiento que de repente no puede encontrar `some-distro-11` le dice por qué, en lugar de parecer un error tipográfico. Cualquier cosa que pin `name:version` o un id de una imagen de plataforma retirada también deja de lanzar. Aún puede inspeccionar la imagen retirada por ID. Las imágenes retiradas llevan `withdrawal_reason`. `end_of_life` identifica una retirada de la versión de la plataforma; inspeccione `eol_date` para su fecha. `legacy` significa que la imagen ya fue retirada y su razón original es desconocida. La consola muestra esta explicación junto al estado. Una `eol_date` en **su propia** imagen es almacenada y mostrada. La retirada automática de fin de vida se aplica solo a las imágenes de la plataforma; no retira sus propias imágenes. ### Eliminar una imagen Abra la imagen desde **Compute → Images** y elija **Delete**. La confirmación requiere el nombre de la imagen. Elimine las referencias de las instancias y los grupos de instancias primero. Después de **Image deletion accepted**, utilice **Refresh** para seguir la limpieza hasta que la página muestre **Image not found**. Los controles de edición y eliminación requieren la propiedad de la cuenta seleccionada y desaparecen al eliminar. Las imágenes del catálogo de la plataforma son de solo lectura fuera de la cuenta de la 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) ``` Una imagen no utilizada devuelve `202` con la imagen en `status: "deleting"`. La limpieza se ejecuta de forma asíncrona. `GET /v1/images/{image_id}` devuelve ese recurso hasta que la limpieza termina, luego devuelve `404`. Una imagen de eliminación no puede ser lanzada o cambiada. Una `DELETE` repetida devuelve `404`, incluso mientras la limpieza está en ejecución. Si las instancias o los grupos de instancias todavía hacen referencia a la imagen, la eliminación devuelve `409` y la deja sin cambios. El mensaje del servidor incluye ambos recuentos, incluyendo cero: `image is in use by 2 instances and 0 pools`. Elimine esas referencias antes de volver a intentarlo. Las imágenes retiradas tienen las mismas comprobaciones. Una imagen ya marcada para su eliminación puede conservarse para instancias o grupos de instancias existentes. En ese caso, la lista de su propietario y las respuestas de detalle incluyen `deletion_retention` con `reason: "in_use"`, `instances` y `instance_pools` cuentas. La consola explica qué referencias están sosteniendo la imagen. Esto significa que se están conservando los datos de respaldo para esos recursos; no significa que el eliminador se haya detenido. La limpieza puede terminar después de eliminar las referencias. El campo se omite cuando no quedan referencias de este tipo. Las compilaciones reemplazadas de **sus propias** imágenes nunca se recuperan para usted. Cada compilación que publicas tiene un espacio para `images` y sus bytes contra `image_storage_gb` hasta que lo eliminas, por lo que una canalización que publica en cada confirmación necesita un paso de eliminación, o la cuota se convierte en el paso de eliminación. Una imagen retirada conserva sus datos hasta que la cuenta propietaria la elimina. Leer una imagen de plataforma pública no otorga permiso para eliminarla. ### Tamaños El volumen de arranque más pequeño que puede contener la imagen. Valores predeterminados al importar al tamaño virtual de la imagen redondeado. Un lanzamiento o reinstalación que pide menos se rechaza. Lo que la imagen está documentada para necesitar. Se almacena y se devuelve para que usted lo lea; nada detiene a una instancia de arranque en un tipo de instancia debajo de ella. ## Solución de problemas Comprueba si una versión más reciente tiene el mismo nombre. La lista predeterminada muestra una entrada por etiqueta, y las caídas generan una más nueva que la ha reemplazado. Añada `?all_versions=true` para ver el historial — la compilación todavía está allí y se puede arrancar por `name:version` o por id si su estado es `active`. Un `name` va tras la etiqueta, y la etiqueta se mueve cuando una nueva compilación se publica como actual. Pin `name:version` o un id en cualquier cosa que tenga que ser reproducible; mantener el nombre desnudo para "siempre la última". Dos causas. Se ha retirado una versión de plataforma que ha pasado el final de su vida útil; el error indica la versión y la fecha. O el nombre no tiene versión actual, lo que sucede después de un `PATCH` con `current: false` en la única compilación actual: la etiqueta entonces apunta a nada, aunque las compilaciones activas detrás de ella todavía se lanzan por `name:version`. Promover a uno para arreglarlo. Leer `faults` — un intento fallido registra la razón en la fila mientras se reintenta, y un fallo repetido del mismo código genera `occurrences` en lugar de agregar una fila. Las causas habituales son una dirección URL prefirmada que ha caducado antes de la obtención, un disco cuyo formato no se puede detectar o no es compatible, un disco que hace referencia a un archivo de respaldo externo o un host que se resuelve en una dirección privada y se rechaza. La detección y las comprobaciones de archivos de respaldo se realizan de forma asincrónica después de la descarga; la aceptación no significa que el disco sea válido. | Código | Significado y recuperación | | - | - | | `IMAGE_IMPORT_START_FAILED` | La importación no pudo programarse. Vuelva a intentar la importación. | | `IMAGE_CONVERSION_FAILED` | El disco descargado no se pudo convertir. Corrija la fuente y vuelva a intentarlo. | | `IMAGE_DELETE_FAILED` | Error al desmontar la imagen. Vuelve a intentar la eliminación. | Tenga en cuenta que una importación que termina pero excede su cuota `image_storage_gb` es rechazada y **no** reintentada: reconstruir los mismos bytes costaría una descarga completa y conversión para llegar a la misma respuesta. Ese nombre ya lleva esa versión. Un nombre es compartido por cada compilación detrás de él a propósito, así que publique bajo una nueva `version` en lugar de un nuevo nombre. Ese es el diseño. Solo el catálogo de la plataforma cruza cuentas; `visibility: "public"` en tu propia imagen no la comparte, y un id de imagen perteneciente a otra cuenta responde `404` en lugar de `403`, por lo que la API nunca confirma que existe.