add comprehensive documentation (#9537 )

2025-12-01 13:50:11 +01:00

8.2 KiB

Raw Blame History

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

Visual execution flows showing cloud-init generation and VM provisioning workflows.

📚 CLOUD_INIT_FUNC_FUNCTIONS_REFERENCE.md

Complete alphabetical reference of all cloud-init functions.

💡 CLOUD_INIT_FUNC_USAGE_EXAMPLES.md

Practical examples for VM cloud-init setup and customization.

🔗 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

#!/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

#!/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

#!/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

#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

network:
  version: 2
  ethernets:
    eth0:
      dhcp4: true
      dhcp6: true

Static IP Configuration

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"

# 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"

# Verify SSH key in cloud-config
grep ssh_authorized_keys user-data.txt

# Check permissions
ls -la ~/.ssh/authorized_keys

"Network Not Configured"

# Check network configuration
ip addr show
ip route show

# View netplan (if used)
cat /etc/netplan/*.yaml

"Packages Failed to Install"

# Check cloud-init package log
tail /var/log/cloud-init-output.log

# Manual package installation
apt-get update && apt-get install -y package-name

install.func/ - Container installation (similar workflow)
core.func/ - Utility functions
error_handler.func/ - Error handling
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

8.2 KiB Raw Blame History