go-infra¶
forge.lthn.ai/core/go-infra provides typed Go clients for infrastructure provider APIs (Hetzner Cloud, Hetzner Robot, CloudNS) and a declarative YAML configuration layer for describing production topology. It also ships CLI commands for production management (core prod) and security monitoring (core monitor).
The library has no framework dependencies beyond the Go standard library, YAML parsing, and testify for tests. All HTTP communication goes through a shared APIClient that handles retries, exponential backoff, and rate-limit compliance automatically.
Module Path¶
Requires Go 1.26+.
Quick Start¶
Using the API Clients Directly¶
import "forge.lthn.ai/core/go-infra"
// Hetzner Cloud -- list all servers
hc := infra.NewHCloudClient(os.Getenv("HCLOUD_TOKEN"))
servers, err := hc.ListServers(ctx)
// Hetzner Robot -- list dedicated servers
hr := infra.NewHRobotClient(user, password)
dedicated, err := hr.ListServers(ctx)
// CloudNS -- ensure a DNS record exists
dns := infra.NewCloudNSClient(authID, authPassword)
changed, err := dns.EnsureRecord(ctx, "example.com", "www", "A", "1.2.3.4", 300)
Loading Infrastructure Configuration¶
import "forge.lthn.ai/core/go-infra"
// Auto-discover infra.yaml by walking up from the current directory
cfg, path, err := infra.Discover(".")
// Or load a specific file
cfg, err := infra.Load("/path/to/infra.yaml")
// Query the configuration
appServers := cfg.AppServers()
for name, host := range appServers {
fmt.Printf("%s: %s (%s)\n", name, host.IP, host.Role)
}
CLI Commands¶
When registered with the core CLI binary, go-infra provides two command groups:
# Production infrastructure management
core prod status # Health check all hosts, services, and load balancer
core prod setup # Phase 1 foundation: discover topology, create LB, configure DNS
core prod setup --dry-run # Preview what setup would do
core prod setup --step=dns # Run a single setup step
core prod dns list # List DNS records for a zone
core prod dns set www A 1.2.3.4 # Create or update a DNS record
core prod lb status # Show load balancer status and target health
core prod lb create # Create load balancer from infra.yaml
core prod ssh noc # SSH into a named host
# Security monitoring (aggregates GitHub Security findings)
core monitor # Scan current repo
core monitor --all # Scan all repos in registry
core monitor --repo core-php # Scan a specific repo
core monitor --severity high # Filter by severity
core monitor --json # JSON output
Package Layout¶
| Path | Description |
|---|---|
client.go |
Shared HTTP API client with retry, exponential backoff, and rate-limit handling |
config.go |
YAML infrastructure configuration parser and typed config structs |
hetzner.go |
Hetzner Cloud API (servers, load balancers, snapshots) and Hetzner Robot API (dedicated servers) |
cloudns.go |
CloudNS DNS API (zones, records, ACME challenge helpers) |
cmd/prod/ |
CLI commands for production infrastructure management (core prod) |
cmd/monitor/ |
CLI commands for security finding aggregation (core monitor) |
Dependencies¶
Direct¶
| Module | Purpose |
|---|---|
forge.lthn.ai/core/cli |
CLI framework (cobra-based command registration) |
forge.lthn.ai/core/go-ansible |
SSH client used by core prod status for host health checks |
forge.lthn.ai/core/go-i18n |
Internationalisation strings for monitor command |
forge.lthn.ai/core/go-io |
Filesystem abstraction used by monitor's registry lookup |
forge.lthn.ai/core/go-log |
Structured error logging |
forge.lthn.ai/core/go-scm |
Repository registry for multi-repo monitoring |
gopkg.in/yaml.v3 |
YAML parsing for infra.yaml |
github.com/stretchr/testify |
Test assertions |
The core library types (config.go, client.go, hetzner.go, cloudns.go) only depend on the standard library and gopkg.in/yaml.v3. The heavier dependencies (cli, go-ansible, go-scm, etc.) are confined to the cmd/ packages.
Environment Variables¶
| Variable | Used by | Description |
|---|---|---|
HCLOUD_TOKEN |
prod setup, prod status, prod lb |
Hetzner Cloud API bearer token |
HETZNER_ROBOT_USER |
prod setup |
Hetzner Robot API username |
HETZNER_ROBOT_PASS |
prod setup |
Hetzner Robot API password |
CLOUDNS_AUTH_ID |
prod setup, prod dns |
CloudNS sub-auth user ID |
CLOUDNS_AUTH_PASSWORD |
prod setup, prod dns |
CloudNS auth password |
Licence¶
EUPL-1.2