418 lines
19 KiB
Markdown
418 lines
19 KiB
Markdown
# infra
|
|
**Import:** `forge.lthn.ai/core/go-infra`
|
|
**Files:** 5
|
|
|
|
## Types
|
|
|
|
### `RetryConfig`
|
|
Controls exponential backoff retry behaviour for `APIClient`.
|
|
- `MaxRetries int`: Maximum number of retry attempts after the initial request. `0` disables retries.
|
|
- `InitialBackoff time.Duration`: Delay before the first retry.
|
|
- `MaxBackoff time.Duration`: Upper bound for the computed backoff delay.
|
|
|
|
### `APIClient`
|
|
Shared HTTP client with retry handling, shared rate-limit blocking, pluggable authentication, and configurable error prefixes. All struct fields are unexported.
|
|
- `func (a *APIClient) Do(req *http.Request, result any) error`: Applies authentication, honours the shared rate-limit window, retries transport failures plus `429` and `5xx` responses, and JSON-decodes into `result` when `result` is non-nil.
|
|
- `func (a *APIClient) DoRaw(req *http.Request) ([]byte, error)`: Runs the same request pipeline as `Do` but returns the raw response body instead of decoding JSON.
|
|
|
|
### `APIClientOption`
|
|
`type APIClientOption func(*APIClient)`
|
|
|
|
Functional option consumed by `NewAPIClient` to mutate a newly created `APIClient`.
|
|
|
|
### `CloudNSClient`
|
|
HTTP client for the CloudNS DNS API. Authentication details, base URL, and delegated `APIClient` state are stored in unexported fields.
|
|
- `func (c *CloudNSClient) ListZones(ctx context.Context) ([]CloudNSZone, error)`: Fetches all zones visible to the configured CloudNS sub-user.
|
|
- `func (c *CloudNSClient) ListRecords(ctx context.Context, domain string) (map[string]CloudNSRecord, error)`: Fetches all records for a zone and returns them keyed by CloudNS record ID.
|
|
- `func (c *CloudNSClient) CreateRecord(ctx context.Context, domain, host, recordType, value string, ttl int) (string, error)`: Creates a record and returns the created record ID.
|
|
- `func (c *CloudNSClient) UpdateRecord(ctx context.Context, domain, recordID, host, recordType, value string, ttl int) error`: Replaces an existing CloudNS record with the supplied values.
|
|
- `func (c *CloudNSClient) DeleteRecord(ctx context.Context, domain, recordID string) error`: Deletes a record by CloudNS record ID.
|
|
- `func (c *CloudNSClient) EnsureRecord(ctx context.Context, domain, host, recordType, value string, ttl int) (bool, error)`: Idempotently creates or updates a record and reports whether a change was applied.
|
|
- `func (c *CloudNSClient) SetACMEChallenge(ctx context.Context, domain, value string) (string, error)`: Creates the `_acme-challenge` TXT record used for DNS-01 validation.
|
|
- `func (c *CloudNSClient) ClearACMEChallenge(ctx context.Context, domain string) error`: Deletes all `_acme-challenge` TXT records in the zone.
|
|
|
|
### `CloudNSZone`
|
|
CloudNS zone metadata returned by `ListZones`.
|
|
- `Name string`: Zone name as returned by CloudNS.
|
|
- `Type string`: Zone type reported by the API.
|
|
- `Zone string`: Zone domain name or zone identifier.
|
|
- `Status string`: Current CloudNS status string for the zone.
|
|
|
|
### `CloudNSRecord`
|
|
CloudNS DNS record model returned by `ListRecords`.
|
|
- `ID string`: CloudNS record ID.
|
|
- `Type string`: DNS record type such as `A`, `CNAME`, or `TXT`.
|
|
- `Host string`: Relative host label stored in the zone.
|
|
- `Record string`: Record payload or answer value.
|
|
- `TTL string`: TTL reported by CloudNS. The API returns it as a string.
|
|
- `Priority string`: Optional priority value for record types that support it.
|
|
- `Status int`: CloudNS numeric status flag for the record.
|
|
|
|
### `Config`
|
|
Top-level `infra.yaml` model loaded by `Load` and `Discover`.
|
|
- `Hosts map[string]*Host`: Named infrastructure hosts keyed by logical host name.
|
|
- `LoadBalancer LoadBalancer`: Managed load balancer definition.
|
|
- `Network Network`: Shared private network definition.
|
|
- `DNS DNS`: DNS provider configuration and desired zone state.
|
|
- `SSL SSL`: Certificate and TLS settings.
|
|
- `Database Database`: Database cluster settings.
|
|
- `Cache Cache`: Cache or session cluster settings.
|
|
- `Containers map[string]*Container`: Named container deployment definitions.
|
|
- `S3 S3Config`: Object storage configuration.
|
|
- `CDN CDN`: CDN provider configuration.
|
|
- `CICD CICD`: CI/CD service configuration.
|
|
- `Monitoring Monitoring`: Health-check and alert thresholds.
|
|
- `Backups Backups`: Backup job schedules.
|
|
- `func (c *Config) HostsByRole(role string) map[string]*Host`: Returns the subset of `Hosts` whose `Role` matches `role`.
|
|
- `func (c *Config) AppServers() map[string]*Host`: Convenience wrapper around `HostsByRole("app")`.
|
|
|
|
### `Host`
|
|
Infrastructure host definition loaded from `infra.yaml`.
|
|
- `FQDN string`: Public hostname for the machine.
|
|
- `IP string`: Primary public IP address.
|
|
- `PrivateIP string`: Optional private network IP.
|
|
- `Type string`: Provider class, such as `hcloud` or `hrobot`.
|
|
- `Role string`: Functional role such as `bastion`, `app`, or `builder`.
|
|
- `SSH SSHConf`: SSH connection settings for the host.
|
|
- `Services []string`: Services expected to run on the host.
|
|
|
|
### `SSHConf`
|
|
SSH connection settings associated with a `Host`.
|
|
- `User string`: SSH username.
|
|
- `Key string`: Path to the private key file. `Load` expands `~` and defaults are applied before use.
|
|
- `Port int`: SSH port. `Load` defaults this to `22` when omitted.
|
|
|
|
### `LoadBalancer`
|
|
Desired Hetzner managed load balancer configuration loaded from `infra.yaml`.
|
|
- `Name string`: Hetzner load balancer name.
|
|
- `FQDN string`: DNS name expected to point at the load balancer.
|
|
- `Provider string`: Provider identifier for the managed load balancer service.
|
|
- `Type string`: Hetzner load balancer type name.
|
|
- `Location string`: Hetzner location or datacenter slug.
|
|
- `Algorithm string`: Load-balancing algorithm name.
|
|
- `Backends []Backend`: Backend targets referenced by host name and port.
|
|
- `Health HealthCheck`: Health-check policy applied to listeners.
|
|
- `Listeners []Listener`: Frontend-to-backend listener mappings.
|
|
- `SSL LBCert`: TLS certificate settings for the load balancer.
|
|
|
|
### `Backend`
|
|
Load balancer backend target declared in `infra.yaml`.
|
|
- `Host string`: Host key in `Config.Hosts` to use as the backend target.
|
|
- `Port int`: Backend port to route traffic to.
|
|
|
|
### `HealthCheck`
|
|
Load balancer health-check settings.
|
|
- `Protocol string`: Protocol used for checks.
|
|
- `Path string`: HTTP path for health checks when the protocol is HTTP-based.
|
|
- `Interval int`: Probe interval in seconds.
|
|
|
|
### `Listener`
|
|
Frontend listener mapping for the managed load balancer.
|
|
- `Frontend int`: Exposed listener port.
|
|
- `Backend int`: Destination backend port.
|
|
- `Protocol string`: Listener protocol.
|
|
- `ProxyProtocol bool`: Whether the Hetzner listener should enable PROXY protocol forwarding.
|
|
|
|
### `LBCert`
|
|
TLS certificate settings for the load balancer.
|
|
- `Certificate string`: Certificate identifier or path.
|
|
- `SAN []string`: Subject alternative names covered by the certificate.
|
|
|
|
### `Network`
|
|
Private network definition from `infra.yaml`.
|
|
- `CIDR string`: Network CIDR block.
|
|
- `Name string`: Logical network name.
|
|
|
|
### `DNS`
|
|
DNS provider settings and desired zone contents.
|
|
- `Provider string`: DNS provider identifier.
|
|
- `Nameservers []string`: Authoritative nameservers for the managed domains.
|
|
- `Zones map[string]*Zone`: Desired DNS zones keyed by zone name.
|
|
|
|
### `Zone`
|
|
Desired DNS zone contents.
|
|
- `Records []DNSRecord`: Desired records for the zone.
|
|
|
|
### `DNSRecord`
|
|
Desired DNS record entry in `infra.yaml`.
|
|
- `Name string`: Record name or host label.
|
|
- `Type string`: DNS record type.
|
|
- `Value string`: Record value.
|
|
- `TTL int`: Record TTL in seconds.
|
|
|
|
### `SSL`
|
|
Top-level TLS configuration.
|
|
- `Wildcard WildcardCert`: Wildcard certificate settings.
|
|
|
|
### `WildcardCert`
|
|
Wildcard certificate request and deployment settings.
|
|
- `Domains []string`: Domain names covered by the wildcard certificate.
|
|
- `Method string`: Certificate issuance method.
|
|
- `DNSProvider string`: DNS provider used for validation.
|
|
- `Termination string`: Termination point for the certificate.
|
|
|
|
### `Database`
|
|
Database cluster configuration.
|
|
- `Engine string`: Database engine name.
|
|
- `Version string`: Engine version.
|
|
- `Cluster string`: Cluster mode or cluster identifier.
|
|
- `Nodes []DBNode`: Database nodes in the cluster.
|
|
- `SSTMethod string`: State snapshot transfer method.
|
|
- `Backup BackupConfig`: Automated backup settings for the database cluster.
|
|
|
|
### `DBNode`
|
|
Single database node definition.
|
|
- `Host string`: Host identifier for the database node.
|
|
- `Port int`: Database port.
|
|
|
|
### `BackupConfig`
|
|
Backup settings attached to `Database`.
|
|
- `Schedule string`: Backup schedule expression.
|
|
- `Destination string`: Backup destination type or endpoint.
|
|
- `Bucket string`: Bucket name when backups target object storage.
|
|
- `Prefix string`: Object key prefix for stored backups.
|
|
|
|
### `Cache`
|
|
Cache or session cluster configuration.
|
|
- `Engine string`: Cache engine name.
|
|
- `Version string`: Engine version.
|
|
- `Sentinel bool`: Whether Redis Sentinel style high availability is enabled.
|
|
- `Nodes []CacheNode`: Cache nodes in the cluster.
|
|
|
|
### `CacheNode`
|
|
Single cache node definition.
|
|
- `Host string`: Host identifier for the cache node.
|
|
- `Port int`: Cache service port.
|
|
|
|
### `Container`
|
|
Named container deployment definition.
|
|
- `Image string`: Container image reference.
|
|
- `Port int`: Optional exposed service port.
|
|
- `Runtime string`: Optional container runtime identifier.
|
|
- `Command string`: Optional command override.
|
|
- `Replicas int`: Optional replica count.
|
|
- `DependsOn []string`: Optional dependency list naming other services or components.
|
|
|
|
### `S3Config`
|
|
Object storage configuration.
|
|
- `Endpoint string`: S3-compatible endpoint URL or host.
|
|
- `Buckets map[string]*S3Bucket`: Named bucket definitions keyed by logical bucket name.
|
|
|
|
### `S3Bucket`
|
|
Single S3 bucket definition.
|
|
- `Purpose string`: Intended bucket role or usage.
|
|
- `Paths []string`: Managed paths or prefixes within the bucket.
|
|
|
|
### `CDN`
|
|
CDN configuration.
|
|
- `Provider string`: CDN provider identifier.
|
|
- `Origin string`: Origin hostname or endpoint.
|
|
- `Zones []string`: Zones served through the CDN.
|
|
|
|
### `CICD`
|
|
CI/CD service configuration.
|
|
- `Provider string`: CI/CD provider identifier.
|
|
- `URL string`: Service URL.
|
|
- `Runner string`: Runner type or runner host reference.
|
|
- `Registry string`: Container registry endpoint.
|
|
- `DeployHook string`: Deploy hook URL or tokenized endpoint.
|
|
|
|
### `Monitoring`
|
|
Monitoring and alert configuration.
|
|
- `HealthEndpoints []HealthEndpoint`: Endpoints that should be polled for health.
|
|
- `Alerts map[string]int`: Numeric thresholds keyed by alert name.
|
|
|
|
### `HealthEndpoint`
|
|
Health endpoint monitored by the platform.
|
|
- `URL string`: Endpoint URL.
|
|
- `Interval int`: Polling interval in seconds.
|
|
|
|
### `Backups`
|
|
Backup schedules grouped by cadence.
|
|
- `Daily []BackupJob`: Jobs that run daily.
|
|
- `Weekly []BackupJob`: Jobs that run weekly.
|
|
|
|
### `BackupJob`
|
|
Scheduled backup job definition.
|
|
- `Name string`: Job name.
|
|
- `Type string`: Backup type or mechanism.
|
|
- `Destination string`: Optional destination override.
|
|
- `Hosts []string`: Optional host list associated with the job.
|
|
|
|
### `HCloudClient`
|
|
HTTP client for the Hetzner Cloud API. Token, base URL, and delegated `APIClient` state are stored in unexported fields.
|
|
- `func (c *HCloudClient) ListServers(ctx context.Context) ([]HCloudServer, error)`: Lists cloud servers.
|
|
- `func (c *HCloudClient) ListLoadBalancers(ctx context.Context) ([]HCloudLoadBalancer, error)`: Lists managed load balancers.
|
|
- `func (c *HCloudClient) GetLoadBalancer(ctx context.Context, id int) (*HCloudLoadBalancer, error)`: Fetches a load balancer by numeric ID.
|
|
- `func (c *HCloudClient) CreateLoadBalancer(ctx context.Context, req HCloudLBCreateRequest) (*HCloudLoadBalancer, error)`: Creates a load balancer from the supplied request payload.
|
|
- `func (c *HCloudClient) DeleteLoadBalancer(ctx context.Context, id int) error`: Deletes a load balancer by numeric ID.
|
|
- `func (c *HCloudClient) CreateSnapshot(ctx context.Context, serverID int, description string) error`: Creates a snapshot image for a server.
|
|
|
|
### `HCloudServer`
|
|
Hetzner Cloud server model returned by `ListServers`.
|
|
- `ID int`: Hetzner server ID.
|
|
- `Name string`: Server name.
|
|
- `Status string`: Provisioning or runtime status string.
|
|
- `PublicNet HCloudPublicNet`: Public networking information.
|
|
- `PrivateNet []HCloudPrivateNet`: Attached private network interfaces.
|
|
- `ServerType HCloudServerType`: Server flavour metadata.
|
|
- `Datacenter HCloudDatacenter`: Datacenter metadata.
|
|
- `Labels map[string]string`: Hetzner labels attached to the server.
|
|
|
|
### `HCloudPublicNet`
|
|
Hetzner Cloud public network metadata.
|
|
- `IPv4 HCloudIPv4`: Primary public IPv4 address.
|
|
|
|
### `HCloudIPv4`
|
|
Hetzner IPv4 model.
|
|
- `IP string`: IPv4 address string.
|
|
|
|
### `HCloudPrivateNet`
|
|
Hetzner private network attachment.
|
|
- `IP string`: Private IP assigned to the server on the network.
|
|
- `Network int`: Numeric network ID.
|
|
|
|
### `HCloudServerType`
|
|
Hetzner server flavour metadata.
|
|
- `Name string`: Server type name.
|
|
- `Description string`: Provider description for the server type.
|
|
- `Cores int`: Number of vCPUs.
|
|
- `Memory float64`: RAM size reported by the API.
|
|
- `Disk int`: Disk size reported by the API.
|
|
|
|
### `HCloudDatacenter`
|
|
Hetzner datacenter or location metadata.
|
|
- `Name string`: Datacenter or location name.
|
|
- `Description string`: Provider description.
|
|
|
|
### `HCloudLoadBalancer`
|
|
Hetzner managed load balancer model.
|
|
- `ID int`: Load balancer ID.
|
|
- `Name string`: Load balancer name.
|
|
- `PublicNet HCloudLBPublicNet`: Public network state, including the IPv4 address.
|
|
- `Algorithm HCloudLBAlgorithm`: Load-balancing algorithm.
|
|
- `Services []HCloudLBService`: Configured listeners and service definitions.
|
|
- `Targets []HCloudLBTarget`: Attached backend targets.
|
|
- `Location HCloudDatacenter`: Location metadata.
|
|
- `Labels map[string]string`: Hetzner labels attached to the load balancer.
|
|
|
|
### `HCloudLBPublicNet`
|
|
Public network state for a Hetzner load balancer.
|
|
- `Enabled bool`: Whether public networking is enabled.
|
|
- `IPv4 HCloudIPv4`: Assigned public IPv4 address.
|
|
|
|
### `HCloudLBAlgorithm`
|
|
Hetzner load-balancing algorithm descriptor.
|
|
- `Type string`: Algorithm name.
|
|
|
|
### `HCloudLBService`
|
|
Hetzner load balancer listener or service definition.
|
|
- `Protocol string`: Listener protocol.
|
|
- `ListenPort int`: Frontend port exposed by the load balancer.
|
|
- `DestinationPort int`: Backend port targeted by the service.
|
|
- `Proxyprotocol bool`: Whether PROXY protocol forwarding is enabled. The API field name is `proxyprotocol`.
|
|
- `HTTP *HCloudLBHTTP`: Optional HTTP-specific settings.
|
|
- `HealthCheck *HCloudLBHealthCheck`: Optional health-check configuration.
|
|
|
|
### `HCloudLBHTTP`
|
|
HTTP-specific load balancer service settings.
|
|
- `RedirectHTTP bool`: Whether plain HTTP requests should be redirected.
|
|
|
|
### `HCloudLBHealthCheck`
|
|
Hetzner load balancer health-check definition.
|
|
- `Protocol string`: Health-check protocol.
|
|
- `Port int`: Backend port to probe.
|
|
- `Interval int`: Probe interval.
|
|
- `Timeout int`: Probe timeout.
|
|
- `Retries int`: Failure threshold before a target is considered unhealthy.
|
|
- `HTTP *HCloudLBHCHTTP`: Optional HTTP-specific health-check options.
|
|
|
|
### `HCloudLBHCHTTP`
|
|
HTTP-specific Hetzner health-check options.
|
|
- `Path string`: HTTP path used for the probe.
|
|
- `StatusCode string`: Expected status code matcher serialized as `status_codes`.
|
|
|
|
### `HCloudLBTarget`
|
|
Backend target attached to a Hetzner load balancer.
|
|
- `Type string`: Target type, such as `ip` or `server`.
|
|
- `IP *HCloudLBTargetIP`: IP target metadata when the target type is IP-based.
|
|
- `Server *HCloudLBTargetServer`: Server reference when the target type is server-based.
|
|
- `HealthStatus []HCloudLBHealthStatus`: Health status entries for the target.
|
|
|
|
### `HCloudLBTargetIP`
|
|
IP-based load balancer target.
|
|
- `IP string`: Backend IP address.
|
|
|
|
### `HCloudLBTargetServer`
|
|
Server-based load balancer target reference.
|
|
- `ID int`: Hetzner server ID.
|
|
|
|
### `HCloudLBHealthStatus`
|
|
Health state for one listening port on a load balancer target.
|
|
- `ListenPort int`: Listener port associated with the status.
|
|
- `Status string`: Health status string such as `healthy`.
|
|
|
|
### `HCloudLBCreateRequest`
|
|
Request payload for `HCloudClient.CreateLoadBalancer`.
|
|
- `Name string`: New load balancer name.
|
|
- `LoadBalancerType string`: Hetzner load balancer type slug.
|
|
- `Location string`: Hetzner location or datacenter slug.
|
|
- `Algorithm HCloudLBAlgorithm`: Algorithm selection.
|
|
- `Services []HCloudLBService`: Listener definitions to create.
|
|
- `Targets []HCloudLBCreateTarget`: Backend targets to attach at creation time.
|
|
- `Labels map[string]string`: Labels to apply to the new load balancer.
|
|
|
|
### `HCloudLBCreateTarget`
|
|
Target entry used during load balancer creation.
|
|
- `Type string`: Target type.
|
|
- `IP *HCloudLBTargetIP`: IP target metadata when the target is IP-based.
|
|
|
|
### `HRobotClient`
|
|
HTTP client for the Hetzner Robot API. Credentials, base URL, and delegated `APIClient` state are stored in unexported fields.
|
|
- `func (c *HRobotClient) ListServers(ctx context.Context) ([]HRobotServer, error)`: Lists dedicated servers available from Robot.
|
|
- `func (c *HRobotClient) GetServer(ctx context.Context, ip string) (*HRobotServer, error)`: Fetches one Robot server by server IP.
|
|
|
|
### `HRobotServer`
|
|
Hetzner Robot dedicated server model.
|
|
- `ServerIP string`: Public server IP address.
|
|
- `ServerName string`: Server hostname.
|
|
- `Product string`: Product or hardware plan name.
|
|
- `Datacenter string`: Datacenter code returned by the API field `dc`.
|
|
- `Status string`: Robot status string.
|
|
- `Cancelled bool`: Whether the server is cancelled.
|
|
- `PaidUntil string`: Billing paid-through date string.
|
|
|
|
## Functions
|
|
|
|
### `func DefaultRetryConfig() RetryConfig`
|
|
Returns the library defaults used by `NewAPIClient`: three retries, `100ms` initial backoff, and `5s` maximum backoff.
|
|
|
|
### `func WithHTTPClient(c *http.Client) APIClientOption`
|
|
Injects a custom `http.Client` into an `APIClient`.
|
|
|
|
### `func WithRetry(cfg RetryConfig) APIClientOption`
|
|
Injects a retry policy into an `APIClient`.
|
|
|
|
### `func WithAuth(fn func(req *http.Request)) APIClientOption`
|
|
Registers a callback that mutates each outgoing request before it is sent.
|
|
|
|
### `func WithPrefix(p string) APIClientOption`
|
|
Sets the error prefix used when wrapping client errors.
|
|
|
|
### `func NewAPIClient(opts ...APIClientOption) *APIClient`
|
|
Builds an `APIClient` with a `30s` HTTP timeout, `DefaultRetryConfig`, default prefix `api`, and any supplied options.
|
|
|
|
### `func NewCloudNSClient(authID, password string) *CloudNSClient`
|
|
Builds a CloudNS client configured for `auth-id` and `auth-password` query-parameter authentication.
|
|
|
|
### `func Load(path string) (*Config, error)`
|
|
Reads and unmarshals `infra.yaml`, expands host SSH key paths, and defaults missing SSH ports to `22`.
|
|
|
|
### `func Discover(startDir string) (*Config, string, error)`
|
|
Searches `startDir` and its parents for `infra.yaml`, returning the parsed config together with the discovered file path.
|
|
|
|
### `func NewHCloudClient(token string) *HCloudClient`
|
|
Builds a Hetzner Cloud client that authenticates requests with a bearer token.
|
|
|
|
### `func NewHRobotClient(user, password string) *HRobotClient`
|
|
Builds a Hetzner Robot client that authenticates requests with HTTP basic auth.
|