Getting Started with Pleiades GSLB¶

This guide helps you run Pleiades GSLB locally in under 10 minutes. You will build the daemon, start it with a minimal configuration, and verify responses using dig.

Who is this for? - Operators/SREs evaluating the software - Developers wanting to try the DNS and health checking behavior

Prerequisites

Required Tools

Linux or macOS host
Go toolchain installed (Go 1.24+)
dig (from bind-utils or dnsutils)

Optional: Container Runtime

Docker/Podman is optional and only needed if you prefer containerized runs.

1) Clone and build

git clone https://your.git/pleiades.git
cd Pleiades
go build ./...

2) Minimal configuration Create a minimal config at ./config.yaml:

cluster:
  id: "dev-cluster"

loadbalancer:
  algorithm: "round-robin"
  endpoints:
    - 203.0.113.10
    - 2001:db8::10

health:
  type: tcp
  port: 80
  checkinterval: "10s"
  timeout: "2s"

metrics:
  enablePrometheus: true
  listenAddr: "0.0.0.0"
  port: 9090

Notes:

Endpoints Must Be Real Servers

Endpoints must be real servers you control. For a quick test without real servers, keep type: tcp and point at hosts that listen on port 80.

Optional: Use Weighted Round-Robin and per-endpoint weights

loadbalancer:
  algorithm: "weighted-round-robin"
  endpoints:
    - 203.0.113.10
    - 203.0.113.11
  weights:
    "203.0.113.10": 5
    "203.0.113.11": 1

This skews responses toward higher‑weight backends.

3) Run

sudo ./gslbd -config ./config.yaml

By default DNS listens on UDP 0.0.0.0:5353 with domain gslb.local.

4) Query with dig

dig @127.0.0.1 -p 5353 A gslb.local
# repeat a few times to see round-robin

dig @127.0.0.1 -p 5353 AAAA gslb.local

If health checks mark an endpoint unhealthy, it will be skipped in answers.

5) Optional: Enable GitOps later When you are ready to try GitOps configuration management, add:

gitops:
  repoURL: "ssh://gitea@git.example.com/infra/gslb-config.git"
  branch: "main"
  pathPrefix: "clusters/dev-cluster"
  pollInterval: "30s"
  requireSignature: true
  allowedSigners: ["<YOUR_GPG_FINGERPRINT>"]
  auth:
    sshKeyPath: "/etc/gslb/gitops_deploy_key"

See the GitOps Operator Guide for repository layout and signing.

6) Optional: Enable Configuration Sync (JetStream) If you run NATS with JetStream, nodes can fetch and watch a cluster YAML config:

state:
  enableConfigSync: true
  nats:
    servers: ["nats://127.0.0.1:4222"]
  config:
    mode: "jetstream"
    stream: "PLEIADES.cfg"
    subjectPrefix: "pleiades.cfg"
    kvBucket: "PLEIADES_CFG"

See: ./StateSyncSetup.md and ../StateSync.md

7) What’s next - Installation (systemd, container): ./Installation.md - Configuration reference (all fields): ../Configuration.md and ./ConfigurationGuide.md - State synchronization (multi-region health via NATS): ./StateSyncSetup.md - Metrics and Grafana: ./MetricsObservability.md - Troubleshooting: ./OperationsTroubleshooting.md