mirror of
https://github.com/community-scripts/ProxmoxVE.git
synced 2025-12-14 19:23:32 +01:00
add comprehensive documentation (#9537)
This commit is contained in:
CanbiZ
28
docs/misc/cloud-init.func/CLOUD_INIT_FUNC_FLOWCHART.md
Normal file
28
docs/misc/cloud-init.func/CLOUD_INIT_FUNC_FLOWCHART.md
Normal file
@ -0,0 +1,28 @@
|
||||
# cloud-init.func Flowchart
|
||||
|
||||
Cloud-init VM provisioning flow.
|
||||
|
||||
## Cloud-Init Generation and Application
|
||||
|
||||
```
|
||||
generate_cloud_init()
|
||||
↓
|
||||
generate_user_data()
|
||||
↓
|
||||
setup_ssh_keys()
|
||||
↓
|
||||
Apply to VM
|
||||
↓
|
||||
VM Boot
|
||||
↓
|
||||
cloud-init phases
|
||||
├─ system
|
||||
├─ config
|
||||
└─ final
|
||||
↓
|
||||
VM Ready ✓
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: December 2025
|
||||
@ -0,0 +1,30 @@
|
||||
# cloud-init.func Functions Reference
|
||||
|
||||
Cloud-init and VM provisioning functions.
|
||||
|
||||
## Core Functions
|
||||
|
||||
### generate_cloud_init()
|
||||
Generate cloud-init configuration.
|
||||
|
||||
### generate_user_data()
|
||||
Generate user-data script for VM.
|
||||
|
||||
### apply_cloud_init()
|
||||
Apply cloud-init to VM.
|
||||
|
||||
### setup_ssh_keys()
|
||||
Deploy SSH public keys.
|
||||
|
||||
### setup_static_ip()
|
||||
Configure static IP on VM.
|
||||
|
||||
### setup_dns()
|
||||
Configure DNS for VM.
|
||||
|
||||
### setup_ipv6()
|
||||
Enable IPv6 on VM.
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: December 2025
|
||||
7
docs/misc/cloud-init.func/CLOUD_INIT_FUNC_INTEGRATION.md
Normal file
7
docs/misc/cloud-init.func/CLOUD_INIT_FUNC_INTEGRATION.md
Normal file
@ -0,0 +1,7 @@
|
||||
# cloud-init.func Integration Guide
|
||||
|
||||
Cloud-init integration with Proxmox VM provisioning.
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: December 2025
|
||||
17
docs/misc/cloud-init.func/CLOUD_INIT_FUNC_USAGE_EXAMPLES.md
Normal file
17
docs/misc/cloud-init.func/CLOUD_INIT_FUNC_USAGE_EXAMPLES.md
Normal file
@ -0,0 +1,17 @@
|
||||
# cloud-init.func Usage Examples
|
||||
|
||||
Examples for VM cloud-init configuration.
|
||||
|
||||
### Example: Basic Cloud-Init
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
|
||||
generate_cloud_init > cloud-init.yaml
|
||||
setup_ssh_keys "$VMID" "$SSH_KEY"
|
||||
apply_cloud_init "$VMID" cloud-init.yaml
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: December 2025
|
||||
339
docs/misc/cloud-init.func/README.md
Normal file
339
docs/misc/cloud-init.func/README.md
Normal file
@ -0,0 +1,339 @@
|
||||
# cloud-init.func Documentation
|
||||
|
||||
## Overview
|
||||
|
||||
The `cloud-init.func` file provides cloud-init configuration and VM initialization functions for Proxmox VE virtual machines. It handles user data, cloud-config generation, and VM setup automation.
|
||||
|
||||
## Purpose and Use Cases
|
||||
|
||||
- **VM Cloud-Init Setup**: Generate and apply cloud-init configurations for VMs
|
||||
- **User Data Generation**: Create user-data scripts for VM initialization
|
||||
- **Cloud-Config**: Generate cloud-config YAML for VM provisioning
|
||||
- **SSH Key Management**: Setup SSH keys for VM access
|
||||
- **Network Configuration**: Configure networking for VMs
|
||||
- **Automated VM Provisioning**: Complete VM setup without manual intervention
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Key Function Groups
|
||||
- **Cloud-Init Core**: Generate and apply cloud-init configurations
|
||||
- **User Data**: Create initialization scripts for VMs
|
||||
- **SSH Setup**: Deploy SSH keys automatically
|
||||
- **Network Configuration**: Setup networking during VM provisioning
|
||||
- **VM Customization**: Apply custom settings to VMs
|
||||
|
||||
### Dependencies
|
||||
- **External**: `cloud-init`, `curl`, `qemu-img`
|
||||
- **Internal**: Uses functions from `core.func`, `error_handler.func`
|
||||
|
||||
### Integration Points
|
||||
- Used by: VM creation scripts (vm/*.sh)
|
||||
- Uses: Environment variables from build.func
|
||||
- Provides: VM initialization and cloud-init services
|
||||
|
||||
## Documentation Files
|
||||
|
||||
### 📊 [CLOUD_INIT_FUNC_FLOWCHART.md](./CLOUD_INIT_FUNC_FLOWCHART.md)
|
||||
Visual execution flows showing cloud-init generation and VM provisioning workflows.
|
||||
|
||||
### 📚 [CLOUD_INIT_FUNC_FUNCTIONS_REFERENCE.md](./CLOUD_INIT_FUNC_FUNCTIONS_REFERENCE.md)
|
||||
Complete alphabetical reference of all cloud-init functions.
|
||||
|
||||
### 💡 [CLOUD_INIT_FUNC_USAGE_EXAMPLES.md](./CLOUD_INIT_FUNC_USAGE_EXAMPLES.md)
|
||||
Practical examples for VM cloud-init setup and customization.
|
||||
|
||||
### 🔗 [CLOUD_INIT_FUNC_INTEGRATION.md](./CLOUD_INIT_FUNC_INTEGRATION.md)
|
||||
How cloud-init.func integrates with VM creation and Proxmox workflows.
|
||||
|
||||
## Key Features
|
||||
|
||||
### Cloud-Init Configuration
|
||||
- **User Data Generation**: Create custom initialization scripts
|
||||
- **Cloud-Config YAML**: Generate standardized cloud-config
|
||||
- **SSH Keys**: Automatically deploy public keys
|
||||
- **Package Installation**: Install packages during VM boot
|
||||
- **Custom Commands**: Run arbitrary commands on first boot
|
||||
|
||||
### VM Network Setup
|
||||
- **DHCP Configuration**: Configure DHCP for automatic IP assignment
|
||||
- **Static IP Setup**: Configure static IP addresses
|
||||
- **IPv6 Support**: Enable IPv6 on VMs
|
||||
- **DNS Configuration**: Set DNS servers for VM
|
||||
- **Firewall Rules**: Basic firewall configuration
|
||||
|
||||
### Security Features
|
||||
- **SSH Key Injection**: Deploy SSH keys during VM creation
|
||||
- **Disable Passwords**: Disable password authentication
|
||||
- **Sudoers Configuration**: Setup sudo access
|
||||
- **User Management**: Create and configure users
|
||||
|
||||
## Function Categories
|
||||
|
||||
### 🔹 Cloud-Init Core Functions
|
||||
- `generate_cloud_init()` - Create cloud-init configuration
|
||||
- `generate_user_data()` - Generate user-data script
|
||||
- `apply_cloud_init()` - Apply cloud-init to VM
|
||||
- `validate_cloud_init()` - Validate cloud-config syntax
|
||||
|
||||
### 🔹 SSH & Security Functions
|
||||
- `setup_ssh_keys()` - Deploy SSH public keys
|
||||
- `setup_sudo()` - Configure sudoers
|
||||
- `create_user()` - Create new user account
|
||||
- `disable_password_auth()` - Disable password login
|
||||
|
||||
### 🔹 Network Configuration Functions
|
||||
- `setup_dhcp()` - Configure DHCP networking
|
||||
- `setup_static_ip()` - Configure static IP
|
||||
- `setup_dns()` - Configure DNS servers
|
||||
- `setup_ipv6()` - Enable IPv6 support
|
||||
|
||||
### 🔹 VM Customization Functions
|
||||
- `install_packages()` - Install packages during boot
|
||||
- `run_custom_commands()` - Execute custom scripts
|
||||
- `configure_hostname()` - Set VM hostname
|
||||
- `configure_timezone()` - Set VM timezone
|
||||
|
||||
## Cloud-Init Workflow
|
||||
|
||||
```
|
||||
VM Created
|
||||
↓
|
||||
cloud-init (system) boot phase
|
||||
↓
|
||||
User-Data Script Execution
|
||||
↓
|
||||
├─ Install packages
|
||||
├─ Deploy SSH keys
|
||||
├─ Configure network
|
||||
└─ Create users
|
||||
↓
|
||||
cloud-init config phase
|
||||
↓
|
||||
Apply cloud-config settings
|
||||
↓
|
||||
cloud-init final phase
|
||||
↓
|
||||
VM Ready for Use
|
||||
```
|
||||
|
||||
## Common Usage Patterns
|
||||
|
||||
### Basic VM Setup with Cloud-Init
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"
|
||||
|
||||
# Generate cloud-init configuration
|
||||
cat > cloud-init.yaml <<EOF
|
||||
#cloud-config
|
||||
hostname: myvm
|
||||
timezone: UTC
|
||||
|
||||
packages:
|
||||
- curl
|
||||
- wget
|
||||
- git
|
||||
|
||||
users:
|
||||
- name: ubuntu
|
||||
ssh_authorized_keys:
|
||||
- ssh-rsa AAAAB3...
|
||||
sudo: ALL=(ALL) NOPASSWD:ALL
|
||||
|
||||
bootcmd:
|
||||
- echo "VM initializing..."
|
||||
|
||||
runcmd:
|
||||
- apt-get update
|
||||
- apt-get upgrade -y
|
||||
EOF
|
||||
|
||||
# Apply to VM
|
||||
qm set VMID --cicustom local:snippets/cloud-init.yaml
|
||||
```
|
||||
|
||||
### With SSH Key Deployment
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"
|
||||
|
||||
# Get SSH public key
|
||||
SSH_KEY=$(cat ~/.ssh/id_rsa.pub)
|
||||
|
||||
# Generate cloud-init with SSH key
|
||||
generate_user_data > user-data.txt
|
||||
|
||||
# Inject SSH key
|
||||
setup_ssh_keys "$VMID" "$SSH_KEY"
|
||||
|
||||
# Create VM with cloud-init
|
||||
qm create $VMID ... --cicustom local:snippets/user-data
|
||||
```
|
||||
|
||||
### Network Configuration
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"
|
||||
|
||||
# Static IP setup
|
||||
setup_static_ip "192.168.1.100" "255.255.255.0" "192.168.1.1"
|
||||
|
||||
# DNS configuration
|
||||
setup_dns "8.8.8.8 8.8.4.4"
|
||||
|
||||
# IPv6 support
|
||||
setup_ipv6
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### ✅ DO
|
||||
- Validate cloud-config syntax before applying
|
||||
- Use cloud-init for automated setup
|
||||
- Deploy SSH keys for secure access
|
||||
- Test cloud-init configuration in non-production first
|
||||
- Use DHCP for easier VM deployment
|
||||
- Document custom cloud-init configurations
|
||||
- Version control cloud-init templates
|
||||
|
||||
### ❌ DON'T
|
||||
- Use weak SSH keys or passwords
|
||||
- Leave SSH password authentication enabled
|
||||
- Hardcode credentials in cloud-init
|
||||
- Skip validation of cloud-config
|
||||
- Use untrusted cloud-init sources
|
||||
- Forget to set timezone on VMs
|
||||
- Mix cloud-init versions
|
||||
|
||||
## Cloud-Config Format
|
||||
|
||||
### Example Cloud-Config
|
||||
```yaml
|
||||
#cloud-config
|
||||
# This is a comment
|
||||
|
||||
# System configuration
|
||||
hostname: myvm
|
||||
timezone: UTC
|
||||
package_upgrade: true
|
||||
|
||||
# Packages to install
|
||||
packages:
|
||||
- curl
|
||||
- wget
|
||||
- git
|
||||
- build-essential
|
||||
|
||||
# SSH keys for users
|
||||
ssh_authorized_keys:
|
||||
- ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC...
|
||||
|
||||
# Users to create
|
||||
users:
|
||||
- name: ubuntu
|
||||
home: /home/ubuntu
|
||||
shell: /bin/bash
|
||||
sudo: ['ALL=(ALL) NOPASSWD:ALL']
|
||||
ssh_authorized_keys:
|
||||
- ssh-rsa AAAAB3...
|
||||
|
||||
# Commands to run on boot
|
||||
runcmd:
|
||||
- apt-get update
|
||||
- apt-get upgrade -y
|
||||
- systemctl restart ssh
|
||||
|
||||
# Files to create
|
||||
write_files:
|
||||
- path: /etc/profile.d/custom.sh
|
||||
content: |
|
||||
export CUSTOM_VAR="value"
|
||||
```
|
||||
|
||||
## VM Network Configuration
|
||||
|
||||
### DHCP Configuration
|
||||
```bash
|
||||
network:
|
||||
version: 2
|
||||
ethernets:
|
||||
eth0:
|
||||
dhcp4: true
|
||||
dhcp6: true
|
||||
```
|
||||
|
||||
### Static IP Configuration
|
||||
```bash
|
||||
network:
|
||||
version: 2
|
||||
ethernets:
|
||||
eth0:
|
||||
addresses:
|
||||
- 192.168.1.100/24
|
||||
gateway4: 192.168.1.1
|
||||
nameservers:
|
||||
addresses: [8.8.8.8, 8.8.4.4]
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Cloud-Init Configuration Not Applied"
|
||||
```bash
|
||||
# Check cloud-init status in VM
|
||||
cloud-init status
|
||||
cloud-init status --long
|
||||
|
||||
# View cloud-init logs
|
||||
tail /var/log/cloud-init.log
|
||||
```
|
||||
|
||||
### "SSH Keys Not Deployed"
|
||||
```bash
|
||||
# Verify SSH key in cloud-config
|
||||
grep ssh_authorized_keys user-data.txt
|
||||
|
||||
# Check permissions
|
||||
ls -la ~/.ssh/authorized_keys
|
||||
```
|
||||
|
||||
### "Network Not Configured"
|
||||
```bash
|
||||
# Check network configuration
|
||||
ip addr show
|
||||
ip route show
|
||||
|
||||
# View netplan (if used)
|
||||
cat /etc/netplan/*.yaml
|
||||
```
|
||||
|
||||
### "Packages Failed to Install"
|
||||
```bash
|
||||
# Check cloud-init package log
|
||||
tail /var/log/cloud-init-output.log
|
||||
|
||||
# Manual package installation
|
||||
apt-get update && apt-get install -y package-name
|
||||
```
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **[install.func/](../install.func/)** - Container installation (similar workflow)
|
||||
- **[core.func/](../core.func/)** - Utility functions
|
||||
- **[error_handler.func/](../error_handler.func/)** - Error handling
|
||||
- **[UPDATED_APP-install.md](../../UPDATED_APP-install.md)** - Application setup guide
|
||||
- **Proxmox Docs**: https://pve.proxmox.com/wiki/Cloud-Init
|
||||
|
||||
## Recent Updates
|
||||
|
||||
### Version 2.0 (Dec 2025)
|
||||
- ✅ Enhanced cloud-init validation
|
||||
- ✅ Improved SSH key deployment
|
||||
- ✅ Better network configuration support
|
||||
- ✅ Added IPv6 support
|
||||
- ✅ Streamlined user and package setup
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: December 2025
|
||||
**Maintainers**: community-scripts team
|
||||
**License**: MIT
|
||||
Reference in New Issue
Block a user