Pulumi Proxmox Provider

Build pulumi provider docs

This repository contains a Pulumi Provider for managing Proxmox VE resources. It allows you to define and manage Proxmox VE resources using Pulumi's infrastructure-as-code approach. (Сurrently in early development stage - focused on LXC container management using)

Overview

Custom Pulumi provider for Proxmox VE written in Python. Main focus is on LXC containers with features missing in existing providers.

Why?

Existing Terraform/Pulumi providers have limitations that affect my workflow:

• LXC disk expansion requires container recreation instead of using Proxmox API
• Missing advanced LXC configuration options
• Limited Proxmox API coverage

This provider is written in Python for easier development and customization.

🔗 Alternative Proxmox IaC Solutions

Terraform Providers

• Telmate/terraform-provider-proxmox - Original Terraform provider
• BPG/terraform-provider-proxmox - Community-maintained fork

Pulumi Providers

• muhlba91/pulumi-proxmoxve - Comprehensive Pulumi provider
• hctamu/pulumi-pve - Alternative Pulumi implementation

📦 Features

Current Implementation

• 🚧 In Development: Core LXC container management
• 🚧 In Development: Enhanced disk operations

Planned Features

• 📦 LXC Containers: Full lifecycle management
• 💾 Disk Management: Dynamic expansion and configuration
• 🌐 Networking: Advanced networking configuration
• 🔧 Templates: Support for LXC templates
• 📊 Monitoring: Resource usage and status monitoring

🛠️ Getting Started

Prerequisites

• Python
• Pulumi CLI
• Access to a Proxmox VE cluster

Installation

Option 1: Install from PyPI (when published)

pip install pulumi-proxmox-provider

Option 2: Install from GitHub (current)

# Install directly from GitHub
pip install git+https://github.com/akmalovaa/pulumi-proxmox-provider.git

# Or clone and install in development mode
git clone https://github.com/akmalovaa/pulumi-proxmox-provider.git
cd pulumi-proxmox-provider
pip install -e .

Option 3: Using uv (recommended for development)

git clone https://github.com/akmalovaa/pulumi-proxmox-provider.git
cd pulumi-proxmox-provider
uv sync

Usage

# Example Python usage - see examples/example_lxc.py for complete example
import pulumi
from pulumi_proxmox_provider import LXCContainer, LXCContainerArgs

# Configuration
config = pulumi.Config("proxmox")

# Create LXC container
lxc = LXCContainer(
    "my-test-container",
    LXCContainerArgs(
        node=config.get("node", "pve"),
        vm_id=210,
        hostname="test-container",
        cores=2,
        memory=512,
        ostemplate="local:vztmpl/ubuntu-24.10-standard_24.10-1_amd64.tar.zst",
        password="secure-password",
        unprivileged=True,
        disks={
            "rootfs": "local-lvm:8",  # 8GB root filesystem
        },
        networks={
            "net0": "name=eth0,bridge=vmbr0,ip=dhcp",
        },
    ),
)

# Export container information
pulumi.export("container_id", lxc.vm_id)
pulumi.export("container_hostname", lxc.hostname)

For more examples, check the examples/ directory.

Resources

• Pulumi Registry - Official Pulumi provider registry
• Proxmox VE API Documentation

Development

uv pip install -e .
# or
uv pip install -e . --force-reinstall

Pulumi create stack and select it:

pulumi stack ls

Preview changes:

uv run pulumi preview --diff

Pre-hook verify manual:

uv run pre-commit run --all-files --hook-stage manual
# or commit disable hooks
git commit -m "Update pre-commit configuration to fixed versions" --no-verify

Logging example:

pulumi.info("message")
pulumi.info("message", resource)
pulumi.debug("hidden by default")
pulumi.warn("warning")
pulumi.error("fatal error")