| Name | proxmox-cloud-importer JSON |
| Version |
0.1.7
JSON |
| download |
| home_page | None |
| Summary | CLI tool for importing cloud images to Proxmox server |
| upload_time | 2025-08-27 23:53:42 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT License Copyright (c) 2025 Yury Sokov 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. |
| keywords |
cli
cloud
images
proxmox
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Proxmox Cloud Image Importer
A CLI tool for importing cloud images to Proxmox server with support for multiple distributions and automatic VM template creation.
## Features
- **Rich CLI Interface**: Beautiful command-line interface with progress bars, tables, and colored output using Rich library
- **Multiple OS Support**: Pre-configured support for Ubuntu, Debian, CentOS Stream, and Rocky Linux cloud images
- **Checksum Verification**: Automatic verification of downloaded images using published checksums
- **Automatic VM Template Creation**: Creates ready-to-use VM templates with proper cloud-init configuration
- **Process Management**: Uses Plumbum library for robust process execution instead of subprocess
- **YAML Configuration**: Flexible configuration system for managing image metadata
- **Download Management**: Intelligent download caching and cleanup options
## Requirements
- Python 3.8+
- Proxmox VE server with CLI access (`qm`, `qemu-img` commands)
- Internet access for downloading cloud images
## Installation
This project uses `uv` for dependency management. Install it first:
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
Then clone and install the project:
```bash
git clone <repository-url>
cd proxmox-cloud-image-importer
uv sync
```
## Quick Start with uvx
If you want to try the tool without installing it, you can use `uvx` (part of the `uv` toolchain) to run it directly:
```bash
# Install uv first if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh
# Run the tool directly from PyPI (once published)
uvx proxmox-cloud-importer list
# Or run from a local directory
uvx --from . proxmox-cloud-importer list
# Or from a git repository
uvx --from git+https://github.com/yurzs/proxmox-cloud-image-importer proxmox-cloud-importer list
```
This approach creates a temporary isolated environment and runs the tool without permanently installing it on your system.
## Configuration
The tool uses a YAML configuration file (`images.yaml`) to define available cloud images and settings. The default configuration includes:
- **Ubuntu 22.04 LTS** and **20.04 LTS**
- **Debian 12** (Bookworm) and **11** (Bullseye)
- **CentOS Stream 9**
- **Rocky Linux 9**
### Configuration Structure
```yaml
images:
ubuntu_22_04:
name: "Ubuntu 22.04 LTS"
description: "Ubuntu 22.04 LTS (Jammy Jellyfish) Cloud Image"
url: "https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img"
format: "qcow2"
os_type: "ubuntu"
version: "22.04"
architecture: "amd64"
checksum_url: "https://cloud-images.ubuntu.com/jammy/current/SHA256SUMS"
cloud_init: true
proxmox:
default_storage: "local-lvm"
default_vm_id_start: 9000
temp_download_path: "/tmp/cloud-images"
settings:
verify_checksums: true
cleanup_downloads: true
default_disk_size: "20G"
qemu_guest_agent: true
```
## Usage
You can run the tool in two ways:
1. **Traditional installation** (after running `uv sync`):
```bash
proxmox-cloud-importer <command>
```
2. **Using uvx** (no installation required):
```bash
uvx --from . proxmox-cloud-importer <command>
# Or from git repository:
uvx --from git+https://github.com/example/proxmox-cloud-image-importer proxmox-cloud-importer <command>
```
### List Available Images
```bash
# Traditional approach
proxmox-cloud-importer list
# Using uvx
uvx --from . proxmox-cloud-importer list
```
### Show Image Information
```bash
# Traditional approach
proxmox-cloud-importer info ubuntu_22_04
# Using uvx
uvx --from . proxmox-cloud-importer info ubuntu_22_04
```
### Download an Image Only
```bash
# Traditional approach
proxmox-cloud-importer download ubuntu_22_04 --output-dir ./downloads
# Using uvx
uvx --from . proxmox-cloud-importer download ubuntu_22_04 --output-dir ./downloads
```
### Import Image to Proxmox
```bash
# Traditional approach - Import with auto-generated VM ID
proxmox-cloud-importer import-image ubuntu_22_04
# Using uvx - Import with auto-generated VM ID
uvx --from . proxmox-cloud-importer import-image ubuntu_22_04
# Traditional approach - Import with specific VM ID and storage
proxmox-cloud-importer import-image ubuntu_22_04 --vm-id 100 --storage local-lvm --template-name "Ubuntu-22.04-Template"
# Using uvx - Import with specific VM ID and storage
uvx --from . proxmox-cloud-importer import-image ubuntu_22_04 --vm-id 100 --storage local-lvm --template-name "Ubuntu-22.04-Template"
# Traditional approach - Download only without importing
proxmox-cloud-importer import-image ubuntu_22_04 --download-only
# Using uvx - Download only without importing
uvx --from . proxmox-cloud-importer import-image ubuntu_22_04 --download-only
```
### Custom Configuration File
```bash
# Traditional approach
proxmox-cloud-importer --config /path/to/custom-images.yaml list
# Using uvx
uvx --from . proxmox-cloud-importer --config /path/to/custom-images.yaml list
```
## Commands
- `list` - List all available cloud images
- `info <image_id>` - Show detailed information about a specific image
- `download <image_id>` - Download a cloud image
- `import-image <image_id>` - Download and import image to Proxmox
## How It Works
1. **Download**: Downloads cloud images from official sources with progress tracking
2. **Verify**: Validates downloaded images against published checksums
3. **Convert**: Converts images to qcow2 format if necessary using qemu-img
4. **Import**: Uses `qm importdisk` to import the disk image to Proxmox storage
5. **Configure**: Creates VM with appropriate settings (memory, CPU, network)
6. **Template**: Converts the VM to a template for easy deployment
## VM Template Configuration
The imported templates are configured with:
- 2 GB RAM (configurable)
- 2 CPU cores (configurable)
- VirtIO network adapter on vmbr0
- VirtIO SCSI controller
- Cloud-init support (IDE2 drive)
- Serial console access
- QEMU guest agent (if enabled)
## Error Handling
The tool includes comprehensive error handling:
- Network connectivity issues
- Checksum verification failures
- Proxmox command execution errors
- Automatic cleanup of failed imports
## Development
### Project Structure
```
proxmox-cloud-image-importer/
├── proxmox_cloud_importer/
│ ├── __init__.py
│ ├── cli.py # CLI interface with Rich
│ ├── config.py # Configuration handling
│ └── importer.py # Core import functionality
├── tests/
├── images.yaml # Default image configuration
├── pyproject.toml # Project configuration
└── README.md
```
### Running Tests
```bash
# With traditional installation
uv run pytest
# With uvx (from local directory)
uvx --from . --with pytest pytest
# With uvx (from git repository)
uvx --from git+https://github.com/example/proxmox-cloud-image-importer --with pytest pytest
```
### Code Formatting
```bash
# With traditional installation
uv run black .
# With uvx
uvx --from . --with black black .
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Run the test suite
6. Submit a pull request
## License
MIT License - see LICENSE file for details
## Troubleshooting
### Common Issues
1. **Permission Denied**: Ensure you have sudo access on the Proxmox server
2. **Storage Not Found**: Verify the storage name in your configuration exists in Proxmox
3. **Network Issues**: Check internet connectivity for image downloads
4. **Checksum Failures**: May indicate network issues or corrupted downloads
### Logging
Enable debug logging:
```bash
# With traditional installation
proxmox-cloud-importer --log-level DEBUG <command>
# With uvx
uvx --from . proxmox-cloud-importer --log-level DEBUG <command>
# Alternative approach using Python module
export PYTHONPATH=.
python -m proxmox_cloud_importer.cli --help
```
For verbose output, check the system logs on the Proxmox server after import failures.
Raw data
{
"_id": null,
"home_page": null,
"name": "proxmox-cloud-importer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "cli, cloud, images, proxmox",
"author": null,
"author_email": "Yury Sokov <me@yurzs.dev>",
"download_url": "https://files.pythonhosted.org/packages/21/72/edce73f332c2dcad28af883058af64e5c09d5f84264dde11ba71d8b30784/proxmox_cloud_importer-0.1.7.tar.gz",
"platform": null,
"description": "# Proxmox Cloud Image Importer\n\nA CLI tool for importing cloud images to Proxmox server with support for multiple distributions and automatic VM template creation.\n\n## Features\n\n- **Rich CLI Interface**: Beautiful command-line interface with progress bars, tables, and colored output using Rich library\n- **Multiple OS Support**: Pre-configured support for Ubuntu, Debian, CentOS Stream, and Rocky Linux cloud images\n- **Checksum Verification**: Automatic verification of downloaded images using published checksums\n- **Automatic VM Template Creation**: Creates ready-to-use VM templates with proper cloud-init configuration\n- **Process Management**: Uses Plumbum library for robust process execution instead of subprocess\n- **YAML Configuration**: Flexible configuration system for managing image metadata\n- **Download Management**: Intelligent download caching and cleanup options\n\n## Requirements\n\n- Python 3.8+\n- Proxmox VE server with CLI access (`qm`, `qemu-img` commands)\n- Internet access for downloading cloud images\n\n## Installation\n\nThis project uses `uv` for dependency management. Install it first:\n\n```bash\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\n\nThen clone and install the project:\n\n```bash\ngit clone <repository-url>\ncd proxmox-cloud-image-importer\nuv sync\n```\n\n## Quick Start with uvx\n\nIf you want to try the tool without installing it, you can use `uvx` (part of the `uv` toolchain) to run it directly:\n\n```bash\n# Install uv first if you haven't already\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Run the tool directly from PyPI (once published)\nuvx proxmox-cloud-importer list\n\n# Or run from a local directory\nuvx --from . proxmox-cloud-importer list\n\n# Or from a git repository\nuvx --from git+https://github.com/yurzs/proxmox-cloud-image-importer proxmox-cloud-importer list\n```\n\nThis approach creates a temporary isolated environment and runs the tool without permanently installing it on your system.\n\n## Configuration\n\nThe tool uses a YAML configuration file (`images.yaml`) to define available cloud images and settings. The default configuration includes:\n\n- **Ubuntu 22.04 LTS** and **20.04 LTS**\n- **Debian 12** (Bookworm) and **11** (Bullseye)\n- **CentOS Stream 9**\n- **Rocky Linux 9**\n\n### Configuration Structure\n\n```yaml\nimages:\n ubuntu_22_04:\n name: \"Ubuntu 22.04 LTS\"\n description: \"Ubuntu 22.04 LTS (Jammy Jellyfish) Cloud Image\"\n url: \"https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img\"\n format: \"qcow2\"\n os_type: \"ubuntu\"\n version: \"22.04\"\n architecture: \"amd64\"\n checksum_url: \"https://cloud-images.ubuntu.com/jammy/current/SHA256SUMS\"\n cloud_init: true\n\nproxmox:\n default_storage: \"local-lvm\"\n default_vm_id_start: 9000\n temp_download_path: \"/tmp/cloud-images\"\n\nsettings:\n verify_checksums: true\n cleanup_downloads: true\n default_disk_size: \"20G\"\n qemu_guest_agent: true\n```\n\n## Usage\n\nYou can run the tool in two ways:\n\n1. **Traditional installation** (after running `uv sync`):\n ```bash\n proxmox-cloud-importer <command>\n ```\n\n2. **Using uvx** (no installation required):\n ```bash\n uvx --from . proxmox-cloud-importer <command>\n # Or from git repository:\n uvx --from git+https://github.com/example/proxmox-cloud-image-importer proxmox-cloud-importer <command>\n ```\n\n### List Available Images\n\n```bash\n# Traditional approach\nproxmox-cloud-importer list\n\n# Using uvx\nuvx --from . proxmox-cloud-importer list\n```\n\n### Show Image Information\n\n```bash\n# Traditional approach\nproxmox-cloud-importer info ubuntu_22_04\n\n# Using uvx\nuvx --from . proxmox-cloud-importer info ubuntu_22_04\n```\n\n### Download an Image Only\n\n```bash\n# Traditional approach\nproxmox-cloud-importer download ubuntu_22_04 --output-dir ./downloads\n\n# Using uvx\nuvx --from . proxmox-cloud-importer download ubuntu_22_04 --output-dir ./downloads\n```\n\n### Import Image to Proxmox\n\n```bash\n# Traditional approach - Import with auto-generated VM ID\nproxmox-cloud-importer import-image ubuntu_22_04\n\n# Using uvx - Import with auto-generated VM ID\nuvx --from . proxmox-cloud-importer import-image ubuntu_22_04\n\n# Traditional approach - Import with specific VM ID and storage\nproxmox-cloud-importer import-image ubuntu_22_04 --vm-id 100 --storage local-lvm --template-name \"Ubuntu-22.04-Template\"\n\n# Using uvx - Import with specific VM ID and storage\nuvx --from . proxmox-cloud-importer import-image ubuntu_22_04 --vm-id 100 --storage local-lvm --template-name \"Ubuntu-22.04-Template\"\n\n# Traditional approach - Download only without importing\nproxmox-cloud-importer import-image ubuntu_22_04 --download-only\n\n# Using uvx - Download only without importing\nuvx --from . proxmox-cloud-importer import-image ubuntu_22_04 --download-only\n```\n\n### Custom Configuration File\n\n```bash\n# Traditional approach\nproxmox-cloud-importer --config /path/to/custom-images.yaml list\n\n# Using uvx\nuvx --from . proxmox-cloud-importer --config /path/to/custom-images.yaml list\n```\n\n## Commands\n\n- `list` - List all available cloud images\n- `info <image_id>` - Show detailed information about a specific image\n- `download <image_id>` - Download a cloud image\n- `import-image <image_id>` - Download and import image to Proxmox\n\n## How It Works\n\n1. **Download**: Downloads cloud images from official sources with progress tracking\n2. **Verify**: Validates downloaded images against published checksums\n3. **Convert**: Converts images to qcow2 format if necessary using qemu-img\n4. **Import**: Uses `qm importdisk` to import the disk image to Proxmox storage\n5. **Configure**: Creates VM with appropriate settings (memory, CPU, network)\n6. **Template**: Converts the VM to a template for easy deployment\n\n## VM Template Configuration\n\nThe imported templates are configured with:\n- 2 GB RAM (configurable)\n- 2 CPU cores (configurable)\n- VirtIO network adapter on vmbr0\n- VirtIO SCSI controller\n- Cloud-init support (IDE2 drive)\n- Serial console access\n- QEMU guest agent (if enabled)\n\n## Error Handling\n\nThe tool includes comprehensive error handling:\n- Network connectivity issues\n- Checksum verification failures\n- Proxmox command execution errors\n- Automatic cleanup of failed imports\n\n## Development\n\n### Project Structure\n\n```\nproxmox-cloud-image-importer/\n\u251c\u2500\u2500 proxmox_cloud_importer/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 cli.py # CLI interface with Rich\n\u2502 \u251c\u2500\u2500 config.py # Configuration handling\n\u2502 \u2514\u2500\u2500 importer.py # Core import functionality\n\u251c\u2500\u2500 tests/\n\u251c\u2500\u2500 images.yaml # Default image configuration\n\u251c\u2500\u2500 pyproject.toml # Project configuration\n\u2514\u2500\u2500 README.md\n```\n\n### Running Tests\n\n```bash\n# With traditional installation\nuv run pytest\n\n# With uvx (from local directory)\nuvx --from . --with pytest pytest\n\n# With uvx (from git repository)\nuvx --from git+https://github.com/example/proxmox-cloud-image-importer --with pytest pytest\n```\n\n### Code Formatting\n\n```bash\n# With traditional installation\nuv run black .\n\n# With uvx\nuvx --from . --with black black .\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Run the test suite\n6. Submit a pull request\n\n## License\n\nMIT License - see LICENSE file for details\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Permission Denied**: Ensure you have sudo access on the Proxmox server\n2. **Storage Not Found**: Verify the storage name in your configuration exists in Proxmox\n3. **Network Issues**: Check internet connectivity for image downloads\n4. **Checksum Failures**: May indicate network issues or corrupted downloads\n\n### Logging\n\nEnable debug logging:\n\n```bash\n# With traditional installation\nproxmox-cloud-importer --log-level DEBUG <command>\n\n# With uvx\nuvx --from . proxmox-cloud-importer --log-level DEBUG <command>\n\n# Alternative approach using Python module\nexport PYTHONPATH=.\npython -m proxmox_cloud_importer.cli --help\n```\n\nFor verbose output, check the system logs on the Proxmox server after import failures.",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2025 Yury Sokov 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.",
"summary": "CLI tool for importing cloud images to Proxmox server",
"version": "0.1.7",
"project_urls": {
"Homepage": "https://github.com/yurzs/proxmox-cloud-importer",
"Issues": "https://github.com/yurzs/proxmox-cloud-importer/issues",
"Repository": "https://github.com/yurzs/proxmox-cloud-importer"
},
"split_keywords": [
"cli",
" cloud",
" images",
" proxmox"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "eb83a3ad7d95ff858a265118e6cef29fee198c6025b750b85aac8401a2f2664a",
"md5": "7f32fd4c08981d74c7d8051072f5849d",
"sha256": "6ad1ff6d281bff74fdd29daa1a2f74a5d0238f936804951989be112fdbb25844"
},
"downloads": -1,
"filename": "proxmox_cloud_importer-0.1.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7f32fd4c08981d74c7d8051072f5849d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 18786,
"upload_time": "2025-08-27T23:53:40",
"upload_time_iso_8601": "2025-08-27T23:53:40.276849Z",
"url": "https://files.pythonhosted.org/packages/eb/83/a3ad7d95ff858a265118e6cef29fee198c6025b750b85aac8401a2f2664a/proxmox_cloud_importer-0.1.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2172edce73f332c2dcad28af883058af64e5c09d5f84264dde11ba71d8b30784",
"md5": "9b535ecdfa74000c7485a781065f604b",
"sha256": "09583921cade48ea02b3a7f683b1d84dba9f06f888a1ac77555d6ad55fcfc501"
},
"downloads": -1,
"filename": "proxmox_cloud_importer-0.1.7.tar.gz",
"has_sig": false,
"md5_digest": "9b535ecdfa74000c7485a781065f604b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 70682,
"upload_time": "2025-08-27T23:53:42",
"upload_time_iso_8601": "2025-08-27T23:53:42.200673Z",
"url": "https://files.pythonhosted.org/packages/21/72/edce73f332c2dcad28af883058af64e5c09d5f84264dde11ba71d8b30784/proxmox_cloud_importer-0.1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-27 23:53:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yurzs",
"github_project": "proxmox-cloud-importer",
"github_not_found": true,
"lcname": "proxmox-cloud-importer"
}
