Add comprehensive documentation and examples

2026-08-19 02:56:18 +00:00 · 2025-04-28 14:59:49 -04:00
parent 45433064b5
commit c4bea36ece
16 changed files with 2077 additions and 23 deletions
@@ -0,0 +1,212 @@
+# Cluster Backup and Restore
+
+This guide explains how to backup and restore Proxmox VE clusters using the PSProxmox module.
+
+## Prerequisites
+
+- PSProxmox module installed
+- Connection to a Proxmox VE server
+- Administrative access to the Proxmox VE cluster
+
+## Cluster Backups
+
+Cluster backups in Proxmox VE contain the cluster configuration, including:
+- Cluster configuration
+- User and role configuration
+- Storage configuration
+- Network configuration
+- Firewall configuration
+- HA configuration
+
+They do not include VM data or container data.
+
+## Creating Cluster Backups
+
+### Basic Backup
+
+To create a basic cluster backup:
+
+```powershell
+# Connect to the Proxmox VE server
+$credential = Get-Credential
+$connection = Connect-ProxmoxServer -Server "proxmox.example.com" -Credential $credential -Realm "pam"
+
+# Create a cluster backup
+$backup = New-ProxmoxClusterBackup -Connection $connection
+```
+
+### Backup with Compression
+
+To create a compressed cluster backup:
+
+```powershell
+$backup = New-ProxmoxClusterBackup -Connection $connection -Compress
+```
+
+### Backup and Wait for Completion
+
+To create a backup and wait for it to complete:
+
+```powershell
+$backup = New-ProxmoxClusterBackup -Connection $connection -Compress -Wait -Timeout 600
+```
+
+This will wait up to 10 minutes (600 seconds) for the backup to complete.
+
+## Listing Cluster Backups
+
+To list all cluster backups:
+
+```powershell
+$backups = Get-ProxmoxClusterBackup -Connection $connection
+```
+
+To get a specific backup by ID:
+
+```powershell
+$backupID = "vzdump-cluster-2023_04_28-12_00_00.vma.lzo"
+$backup = Get-ProxmoxClusterBackup -Connection $connection -BackupID $backupID
+```
+
+## Restoring Cluster Backups
+
+### Basic Restore
+
+To restore a cluster backup:
+
+```powershell
+$backupID = "vzdump-cluster-2023_04_28-12_00_00.vma.lzo"
+Restore-ProxmoxClusterBackup -Connection $connection -BackupID $backupID -Force
+```
+
+The `-Force` parameter is required to confirm the restore operation.
+
+### Restore and Wait for Completion
+
+To restore a backup and wait for it to complete:
+
+```powershell
+Restore-ProxmoxClusterBackup -Connection $connection -BackupID $backupID -Force -Wait -Timeout 600
+```
+
+This will wait up to 10 minutes (600 seconds) for the restore to complete.
+
+## Best Practices
+
+### Backup Frequency
+
+- Create regular backups of your cluster configuration
+- Automate backup creation using scheduled tasks
+- Keep multiple backups to ensure you can restore to different points in time
+
+### Backup Verification
+
+- Verify that backups are created successfully
+- Test restoring backups in a non-production environment
+- Document the backup and restore procedures
+
+### Backup Storage
+
+- Store backups in a secure location
+- Consider storing backups off-site
+- Implement backup rotation to manage storage space
+
+## Example: Automated Backup Script
+
+Here's an example script for automated cluster backups:
+
+```powershell
+# Automated-Cluster-Backup.ps1
+# This script creates a cluster backup and logs the result
+
+# Import the PSProxmox module
+Import-Module PSProxmox
+
+# Connect to the Proxmox VE server
+$securePassword = ConvertTo-SecureString "password" -AsPlainText -Force
+$connection = Connect-ProxmoxServer -Server "proxmox.example.com" -Username "root" -Password $securePassword -Realm "pam"
+
+# Create a timestamp for the log
+$timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
+
+try {
+    # Create a cluster backup
+    $backup = New-ProxmoxClusterBackup -Connection $connection -Compress -Wait -Timeout 600
+    
+    # Log the successful backup
+    $logMessage = "$timestamp - Backup created successfully: $($backup.BackupID)"
+    Add-Content -Path "C:\Logs\ProxmoxBackup.log" -Value $logMessage
+}
+catch {
+    # Log the error
+    $logMessage = "$timestamp - Backup failed: $($_.Exception.Message)"
+    Add-Content -Path "C:\Logs\ProxmoxBackup.log" -Value $logMessage
+}
+finally {
+    # Disconnect from the server
+    Disconnect-ProxmoxServer -Connection $connection
+}
+```
+
+## Example: Restore Script
+
+Here's an example script for restoring a cluster backup:
+
+```powershell
+# Restore-Cluster-Backup.ps1
+# This script restores a cluster backup
+
+# Import the PSProxmox module
+Import-Module PSProxmox
+
+# Connect to the Proxmox VE server
+$credential = Get-Credential -Message "Enter your Proxmox VE credentials"
+$connection = Connect-ProxmoxServer -Server "proxmox.example.com" -Credential $credential -Realm "pam"
+
+# Get the latest backup
+$latestBackup = Get-ProxmoxClusterBackup -Connection $connection | Sort-Object -Property Time -Descending | Select-Object -First 1
+
+if ($latestBackup) {
+    Write-Host "Latest backup: $($latestBackup.BackupID) from $(Get-Date -Date $latestBackup.Time -Format 'yyyy-MM-dd HH:mm:ss')"
+    
+    # Confirm the restore operation
+    $confirm = Read-Host "Do you want to restore this backup? (y/n)"
+    
+    if ($confirm -eq "y") {
+        # Restore the backup
+        Restore-ProxmoxClusterBackup -Connection $connection -BackupID $latestBackup.BackupID -Force -Wait -Timeout 600
+        Write-Host "Backup restored successfully"
+    }
+    else {
+        Write-Host "Restore operation cancelled"
+    }
+}
+else {
+    Write-Host "No backups found"
+}
+
+# Disconnect from the server
+Disconnect-ProxmoxServer -Connection $connection
+```
+
+## Troubleshooting
+
+### Backup Creation Fails
+
+If backup creation fails, check:
+- The user has sufficient permissions
+- There is enough disk space
+- The storage is accessible
+- The cluster is healthy
+
+### Restore Operation Fails
+
+If restore operation fails, check:
+- The backup file exists and is accessible
+- The backup file is not corrupted
+- The user has sufficient permissions
+- The cluster is in a state that allows restore operations
+
+## Next Steps
+
+Now that you know how to backup and restore Proxmox VE clusters, you can proceed to the [High Availability](High-Availability.md) guide to learn how to configure high availability for your cluster.
@@ -0,0 +1,145 @@
+# Creating VMs
+
+This guide explains how to create virtual machines using the PSProxmox module.
+
+## Prerequisites
+
+- PSProxmox module installed
+- Connection to a Proxmox VE server
+
+## Basic VM Creation
+
+The simplest way to create a VM is to use the `New-ProxmoxVM` cmdlet with basic parameters:
+
+```powershell
+# Connect to the Proxmox VE server
+$credential = Get-Credential
+$connection = Connect-ProxmoxServer -Server "proxmox.example.com" -Credential $credential -Realm "pam"
+
+# Create a basic VM
+$vm = New-ProxmoxVM -Connection $connection -Node "pve1" -Name "test-vm" -Memory 2048 -Cores 2 -DiskSize 32 -Start
+```
+
+This creates a VM with the following specifications:
+- Name: test-vm
+- Memory: 2 GB
+- CPU: 2 cores
+- Disk: 32 GB
+- The VM will be started after creation
+
+## Advanced VM Creation
+
+For more control over the VM configuration, you can specify additional parameters:
+
+```powershell
+$vm = New-ProxmoxVM -Connection $connection -Node "pve1" -Name "web-server" `
+    -Memory 4096 -Cores 2 -Sockets 1 -DiskSize 50 -Storage "local-lvm" `
+    -OSType "l26" -NetworkModel "virtio" -NetworkBridge "vmbr0" `
+    -Description "Web server for testing" -Start
+```
+
+This creates a VM with more specific configuration:
+- Name: web-server
+- Memory: 4 GB
+- CPU: 2 cores, 1 socket
+- Disk: 50 GB on local-lvm storage
+- OS Type: Linux 2.6+ kernel
+- Network: virtio model on vmbr0 bridge
+- Description: "Web server for testing"
+- The VM will be started after creation
+
+## Using the VM Builder Pattern
+
+For complex VM configurations, you can use the VM builder pattern:
+
+```powershell
+# Create a VM builder
+$builder = New-ProxmoxVMBuilder -Name "db-server"
+
+# Configure the VM using the builder pattern
+$builder.WithMemory(8192)                                # 8 GB of memory
+        .WithCores(4)                                    # 4 CPU cores
+        .WithSockets(2)                                  # 2 CPU sockets
+        .WithDisk(100, "local-lvm")                      # 100 GB primary disk on local-lvm storage
+        .WithAdditionalDisk(200, "local-lvm")            # 200 GB additional disk on local-lvm storage
+        .WithNetwork("virtio", "vmbr0")                  # virtio network on vmbr0 bridge
+        .WithAdditionalNetwork("virtio", "vmbr1")        # Additional network interface on vmbr1
+        .WithIPConfig("192.168.1.20/24", "192.168.1.1")  # Static IP configuration for first interface
+        .WithCPUType("host")                             # CPU type
+        .WithVGA("std")                                  # VGA type
+        .WithBoot("order=scsi0;net0")                    # Boot order
+        .WithDescription("Database server for production") # Description
+        .WithStart($true)                                # Start the VM after creation
+
+# Create the VM using the builder
+$vm = New-ProxmoxVM -Connection $connection -Node "pve1" -Builder $builder
+```
+
+The builder pattern allows you to:
+- Chain configuration methods together
+- Configure complex settings like multiple disks and network interfaces
+- Set advanced parameters like CPU type, VGA type, and boot order
+
+## Creating VMs from Templates
+
+If you have VM templates, you can create VMs from them using the `New-ProxmoxVMFromTemplate` cmdlet:
+
+```powershell
+# Create a VM from a template
+$vm = New-ProxmoxVMFromTemplate -Connection $connection -Node "pve1" -TemplateName "Ubuntu-Template" -Name "web01" -Start
+```
+
+You can also override template settings:
+
+```powershell
+# Create a VM from a template with custom settings
+$vm = New-ProxmoxVMFromTemplate -Connection $connection -Node "pve1" -TemplateName "Ubuntu-Template" `
+    -Name "web01" -Memory 4096 -Cores 2 -DiskSize 50 -Start
+```
+
+## Creating Multiple VMs from Templates
+
+You can create multiple VMs from a template in one operation:
+
+```powershell
+# Create multiple VMs from a template
+$vms = New-ProxmoxVMFromTemplate -Connection $connection -Node "pve1" -TemplateName "Ubuntu-Template" `
+    -Prefix "web" -Count 3 -Start
+```
+
+This creates three VMs named "web1", "web2", and "web3".
+
+You can also specify a starting index:
+
+```powershell
+# Create multiple VMs from a template with a custom starting index
+$vms = New-ProxmoxVMFromTemplate -Connection $connection -Node "pve1" -TemplateName "Ubuntu-Template" `
+    -Prefix "web" -Count 3 -StartIndex 10 -Start
+```
+
+This creates three VMs named "web10", "web11", and "web12".
+
+## Creating VMs with IP Addresses from a Pool
+
+If you have IP pools configured, you can assign IP addresses from them:
+
+```powershell
+# Create a VM with an IP address from a pool
+$vm = New-ProxmoxVMFromTemplate -Connection $connection -Node "pve1" -TemplateName "Ubuntu-Template" `
+    -Name "web01" -IPPool "Production" -Start
+```
+
+This assigns an IP address from the "Production" pool to the VM.
+
+## Best Practices
+
+- Use descriptive names for your VMs
+- Use templates for consistent VM configurations
+- Use the builder pattern for complex VM configurations
+- Document your VM configurations
+- Use IP pools for IP address management
+- Test your VM configurations before deploying to production
+
+## Next Steps
+
+Now that you know how to create VMs, you can proceed to the [Managing VMs](Managing-VMs.md) guide to learn how to manage them.
@@ -0,0 +1,110 @@
+# Installation Guide
+
+This guide explains how to install the PSProxmox module.
+
+## Prerequisites
+
+- PowerShell 5.1 or later
+- Windows PowerShell or PowerShell Core
+- .NET Framework 4.7.2 or later (for Windows PowerShell)
+- .NET Core 2.0 or later (for PowerShell Core)
+
+## Installation Methods
+
+### Method 1: Install from PowerShell Gallery (Recommended)
+
+The PSProxmox module is available on the PowerShell Gallery. To install it, run the following command:
+
+```powershell
+Install-Module -Name PSProxmox -Scope CurrentUser
+```
+
+If you want to install it for all users on the system, run the following command with administrative privileges:
+
+```powershell
+Install-Module -Name PSProxmox -Scope AllUsers
+```
+
+### Method 2: Install from GitHub
+
+You can also install the PSProxmox module directly from GitHub:
+
+1. Download the latest release from the [GitHub repository](https://github.com/freedbygrace/PSProxmox/releases)
+2. Extract the ZIP file
+3. Run the `Install-PSProxmox.ps1` script included in the package:
+
+```powershell
+.\Install-PSProxmox.ps1
+```
+
+### Method 3: Manual Installation
+
+You can manually install the PSProxmox module by copying the files to your PowerShell modules directory:
+
+1. Download the latest release from the [GitHub repository](https://github.com/freedbygrace/PSProxmox/releases)
+2. Extract the ZIP file
+3. Copy the extracted files to a folder named "PSProxmox" in your PowerShell modules directory:
+
+For Windows PowerShell:
+```powershell
+Copy-Item -Path .\PSProxmox-Dist\* -Destination "$env:USERPROFILE\Documents\WindowsPowerShell\Modules\PSProxmox" -Recurse -Force
+```
+
+For PowerShell Core:
+```powershell
+Copy-Item -Path .\PSProxmox-Dist\* -Destination "$env:USERPROFILE\Documents\PowerShell\Modules\PSProxmox" -Recurse -Force
+```
+
+## Verifying the Installation
+
+To verify that the PSProxmox module is installed correctly, run the following command:
+
+```powershell
+Get-Module -Name PSProxmox -ListAvailable
+```
+
+You should see output similar to the following:
+
+```
+    Directory: C:\Users\username\Documents\WindowsPowerShell\Modules
+
+ModuleType Version    Name                                ExportedCommands
+---------- -------    ----                                ----------------
+Binary     2023.04... PSProxmox                           {Clear-ProxmoxIPPool, Connect-ProxmoxServer, Disconnect-ProxmoxServer, Get-ProxmoxCluster...}
+```
+
+## Importing the Module
+
+To import the PSProxmox module into your PowerShell session, run the following command:
+
+```powershell
+Import-Module PSProxmox
+```
+
+You can verify that the module is imported correctly by running:
+
+```powershell
+Get-Command -Module PSProxmox
+```
+
+This will list all the cmdlets available in the PSProxmox module.
+
+## Updating the Module
+
+To update the PSProxmox module to the latest version, run the following command:
+
+```powershell
+Update-Module -Name PSProxmox
+```
+
+## Uninstalling the Module
+
+To uninstall the PSProxmox module, run the following command:
+
+```powershell
+Uninstall-Module -Name PSProxmox
+```
+
+## Next Steps
+
+Now that you have installed the PSProxmox module, you can proceed to the [Connection Guide](Connection.md) to learn how to connect to a Proxmox VE server.
@@ -0,0 +1,47 @@
+# PSProxmox Guides
+
+This directory contains guides for common tasks with the PSProxmox module.
+
+## Getting Started
+
+- [Installation Guide](Installation.md)
+- [Connection Guide](Connection.md)
+- [Authentication Methods](Authentication.md)
+
+## VM Management
+
+- [Creating VMs](Creating-VMs.md)
+- [Managing VMs](Managing-VMs.md)
+- [VM Templates](VM-Templates.md)
+- [VM Snapshots](VM-Snapshots.md)
+- [VM Migration](VM-Migration.md)
+
+## Cluster Management
+
+- [Cluster Setup](Cluster-Setup.md)
+- [Cluster Backup and Restore](Cluster-Backup-Restore.md)
+- [High Availability](High-Availability.md)
+
+## Storage Management
+
+- [Storage Types](Storage-Types.md)
+- [Managing Storage](Managing-Storage.md)
+- [Storage Replication](Storage-Replication.md)
+
+## Network Management
+
+- [Network Configuration](Network-Configuration.md)
+- [SDN Setup](SDN-Setup.md)
+- [Firewall Configuration](Firewall-Configuration.md)
+
+## User Management
+
+- [User and Role Management](User-Role-Management.md)
+- [Permissions and ACLs](Permissions-ACLs.md)
+- [API Tokens](API-Tokens.md)
+
+## Advanced Topics
+
+- [Automation and Scripting](Automation-Scripting.md)
+- [Performance Tuning](Performance-Tuning.md)
+- [Troubleshooting](Troubleshooting.md)