Tutorials & Examples

This page contains step-by-step tutorials to help you get hands-on with Nexus 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: Declarative configuration with GitOps Goal: distribute configuration to your nodes from a Git repository.

NATS JetStream config sync has been removed. Configuration is now distributed via GitOps self-restart: each node independently polls a Git repo, validates the config, writes it to its own config file, and gracefully restarts onto it. Data-plane objects (pools/members/services) are replicated by the rqlite datastore, not NATS. See the GitOps User Guide for the full walkthrough.

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.

Tutorial 7: Real-user measurement (RUM) routing Goal: answer DNS queries with the member that is fastest for the actual user, measured from browsers. Prereqs: pro license; a small always-on URL on each member (e.g. a 204 handler). Steps:

1. Set a rumUrl on each member: gslbctl members update <id> --name web-01 --rum-url https://web-01.example.com/__rum.
2. Embed the beacon on your site: <script src="https://<nexus-host>/rum.js" data-domain="app.example.com" async></script>.
3. Add the rum step to the service filter chain (e.g. ["geo-ip", "rum"]).
4. Watch coverage grow with gslbctl rum status; inspect per-query decisions with gslbctl trace <service-id> --client-ip <ip>. Full walkthrough (including a 10-minute lab with simulated measurements): RUMRouting.md.

Appendix: Example docker-compose for lab

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