66 lines
3.4 KiB
Markdown
66 lines
3.4 KiB
Markdown
# Hetzner Robot API Rhai Client & Local VM Orchestrator
|
|
|
|
This project provides two core functionalities:
|
|
1. A **Rhai scripting client** to programmatically manage Hetzner dedicated servers via the Robot API.
|
|
2. A **local VM orchestrator** (`alpine-boot.sh`) to quickly set up and run a lightweight Alpine Linux virtual machine on any host, ideal for development and testing.
|
|
|
|
This allows you to use the Rhai scripts to order a new server from Hetzner, and then use the `alpine-boot.sh` script on that new server to stand up a local virtualized environment.
|
|
|
|
## 1. Hetzner Rhai Client
|
|
|
|
The primary goal of this component is to offer a flexible and scriptable interface to the Hetzner Robot API, enabling automation of server management tasks. By leveraging Rhai, users can write simple yet powerful scripts to interact with their Hetzner infrastructure.
|
|
|
|
### Rhai Examples
|
|
|
|
The `examples/` directory contains several Rhai scripts demonstrating the capabilities of this client:
|
|
|
|
- [`examples/server_management.rhai`](examples/server_management.rhai): Showcases basic server management operations.
|
|
- [`examples/ssh_key_management.rhai`](examples/ssh_key_management.rhai): Demonstrates how to manage SSH keys.
|
|
- [`examples/boot_management.rhai`](examples/boot_management.rhai): Provides examples for managing server boot configurations.
|
|
- [`examples/server_ordering.rhai`](examples/server_ordering.rhai): Contains comprehensive examples for ordering new servers and addons.
|
|
|
|
## 2. Local VM Setup with `alpine-boot.sh`
|
|
|
|
For local development and testing, this project includes a script to quickly boot a lightweight Alpine Linux virtual machine using `cloud-hypervisor` and `virtiofs`. The [`alpine-boot.sh`](alpine-boot.sh) script automates the entire process, from downloading the OS to configuring and launching the VM.
|
|
|
|
### Prerequisites
|
|
|
|
On a fresh Debian-based system (like an Ubuntu server ordered from Hetzner), you must first install the required dependencies. These commands only need to be run once.
|
|
|
|
```bash
|
|
# Install dependencies from apt
|
|
sudo apt update && sudo apt install -y curl tar virtiofsd
|
|
|
|
# Download and install a static cloud-hypervisor binary
|
|
wget https://github.com/cloud-hypervisor/cloud-hypervisor/releases/download/v47.0/cloud-hypervisor-static
|
|
chmod +x cloud-hypervisor-static
|
|
sudo ln -s "$(pwd)/cloud-hypervisor-static" /usr/local/bin/cloud-hypervisor
|
|
```
|
|
*Note: The `cloud-hypervisor` version is pinned for stability.*
|
|
|
|
### Script Usage
|
|
|
|
#### Basic Boot
|
|
To download all assets and boot the VM with default settings (hostname `alpine-3.22`, root password `root`):
|
|
```bash
|
|
./alpine-boot.sh
|
|
```
|
|
|
|
#### Customizing the VM
|
|
You can customize the VM using command-line options:
|
|
- `--hostname <name>`: Set a custom hostname.
|
|
- `--root-password <password>`: Set a custom root password.
|
|
|
|
**Example:**
|
|
```bash
|
|
./alpine-boot.sh --hostname my-alpine --root-password mysecretpassword
|
|
```
|
|
|
|
#### Other Commands
|
|
- `download-only`: Downloads assets without booting.
|
|
- `clean`: Removes the workspace and all downloaded files.
|
|
- `help`: Displays the help message.
|
|
|
|
## Important Note on IPv6 Addresses
|
|
|
|
When ordering a Hetzner server without an IPv4 addon, it might be assigned an IPv6 network like `2a01:4f8:221:1fe3::/64`. You cannot directly SSH to this network address. Hetzner does not use SLAAC for server assignments. The actual address to SSH to will typically be the network address with `2` appended (e.g., `2a01:4f8:221:1fe3::2`). |