> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/learn-the-platform/es/modulo-8-desarrolladores-y-devops/04-terraform-packer.md).

# Terraform y Packer

Infraestructura declarativa como código para VergeOS usando el proveedor de Terraform, OpenTofu y el complemento Packer para la creación automatizada de imágenes doradas.

La infraestructura como código (IaC) aporta el mismo control de versiones, revisión por pares y repetibilidad en los que confían los equipos de software para la provisión de infraestructura. La **Proveedor Terraform de VergeOS** te permite declarar VMs, redes y usuarios en archivos de configuración HCL, mientras que el **complemento de Packer** automatiza la creación de imágenes doradas. Juntos forman una canalización declarativa: Packer crea las imágenes, Terraform despliega la infraestructura.

## Proveedor de Terraform

El proveedor Terraform de VergeOS se publica en el Registro de Terraform y es totalmente compatible con **OpenTofu** (la bifurcación de código abierto de Terraform). Te permite gestionar recursos de VergeOS mediante `terraform plan` / `terraform apply` flujos de trabajo.

### Configuración del proveedor

```hcl
terraform {
  required_providers {
    vergeio = {
      source  = "verge-io/vergeio"
      version = "~> 2.7"
    }
  }
}

provider "vergeio" {
  host     = "https://vergeos.example.com"
  username = "admin"
  password = var.vergeos_password
  insecure = true  # Establézcalo en true para certificados SSL autofirmados
}
```

| Parámetro    | Requerido | Descripción                                                          |
| ------------ | --------- | -------------------------------------------------------------------- |
| **host**     | Sí        | URL o dirección IP del sistema o inquilino de VergeOS                |
| **username** | Sí        | Nombre de usuario de VergeOS con los permisos adecuados              |
| **password** | Sí        | Contraseña para el usuario especificado (marcar como `confidencial`) |
| **insecure** | No        | Establezca `true` para aceptar certificados SSL autofirmados         |

{% hint style="success" %}
**Compatible con OpenTofu**

La configuración del proveedor es idéntica para OpenTofu. Simplemente sustituye `terraform` los comandos con `tofu` — no se requieren cambios en el código.
{% endhint %}

### Recursos

El proveedor actualmente admite cinco tipos de recursos administrados para crear y actualizar objetos de VergeOS:

| Recurso                  | Propósito                              | Atributos clave                                                                                                                                                                                  |
| ------------------------ | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`vergeio_vm`**         | Crear y administrar máquinas virtuales | `cpu_cores`, `ram`, `os_family`, `machine_type`, `ha_group`, `cluster`, `guest_agent`, `uefi`, `secure_boot`, `snapshot_profile`, `powerstate`, en línea `vergeio_drive` y `vergeio_nic` bloques |
| **`vergeio_network`**    | Configurar redes virtuales             | `network` (CIDR), `dhcp_enabled`, `dhcp_start`, `dhcp_stop`, `vnet_default_gateway`, `powerstate`                                                                                                |
| **`vergeio_user`**       | Aprovisionar usuarios                  | Administración de cuentas de usuario dentro de VergeOS                                                                                                                                           |
| **`vergeio_member`**     | Gestionar la pertenencia a grupos      | Asociar usuarios con grupos para RBAC                                                                                                                                                            |
| **`vergeio_tag_member`** | Asignar etiquetas a objetos            | Adjuntar etiquetas a VMs, redes y otros objetos de VergeOS (VergeOS v26+)                                                                                                                        |

### Fuentes de datos

Diez fuentes de datos de solo lectura te permiten consultar objetos existentes de VergeOS para usarlos en tus configuraciones:

| Fuente de datos               | Devuelve                                                          |
| ----------------------------- | ----------------------------------------------------------------- |
| **`vergeio_version`**         | Información actual de la versión de VergeOS                       |
| **`vergeio_clusters`**        | Clústeres de cómputo/almacenamiento disponibles                   |
| **`vergeio_nodes`**           | Nodos en el entorno                                               |
| **`vergeio_networks`**        | Redes virtuales existentes                                        |
| **`vergeio_vms`**             | Máquinas virtuales (filtrables por nombre, estado de instantánea) |
| **`vergeio_groups`**          | Grupos de usuarios para RBAC                                      |
| **`vergeio_mediasources`**    | ISOs y archivos multimedia cargados                               |
| **`vergeio_cloudinitfiles`**  | Archivos de configuración cloud-init disponibles                  |
| **`vergeio_resource_groups`** | Grupos de recursos de hardware (PCI, USB, grupos de vGPU)         |
| **`vergeio_tags`**            | Etiquetas configuradas en VergeOS                                 |

### Ejemplos de HCL

#### VM con unidad y NIC

Este ejemplo crea un servidor web Linux con una unidad virtio-scsi de 10 GB y una NIC conectada a una red interna:

```hcl
resource "vergeio_vm" "web_server" {
  name                 = "my-web-server"
  description          = "Servidor web"
  enabled              = true
  os_family            = "linux"
  cpu_cores            = 2
  machine_type         = "q35"
  ram                  = 2048
  powerstate           = false
  guest_agent          = true
  cloudinit_datasource = "nocloud"
  ha_group             = "web"

  # Almacenamiento
  vergeio_drive {
    name           = "Disco del SO del servidor web"
    description    = "Disco del sistema operativo"
    disksize       = 10
    interface      = "virtio-scsi"
    preferred_tier = 3
    orderid        = 0
  }

  # Redes
  vergeio_nic {
    name        = "Red del servidor web"
    description = "NIC para el servidor web"
    interface   = "virtio"
    enabled     = true
    vnet        = vergeio_network.web_network.id
  }
}
```

#### Red interna con DHCP

```hcl
resource "vergeio_network" "web_network" {
  name         = "web-internal-network"
  network      = "192.168.10.0/24"
  dhcp_enabled = true
  dhcp_start   = "192.168.10.100"
  dhcp_stop    = "192.168.10.200"
}
```

#### Consulta de VMs existentes

Usa fuentes de datos para referenciar infraestructura existente sin administrarla:

```hcl
data "vergeio_vms" "production" {
  filter_name = "prod-db"
  is_snapshot  = false
}

output "production_vms" {
  value = data.vergeio_vms.production.vms
}
```

#### Integración de Cloud-Init

El `vergeio_vm` recurso admite cloud-init para la automatización del primer arranque. El esquema del proveedor expone un `cloudinit_datasource` atributo en la VM y una `vergeio_cloudinitfiles` fuente de datos para referenciar archivos cloud-init que ya existen en VergeOS:

```hcl
resource "vergeio_vm" "app_server" {
  name                 = "app-server-01"
  os_family            = "linux"
  cpu_cores            = 4
  machine_type         = "q35"
  ram                  = 8192
  guest_agent          = true
  cloudinit_datasource = "nocloud"

  vergeio_drive {
    name           = "Disco del SO"
    disksize       = 20
    interface      = "virtio-scsi"
    preferred_tier = 2
  }

  vergeio_nic {
    interface = "virtio"
    vnet      = vergeio_network.web_network.id
  }
}
```

Para conocer la sintaxis exacta usada para adjuntar archivos cloud-init en línea en el recurso de VM (frente a referenciar archivos precargados mediante la fuente de datos), consulta el [repositorio del proveedor](https://github.com/verge-io/terraform-provider-vergeio) — la forma a nivel de campo puede evolucionar entre versiones.

### Madurez y hoja de ruta

{% hint style="warning" %}
**Consulta la cobertura actual de recursos**

El proveedor Terraform de VergeOS está en desarrollo activo, y aún no todos los objetos de VergeOS están expuestos como un recurso administrado. Algunos ejemplos de áreas que pueden no tener cobertura completa del proveedor en un momento dado incluyen el aprovisionamiento de inquilinos, la administración de perfiles de instantáneas y la configuración de redes externas/WAN.

Consulta siempre el [repositorio de GitHub](https://github.com/verge-io/terraform-provider-vergeio) y la entrada del Registro de Terraform para ver la cobertura actual de recursos y las notas de la versión antes de diseñar una configuración en torno a ellos.
{% endhint %}

## Complemento de Packer

El **Complemento de Packer para VergeOS** (`github.com/verge-io/packer-plugin-vergeio`) automatiza la creación de imágenes de VM directamente en la plataforma VergeOS. Mientras Terraform administra la infraestructura en ejecución, Packer se centra en crear las **imágenes doradas** que sirven como base para las implementaciones.

### ¿Por qué Packer?

```mermaid
flowchart LR
    A["ISO base"] --> B["Compilación de Packer"]
    B --> C["Instalar paquetes<br/>Endurecer el SO<br/>Configurar servicios"]
    C --> D["Imagen dorada"]
    D --> E["Receta de VM"]
    D --> F["Despliegue con Terraform"]
    D --> G["Aprovisionamiento manual"]

    style B fill:#4a9eff,color:#fff
    style D fill:#2ecc71,color:#fff
```

Las imágenes doradas garantizan que cada VM desplegada comience desde una base conocida, probada y endurecida. En lugar de aprovisionar un SO limpio y ejecutar scripts de configuración en cada despliegue, Packer precocina la imagen una sola vez:

* **Consistencia** — Cada VM creada a partir de la imagen es idéntica
* **Velocidad** — No hay retraso de aprovisionamiento en el primer arranque; las VMs están listas de inmediato
* **Cumplimiento** — Las líneas base de seguridad y los parches se integran durante la compilación
* **Integración de la canalización** — Desencadena recompilaciones de imágenes desde CI/CD en los días de parches del SO

### Configuración del complemento

El complemento de Packer se declara en un `required_plugins` bloque junto con un `source` y `build` para la imagen de destino. Los nombres exactos de los campos para el `source "vergeio"` bloque (punto de conexión, credenciales, tamaño de la VM, opciones de disco, etc.) deben tomarse del repositorio del complemento, ya que pueden evolucionar entre versiones:

* [`verge-io/packer-plugin-vergeio` en GitHub](https://github.com/verge-io/packer-plugin-vergeio)

Una típica `required_plugins` declaración se ve así:

```hcl
packer {
  required_plugins {
    vergeio = {
      source  = "github.com/verge-io/vergeio"
      version = ">= 0.1.1"
    }
  }
}
```

### Capacidades

A alto nivel, el complemento impulsa el ciclo de vida completo de compilación de Packer contra la API de VergeOS: crea una VM temporal, ejecuta aprovisionadores y captura la imagen resultante. Para conocer el esquema de configuración exacto, los tipos de invitados admitidos y el comportamiento de apagado/limpieza, consulta directamente el repositorio del complemento:

* [`verge-io/packer-plugin-vergeio` en GitHub](https://github.com/verge-io/packer-plugin-vergeio)

### Canalización de Packer → Recetas

Las imágenes de Packer se integran de forma natural con el sistema de **Receta** de recetas de VergeOS. Un flujo de trabajo típico:

1. **Packer** compila y endurece la imagen dorada según un cronograma (p. ej., ciclo mensual de parches)
2. La imagen se registra como una **Receta de VM** en el Marketplace de VergeOS
3. Los usuarios despliegan VMs estandarizadas a partir de la receta — ya sea a través de la UI o mediante Terraform
4. Las actualizaciones fluyen automáticamente: recompila la imagen de Packer, actualiza la receta y todos los nuevos despliegues obtienen la versión más reciente

## Patrones de flujo de trabajo de IaC

### Flujo de trabajo solo con Terraform

Para equipos que quieren infraestructura declarativa sin canalizaciones de imágenes:

```mermaid
flowchart LR
    A["Configuración HCL"] --> B["terraform plan"]
    B --> C["terraform apply"]
    C --> D["VergeOS API"]
    D --> E["VMs + redes<br/>creadas"]

    style B fill:#7b42f5,color:#fff
    style C fill:#4a9eff,color:#fff
```

### Canalización completa (Packer + Terraform)

Para entornos de producción con gestión de imágenes doradas:

```mermaid
flowchart LR
    A["ISO base"] --> B["Compilación de Packer"]
    B --> C["Imagen dorada"]
    C --> D["Despliegue con Terraform"]
    D --> E["VMs de producción"]
    F["Disparador de CI/CD"] -.-> B

    style B fill:#2ecc71,color:#fff
    style D fill:#4a9eff,color:#fff
```

### Combinado con otras herramientas

Terraform se encarga del aprovisionamiento; las herramientas de gestión de configuración se encargan del resto:

| Fase                     | Herramienta                     | Propósito                                         |
| ------------------------ | ------------------------------- | ------------------------------------------------- |
| **Creación de imágenes** | Packer                          | Compilar imágenes doradas endurecidas             |
| **Aprovisionamiento**    | Terraform                       | Desplegar VMs, redes, usuarios                    |
| **Configuración**        | Ansible / cloud-init            | Configuración de software posterior al despliegue |
| **Monitoreo**            | Prometheus / alertas de VergeOS | Observar la infraestructura desplegada            |

{% hint style="info" %}
**Puente VMware**

En VMware, el proveedor vSphere de Terraform gestiona ESXi/vCenter/vSAN como componentes separados y Packer utiliza el `vsphere-iso` compilador a través de vCenter. El único proveedor de `vergeio` VergeOS gestiona VMs, redes, unidades y usuarios a través de un único punto de conexión de API, y el complemento de Packer apunta a la misma API.
{% endhint %}

{% hint style="info" %}
**Puente Nutanix**

El proveedor Terraform de Nutanix (`nutanix/nutanix`) y el complemento de Packer apuntan ambos a la API v3 de Prism Central. El proveedor de VergeOS se comunica con un único punto de conexión (la URL del sistema o inquilino de VergeOS) sin una instancia de administración separada, y expone la configuración de cloud-init directamente en el `vergeio_vm` recurso mediante la `cloudinit_datasource` atributo y la `vergeio_cloudinitfiles` fuente de datos.
{% endhint %}

## Buenas prácticas

### Gestión del estado

* **Usa backends de estado remotos** (S3, Consul, Terraform Cloud) para la colaboración en equipo
* **Nunca cometas** `terraform.tfstate` al control de versiones — puede contener credenciales
* **Bloquea los archivos de estado** para evitar modificaciones simultáneas en entornos multiusuario

### Seguridad

* **Usa variables** para valores confidenciales (`var.vergeos_password`) — nunca codifiques credenciales de forma fija
* **Marca las salidas confidenciales** con `sensitive = true` para evitar la exposición accidental en los registros
* **Restringe los permisos del proveedor** — crea un usuario dedicado de la API de VergeOS con el mínimo acceso requerido

### Organización de módulos

* **Separa los entornos** en espacios de trabajo o directorios (`dev/`, `staging/`, `prod/`)
* **Crear módulos reutilizables** para patrones comunes (p. ej., un módulo "web-server" con VM + red + reglas de firewall)
* **Fijar las versiones del proveedor** para evitar cambios incompatibles inesperados durante las actualizaciones

## Lectura adicional

* [Proveedor de Terraform — GitHub](https://github.com/verge-io/terraform-provider-vergeio)
* [Registro de Terraform — Proveedor VergeIO](https://registry.terraform.io/providers/verge-io/vergeio/latest)
* [Complemento de Packer — GitHub](https://github.com/verge-io/packer-plugin-vergeio)
* [Registro de OpenTofu — Proveedor VergeIO](https://search.opentofu.org/provider/verge-io/vergeio/latest)
* [Documentación de VergeOS — Proveedor de Terraform](https://docs.verge.io/product-guide/tools-integrations/terraform-provider/)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.verge.io/learn-the-platform/es/modulo-8-desarrolladores-y-devops/04-terraform-packer.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.