> 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/03-powershell-module.md). # Módulo de PowerShell (PSVergeOS) **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) ```powershell Install-Module -Name PSVergeOS -Scope CurrentUser ``` ### Instalación manual (desarrollo) ```powershell git clone https://github.com/verge-io/PSVergeOS.git Import-Module ./PSVergeOS/PSVergeOS.psd1 ``` ### Verificar la instalación ```powershell 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: ```powershell Connect-VergeOS -Server "vergeos.example.com" # Solicita credenciales de forma interactiva ``` ### Objeto PSCredential Almacena las credenciales de forma segura para scripts no interactivos: ```powershell $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: ```powershell Connect-VergeOS -Server "vergeos.example.com" -Token $env:VERGEOS_TOKEN ``` ### Certificados autofirmados Para entornos de laboratorio y desarrollo con certificados autofirmados: ```powershell Connect-VergeOS -Server "192.168.1.100" -Token $token -SkipCertificateCheck ``` {% hint style="warning" %} Usa `-SkipCertificateCheck` solo en entornos de prueba. En sistemas de producción, configura certificados SSL válidos. {% endhint %} ## 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: ```powershell # 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: ```powershell # 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 ```powershell # 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 ```powershell # 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 ```powershell # 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 ```powershell # 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 ```powershell # 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:** ```powershell # 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+):** ```bash # 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. {% hint style="info" %} **¿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. {% endhint %} ## Recursos adicionales * [Repositorio de GitHub](https://github.com/verge-io/PSVergeOS) — código fuente, incidencias y 16 scripts de ejemplo * [PowerShell Gallery](https://www.powershellgallery.com/packages/PSVergeOS) — última versión e información de instalación * [Documentación de PowerShell 7.4](https://learn.microsoft.com/en-us/powershell/) — referencia del entorno de ejecución de PowerShell --- # 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/03-powershell-module.md?ask=&goal= ``` `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.