Hetzner Module

This module provides a V client for interacting with Hetzner's Robot API, allowing you to manage dedicated servers programmatically.

Setup

1. Create an account on Hetzner Robot
2. Configure the client using heroscript:

import freeflowuniverse.crystallib.virt.hetzner

heroscript := '
!!hetzner.configure
    name:'my_instance'
    url:'https://robot-ws.your-server.de'
    user:'your-username'
    password:'your-password'
    whitelist:''  // comma separated list of servers to whitelist
'

// Apply the configuration (only needs to be done once)
hetzner.play(heroscript: heroscript)!

Usage

Initialize Client

// Get a configured client instance
mut cl := hetzner.get(name: 'my_instance')!

Configuration Notes

• The client uses crystallib's httpconnection module which provides:
• Built-in Redis caching for API responses
• Automatic retry mechanism for failed requests
• Proper Basic auth handling
• Consistent error handling

Examples

see examples/virt/hetzner

Available Operations

List Servers

// Get list of all servers
servers := cl.servers_list()!

Get Server Information

// Get server info by name
server_info := cl.server_info_get(name: 'server_name')!

// Get server info by ID
server_info := cl.server_info_get(id: 123)!

The ServerInfo struct contains:- server_ip: Primary IP address

• server_ipv6_net: IPv6 network
• server_number: Server ID
• server_name: Server name
• product: Product description
• dc: Datacenter location
• traffic: Traffic information
• status: Current server status
• cancelled: Cancellation status
• paid_until: Payment status date
• ip: List of IP addresses
• subnet: List of subnets

Server Management Operations

Reset Server

// Reset server with wait for completion
cl.server_reset(name: 'server_name', wait: true)!

// Reset server without waiting
cl.server_reset(name: 'server_name', wait: false)!

Enable Rescue Mode

// Enable rescue mode and wait for completion
cl.server_rescue(name: 'server_name', wait: true)!

// Enable rescue mode with automatic Crystal installation
cl.server_rescue(name: 'server_name', wait: true, crystal_install: true)!

Complete Example

Here's a complete example showing common operations:

#!/usr/bin/env -S v run

import freeflowuniverse.crystallib.virt.hetzner
import freeflowuniverse.crystallib.ui.console

fn main() {
    // Get client instance
    mut cl := hetzner.get('my_instance')!

    // List all servers
    servers := cl.servers_list()!
    println('Available servers:')
    println(servers)

    // Get specific server info
    mut server_info := cl.server_info_get(name: 'my_server')!
    println('Server details:')
    println(server_info)

    // Put server in rescue mode
    cl.server_rescue(name: "my_server", wait: true)!

    // Reset server
    cl.server_reset(name: "my_server", wait: true)!
}

Features

• Server listing and information retrieval
• Hardware reset functionality
• Rescue mode management
• SSH key management
• Automatic server status monitoring
• Built-in caching for API responses
• Integration with Crystal installation tools

Notes

• The module uses Redis for caching API responses (60-second cache duration)
• Server operations that include wait: true will monitor the server until the operation completes
• Reset operations with wait: true will timeout after 5 minutes if the server doesn't come back online
• The module automatically manages SSH keys for rescue mode operations
• API description is on https://robot.hetzner.com/doc/webservice/en.html#preface

fn get(args_ ArgsGet) !&HetznerManager

fn heroscript_default() !string

fn play(args_ PlayArgs) !

fn switch(name string)

switch instance to be used for hetzner

struct ArgsGet {
pub mut:
	name string = 'default'
}

///////FACTORY

struct HetznerManager {
pub mut:
	name        string = 'default'
	description string
	baseurl     string
	whitelist   string // comma separated list of servers we whitelist to work on
	user        string
	password    string
	conn        ?&httpconnection.HTTPConnection
}

THIS IS THE SOURCE OF THE INFORMATION OF THIS FILE, HERE WE HAVE THE CONFIG OBJECT CONFIGURED AND MODELLED

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

put server in rescue mode, if sshkey_name not specified then will use the first one in the list

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

struct PlayArgs {
pub mut:
	name       string = 'default'
	heroscript string // if filled in then plbook will be made out of it
	plbook     ?playbook.PlayBook
	reset      bool
	start      bool
	stop       bool
	restart    bool
	delete     bool
	configure  bool // make sure there is at least one installed
}

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 ServerRebootArgs {
pub mut:
	id   int
	name string
	wait bool = true
}

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

struct Subnet {
pub mut:
	ip   string
	mask string
}