diff --git a/docs/lxc_autoscale_api/README.md b/docs/lxc_autoscale_api/README.md deleted file mode 100644 index 2659b0d..0000000 --- a/docs/lxc_autoscale_api/README.md +++ /dev/null @@ -1,141 +0,0 @@ -# LXC AutoScale API Documentation - -**LXC AutoScale API** is a powerful RESTful interface designed to give you programmatic control over LXC containers hosted on a Proxmox server. With this API, you can automate and fine-tune various aspects of container management, including resource allocation, snapshots, and cloning. Whether you're looking to optimize performance during peak hours or conserve resources at night, the LXC AutoScale API offers the flexibility to tailor container behavior to your specific needs. - -## Summary - -- **[Installation](#installation)**: Instructions for installing the LXC AutoScale API on your Proxmox host. -- **[Routes](#routes)**: Detailed descriptions of available API endpoints, including examples of how to use them. -- **[Logs](#logs)**: Information on where to find and how to interpret the logs generated by the API service. -- **[Examples](examples/README.md)**: Ensure your containers are running optimally based on real-time conditions. -- **[Best Practices and Tips](#best-practices-and-tips)**: Recommendations for effectively using the API in various scenarios. - -## Installation - -Installing the LXC AutoScale API on your Proxmox host is straightforward and can be done in a few simple steps. This section outlines the installation process, whether you're setting up the full LXC AutoScale ML package or just the API component. - -### Installing the Full LXC AutoScale ML Package - -To install the complete LXC AutoScale ML package, which includes the API, run the following command: - -```bash -curl -sSL https://raw.githubusercontent.com/fabriziosalmi/proxmox-lxc-autoscale/main/install.sh | bash -``` - -This command will download and execute the installation script, setting up everything you need to start using LXC AutoScale ML and its API. - -### Installing the LXC AutoScale API Only - -If you prefer to install just the LXC AutoScale API component, use the following command: - -```bash -curl -sSL https://raw.githubusercontent.com/fabriziosalmi/proxmox-lxc-autoscale/main/lxc_autoscale_ml/install_api.sh | bash -``` - -This command installs only the API, allowing you to control LXC containers programmatically without the additional machine learning capabilities. - -After installation, ensure that the API service is running and accessible on your network. - ---- - -## Routes - -The LXC AutoScale API provides a range of endpoints that allow you to interact with your Proxmox host programmatically. Below is a comprehensive list of available routes, along with examples of how to use each one. - -| Endpoint | Methods | Description | Example | -|-----------------------------|---------|------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------| -| `/scale/cores` | POST | Set the exact number of CPU cores for an LXC container. | `curl -X POST http://proxmox:5000/scale/cores -H "Content-Type: application/json" -d '{"vm_id": 104, "cores": 4}'` | -| `/scale/ram` | POST | Set the exact amount of RAM for an LXC container. | `curl -X POST http://proxmox:5000/scale/ram -H "Content-Type: application/json" -d '{"vm_id": 104, "memory": 4096}'` | -| `/scale/storage/increase` | POST | Increase the storage size of an LXC container's root filesystem. | `curl -X POST http://proxmox:5000/scale/storage/increase -H "Content-Type: application/json" -d '{"vm_id": 104, "disk_size": 2}'` | -| `/snapshot/create` | POST | Create a snapshot for an LXC container. | `curl -X POST http://proxmox:5000/snapshot/create -H "Content-Type: application/json" -d '{"vm_id": 104, "snapshot_name": "my_snapshot"}'` | -| `/snapshot/list` | GET | List all snapshots for an LXC container. | `curl -X GET "http://proxmox:5000/snapshot/list?vm_id=104"` | -| `/snapshot/rollback` | POST | Rollback to a specific snapshot. | `curl -X POST http://proxmox:5000/snapshot/rollback -H "Content-Type: application/json" -d '{"vm_id": 104, "snapshot_name": "my_snapshot"}'` | -| `/clone/create` | POST | Clone an LXC container. | `curl -X POST http://proxmox:5000/clone/create -H "Content-Type: application/json" -d '{"vm_id": 104, "new_vm_id": 105, "new_vm_name": "cloned_container"}'` | -| `/clone/delete` | DELETE | Delete a cloned LXC container. | `curl -X DELETE http://proxmox:5000/clone/delete -H "Content-Type: application/json" -d '{"vm_id": 105}'` | -| `/resource/vm/status` | GET | Check the resource allocation and usage for an LXC container. | `curl -X GET "http://proxmox:5000/resource/vm/status?vm_id=104"` | -| `/resource/node/status` | GET | Check the resource usage of a specific node. | `curl -X GET "http://proxmox:5000/resource/node/status?node_name=proxmox"` | -| `/health/check` | GET | Perform a health check on the API server. | `curl -X GET http://proxmox:5000/health/check` | -| `/routes` | GET | List all available routes. | `curl -X GET http://proxmox:5000/routes` | - -### Detailed Descriptions - -- **`/scale/cores`**: Allows you to set a specific number of CPU cores for a container. This is useful for adjusting resources based on the time of day or anticipated workload. -- **`/scale/ram`**: Lets you set the amount of RAM for a container. This can be used to allocate more memory during peak usage or reduce it during off-hours to save resources. -- **`/scale/storage/increase`**: Increases the storage size of the container’s root filesystem. This endpoint is particularly useful when a container’s storage requirements grow over time. -- **`/snapshot/create`**: Creates a snapshot of a container. Snapshots are essential for backup and recovery, allowing you to restore a container to a - - previous state if needed. -- **`/snapshot/list`**: Lists all snapshots for a given container. This endpoint helps you manage and review the available snapshots. -- **`/snapshot/rollback`**: Rolls back a container to a specific snapshot. Use this endpoint to revert changes made during the day or after testing new configurations. -- **`/clone/create`**: Clones a container, creating an exact copy under a new VM ID. This is ideal for testing or duplicating environments without affecting the original container. -- **`/clone/delete`**: Deletes a cloned container. This endpoint helps keep your environment clean by removing containers that are no longer needed. -- **`/resource/vm/status`**: Retrieves the current resource allocation and usage for a specific container, helping you monitor its performance. -- **`/resource/node/status`**: Provides an overview of the resource usage on a specific Proxmox node, allowing you to manage and optimize node performance. -- **`/health/check`**: Performs a health check on the API server to ensure it’s running correctly. This is useful for automated monitoring and alerting systems. -- **`/routes`**: Lists all available API routes, providing an overview of the endpoints you can interact with. - -These routes offer a wide range of functionality, enabling comprehensive management of your LXC containers via simple HTTP requests. - ---- - -## Logs - -Logging is a critical component of managing and troubleshooting the LXC AutoScale API. The service generates several log files that provide detailed information about its operations. - -### Log Files - -- **`/var/log/autoscaleapi.log`**: The main log file for the API, containing detailed information about API requests, responses, and any internal processing. -- **`/var/log/autoscaleapi_access.log`**: Logs all incoming requests to the API, including timestamps, request methods, endpoints accessed, and the source IP addresses. This log is essential for monitoring API usage and identifying potential security issues. -- **`/var/log/autoscaleapi_error.log`**: Captures errors encountered by the API service. Reviewing this log can help diagnose issues and ensure that the API runs smoothly. - -### Log Management - -Regularly review these logs to monitor the health and performance of the API service. Consider implementing log rotation to manage disk space, especially in environments with high API traffic. You can use tools like `logrotate` to automate the rotation, compression, and removal of old log files. - -Example `logrotate` configuration: - -```bash -/var/log/autoscaleapi*.log { - daily - missingok - rotate 7 - compress - delaycompress - notifempty - create 640 root adm - sharedscripts - postrotate - systemctl reload lxc_autoscale_api.service > /dev/null 2>&1 || true - endscript -} -``` - -This configuration rotates the log files daily, keeps seven days of logs, compresses old logs, and ensures the service continues to operate without interruption. - ---- - -## Best Practices and Tips - -### 1. Secure Your API - -Given that the API allows direct control over LXC containers, it’s crucial to secure it properly. Consider the following measures: - -- **Use a Firewall**: Restrict access to the API by configuring your firewall to allow only trusted IP addresses. -- **Enable HTTPS**: Protect data in transit by securing the API with HTTPS. You can use a reverse proxy like Nginx or Apache to handle SSL/TLS encryption. -- **Implement Authentication**: Add basic authentication or API tokens to restrict access to authorized users only. - -### 2. Monitor API Usage - -Regularly monitor the `autoscaleapi_access.log` file to track API usage. Look for unusual patterns that could indicate unauthorized access or potential misuse of the API. - -### 3. Automate Routine Tasks - -Use cron jobs in combination with API requests to automate routine tasks such as scaling resources or creating snapshots. This reduces manual intervention and helps maintain optimal performance. - -### 4. Test Before Production - -When implementing new API routes or making changes to existing ones, always test in a non-production environment first. This helps ensure that the commands work as expected without disrupting live services. - -### 5. Document Your API Usage - -Maintain documentation of how your environment interacts with the LXC AutoScale API, including the routes used, the purpose of each request, and any scripts or automation tools that rely on the API. This documentation is invaluable for troubleshooting and for onboarding new team members. diff --git a/docs/lxc_autoscale_api/examples/README.md b/docs/lxc_autoscale_api/examples/README.md deleted file mode 100644 index bc59c1f..0000000 --- a/docs/lxc_autoscale_api/examples/README.md +++ /dev/null @@ -1,400 +0,0 @@ -## LXC AutoScale API examples - -The LXC AutoScale API offers powerful capabilities for managing and automating LXC containers on a Proxmox server. By leveraging this API, you can dynamically adjust resources, automate routine tasks, and ensure your containers are running optimally based on real-time conditions. Below are practical examples of how you can use the API to enhance your container management. Each example provides a detailed command that you can implement directly in your environment. - -## Summary - -- [Dynamic CPU Scaling](#dynamic-cpu-scaling): Adjust CPU cores based on time of day. -- [Automated Memory Management](#automated-memory-management): Increase or decrease RAM allocation based on workload demand. -- [Scheduled Storage Expansion](#scheduled-storage-expansion): Automatically expand storage before a large data import. -- [Daily Snapshot Creation](#daily-snapshot-creation): Create a daily snapshot for quick recovery. -- [Snapshot Rollback for Recovery](#snapshot-rollback-for-recovery): Rollback to a snapshot if issues arise. -- [On-Demand Container Cloning](#on-demand-container-cloning): Clone a container for testing purposes. -- [Clean Up Cloned Containers](#clean-up-cloned-containers): Delete a cloned container after testing. -- [Monitor Container Resources](#monitor-container-resources): Regularly check and log container resource usage. -- [Node Resource Usage Monitoring](#node-resource-usage-monitoring): Track resource usage of a Proxmox node. -- [Automated Health Check](#automated-health-check): Perform regular health checks on the API server. -- [Document Available API Routes](#document-available-api-routes): List all available API routes. -- [Temporary Resource Boost for Maintenance](#temporary-resource-boost-for-maintenance): Temporarily increase resources before maintenance. -- [Preemptive Resource Scaling](#preemptive-resource-scaling): Automatically scale resources if CPU usage exceeds a threshold. -- [Automate Cleanup Tasks](#automate-cleanup-tasks): Remove old snapshots and logs to save space. -- [Rolling Snapshot Backup](#rolling-snapshot-backup): Maintain a rolling backup by keeping only the last 7 snapshots. -- [Real-Time Traffic-Based Scaling](#real-time-traffic-based-scaling): Scale up resources dynamically based on network traffic. -- [Clone and Test Environment](#clone-and-test-environment): Automatically clone and delete a test environment. -- [Monitor and Alert on Resource Thresholds](#monitor-and-alert-on-resource-thresholds): Set up monitoring and alerting for resource usage. -- [Health Check and Restart Unresponsive Containers](#health-check-and-restart-unresponsive-containers): Automatically restart a container if it becomes unresponsive. -- [Daily Performance Reports](#daily-performance-reports): Generate and send daily container performance reports. -- [Automated Pre-Deployment Snapshots](#automated-pre-deployment-snapshots): Create a snapshot before deploying changes. -- [Automatic Node Resource Balancing](#automatic-node-resource-balancing): Rebalance resources across nodes based on usage. -- [Log Cleanup Automation](#log-cleanup-automation): Automatically clean up logs to save disk space. -- [Periodic Resource Scaling Based on Historical Data](#periodic-resource-scaling-based-on-historical-data): Scale resources based on historical usage trends. -- [Pre-Scaling for High-Traffic Events](#pre-scaling-for-high-traffic-events): Increase resources before an anticipated high-traffic event. -- [Real-Time Usage Alerts](#real-time-usage-alerts): Set up real-time alerts for CPU or memory usage thresholds. -- [Automatic Downgrade After Off-Peak](#automatic-downgrade-after-off-peak): Downgrade resources after an off-peak period. - ---- - -## Dynamic CPU Scaling - -Adjust the number of CPU cores based on time of day. - -**Increase cores at 8:00 AM:** -```bash -0 8 * * * curl -X POST http://proxmox:5000/scale/cores \ --H "Content-Type: application/json" \ --d '{"vm_id": 104, "cores": 8}' -``` - -**Decrease cores at 8:00 PM:** -```bash -0 20 * * * curl -X POST http://proxmox:5000/scale/cores \ --H "Content-Type: application/json" \ --d '{"vm_id": 104, "cores": 4}' -``` - ---- - -## Automated Memory Management - -Increase and decrease RAM allocation based on workload demand. - -**Increase RAM at 9:00 AM:** -```bash -0 9 * * * curl -X POST http://proxmox:5000/scale/ram \ --H "Content-Type: application/json" \ --d '{"vm_id": 104, "memory": 8192}' -``` - -**Decrease RAM at 7:00 PM:** -```bash -0 19 * * * curl -X POST http://proxmox:5000/scale/ram \ --H "Content-Type: application/json" \ --d '{"vm_id": 104, "memory": 4096}' -``` - ---- - -## Scheduled Storage Expansion - -Automatically expand storage when needed, such as before a large data import. - -**Increase storage at midnight:** -```bash -0 0 * * * curl -X POST http://proxmox:5000/scale/storage/increase \ --H "Content-Type: application/json" \ --d '{"vm_id": 104, "disk_size": 5}' -``` - ---- - -## Daily Snapshot Creation - -Create a daily snapshot of a container to ensure quick recovery. - -**Create a snapshot at 6:00 AM:** -```bash -0 6 * * * curl -X POST http://proxmox:5000/snapshot/create \ --H "Content-Type: application/json" \ --d '{"vm_id": 104, "snapshot_name": "daily_snapshot_$(date +\%F)"}' -``` - ---- - -## Snapshot Rollback for Recovery - -Rollback to the latest snapshot in case of issues. - -**Rollback at 11:00 PM if needed:** -```bash -0 23 * * * curl -X POST http://proxmox:5000/snapshot/rollback \ --H "Content-Type: application/json" \ --d '{"vm_id": 104, "snapshot_name": "daily_snapshot_$(date +\%F)"}' -``` - ---- - -## On-Demand Container Cloning - -Clone a container to test new software updates or changes. - -**Create a clone:** -```bash -curl -X POST http://proxmox:5000/clone/create \ --H "Content-Type: application/json" \ --d '{"vm_id": 104, "new_vm_id": 105, "new_vm_name": "test_clone"}' -``` - ---- - -## Clean Up Cloned Containers - -Delete a cloned container after testing is complete. - -**Delete the clone:** -```bash -curl -X DELETE http://proxmox:5000/clone/delete \ --H "Content-Type: application/json" \ --d '{"vm_id": 105}' -``` - ---- - -## Monitor Container Resources - -Regularly check and log the resource usage of a container. - -**Log resource usage every hour:** -```bash -0 * * * * curl -X GET "http://proxmox:5000/resource/vm/status?vm_id=104" >> /var/log/lxc_vm_status.log -``` - ---- - -## Node Resource Usage Monitoring - -Track the resource usage of the Proxmox node to identify potential issues. - -**Check node status at 5-minute intervals:** -```bash -*/5 * * * * curl -X GET "http://proxmox:5000/resource/node/status?node_name=proxmox" >> /var/log/node_status.log -``` - ---- - -## Automated Health Check - -Perform regular health checks on the API server. - -**Health check every 5 minutes:** -```bash -*/5 * * * * curl -X GET http://proxmox:5000/health/check -``` - ---- - -## Document Available API Routes - -List all available API routes for reference. - -**List routes:** -```bash -curl -X GET http://proxmox:5000/routes -``` - ---- - -## Temporary Resource Boost for Maintenance - -Temporarily increase resources before running a maintenance task. - -**Boost resources at 11:55 PM:** -```bash -55 23 * * * curl -X POST http://proxmox:5000/scale/cores \ --H "Content-Type: application/json" \ --d '{"vm_id": 104, "cores": 8}' && \ -curl -X POST http://proxmox:5000/scale/ram \ --H "Content-Type: application/json" \ --d '{"vm_id": 104, "memory": 16384}' -``` - -**Scale back after maintenance:** -```bash -30 0 * * * curl -X POST http://proxmox:5000/scale/cores \ --H "Content-Type: application/json" \ --d '{"vm_id": 104, "cores": 4}' && \ -curl -X POST http://proxmox:5000/scale/ram \ --H "Content-Type: application/json" \ --d '{"vm_id": 104, "memory": 8192}' -``` - ---- - -## Preemptive Resource Scaling - -Automatically scale resources if CPU usage exceeds 75%. - -**Monitor and scale up if needed:** -```bash -* * * * * curl -X GET "http://proxmox:5000/resource/vm/status?vm_id=104" | jq '.cpu' | \ -if [ $(jq '.cpu' response.json) -gt 75 ]; then curl -X POST http://proxmox:5000/scale/cores -d '{"cores": 6}'; fi -``` - ---- - -## Automate Cleanup Tasks - -Remove old snapshots after a specified number of days to save space. - -**Cleanup old snapshots every Sunday at midnight:** -```bash -0 0 * * 0 curl -X GET "http://proxmox:5000/snapshot/list?vm_id=104" | jq -r '.[] | select(.timestamp < (now - 7 * 86400)) | .name' | \ -while read snapshot; do curl -X POST http://proxmox:5000/snapshot/delete -H "Content-Type: application/json" -d '{"vm_id": 104, "snapshot_name": "$snapshot"}'; done -``` - ---- - -## Rolling Snapshot Backup - -Maintain a rolling backup by keeping only the last 7 snapshots. - -**Create and manage rolling backups:** -```bash -0 2 * * * curl -X POST http://proxmox:5000/snapshot/create \ --H "Content-Type: application/json" \ --d '{"vm_id": 104, "snapshot_name": "rolling_backup_$(date +\%F)"}' && \ -curl -X GET "http://proxmox:5000/snapshot/list?vm_id=104" | jq -r '.[] | select(.timestamp < (now - 7 * 86400)) | .name' | \ -while read snapshot; do curl -X POST http://proxmox:5000/snapshot/delete -H "Content-Type: application/json" -d '{"vm_id": 104, "snapshot_name": "$snapshot"}'; done -``` - ---- - -## Real-Time Traffic-Based Scaling - -Scale up resources dynamically based on real-time network traffic. - -**Scale cores based on traffic:** -```bash -* * * * * curl -X GET "http://proxmox:5000/resource/vm/status?vm_id=104" | jq '.network.traffic' | \ -if [ $(jq '.network.traffic' response.json) -gt 1000 ]; then curl -X POST http://proxmox:5000/scale/cores -d '{"cores": 8}'; fi -``` - ---- - -## Clone and Test Environment - -Automatically clone the environment for testing, then delete it after use. - -**Clone at midnight and delete at 4:00 AM:** -```bash -0 0 * * * curl -X POST http://proxmox:5000/clone/create \ --H "Content-Type: application/json" \ --d '{"vm_id": 104, "new_vm_id": 106, "new_vm_name": "test_clone"}' - -0 4 * * * curl -X DELETE http://proxmox:5000/clone/delete \ --H "Content-Type: application/json" \ --d '{"vm_id": 106}' -``` - ---- - -## Monitor and Alert on Resource Thresholds - -Set up monitoring and alerting when certain resource thresholds are exceeded. - -**Monitor CPU and alert if usage exceeds 85%:** -```bash -* * * * * curl -X GET "http://proxmox:5000/resource/vm/status?vm_id=104" | \ -if [ $(jq '.cpu' response.json) -gt 85 ]; then curl -X POST -d "alert: CPU usage high" http://alertmanager:9093/alert; fi -``` - ---- - -## Health Check and Restart Unresponsive Containers - -Automatically restart a container if it becomes unresponsive. - -**Health check and restart:** -```bash -* * * * * curl -X GET "http://proxmox:5000/health/check?vm_id=104" | \ -if [ $(jq '.status' response.json) != "healthy" ]; then curl -X POST http://proxmox:5000/vm/restart -H "Content-Type: application/json" -d '{"vm_id": 104}'; fi -``` - ---- - -## Daily Performance Reports - -Generate and send a daily report on container performance. - -**Generate and send report at 7:00 AM:** -```bash -0 7 * * * curl -X GET "http://proxmox:5000/resource/vm/status?vm_id=104" | \ -mail -s "Daily Performance Report" admin@example.com -``` - ---- - -## Automated Pre-Deployment Snapshots - -Create a snapshot before deploying changes to a container. - -**Snapshot before deployment:** -```bash -0 3 * * * curl -X POST http://proxmox:5000/snapshot/create \ --H "Content-Type: application/json" \ --d '{"vm_id": 104, "snapshot_name": "pre_deploy_snapshot_$(date +\%F)"}' -``` - ---- - -## Automatic Node Resource Balancing - -Automatically rebalance resources across nodes when usage is high. - -**Check and rebalance at 5-minute intervals:** -```bash -*/5 * * * * curl -X GET "http://proxmox:5000/resource/node/status?node_name=proxmox" | jq '.memory' | \ -if [ $(jq '.memory.usage' response.json) -gt 80 ]; then curl -X POST http://proxmox:5000/scale/ram -d '{"vm_id": 104, "memory": 4096}'; fi -``` - ---- - -## Log Cleanup Automation - -Automatically clean up logs to save disk space. - -**Cleanup logs every week:** -```bash -0 0 * * 0 curl -X POST http://proxmox:5000/vm/execute \ --H "Content-Type: application/json" \ --d '{"vm_id": 104, "command": "find /var/log -type f -name '*.log' -mtime +7 -delete"}' -``` - ---- - -## Periodic Resource Scaling Based on Historical Data - -Automatically scale resources based on historical usage trends. - -**Scale resources on Monday based on last week's usage:** -```bash -0 6 * * 1 curl -X GET "http://proxmox:5000/resource/vm/status?vm_id=104" | jq '.cpu' | \ -if [ $(jq '.cpu' response.json) -gt 70 ]; then curl -X POST http://proxmox:5000/scale/cores -d '{"cores": 6}'; fi -``` - ---- - -## Pre-Scaling for High-Traffic Events - -Increase resources before an anticipated high-traffic event. - -**Pre-scale cores at 9:55 AM:** -```bash -55 9 * * * curl -X POST http://proxmox:5000/scale/cores \ --H "Content-Type: application/json" \ --d '{"vm_id": 104, "cores": 8}' -``` - ---- - -## Real-Time Usage Alerts - -Set up real-time alerts for CPU or memory usage exceeding thresholds. - -**Alert if memory usage exceeds 90%:** -```bash -* * * * * curl -X GET "http://proxmox:5000/resource/vm/status?vm_id=104" | \ -if [ $(jq '.memory.usage' response.json) -gt 90 ]; then curl -X POST -d "alert: High memory usage" http://alertmanager:9093/alert; fi -``` - ---- - -## Automatic Downgrade After Off-Peak - -Downgrade resources after an off-peak period to save on resource allocation. - -**Reduce RAM after 11:00 PM:** -```bash -0 23 * * * curl -X POST http://proxmox:5000/scale/ram \ --H "Content-Type: application/json" \ --d '{"vm_id": 104, "memory": 2048}' -```