Skip to content

Tutorials & Examples

This page contains step-by-step tutorials to help you get hands-on with Pleiades GSLB.

Tutorial 1: Single-node quickstart Goal: run one gslbd instance locally and answer A/AAAA queries. 1) Follow Getting Started to build and run with a minimal config. 2) Verify health checks and DNS answers using dig. 3) Explore Prometheus metrics at http://localhost:9090/metrics.

Tutorial 2: Two nodes with state sync Goal: run two gslbd instances that share health via NATS. Prereqs: a NATS server with JetStream (can be a single node for a lab). Steps: 1) Configure NATS (see StateSyncSetup.md) and obtain client TLS materials if using TLS. 2) Prepare two configs with unique node.id, same cluster.id, and the same state.nats settings. 3) Start both nodes (different hosts or different containers/ports on one host). 4) Observe gslbd_state_active_members on both; it should be 2. 5) Simulate a backend failure and watch quorum behavior depending on state.healthPolicy.

Tutorial 3: Weighted Round-Robin with per-endpoint weights Goal: steer more traffic to a stronger backend using weights. Steps: 1) Start from the Getting Started config and change the load balancer to WRR: 

loadbalancer:
  algorithm: "weighted-round-robin"
  endpoints:
    - 203.0.113.10
    - 203.0.113.11
    - 2001:db8::10
  weights:
    "203.0.113.10": 5
    "203.0.113.11": 1
    "2001:db8::10": 3
2) Restart gslbd and issue multiple dig queries; you should observe a higher share of answers for the higher-weight IPs. 3) Set a weight to 0 to temporarily drain a backend without removing it.

Tutorial 4: Enable Configuration Sync (JetStream) Goal: distribute configuration as YAML to your nodes via NATS JetStream. Prereqs: a NATS server with JetStream; basic understanding of State Sync. Steps: 1) Ensure state.nats.servers points to your NATS and (optionally) set a JetStream domain. 2) Enable configuration sync in node config: 

state:
  enableConfigSync: true
  nats:
    servers: ["nats://127.0.0.1:4222"]
    jetStream:
      domain: "gslb"
  config:
    mode: "jetstream"
    stream: "PLEIADES.cfg"
    subjectPrefix: "pleiades.cfg"
    kvBucket: "PLEIADES_CFG"
3) Start gslbd. It will attempt to load a snapshot from KV and watch the stream for your cluster.id. 4) Publish a YAML ClusterConfig (see docs/StateSync.md example) to KV/Stream using your preferred tooling. In upcoming releases a helper tool will be provided. 5) Verify logs show the received version/commit and watch for apply status.

Tutorial 5: GitOps rollout Goal: manage configuration changes via a signed Git repo. Steps: 1) Set up a Git repo with clusters/<cluster>/gslbd.yaml (see GitOpsUserGuide.md). 2) Enable GitOps in /etc/gslb/config.yaml with requireSignature: true and allowedSigners. 3) Make a change (add/remove an endpoint), sign the commit, and push. 4) Wait for the poll interval or restart gslbd to reconcile immediately. 5) Verify changes were applied (DNS answers, health gauges) and check metrics gslbd_gitops_last_apply_info{sha,signer}.

Tutorial 6: Secure HTTPS health checks Goal: enforce TLS verification for HTTP health checks. Steps: 1) Configure backend with a valid certificate (public or internal CA) and known hostname. 2) Set health.http.tls: true, insecureSkipVerify: false, and http.host to the certificate hostname. 3) Verify health becomes healthy; if not, use curl -vk https://<ip>:<port>/healthz -H 'Host: your.host' to debug.

Appendix: Example docker-compose for lab 

version: "3"
services:
  nats:
    image: nats:2
    command: ["-js", "-m", "8222"]
    ports: ["4222:4222", "8222:8222"]
  gslbd1:
    image: pleiades/gslbd:local
    depends_on: [nats]
    volumes:
      - ./config1.yaml:/etc/gslb/config.yaml:ro
    ports:
      - "5353:5353/udp"
      - "9090:9090"
  gslbd2:
    image: pleiades/gslbd:local
    depends_on: [nats]
    volumes:
      - ./config2.yaml:/etc/gslb/config.yaml:ro
    ports:
      - "5354:5353/udp"
      - "9091:9090"