2026-01-14 02:59:52 +00:00
|
|
|
# Troubleshooting Guide\n\nThis comprehensive troubleshooting guide helps you diagnose and resolve common issues with Infrastructure Automation.\n\n## What You'll Learn\n\n- Common issues and their solutions\n- Diagnostic commands and techniques\n- Error message interpretation\n- Performance optimization\n- Recovery procedures\n- Prevention strategies\n\n## General Troubleshooting Approach\n\n### 1. Identify the Problem\n\n```\n# Check overall system status\nprovisioning env\nprovisioning validate config\n\n# Check specific component status\nprovisioning show servers --infra my-infra\nprovisioning taskserv list --infra my-infra --installed\n```\n\n### 2. Gather Information\n\n```\n# Enable debug mode for detailed output\nprovisioning --debug <command>\n\n# Check logs and errors\nprovisioning show logs --infra my-infra\n```\n\n### 3. Use Diagnostic Commands\n\n```\n# Validate configuration\nprovisioning validate config --detailed\n\n# Test connectivity\nprovisioning provider test aws\nprovisioning network test --infra my-infra\n```\n\n## Installation and Setup Issues\n\n### Issue: Installation Fails\n\n**Symptoms:**\n\n- Installation script errors\n- Missing dependencies\n- Permission denied errors\n\n**Diagnosis:**\n\n```\n# Check system requirements\nuname -a\ndf -h\nwhoami\n\n# Check permissions\nls -la /usr/local/\nsudo -l\n```\n\n**Solutions:**\n\n#### Permission Issues\n\n```\n# Run installer with sudo\nsudo ./install-provisioning\n\n# Or install to user directory\n./install-provisioning --prefix=$HOME/provisioning\nexport PATH="$HOME/provisioning/bin:$PATH"\n```\n\n#### Missing Dependencies\n\n```\n# Ubuntu/Debian\nsudo apt update\nsudo apt install -y curl wget tar build-essential\n\n# RHEL/CentOS\nsudo dnf install -y curl wget tar gcc make\n```\n\n#### Architecture Issues\n\n```\n# Check architecture\nuname -m\n\n# Download correct architecture package\n# x86_64: Intel/AMD 64-bit\n# arm64: ARM 64-bit (Apple Silicon)\nwget https://releases.example.com/provisioning-linux-x86_64.tar.gz\n```\n\n### Issue: Command Not Found\n\n**Symptoms:**\n\n```\nbash: provisioning: command not found\n```\n\n**Diagnosis:**\n\n```\n# Check if provisioning is installed\nwhich provisioning\nls -la /usr/local/bin/provisioning\n\n# Check PATH\necho $PATH\n```\n\n**Solutions:**\n\n```\n# Add to PATH\nexport PATH="/usr/local/bin:$PATH"\n\n# Make permanent (add to shell profile)\necho 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc\nsource ~/.bashrc\n\n# Create symlink if missing\nsudo ln -sf /usr/local/provisioning/core/nulib/provisioning /usr/local/bin/provisioning\n```\n\n### Issue: Nushell Plugin Errors\n\n**Symptoms:**\n\n```\nPlugin not found: nu_plugin_kcl\nPlugin registration failed\n```\n\n**Diagnosis:**\n\n```\n# Check Nushell version\nnu --version\n\n# Check KCL installation (required for nu_plugin_kcl)\nkcl version\n\n# Check plugin registration\nnu -c "version | get installed_plugins"\n```\n\n**Solutions:**\n\n```\n# Install KCL CLI (required for nu_plugin_kcl)\n# Download from: https://github.com/kcl-lang/cli/releases\n\n# Re-register plugins\nnu -c "plugin add /usr/local/provisioning/plugins/nu_plugin_kcl"\nnu -c "plugin add /usr/local/provisioning/plugins/nu_plugin_tera"\n\n# Restart Nushell after plugin registration\n```\n\n## Configuration Issues\n\n### Issue: Configuration Not Found\n\n**Symptoms:**\n\n```\nConfiguration file not found\nFailed to load configuration\n```\n\n**Diagnosis:**\n\n```\n# Check configuration file locations\nprovisioning env | grep config\n\n# Check if files exist\nls -la ~/.config/provisioning/\nls -la /usr/local/provisioning/config.defaults.toml\n```\n\n**Solutions:**\n\n```\n# Initialize user configuration\nprovisioning init config\n\n# Create missing directories\nmkdir -p ~/.config/provisioning\n\n# Copy template\ncp /usr/local/provisioning/config-examples/config.user.toml ~/.config/provisioning/config.toml\n\n# Verify configuration\nprovisioning validate config\n```\n\n### Issue: Configuration Validation Errors\n\n**Symptoms:**\n\n```\nConfiguration validation failed\nInvalid configuration
|
