diff --git a/Module/2025.07.03.1200/LICENSE b/Module/2025.07.03.1200/LICENSE new file mode 100644 index 0000000..6fb1a0a --- /dev/null +++ b/Module/2025.07.03.1200/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2023 freedbygrace + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/Module/2025.07.03.1200/PSProxmox.psd1 b/Module/2025.07.03.1200/PSProxmox.psd1 new file mode 100644 index 0000000..999e9ff --- /dev/null +++ b/Module/2025.07.03.1200/PSProxmox.psd1 @@ -0,0 +1,149 @@ +@{ + ModuleVersion = '2025.07.03.1200' + GUID = 'd24f0894-3d0c-4ef1-a41e-b273c3db86ad' + Author = 'PSProxmox Team' + CompanyName = 'PSProxmox' + Copyright = 'Copyright © 2023' + Description = 'PowerShell module for managing Proxmox VE clusters' + PowerShellVersion = '5.1' + DotNetFrameworkVersion = '4.7.2' + CompatiblePSEditions = @('Desktop', 'Core') + # Assemblies that must be loaded prior to importing this module + RequiredAssemblies = @('bin\PSProxmox.dll', 'lib\Newtonsoft.Json.dll') + # Root module + RootModule = 'bin\PSProxmox.dll' + # Script files (.ps1) that are run in the caller's environment prior to importing this module + ScriptsToProcess = @() + # Type files (.ps1xml) to be loaded when importing this module + TypesToProcess = @() + # Format files (.ps1xml) to be loaded when importing this module + FormatsToProcess = @() + FunctionsToExport = @() + CmdletsToExport = @( + # Session Management + 'Connect-ProxmoxServer', + 'Disconnect-ProxmoxServer', + 'Test-ProxmoxConnection', + + # Node and VM Management + 'Get-ProxmoxNode', + 'Get-ProxmoxVM', + 'New-ProxmoxVM', + 'New-ProxmoxVMBuilder', + 'Remove-ProxmoxVM', + 'Start-ProxmoxVM', + 'Stop-ProxmoxVM', + 'Restart-ProxmoxVM', + + # Storage Management + 'Get-ProxmoxStorage', + 'New-ProxmoxStorage', + 'Remove-ProxmoxStorage', + + # Network Management + 'Get-ProxmoxNetwork', + 'New-ProxmoxNetwork', + 'Remove-ProxmoxNetwork', + + # User and Role Management + 'Get-ProxmoxUser', + 'New-ProxmoxUser', + 'Remove-ProxmoxUser', + 'Get-ProxmoxRole', + 'New-ProxmoxRole', + 'Remove-ProxmoxRole', + + # SDN Management + 'Get-ProxmoxSDNZone', + 'New-ProxmoxSDNZone', + 'Remove-ProxmoxSDNZone', + 'Get-ProxmoxSDNVnet', + 'New-ProxmoxSDNVnet', + 'Remove-ProxmoxSDNVnet', + + # Cluster Management + 'Get-ProxmoxCluster', + 'Join-ProxmoxCluster', + 'Leave-ProxmoxCluster', + 'New-ProxmoxClusterBackup', + 'Restore-ProxmoxClusterBackup', + + # Template Management + 'Get-ProxmoxVMTemplate', + 'New-ProxmoxVMTemplate', + 'Remove-ProxmoxVMTemplate', + 'New-ProxmoxVMFromTemplate', + + # IP Management + 'New-ProxmoxIPPool', + 'Get-ProxmoxIPPool', + 'Clear-ProxmoxIPPool', + + # Cloud Image Management + 'Get-ProxmoxCloudImage', + 'Save-ProxmoxCloudImage', + 'Invoke-ProxmoxCloudImageCustomization', + 'New-ProxmoxCloudImageTemplate', + 'Set-ProxmoxVMCloudInit', + + # LXC Container Management + 'Get-ProxmoxContainer', + 'New-ProxmoxContainer', + 'New-ProxmoxContainerBuilder', + 'Remove-ProxmoxContainer', + 'Start-ProxmoxContainer', + 'Stop-ProxmoxContainer', + 'Restart-ProxmoxContainer', + + # TurnKey Template Management + 'Get-ProxmoxTurnKeyTemplate', + 'Save-ProxmoxTurnKeyTemplate', + 'New-ProxmoxContainerFromTurnKey', + + # VM SMBIOS Management + 'Get-ProxmoxVMSMBIOS', + 'Set-ProxmoxVMSMBIOS' + ) + VariablesToExport = @() + AliasesToExport = @() + PrivateData = @{ + PSData = @{ + Tags = @('Proxmox', 'VirtualMachine', 'Cluster', 'Management') + LicenseUri = 'https://github.com/Grace-Solutions/PSProxmox/blob/main/LICENSE' + ProjectUri = 'https://github.com/Grace-Solutions/PSProxmox' + ReleaseNotes = 'Updated to .NET Standard 2.0 for dual PowerShell 5.1/7+ support. Added missing SMBIOS cmdlets to exports. Complete compatibility with both Windows PowerShell and PowerShell Core. See https://github.com/Grace-Solutions/PSProxmox/releases/tag/v2025.07.03.1200' + } + } +} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/Module/2025.07.03.1200/README.md b/Module/2025.07.03.1200/README.md new file mode 100644 index 0000000..4988250 --- /dev/null +++ b/Module/2025.07.03.1200/README.md @@ -0,0 +1,263 @@ +# PSProxmox + +PSProxmox is a C#-based PowerShell module for managing Proxmox VE clusters. It provides a comprehensive set of cmdlets for interacting with Proxmox VE API, featuring structured return objects, mass deployment tools, automatic IP management, and more. + +## Features + +- **Session Management**: Authenticate and persist sessions with Proxmox VE clusters +- **Core CRUD Operations**: Manage VMs, Storage, Network, Users, Roles, SDN, and Clusters +- **Templates**: Create and use VM deployment templates +- **Mass Creation**: Bulk create VMs with prefix/counter +- **IP Management**: CIDR parsing, subnetting, FIFO IP queue assignment +- **Structured Objects**: All outputs are typed C# classes (PowerShell-native) +- **Pipeline Support**: Cmdlets support pipeline input where appropriate + +## Project Structure + +- **Module/**: Contains the PowerShell module files +- **PSProxmox/**: Contains the C# source code for the module +- **Documentation/**: Contains detailed documentation and examples +- **Scripts/**: Contains build and installation scripts +- **Release/**: Contains built releases (created by build script) + +## Installation + +### From PowerShell Gallery (Recommended) + +```powershell +# Install from PowerShell Gallery +Install-Module -Name PSProxmox -Scope CurrentUser +``` + +### Manual Installation + +```powershell +# Clone the repository +git clone https://github.com/freedbygrace/PSProxmox.git +cd PSProxmox + +# Build the module +.\Scripts\build.ps1 + +# Install the module +.\Scripts\Install-PSProxmox.ps1 +``` + +## Getting Started + +### Connecting to a Proxmox VE Server + +```powershell +# Connect using username and password +$securePassword = ConvertTo-SecureString "password" -AsPlainText -Force +$connection = Connect-ProxmoxServer -Server "proxmox.example.com" -Username "root" -Password $securePassword -Realm "pam" + +# Connect using a credential object +$credential = Get-Credential +$connection = Connect-ProxmoxServer -Server "proxmox.example.com" -Credential $credential -Realm "pam" +``` + +### Managing Virtual Machines + +```powershell +# Get all VMs +$vms = Get-ProxmoxVM -Connection $connection + +# Get a specific VM +$vm = Get-ProxmoxVM -Connection $connection -VMID 100 + +# Create a new VM +$vm = New-ProxmoxVM -Connection $connection -Node "pve1" -Name "test-vm" -Memory 2048 -Cores 2 -DiskSize 32 -Start + +# Create a new VM using the builder pattern +$builder = New-ProxmoxVMBuilder -Name "web-server" +$builder.WithMemory(4096) + .WithCores(2) + .WithDisk(50, "local-lvm") + .WithNetwork("virtio", "vmbr0") + .WithIPConfig("192.168.1.10/24", "192.168.1.1") + .WithStart($true) + +$vm = New-ProxmoxVM -Connection $connection -Node "pve1" -Builder $builder + +# Start, stop, and restart VMs +Start-ProxmoxVM -Connection $connection -Node "pve1" -VMID 100 +Stop-ProxmoxVM -Connection $connection -Node "pve1" -VMID 100 +Restart-ProxmoxVM -Connection $connection -Node "pve1" -VMID 100 + +# Remove a VM +Remove-ProxmoxVM -Connection $connection -Node "pve1" -VMID 100 -Confirm:$false +``` + +### Managing Templates + +```powershell +# Create a template from an existing VM +$template = New-ProxmoxVMTemplate -Connection $connection -VMID 100 -Name "Ubuntu-Template" -Description "Ubuntu 20.04 Template" + +# Get all templates +$templates = Get-ProxmoxVMTemplate + +# Create a VM from a template +$vm = New-ProxmoxVMFromTemplate -Connection $connection -Node "pve1" -TemplateName "Ubuntu-Template" -Name "web01" -Start + +# Create multiple VMs from a template +$vms = New-ProxmoxVMFromTemplate -Connection $connection -Node "pve1" -TemplateName "Ubuntu-Template" -Prefix "web" -Count 3 -Start +``` + +### Managing Storage + +```powershell +# Get all storage +$storage = Get-ProxmoxStorage -Connection $connection + +# Get storage on a specific node +$storage = Get-ProxmoxStorage -Connection $connection -Node "pve1" + +# Create a new storage +$storage = New-ProxmoxStorage -Connection $connection -Name "backup" -Type "dir" -Path "/mnt/backup" -Content "backup,iso" + +# Remove a storage +Remove-ProxmoxStorage -Connection $connection -Name "backup" -Confirm:$false +``` + +### Managing Networks + +```powershell +# Get all network interfaces on a node +$networks = Get-ProxmoxNetwork -Connection $connection -Node "pve1" + +# Create a new bridge interface +$network = New-ProxmoxNetwork -Connection $connection -Node "pve1" -Interface "vmbr1" -Type "bridge" -BridgePorts "eth1" -Method "static" -Address "192.168.2.1" -Netmask "255.255.255.0" -Autostart + +# Remove a network interface +Remove-ProxmoxNetwork -Connection $connection -Node "pve1" -Interface "vmbr1" -Confirm:$false +``` + +### Managing Users and Roles + +```powershell +# Get all users +$users = Get-ProxmoxUser -Connection $connection + +# Create a new user +$securePassword = ConvertTo-SecureString "password" -AsPlainText -Force +$user = New-ProxmoxUser -Connection $connection -Username "john" -Realm "pam" -Password $securePassword -FirstName "John" -LastName "Doe" -Email "john.doe@example.com" + +# Remove a user +Remove-ProxmoxUser -Connection $connection -UserID "john@pam" -Confirm:$false + +# Get all roles +$roles = Get-ProxmoxRole -Connection $connection + +# Create a new role +$role = New-ProxmoxRole -Connection $connection -RoleID "Developer" -Privileges "VM.Allocate", "VM.Config.Disk", "VM.Config.CPU", "VM.PowerMgmt" + +# Remove a role +Remove-ProxmoxRole -Connection $connection -RoleID "Developer" -Confirm:$false +``` + +### Managing SDN + +```powershell +# Get all SDN zones +$zones = Get-ProxmoxSDNZone -Connection $connection + +# Create a new SDN zone +$zone = New-ProxmoxSDNZone -Connection $connection -Zone "zone1" -Type "vlan" -Bridge "vmbr0" + +# Remove an SDN zone +Remove-ProxmoxSDNZone -Connection $connection -Zone "zone1" -Confirm:$false + +# Get all SDN VNets +$vnets = Get-ProxmoxSDNVnet -Connection $connection + +# Create a new SDN VNet +$vnet = New-ProxmoxSDNVnet -Connection $connection -VNet "vnet1" -Zone "zone1" -IPv4 "192.168.1.0/24" -Gateway "192.168.1.1" + +# Remove an SDN VNet +Remove-ProxmoxSDNVnet -Connection $connection -VNet "vnet1" -Confirm:$false +``` + +### Managing Clusters + +```powershell +# Get cluster information +$cluster = Get-ProxmoxCluster -Connection $connection + +# Join a node to a cluster +$securePassword = ConvertTo-SecureString "password" -AsPlainText -Force +Join-ProxmoxCluster -Connection $connection -ClusterName "cluster1" -HostName "pve1" -Password $securePassword + +# Leave a cluster +Leave-ProxmoxCluster -Connection $connection -Force + +# Create a cluster backup +$backup = New-ProxmoxClusterBackup -Connection $connection -Compress -Wait + +# Restore a cluster backup +Restore-ProxmoxClusterBackup -Connection $connection -BackupID "vzdump-cluster-2023_04_28-12_00_00.vma.lzo" -Force -Wait +``` + +### Managing IP Addresses + +```powershell +# Create a new IP pool +$pool = New-ProxmoxIPPool -Name "Production" -CIDR "192.168.1.0/24" -ExcludeIPs "192.168.1.1", "192.168.1.254" + +# Get all IP pools +$pools = Get-ProxmoxIPPool + +# Get a specific IP pool +$pool = Get-ProxmoxIPPool -Name "Production" + +# Clear an IP pool +Clear-ProxmoxIPPool -Name "Production" +``` + +## Disconnecting + +```powershell +# Disconnect from the server +Disconnect-ProxmoxServer -Connection $connection +``` + +## Development + +### Building the Module + +To build the module from source: + +```powershell +# Run the build script +.\Scripts\build.ps1 +``` + +This will: +1. Compile the C# code +2. Create a versioned release in the Release folder +3. Update the Module folder with the latest build +4. Create a ZIP package for distribution + +### Project Organization + +- **C# Source Code**: All C# source code is in the PSProxmox folder +- **PowerShell Module**: The PowerShell module files are in the Module folder +- **Documentation**: Comprehensive documentation is in the Documentation folder +- **Scripts**: Build and installation scripts are in the Scripts folder + +## Documentation + +For detailed documentation, see the [Documentation](Documentation) directory. The documentation includes: + +- [Cmdlet Reference](Documentation/cmdlets/README.md) +- [Examples](Documentation/examples/README.md) +- [Guides](Documentation/guides/README.md) + +## Contributing + +Contributions are welcome! Please feel free to submit a Pull Request. + +## License + +This project is licensed under the MIT License - see the LICENSE file for details. diff --git a/Module/PSProxmox.psd1 b/Module/PSProxmox.psd1 index 999e9ff..894501e 100644 --- a/Module/PSProxmox.psd1 +++ b/Module/PSProxmox.psd1 @@ -9,7 +9,7 @@ DotNetFrameworkVersion = '4.7.2' CompatiblePSEditions = @('Desktop', 'Core') # Assemblies that must be loaded prior to importing this module - RequiredAssemblies = @('bin\PSProxmox.dll', 'lib\Newtonsoft.Json.dll') + RequiredAssemblies = @('bin\PSProxmox.dll') # Root module RootModule = 'bin\PSProxmox.dll' # Script files (.ps1) that are run in the caller's environment prior to importing this module diff --git a/Module/lib/Newtonsoft.Json.dll b/Module/lib/Newtonsoft.Json.dll deleted file mode 100644 index 3af21d5..0000000 Binary files a/Module/lib/Newtonsoft.Json.dll and /dev/null differ diff --git a/PSProxmox/PSProxmox.psd1 b/PSProxmox/PSProxmox.psd1 index 7076327..6adfe57 100644 --- a/PSProxmox/PSProxmox.psd1 +++ b/PSProxmox/PSProxmox.psd1 @@ -9,7 +9,7 @@ DotNetFrameworkVersion = '4.7.2' CompatiblePSEditions = @('Desktop', 'Core') # Assemblies that must be loaded prior to importing this module - RequiredAssemblies = @('bin\PSProxmox.dll', 'lib\Newtonsoft.Json.dll') + RequiredAssemblies = @('bin\PSProxmox.dll') # Root module RootModule = 'bin\PSProxmox.dll' # Script files (.ps1) that are run in the caller's environment prior to importing this module diff --git a/Scripts/build.ps1 b/Scripts/build.ps1 index 09117ce..c5ae764 100644 --- a/Scripts/build.ps1 +++ b/Scripts/build.ps1 @@ -1,6 +1,11 @@ # build.ps1 # This script builds the PSProxmox module and creates a release package +param( + [switch]$Publish, + [string]$NuGetApiKey = $env:NUGET_API_KEY +) + # Set script root path for relative paths $scriptRoot = $PSScriptRoot $rootPath = Split-Path -Parent $scriptRoot @@ -54,7 +59,7 @@ if (-not (Test-Path -Path "$releaseVersionDir\bin")) { Write-Host "Updating Module directory with built files..." Copy-Item -Path "$releaseBinDir\PSProxmox.dll" -Destination "$rootPath\Module\bin" -Force -# Copy dependencies to the Module directory +# Copy dependencies to the Module directory (all dependencies now in bin) Write-Host "Copying dependencies to Module directory..." Copy-Item -Path "$releaseBinDir\Newtonsoft.Json.dll" -Destination "$rootPath\Module\bin" -Force @@ -64,3 +69,54 @@ Compress-Archive -Path "$releaseVersionDir\*" -DestinationPath $zipPath -Force Write-Host "Created release package: $zipPath" Write-Host "Build completed successfully!" + +# Publish to PowerShell Gallery if requested +if ($Publish) { + Write-Host "Publishing to PowerShell Gallery..." + + if (-not $NuGetApiKey) { + Write-Error "NuGetApiKey is required for publishing. Set the NUGET_API_KEY environment variable or pass -NuGetApiKey parameter." + exit 1 + } + + # Create proper folder structure for publishing: Module\PSProxmox\Version\Content + $publishBaseDir = "$rootPath\Publish" + $publishModuleDir = "$publishBaseDir\PSProxmox" + $publishVersionDir = "$publishModuleDir\$version" + + # Clean and create publish directory structure + if (Test-Path -Path $publishBaseDir) { + Remove-Item -Path $publishBaseDir -Recurse -Force + } + New-Item -Path $publishVersionDir -ItemType Directory -Force | Out-Null + Write-Host "Created publish directory: $publishVersionDir" + + # Copy module content to version directory + Copy-Item -Path "$rootPath\Module\PSProxmox.psd1" -Destination $publishVersionDir -Force + Copy-Item -Path "$rootPath\LICENSE" -Destination $publishVersionDir -Force + Copy-Item -Path "$rootPath\README.md" -Destination $publishVersionDir -Force + Copy-Item -Path "$rootPath\Module\bin" -Destination $publishVersionDir -Recurse -Force + + # Also copy the manifest to the module level for Publish-Module to find + Copy-Item -Path "$rootPath\Module\PSProxmox.psd1" -Destination $publishModuleDir -Force + + # Remove lib directory since we're loading everything from bin now + if (Test-Path -Path "$publishVersionDir\lib") { + Remove-Item -Path "$publishVersionDir\lib" -Recurse -Force + } + + try { + # Publish from the PSProxmox level (not the version level) + Publish-Module -Path $publishModuleDir -NuGetApiKey $NuGetApiKey -LicenseUri 'https://github.com/Grace-Solutions/PSProxmox/blob/main/LICENSE' -Tag 'Proxmox','VirtualMachine','Cluster','Management' -ReleaseNotes "Updated to .NET Standard 2.0 for dual PowerShell 5.1/7+ support. Added missing SMBIOS cmdlets. Complete compatibility with both Windows PowerShell and PowerShell Core. Version consistency across all binaries." -Verbose + Write-Host "Successfully published PSProxmox version $version to PowerShell Gallery!" -ForegroundColor Green + + # Clean up publish directory after successful publish + Remove-Item -Path $publishBaseDir -Recurse -Force + Write-Host "Cleaned up temporary publish directory" + } + catch { + Write-Error "Failed to publish module: $($_.Exception.Message)" + Write-Host "Publish directory preserved at: $publishBaseDir" + exit 1 + } +}