mirror of
https://github.com/Grace-Solutions/PSProxmox.git
synced 2026-08-08 22:33:23 +00:00
Alphaeus Mote
301 lines
9.1 KiB
Markdown
301 lines
9.1 KiB
Markdown
# 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
|
|
- **Cloud Images**: Download, customize, and create templates from cloud images
|
|
- **Cloud-Init Support**: Configure VMs with Cloud-Init for easy customization
|
|
- **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/Grace-Solutions/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
|
|
Connect-ProxmoxServer -Server "proxmox.example.com" -Username "root" -Password $securePassword -Realm "pam"
|
|
|
|
# Connect using a credential object
|
|
$credential = Get-Credential
|
|
Connect-ProxmoxServer -Server "proxmox.example.com" -Credential $credential -Realm "pam"
|
|
|
|
# Test the connection
|
|
Test-ProxmoxConnection -Detailed
|
|
```
|
|
|
|
### Managing Virtual Machines
|
|
|
|
```powershell
|
|
# Get all VMs (uses the default connection automatically)
|
|
$vms = Get-ProxmoxVM
|
|
|
|
# Get a specific VM
|
|
$vm = Get-ProxmoxVM -VMID 100
|
|
|
|
# Create a new VM
|
|
$vm = New-ProxmoxVM -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 -Node "pve1" -Builder $builder
|
|
|
|
# Start, stop, and restart VMs
|
|
Start-ProxmoxVM -Node "pve1" -VMID 100
|
|
Stop-ProxmoxVM -Node "pve1" -VMID 100
|
|
Restart-ProxmoxVM -Node "pve1" -VMID 100
|
|
|
|
# Remove a VM
|
|
Remove-ProxmoxVM -Node "pve1" -VMID 100 -Confirm:$false
|
|
```
|
|
|
|
### Managing Templates
|
|
|
|
```powershell
|
|
# Create a template from an existing VM
|
|
$template = New-ProxmoxVMTemplate -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 -Node "pve1" -TemplateName "Ubuntu-Template" -Name "web01" -Start
|
|
|
|
# Create multiple VMs from a template
|
|
$vms = New-ProxmoxVMFromTemplate -Node "pve1" -TemplateName "Ubuntu-Template" -Prefix "web" -Count 3 -Start
|
|
```
|
|
|
|
### Working with Cloud Images
|
|
|
|
```powershell
|
|
# List available cloud images
|
|
Get-ProxmoxCloudImage -Distribution "ubuntu" -Release "22.04"
|
|
|
|
# Download a cloud image
|
|
$imagePath = Save-ProxmoxCloudImage -Distribution "ubuntu" -Release "22.04" -Variant "server"
|
|
|
|
# Customize the cloud image (resize to 20GB)
|
|
$customizedImagePath = Invoke-ProxmoxCloudImageCustomization -ImagePath $imagePath -Resize 20 -ConvertTo "qcow2"
|
|
|
|
# Create a template from the cloud image
|
|
$template = New-ProxmoxCloudImageTemplate -Node "pve1" -Name "ubuntu-22.04" -ImagePath $customizedImagePath -Storage "local-lvm" -Memory 2048 -Cores 2 -DiskSize 20
|
|
|
|
# Alternatively, download and create a template in one step
|
|
$template = New-ProxmoxCloudImageTemplate -Node "pve1" -Name "ubuntu-22.04" -Distribution "ubuntu" -Release "22.04" -Storage "local-lvm" -Memory 2048 -Cores 2 -DiskSize 20
|
|
|
|
# Configure Cloud-Init for a VM
|
|
$password = ConvertTo-SecureString "SecurePassword123!" -AsPlainText -Force
|
|
$sshKey = Get-Content -Path "~/.ssh/id_rsa.pub"
|
|
Set-ProxmoxVMCloudInit -Node "pve1" -VMID 100 -Username "admin" -Password $password -SSHKey $sshKey -IPConfig "dhcp" -DNS "8.8.8.8,8.8.4.4"
|
|
|
|
# Create a VM from the template with static IP
|
|
$vm = New-ProxmoxVMFromTemplate -Node "pve1" -TemplateName "ubuntu-22.04" -Name "web01"
|
|
Set-ProxmoxVMCloudInit -Node "pve1" -VMID $vm.VMID -Username "admin" -Password $password -IPConfig "ip=192.168.1.100/24,gw=192.168.1.1"
|
|
Start-ProxmoxVM -Node "pve1" -VMID $vm.VMID
|
|
```
|
|
|
|
### Managing Storage
|
|
|
|
```powershell
|
|
# Get all storage
|
|
$storage = Get-ProxmoxStorage
|
|
|
|
# Get storage on a specific node
|
|
$storage = Get-ProxmoxStorage -Node "pve1"
|
|
|
|
# Create a new storage
|
|
$storage = New-ProxmoxStorage -Name "backup" -Type "dir" -Path "/mnt/backup" -Content "backup,iso"
|
|
|
|
# Remove a storage
|
|
Remove-ProxmoxStorage -Name "backup" -Confirm:$false
|
|
```
|
|
|
|
### Managing Networks
|
|
|
|
```powershell
|
|
# Get all network interfaces on a node
|
|
$networks = Get-ProxmoxNetwork -Node "pve1"
|
|
|
|
# Create a new bridge interface
|
|
$network = New-ProxmoxNetwork -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 -Node "pve1" -Interface "vmbr1" -Confirm:$false
|
|
```
|
|
|
|
### Managing Users and Roles
|
|
|
|
```powershell
|
|
# Get all users
|
|
$users = Get-ProxmoxUser
|
|
|
|
# Create a new user
|
|
$securePassword = ConvertTo-SecureString "password" -AsPlainText -Force
|
|
$user = New-ProxmoxUser -Username "john" -Realm "pam" -Password $securePassword -FirstName "John" -LastName "Doe" -Email "john.doe@example.com"
|
|
|
|
# Remove a user
|
|
Remove-ProxmoxUser -UserID "john@pam" -Confirm:$false
|
|
|
|
# Get all roles
|
|
$roles = Get-ProxmoxRole
|
|
|
|
# Create a new role
|
|
$role = New-ProxmoxRole -RoleID "Developer" -Privileges "VM.Allocate", "VM.Config.Disk", "VM.Config.CPU", "VM.PowerMgmt"
|
|
|
|
# Remove a role
|
|
Remove-ProxmoxRole -RoleID "Developer" -Confirm:$false
|
|
```
|
|
|
|
### Managing SDN
|
|
|
|
```powershell
|
|
# Get all SDN zones
|
|
$zones = Get-ProxmoxSDNZone
|
|
|
|
# Create a new SDN zone
|
|
$zone = New-ProxmoxSDNZone -Zone "zone1" -Type "vlan" -Bridge "vmbr0"
|
|
|
|
# Remove an SDN zone
|
|
Remove-ProxmoxSDNZone -Zone "zone1" -Confirm:$false
|
|
|
|
# Get all SDN VNets
|
|
$vnets = Get-ProxmoxSDNVnet
|
|
|
|
# Create a new SDN VNet
|
|
$vnet = New-ProxmoxSDNVnet -VNet "vnet1" -Zone "zone1" -IPv4 "192.168.1.0/24" -Gateway "192.168.1.1"
|
|
|
|
# Remove an SDN VNet
|
|
Remove-ProxmoxSDNVnet -VNet "vnet1" -Confirm:$false
|
|
```
|
|
|
|
### Managing Clusters
|
|
|
|
```powershell
|
|
# Get cluster information
|
|
$cluster = Get-ProxmoxCluster
|
|
|
|
# Join a node to a cluster
|
|
$securePassword = ConvertTo-SecureString "password" -AsPlainText -Force
|
|
Join-ProxmoxCluster -ClusterName "cluster1" -HostName "pve1" -Password $securePassword
|
|
|
|
# Leave a cluster
|
|
Leave-ProxmoxCluster -Force
|
|
|
|
# Create a cluster backup
|
|
$backup = New-ProxmoxClusterBackup -Compress -Wait
|
|
|
|
# Restore a cluster backup
|
|
Restore-ProxmoxClusterBackup -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
|
|
# Get the current connection and disconnect from the server
|
|
$connection = Test-ProxmoxConnection -Detailed
|
|
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)
|
|
- [Installation Guide](Documentation/guides/Installation.md)
|
|
- [Cloud Image Templates Guide](Documentation/guides/CloudImageTemplates.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.
|