Módulo de PowerShell (PSVergeOS)

Gestiona la infraestructura de VergeOS con el módulo PowerShell PSVergeOS: más de 200 cmdlets para automatización del ciclo de vida de VM, redes, almacenamiento, multitenencia, VPN y recuperación ante desastres.

PSVergeOS es un módulo de PowerShell multiplataforma que proporciona más de 200 cmdlets para administrar la infraestructura de VergeOS a través de la API REST. Si tu equipo ya usa PowerShell para la administración de Windows Server, Active Directory o VMware, PSVergeOS te permite extender esos mismos flujos de trabajo y patrones de scripting a VergeOS — con compatibilidad total con la canalización, autocompletado por pestañas y la familiar Verbo-Sustantivo convención de nomenclatura de cmdlets.

Requisitos e instalación

Requisito	Versión
PowerShell	7.4 o posterior
VergeOS	26.0 o posterior
Plataforma	Windows, macOS, Linux

Desde PowerShell Gallery (recomendado)

Install-Module -Name PSVergeOS -Scope CurrentUser

Instalación manual (desarrollo)

git clone https://github.com/verge-io/PSVergeOS.git
Import-Module ./PSVergeOS/PSVergeOS.psd1

Verificar la instalación

Get-Module PSVergeOS -ListAvailable
Get-Command -Module PSVergeOS | Measure-Object  # Debería mostrar más de 200 cmdlets

Autenticación

PSVergeOS admite varios métodos de autenticación para adaptarse a distintos entornos — desde sesiones administrativas interactivas hasta canalizaciones totalmente automatizadas.

Credenciales interactivas

Solicita nombre de usuario y contraseña al momento de la conexión:

Connect-VergeOS -Server "vergeos.example.com"
# Solicita credenciales de forma interactiva

Objeto PSCredential

Almacena las credenciales de forma segura para scripts no interactivos:

$cred = Get-Credential
Connect-VergeOS -Server "vergeos.example.com" -Credential $cred

Token de API

Usa un token de API pre-generado para canalizaciones de automatización:

Connect-VergeOS -Server "vergeos.example.com" -Token $env:VERGEOS_TOKEN

Certificados autofirmados

Para entornos de laboratorio y desarrollo con certificados autofirmados:

Connect-VergeOS -Server "192.168.1.100" -Token $token -SkipCertificateCheck

Usa -SkipCertificateCheck solo en entornos de prueba. En sistemas de producción, configura certificados SSL válidos.

Administración de varios servidores

PSVergeOS puede administrar varios sistemas VergeOS desde una única sesión de PowerShell. Usa el parámetro -PassThru para capturar objetos de conexión y el parámetro -Server para dirigir acciones a sistemas específicos:

# Conectar a varios sistemas
$prod = Connect-VergeOS -Server "prod.vergeos.local" -Token $env:PROD_TOKEN -PassThru
$dev  = Connect-VergeOS -Server "dev.vergeos.local"  -Token $env:DEV_TOKEN  -PassThru

# Consultar VMs en un servidor específico
Get-VergeVM -Server $prod
Get-VergeVM -Server $dev

# Cambiar la conexión predeterminada
Set-VergeConnection -Server "prod.vergeos.local"

Esto es especialmente valioso para los MSP que administran varios entornos de clientes u organizaciones con clústeres de VergeOS de producción y desarrollo separados.

Categorías de cmdlets

El módulo organiza sus más de 200 cmdlets en categorías funcionales. Cada categoría cubre el ciclo de vida CRUD completo, además de acciones específicas del recurso.

Categoría	Descripción
Conexión	Conectar, desconectar y administrar conexiones al servidor
Máquinas virtuales	Ciclo de vida, control de energía, instantáneas, discos, NIC, clonación
Redes	Redes virtuales, reglas de firewall, DNS, DHCP, diagnósticos
VPN	Conexiones/políticas IPSec, interfaces/pares WireGuard
NAS y almacenamiento	Servicios NAS, volúmenes, recursos compartidos CIFS/NFS, instantáneas, sincronización
Inquilinos	Aprovisionamiento, instantáneas, asignación de bloques de almacenamiento/red
Usuarios y grupos	Administración de cuentas, permisos, claves de API
Sistema	Clústeres, nodos, licencias, configuraciones
Certificados	Administración de certificados SSL
Etiquetas	Etiquetado y categorización de recursos
Webhooks	Ganchos de automatización impulsados por eventos
Supervisión y tareas	Alertas, registros, seguimiento de tareas asíncronas
Copias de seguridad y recuperación ante desastres	Perfiles de instantáneas, instantáneas en la nube, administración de sitios, sincronización
Archivos y medios	Administración de ISO, cargas de archivos
Grupos de recursos	Agrupación lógica de recursos

Cmdlets de VPN (IPSec y WireGuard)

La categoría VPN merece una atención especial: PSVergeOS proporciona administración completa tanto para implementaciones VPN de IPSec como de WireGuard:

IPSec:

• New-VergeIPSecConnection / Get-VergeIPSecConnection / Remove-VergeIPSecConnection
• New-VergeIPSecPolicy / Get-VergeIPSecPolicy / Remove-VergeIPSecPolicy

WireGuard:

• New-VergeWireGuardInterface / Get-VergeWireGuardInterface / Remove-VergeWireGuardInterface
• New-VergeWireGuardPeer / Get-VergeWireGuardPeer / Remove-VergeWireGuardPeer

Compatibilidad con la canalización

Una de las mayores fortalezas de PSVergeOS es la compatibilidad total con la canalización de PowerShell. Los cmdlets aceptan entrada de la canalización y producen salida para la canalización, lo que permite líneas únicas concisas para operaciones masivas:

# Detener todas las VMs de desarrollo
Get-VergeVM -Name "Dev-*" | Stop-VergeVM -Confirm:$false

# Crear instantáneas de todas las VMs de producción
Get-VergeVM -Name "Prod-*" | ForEach-Object {
    New-VergeVMSnapshot -VMName $_.Name -Name "Daily-$(Get-Date -Format 'yyyyMMdd')"
}

# Encender todas las VMs en una red específica
Get-VergeVM | Where-Object { $_.Network -eq "app-network" } | Start-VergeVM

La compatibilidad con la canalización hace que PSVergeOS sea especialmente eficaz para tareas de mantenimiento programadas integradas con el Programador de tareas de Windows o trabajos cron de Linux.

Ejemplos prácticos

Instantáneas masivas con retención

# Conectar al sistema VergeOS
Connect-VergeOS -Server "vergeos.example.com" -Token $env:VERGEOS_TOKEN

# Crear instantáneas de todas las VMs de producción en ejecución con una retención de 24 horas
$vms = Get-VergeVM -Name "Prod-*" | Where-Object { $_.PowerState -eq "Running" }

foreach ($vm in $vms) {
    $snapshot = New-VergeVMSnapshot -VMName $vm.Name `
        -Name "Nightly-$(Get-Date -Format 'yyyyMMdd-HHmm')" `
        -Retention 86400
    Write-Host "Instantánea creada para $($vm.Name): $($snapshot.Name)"
}

Write-Host "Completadas $($vms.Count) instantáneas"

Exportación CSV del inventario de VMs

# Exportar el inventario completo de VMs a CSV para informes
Get-VergeVM | Select-Object Name, PowerState, RAM, CPUCores, OS,
    @{N='DiskGB'; E={[math]::Round($_.DiskSize / 1GB, 2)}},
    Created, Description |
    Export-Csv -Path "vm-inventory-$(Get-Date -Format 'yyyyMMdd').csv" -NoTypeInformation

Write-Host "Inventario exportado a vm-inventory-$(Get-Date -Format 'yyyyMMdd').csv"

Creación de red con reglas de firewall

# Crear una red interna con DHCP y reglas de firewall
$network = New-VergeNetwork -Name "web-tier" `
    -NetworkAddress "10.20.1.0/24" `
    -IPAddress "10.20.1.1" `
    -DHCPEnabled $true

# Agregar reglas de firewall
New-VergeNetworkRule -Network $network.Name `
    -Name "Allow HTTPS" -Action Accept -Protocol TCP -DestPort 443

New-VergeNetworkRule -Network $network.Name `
    -Name "Allow SSH" -Action Accept -Protocol TCP -DestPort 22

# Aplicar las reglas y encender
Invoke-VergeNetworkApplyRules -Network $network.Name
Start-VergeNetwork -Name $network.Name

Write-Host "La red '$($network.Name)' está en línea con las reglas de firewall aplicadas"

Informe de recursos multitenant

# Generar un resumen de recursos en todos los inquilinos
$report = @()

foreach ($tenant in Get-VergeTenant) {
    $tenantVMs = Get-VergeVM -Tenant $tenant.Name
    $report += [PSCustomObject]@{
        Tenant    = $tenant.Name
        VMCount   = $tenantVMs.Count
        TotalRAM  = ($tenantVMs | Measure-Object -Property RAM -Sum).Sum
        TotalCPU  = ($tenantVMs | Measure-Object -Property CPUCores -Sum).Sum
        Running   = ($tenantVMs | Where-Object PowerState -eq "Running").Count
        Stopped   = ($tenantVMs | Where-Object PowerState -ne "Running").Count
    }
}

$report | Format-Table -AutoSize
$report | Export-Csv "tenant-report.csv" -NoTypeInformation

Configuración de VPN WireGuard

# Crear una interfaz WireGuard en la red externa
$wgInterface = New-VergeWireGuardInterface -Network "External" `
    -Name "Remote-Access" `
    -IPAddress "10.100.0.1/24" `
    -ListenPort 51820

# Agregar un par para un usuario remoto
New-VergeWireGuardPeer -Interface $wgInterface.Name `
    -Name "Engineer-1" `
    -AllowedIPs "10.100.0.2/32" `
    -AutoGenerateConfig $true

# Aplicar reglas de red
Invoke-VergeNetworkApplyRules -Network "External"

Integración con el Programador de tareas

Los scripts de PSVergeOS se integran de forma natural con los sistemas de tareas programadas para una automatización sin intervención:

Programador de tareas de Windows:

# Guardar como C:\Scripts\nightly-snapshot.ps1
Import-Module PSVergeOS
Connect-VergeOS -Server "vergeos.local" -Token $env:VERGEOS_TOKEN -SkipCertificateCheck
Get-VergeVM -Name "Prod-*" | ForEach-Object {
    New-VergeVMSnapshot -VMName $_.Name -Name "Nightly-$(Get-Date -Format 'yyyyMMdd')" -Retention 86400
}
Disconnect-VergeOS

cron de Linux (PowerShell 7.4+):

# Ejecutar cada noche a las 2:00 AM
0 2 * * * /usr/bin/pwsh -File /opt/scripts/nightly-snapshot.ps1

Casos de uso comunes

Operaciones masivas de VMs

Detén, inicia, crea instantáneas o migra varias VMs con líneas únicas de la canalización. Ideal para ventanas de mantenimiento.

Informes de infraestructura

Exporta inventario de VMs, uso de recursos y datos de configuración a CSV para auditoría y planificación de capacidad.

Automatización de red

Crea redes, configura DHCP, administra reglas de firewall y establece túneles VPN mediante programación.

Mantenimiento programado

Intégralo con el Programador de tareas o cron para instantáneas automáticas, limpieza y comprobaciones de cumplimiento.

¿Vienes de VMware o Nutanix?

PSVergeOS usa la Verbo-Sustantivo convención estándar de PowerShell, así que la memoria muscular se transfiere — Get-VM | Stop-VM se convierte en Get-VergeVM | Stop-VergeVM. La autenticación admite mensajes interactivos, objetos PSCredential y tokens de API, por lo que aquí se aplican los mismos patrones de scripting que ya usas para la automatización no interactiva. Para administrar más de un sistema VergeOS desde una sola sesión, pasa -Server en cada cmdlet para dirigir una conexión específica.

Recursos adicionales

• Repositorio de GitHub — código fuente, incidencias y 16 scripts de ejemplo
• PowerShell Gallery — última versión e información de instalación
• Documentación de PowerShell 7.4 — referencia del entorno de ejecución de PowerShell