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:

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

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

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

##!!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 incubaid.herolib.virt.hetznermanager
import incubaid.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.

fn delete(args ArgsGet) !

fn exists(args ArgsGet) !bool

does the config exists?

fn get(args ArgsGet) !&HetznerManager

fn heroscript_loads(heroscript string) !HetznerManager

fn list(args ArgsList) ![]&HetznerManager

if fromdb set: load from filesystem, and not from mem, will also reset what is in mem

fn new(args ArgsGet) !&HetznerManager

fn play(mut plbook PlayBook) !

fn play2(mut plbook PlayBook) !

play processes playbook actions for the hetznermanager module. It allows configuring and managing Hetzner servers through heroscript.

fn set(o HetznerManager) !

register the config for the future

fn switch(name string)

switch instance to be used for hetznermanager

struct ArgsGet {
pub mut:
	name   string = 'default'
	fromdb bool // will load from filesystem
	create bool // default will not create if not exist
}

///////FACTORY

struct ArgsList {
pub mut:
	fromdb bool // will load from filesystem
}

struct HetznerManager {
pub mut:
	name        string = 'default'
	description string
	baseurl     string = 'https://robot-ws.your-server.de'
	whitelist   []int // comma separated list of servers we whitelist to work on
	user        string
	password    string
	sshkey      string
	nodes       []HetznerNode
}

fn (mut h HetznerManager) check_whitelist(args_ ServerRescueArgs) !

fn (mut h HetznerManager) connection() !&httpconnection.HTTPConnection

fn (mut h HetznerManager) key_create(name string, data string) !SSHKey

Create a new SSH key

fn (mut h HetznerManager) key_delete(name string) !

Delete an SSH key

fn (mut h HetznerManager) key_exists(name string) bool

fn (mut h HetznerManager) key_get(name string) !SSHKey

Get a specific SSH key by fingerprint

fn (mut h HetznerManager) keys_get() ![]SSHKey

fn (mut h HetznerManager) server_info_get(args_ ServerGetArgs) !ServerInfoDetailed

fn (mut h HetznerManager) server_rescue(args_ ServerRescueArgs) !ServerInfoDetailed

fn (mut h HetznerManager) server_rescue_node(args ServerRescueArgs) !&builder.Node

fn (mut h HetznerManager) server_reset(args ServerRebootArgs) !ResetInfo

fn (mut h HetznerManager) servers_list() ![]ServerInfo

fn (mut h HetznerManager) ubuntu_install(args ServerInstallArgs) !&builder.Node

struct HetznerNode {
pub mut:
	id          string
	name        string = 'default'
	description string
}

struct RescueInfo {
pub mut:
	server_ip       string
	server_ipv6_net string
	server_number   int
	os              string
	arch            int
	active          bool
	password        string
	authorized_key  []string
	host_key        []string
}

///////////////////////////RESCUE

struct SSHKey {
pub mut:
	name        string
	fingerprint string
	type_       string @[json: 'type']
	size        int
	created_at  string
	data        string
}

struct ServerGetArgs {
pub mut:
	id   int
	name string
}

///////////////////////////GETID

struct ServerInfo {
pub mut:
	server_ip       string
	server_ipv6_net string
	server_number   int
	server_name     string
	product         string
	dc              string
	traffic         string
	status          string
	cancelled       bool
	paid_until      string
	ip              []string
	subnet          []Subnet
}

///////////////////////// LIST

struct ServerInfoDetailed {
	ServerInfo
pub mut:
	reset    bool
	rescue   bool
	vnc      bool
	windows  bool
	plesk    bool
	cpanel   bool
	wol      bool
	hot_swap bool
	// linked_storagebox    int
}

struct ServerInstallArgs {
pub mut:
	id                   int
	name                 string
	wait                 bool = true
	hero_install         bool
	hero_install_compile bool
	raid                 bool
}

struct ServerRebootArgs {
pub mut:
	id   int
	name string
	wait bool = true
	msg  string
}

struct ServerRescueArgs {
pub mut:
	id           int
	name         string
	wait         bool = true
	hero_install bool
	reset        bool // ask to do reset/rescue even if its already in that state
	retry        int = 3
}

struct Subnet {
pub mut:
	ip   string
	mask string
}