Biblioteca de imágenes de SO
Problema y propósito
Una máquina virtual puede iniciarse a partir de una imagen de SO preparada en cuestión de segundos, mientras que un medio de instalación requiere decenas de minutos. Pero el disco de la nueva máquina se crea como un clon ZFS, y un clon reside en el mismo pool que su padre. Por lo tanto, la imagen ya debe estar en el pool donde se crea la máquina. Descargar gigabytes desde un servidor externo cada vez que se crea una VM no tiene sentido.
La biblioteca de imágenes separa estos dos eventos en el tiempo. Primero, el administrador importa la imagen en el clúster una sola vez y la distribuye entre los pools. Después, las máquinas se crean a partir de copias locales, sin acceder a la red externa.
Esto divide el modelo en dos partes. Fuera del clúster se encuentra la fuente
de la biblioteca: un servidor web estándar con un archivo manifest.json que enumera las
imágenes disponibles. Dentro del clúster se encuentra el catálogo de imágenes: las imágenes que ya
se han importado, con un mapa de distribución entre pools y el estado de cada copia.
La sincronización lee la primera parte; la importación llena la segunda.
La tercera característica del modelo es menos evidente. El registro de una fuente no tiene un parámetro
"qué VDC" (centro de datos virtual): el rol Cluster master crea una
fuente compartida del clúster, y un administrador de VDC crea una fuente de su propio VDC.
La importación sí tiene ese parámetro, pero deciden los derechos. El rol Cluster master importa
solo imágenes compartidas, y se ignora el VDC especificado. Un administrador de VDC debe
especificar su propio VDC: sin él, la importación se rechaza con el código -49005, y
con otro VDC, con el código -49006.
En la interfaz web de vStack Center, la biblioteca se abre desde la sección «Image library», con las pestañas «Images» y «Sources»: el catálogo de imágenes del clúster, la adición de una imagen desde una fuente, la eliminación de una imagen y el registro, la sincronización y la eliminación de fuentes. Cada operación de la biblioteca también está disponible a través de la API del clúster, mediante llamadas a la API o un sistema de automatización que realice esas llamadas. Las operaciones se enumeran al final de esta página; las estructuras de solicitud y de respuesta se encuentran en la referencia de la API.
Esta página explica el modelo. Para importar una imagen, consulte Cómo importar una imagen de SO en el clúster; para eliminar una imagen del clúster, consulte Cómo eliminar una imagen de SO.
Modelo y entidades
Fuente de la biblioteca. Un servidor externo con imágenes. Una fuente tiene un nombre, una URL raíz de la biblioteca y la hora de su última sincronización, que está vacía si todavía no se ha sincronizado. La URL debe utilizar http o https; https es obligatorio de forma predeterminada. El http sin cifrar solo se permite con autorización explícita. La URL es única dentro del clúster: la misma URL raíz no puede registrarse dos veces.
Manifiesto. El archivo manifest.json en la raíz de la fuente es un catálogo de lo que
ofrece la fuente. El propietario de la biblioteca redacta el manifiesto, y cada entrada contiene
los metadatos completos de la imagen: los obligatorios name, version, format, url_path,
size y sha256, y los opcionales description, os_type, net_link_pattern,
zero_based_link, default_shell, sector_size_logical, sector_size_physical,
guest_customization, uefi, min_size y uuid. El clúster determina por sí mismo
si una imagen puede importarse: solo pueden importarse las imágenes en formato zfs.
El campo uuid es formalmente opcional, pero la importación lo utiliza para encontrar la imagen en
el manifiesto: una entrada sin uuid no puede importarse. El identificador es
único a nivel global: el manifiesto no debe contener dos entradas con el mismo uuid.
Imagen en el catálogo del clúster. Una imagen importada se direcciona mediante un identificador sustituto (UUID). Los nombres de las imágenes no son únicos, por lo que las operaciones utilizan el identificador y no el nombre. Una imagen tiene una etapa del ciclo de vida y un mapa de su distribución real entre pools.
Copia en un par nodo → pool. La distribución se realiza por pool, y cada par nodo → pool tiene su propio resultado. Esto explica el estado "no distribuida en todas partes" y la dependencia inversa: los discos de las VM en un pool son clones ZFS de la copia de la imagen en ese pool concreto.
| Entidad | Se direcciona mediante | Pertenece a |
|---|---|---|
| Fuente de la biblioteca | Identificador entero | El clúster (compartida) o un VDC |
| Imagen en el catálogo | Identificador UUID | El VDC propietario o el clúster |
| Copia de la imagen | Un par nodo → pool | El pool |
Cómo funciona
Trabajar con la biblioteca implica ocho operaciones, cada una con su propio privilegio.
| Tarea | Modo | Privilegio |
|---|---|---|
| Registrar o reconfigurar una fuente | Síncrono | Manage Image Library |
| Eliminar una fuente | Síncrono | Manage Image Library |
| Ver las fuentes disponibles | Síncrono | View Image Library |
| Leer el catálogo de la fuente | Síncrono | Sync Image Library |
| Importar una imagen en el clúster | Asíncrono | Import Golden Image |
| Ver el catálogo de imágenes del clúster | Síncrono | View Image Catalog |
| Obtener el mapa de dependencias de una imagen | Síncrono | View Image Dependencies |
| Eliminar una imagen del clúster | Síncrono | Remove OS Image |
Todos los privilegios tienen como ámbito el VDC correspondiente; el rol Cluster master tiene ámbito global. El derecho a ver las dependencias es independiente del derecho a eliminar imágenes: la visualización puede concederse de forma amplia, mientras que la eliminación no.
La sincronización lee el manifiesto, no las imágenes
La sincronización descarga solo manifest.json y devuelve el catálogo de imágenes
de la fuente. No se transfiere ningún byte de las imágenes, por lo que la operación es económica y
segura. También actualiza la hora de la última sincronización de la fuente. Una imagen en un
formato no admitido no desaparece del catálogo: se devuelve con un indicador
"no apta para importación", que muestra por qué la importación no la aceptará.
Las solicitudes a URL externas están protegidas contra la sustitución del destino. Se comprueban el esquema (solo http o https) y el resultado de la resolución de nombres. El clúster rechaza las direcciones de loopback, las de enlace local (link-local), incluida la dirección del servicio de metadatos, los rangos privados RFC 1918, el espacio de direcciones compartido de NAT de nivel de operador (CGNAT), la "red cero" y la dirección de difusión. Las formas IPv6 encubiertas con IPv4 mapeado se reducen a IPv4 y se comprueban con la misma lista; se bloquean las direcciones IPv6 nativas de loopback, de enlace local y las direcciones locales únicas (ULA). El cuerpo del manifiesto está limitado a 100 MB.
La importación distribuye la imagen entre los pools
La importación responde de inmediato, confirmando que se aceptó el trabajo y no que la imagen
esté lista: el trabajo continúa en segundo plano. El servicio de distribución dedicado
vstack-center-image-distributor transfiere los bytes mediante un protocolo de dos fases;
el despachador del clúster solo orquesta el proceso. Un único componente escribe en
el catálogo de imágenes, por lo que no hay escrituras concurrentes en el estado de la imagen.
El progreso y el resultado son visibles en el catálogo de imágenes del clúster: una imagen tiene una etapa y un mapa de distribución con una entrada por cada pool.
| Etapa | Significado | Acción |
|---|---|---|
importing | La imagen se está descargando y distribuyendo | Espere |
active | La imagen se ha distribuido a todos los pools seleccionados | Se pueden crear VM |
partial_active | Algunos pools no recibieron una copia | Complete la distribución importando de nuevo la misma versión |
failed | El intento falló por completo | Investigue la causa y reinicie la importación |
deleting | La imagen se está eliminando | Espere el resultado; la importación y otra eliminación se rechazan con el código -48004 |
No hay reintentos automáticos, por diseño. Cualquier fallo (descarga, suma de comprobación,
distribución o pérdida del trabajo por parte del servicio) establece la imagen en failed y
crea una entrada de registro. El administrador inicia un reintento importando de nuevo.
La misma lógica se aplica tras reiniciar el despachador: las importaciones incompletas se
marcan como fallidas, en lugar de reintentarse de forma silenciosa.
El éxito parcial no se revierte. Los pools que recibieron una copia la conservan; importar de nuevo la misma versión entrega las copias restantes.
La creación de la VM espera a un pool preparado
Mientras la imagen tenga un mapa de distribución, su copia en el pool seleccionado para
la creación de la máquina debe estar activa. De lo contrario, la creación de la VM se rechaza con el código
-259 antes de crear nada. Por lo tanto, el orden de las operaciones invierte el
enfoque habitual: primero la imagen en el pool y después la máquina en ese pool.
Para obtener detalles sobre la creación, consulte
Cómo crear, eliminar y migrar una máquina virtual.
Visibilidad y pertenencia
Las imágenes y las fuentes tienen el mismo ámbito de visibilidad. Cluster master ve todo. Un administrador de VDC ve los objetos compartidos del clúster más los objetos asignados a sus VDC. Un principal sin VDC solo ve los objetos compartidos. La URL de la fuente solo se muestra a su propietario; los demás no pueden verla.
La visibilidad y la pertenencia son derechos distintos. Un administrador de VDC no puede eliminar una imagen que se ha hecho visible para su VDC mediante una concesión de visibilidad: la eliminación requiere la pertenencia. La importación de una nueva versión de una imagen existente también está disponible solo para el propietario o el rol Cluster master. Las imágenes inexistentes y las invisibles devuelven la misma respuesta, "no encontrada", por lo que la respuesta no puede revelar la existencia de una imagen restringida ajena.
Cada cambio se registra primero
El registro y la eliminación de fuentes, la sincronización, la importación y la eliminación
de imágenes escriben un registro de intención en el registro de seguridad
antes de la propia acción. La escritura del registro tiene un límite
de tiempo de dos segundos de forma predeterminada. Si el registro no acepta el evento, la
operación no se inicia y devuelve el código -503. No cambia nada ni en el
catálogo ni en los nodos.
Las lecturas correctas de la lista de fuentes y del catálogo de imágenes no se registran,
pero una denegación de acceso en cualquier operación con imágenes deja una entrada
auth.image_library_access_denied. La visualización de dependencias se registra como un evento
config.image_dependencies_viewed. Las etapas de la eliminación tienen sus propias entradas:
config.image_remove_initiated, config.image_removed,
config.image_remove_partial, config.image_remove_failed y
config.image_remove_blocked_dependencies. Cada
registro contiene una asociación con un VDC
o una indicación de que el objeto se comparte en todo el clúster,
el ámbito de acceso del autor de la llamada y su identificador. El registro no contiene rutas
de almacenamiento ni la topología de los pools, solo identificadores de nodos y recuentos agregados.
Limitaciones
Solo puede importarse el formato zfs. Una copia de la imagen en un pool es un dataset ZFS
a partir del cual se clonan los discos de las máquinas, por lo que no hay dónde distribuir otro
formato. Una imagen en otro formato aparece en el catálogo de la fuente como no apta
para importación, y la propia importación devuelve el código -48005. Solución alternativa: incluya una variante zfs
de la imagen en el manifiesto.
El http sin cifrar está bloqueado de forma predeterminada. La biblioteca proporciona los datos a partir
de los cuales se construyen todas las máquinas del clúster, por lo que el canal debe poder verificarse. Sin
autorización explícita, una URL http se rechaza con el código -46011. Solución alternativa:
publique la fuente mediante https; reserve la autorización para un entorno de pruebas aislado.
Las direcciones internas están prohibidas. Un host de fuente que se resuelve en loopback,
enlace local, la dirección del servicio de metadatos, un rango privado RFC 1918, CGNAT, la
"red cero" o la dirección de difusión se rechaza con el código -46012.
La restricción no puede levantarse: impide que el clúster acceda a sí mismo
por indicación de un tercero. Una biblioteca en una red interna queda totalmente
sujeta a esta restricción. Solución alternativa: traslade la biblioteca a una dirección fuera de los
rangos enumerados.
Eliminar una fuente no elimina sus imágenes. Eliminar una fuente borra solo el registro y sus vínculos con VDC; las imágenes importadas desde ella permanecen en el catálogo, pero pierden su vínculo con la fuente. Un administrador de VDC solo elimina la fuente de su VDC; una fuente compartida del clúster la elimina el rol Cluster master. Para cambiar la URL, no es necesario eliminar la fuente: el registro con un identificador de fuente existente sobrescribe su nombre y su URL.
La importación requiere el servicio de distribución. Sin un
vstack-center-image-distributor desplegado (y su vhost obligatorio imgdistr_vhost),
no hay nada que transfiera los bytes. La única solución alternativa es desplegar el
servicio; la sincronización no implica al servicio de distribución y lee
solo el manifiesto.
Las comprobaciones de dependencias pueden ser incompletas. El mapa de clones se compone consultando todos los nodos, y un nodo inaccesible no se incluye en la respuesta; se marca como omitido. Solución alternativa: espere a que el nodo vuelva y obtenga el mapa de nuevo; en esta situación, la eliminación seguirá teniendo un resultado parcial.
Lecturas adicionales
- Cómo importar una imagen de SO en el clúster: lectura del catálogo de la fuente, inicio de la importación y supervisión de la distribución entre pools.
- Cómo eliminar una imagen de SO: comprobación de dependencias, eliminación irreversible e investigación de un resultado parcial.
- Cómo crear, eliminar y migrar una máquina virtual: selección de una imagen y de un pool al crear una máquina.
Métodos de la API
Las operaciones de la API tratadas en esta página son os-library-set,
os-library-delete, os-library-list, os-library-sync, os-image-import,
os-image-from-vm, golden-images-list, golden-image-clones y
golden-image-remove; consulte la
referencia de la API.