Hetzner Module

This module provides a V client for interacting with Hetzner's Robot API, allowing you to manage dedicated servers programmatically. It supports both direct V-lang function calls and execution through HeroScript.

1. Configuration

Before using the module, you need to configure at least one client instance with your Hetzner Robot credentials. This is done using the hetznermanager.configure action in HeroScript. It's recommended to store your password in an environment variable for security.

!!hetznermanager.configure
	name:"main"
	user:"<your_robot_username>"
	password:"${HETZNER_PASSWORD}"
	whitelist:"2111181, 2392178" // Optional: comma-separated list of server IDs to operate on
	sshkey: "name of sshkey as used with hetzner"

2. Usage

You can interact with the Hetzner module in two ways: via HeroScript for automation or directly using V functions for more complex logic.

2.1. HeroScript Usage

HeroScript provides a simple, declarative way to execute server operations. You can run a script containing these actions using playcmds.run().

Example Script:


# Place a server into rescue mode
!!hetznermanager.server_rescue
    instance: 'main'               // The configured client instance to use
    server_name: 'your-server-name'  // The name of the server to manage (or use `id`)
    wait: true                     // Wait for the operation to complete
    hero_install: true             // Automatically install Herolib in the rescue system

# Install Ubuntu 24.04 on a server
!!hetznermanager.ubuntu_install
    instance: 'main'
    id: 1234567                   // The ID of the server (or use `server_name`)
    wait: true
    hero_install: true            // Install Herolib on the new OS

# Reset a server
!!hetznermanager.server_reset
    instance: 'main'
    server_name: 'your-server-name'
    wait: true

# Add a new SSH key to your Hetzner account
!!hetznermanager.key_create
    instance: 'main'
    key_name: 'my-laptop-key'
    data: 'ssh-rsa AAAA...'

Available Heroscript Actions:

!!hetznermanager.configure: Configures a new client instance.
- name (string): A unique name for this configuration.
- user (string): Hetzner Robot username.
- password (string): Hetzner Robot password.
- whitelist (string, optional): Comma-separated list of server IDs to restrict operations to.
- sshkey (string, optional): Default public SSH key to deploy in rescue mode.
!!hetznermanager.server_rescue: Activates the rescue system.
- instance (string, optional): The client instance to use (defaults to 'default').
- server_name or id (string/int): Identifies the target server.
- wait (bool, optional): Wait for the server to reboot into rescue (default: true).
- hero_install (bool, optional): Install Herolib in the rescue system (default: false).
- reset (bool, optional): Force activation even if already in rescue mode (default: false).
!!hetznermanager.ubuntu_install: Performs a fresh installation of Ubuntu 24.04.
- instance (string, optional): The client instance to use (defaults to 'default').
- server_name or id (string/int): Identifies the target server.
- wait (bool, optional): Wait for the installation and reboot to complete (default: true).
- hero_install (bool, optional): Install Herolib on the newly installed system (default: false).
!!hetznermanager.server_reset: Triggers a hardware reset.
- All parameters are the same as server_rescue, except for hero_install and reset.
!!hetznermanager.key_create / key_delete: Manages SSH keys in your account.
- instance (string, optional): The client instance to use.
- key_name (string): The name of the key.
- data (string, for create): The public key data.

2.2. V Language Usage

For more granular control, you can call the module functions directly from your V code.

import freeflowuniverse.herolib.virt.hetznermanager
import freeflowuniverse.herolib.ui.console

// Get a configured client instance by the name you provided during configuration
mut cl := hetznermanager.get(name: 'main')!

// Get list of all servers
servers := cl.servers_list()!
console.print_header('Available Servers')
//팁 In V, you can print structs directly for a quick overview.
println(servers)

// Get detailed info for a specific server by name
server_info := cl.server_info_get(name: 'your-server-name')!
console.print_header('Server details for ${server_info.server_name}')
println(server_info)

// Enable rescue mode and wait for completion
cl.server_rescue(name: 'your-server-name', wait: true, hero_install: true)!
println('Server is now in rescue mode.')

// Reset a server and wait for it to come back online
cl.server_reset(name: 'your-server-name', wait: true)!
println('Server has been reset.')

Features

Server listing and information retrieval
Hardware reset functionality
Rescue mode management with optional Herolib installation
Automated Ubuntu 24.04 installation
SSH key management
Automatic server status monitoring during long operations
Built-in caching for API responses to reduce rate-limiting
Integration with Herolib installation tools

Notes

The module uses Redis for caching API responses (default 60-second cache duration).
Server operations that include wait: true will monitor the server until the operation completes, providing feedback on the process.
Reset operations with wait: true will timeout after 2 minutes if the server doesn't respond to SSH.
The module automatically manages ssh-keygen -R to remove old host keys during reboots and reinstalls.
The official API documentation can be found at https://robot.hetzner.com/doc/webservice/en.html#preface.

5.8 KiB Raw Blame History