> 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-desarrollador-y-devops/04-terraform-packer.md).

# Terraform y Packer

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

## Proveedor de Terraform

El proveedor de Terraform de VergeOS se publica en el Registro de Terraform y es totalmente compatible con **OpenTofu** (el fork de Terraform de código abierto). Te permite administrar los recursos de VergeOS mediante los estándar `terraform plan` / `terraform apply` flujos de trabajo.

### Configuración del proveedor

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

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

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

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

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

### Recursos

Actualmente, el proveedor admite cuatro 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`, `clúster`, `guest_agent`, `uefi`, `secure_boot`, `snapshot_profile`, `powerstate`, en línea `vergeio_drive` y `vergeio_nic` blocks |
| **`vergeio_network`** | Configurar redes virtuales             | `network_address` (CIDR), `dhcp_enabled`, `dhcp_start`, `dhcp_end`, `dns_server_list`, `gateway`, `powerstate`                                                                                  |
| **`vergeio_user`**    | Aprovisionar usuarios                  | Gestión de cuentas de usuario dentro de VergeOS                                                                                                                                                 |
| **`vergeio_member`**  | Administrar la pertenencia a grupos    | Asociar usuarios con grupos para RBAC                                                                                                                                                           |

### Fuentes de datos

Ocho 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 de la versión actual 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`**   | ISO y archivos multimedia cargados                                |
| **`vergeio_cloudinitfiles`** | Archivos de configuración cloud-init disponibles                  |

### Ejemplos de HCL

#### VM con disco y NIC

Este ejemplo crea un servidor web Linux con un disco 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_address = "192.168.10.0/24"
  dns_server_list = ["8.8.8.8", "8.8.4.4"]
  dhcp_enabled    = true
  dhcp_start      = "192.168.10.100"
  dhcp_end        = "192.168.10.200"
}
```

#### Consultando 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

La `vergeio_vm` el 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 que se usa para adjuntar archivos cloud-init en línea en el recurso de VM (frente a hacer referencia a archivos precargados mediante la fuente de datos), consulta el [repositorio del proveedor](https://github.com/verge-io/terraform-provider-vergeio) — el formulario a nivel de campo puede evolucionar entre versiones.

### Madurez y hoja de ruta

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

El proveedor de Terraform de VergeOS está en desarrollo activo y aún no todos los objetos de VergeOS se exponen como recursos administrados. Entre las áreas que pueden no tener una cobertura completa del proveedor en un momento dado se incluyen el aprovisionamiento de tenants, 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 lista del Registro de Terraform para conocer la cobertura actual de recursos y las notas de la versión antes de diseñar una configuración basada en ellos.
{% endhint %}

## Plugin de Packer

La **Plugin 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 construir las **imágenes doradas** que sirven como base para las implementaciones.

### ¿Por qué Packer?

```mermaid
flowchart LR
    A["ISO base"] --> B["Construcción con 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 parta de una base conocida, probada y endurecida. En lugar de aprovisionar un SO vacío y ejecutar scripts de configuración en cada despliegue, Packer preconstruye la imagen una sola vez:

* **Consistencia** — Cada VM creada a partir de la imagen es idéntica
* **Velocidad** — Sin retraso de aprovisionamiento en el primer arranque; las VM están listas de inmediato
* **Cumplimiento** — Las bases de seguridad y los parches se incorporan en tiempo de compilación
* **Integración de la canalización** — Dispara reconstrucciones de imágenes desde CI/CD en los días de parches del SO

### Configuración del plugin

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

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

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

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

### Capacidades

A alto nivel, el plugin impulsa todo el ciclo de vida 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 exacto de configuración, los tipos de invitado compatibles y el comportamiento de apagado/limpieza, consulta directamente el repositorio del plugin:

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

### Canalización Packer → Recetas

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

1. **Packer** construye y endurece la imagen dorada según un calendario (por ejemplo, ciclo mensual de parches)
2. La imagen se registra como una **Receta de VM** en el Marketplace de VergeOS
3. Los usuarios implementan VMs estandarizadas a partir de la receta, ya sea mediante la interfaz de usuario o a través de Terraform
4. Las actualizaciones fluyen automáticamente: reconstruye 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["API de VergeOS"]
    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["Construcción con Packer"]
    B --> C["Imagen dorada"]
    C --> D["Despliegue con Terraform"]
    D --> E["VMs de producción"]
    F["Disparador 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                          | Construir imágenes doradas endurecidas            |
| **Aprovisionamiento**    | Terraform                       | Desplegar VMs, redes y usuarios                   |
| **Configuración**        | Ansible / cloud-init            | Configuración de software posterior al despliegue |
| **Supervisión**          | Prometheus / alertas de VergeOS | Observar la infraestructura desplegada            |

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

En VMware, el proveedor vSphere de Terraform administra ESXi/vCenter/vSAN como preocupaciones separadas y Packer usa el `vsphere-iso` constructor a través de vCenter. El único proveedor `vergeio` de VergeOS administra VMs, redes, discos y usuarios a través de un único endpoint de API, y el plugin de Packer apunta a la misma API.
{% endhint %}

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

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

## Prácticas recomendadas

### Gestión del estado

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

### Seguridad

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

### Organización de módulos

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

## Lecturas adicionales

* [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)
* [Plugin 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.