---
title: go-infra
description: Infrastructure provider API clients and YAML-based configuration for managing production environments.
---

# 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

```
forge.lthn.ai/core/go-infra
```

Requires **Go 1.26+**.

## Quick Start

### Using the API Clients Directly

```go
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

```go
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:

```bash
# 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