3998b80194
Introduced new and updated documentation files across the docs/ directory, including project structure guides, function library references, and standardized READMEs for ct, install, vm, tools, api, and misc. This update fully documents all nine function libraries, provides quick start and learning paths, and mirrors the project structure for easier navigation and contribution.
340 lines
8.2 KiB
Markdown
340 lines
8.2 KiB
Markdown
# 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
|