Merge pull request 'cluster: migrate to using pkg/rings for Addresses' (#51) from pr-amery-rings into main

Reviewed-on: #51

Makefile

@@ -15,7 +15,8 @@ TMPDIR ?= .tmp
 REVIVE ?= $(GOBIN)/revive
 REVIVE_CONF ?= $(TOOLSDIR)/revive.toml
 REVIVE_RUN_ARGS ?= -config $(REVIVE_CONF) -formatter friendly
-REVIVE_INSTALL_URL ?= github.com/mgechev/revive@master
+REVIVE_VERSION ?= v1.3.7
+REVIVE_INSTALL_URL ?= github.com/mgechev/revive@$(REVIVE_VERSION)
 
 GO_INSTALL_URLS = \
 	$(REVIVE_INSTALL_URL) \

cmd/jpictl/dns.go

@@ -52,7 +52,7 @@ func populateDNSManager(mgr *dns.Manager, m *cluster.Cluster) error {
 
 	m.ForEachZone(func(z *cluster.Zone) bool {
 		z.ForEachMachine(func(p *cluster.Machine) bool {
-			err = mgr.AddHost(ctx, z.Name, p.ID, p.IsActive(), p.PublicAddresses...)
+			err = mgr.AddHost(ctx, z.Name, int(p.ID), p.IsActive(), p.PublicAddresses...)
 			return err != nil
 		})
 

cmd/jpictl/gateway.go

@@ -4,7 +4,6 @@ import (
 	"bytes"
 	"fmt"
 	"os"
-	"strconv"
 	"strings"
 
 	"github.com/spf13/cobra"
@@ -128,7 +127,7 @@ func gatewayListAll(zi cluster.ZoneIterator) error {
 			return false
 		}
 		for _, i := range ids {
-			sIDs = append(sIDs, strconv.Itoa(i))
+			sIDs = append(sIDs, i.String())
 		}
 		b.WriteString(strings.Join(sIDs, ", "))
 		b.WriteString("\n")

go.mod

@@ -4,7 +4,7 @@ go 1.19
 
 require (
 	asciigoat.org/ini v0.2.5
-	darvaza.org/core v0.13.1
+	darvaza.org/core v0.13.3
 	darvaza.org/resolver v0.9.2
 	darvaza.org/sidecar v0.4.0
 	darvaza.org/slog v0.5.7

go.sum

@@ -4,8 +4,8 @@ asciigoat.org/ini v0.2.5 h1:4gRIp9rU+XQt8+HMqZO5R7GavMv9Yl2+N+je6djDIAE=
 asciigoat.org/ini v0.2.5/go.mod h1:gmXzJ9XFqf1NLk5nQkj04USQ4tMtdRJHNQX6vp3DzjU=
 darvaza.org/cache/x/simplelru v0.1.8 h1:rvFucut4wKYbsYc994yR3P0M08NqlsvZxr5G4QK82tw=
 darvaza.org/cache/x/simplelru v0.1.8/go.mod h1:Mv1isOJTcXYK+aK0AvUe+/3KpRTXDsYga6rdTS/upNs=
-darvaza.org/core v0.13.1 h1:ZoAfZ3OLnw+t28qMQQxXrDIkETmT2h5gAO6F1XuBpwg=
-darvaza.org/core v0.13.1/go.mod h1:47Ydh67KnzjLNu1mzX3r2zpphbxQqEaihMsUq5GflQ4=
+darvaza.org/core v0.13.3 h1:DOsidY49WXsWiJulOIxDq578h/3ekgx0trWxbvgv5bc=
+darvaza.org/core v0.13.3/go.mod h1:47Ydh67KnzjLNu1mzX3r2zpphbxQqEaihMsUq5GflQ4=
 darvaza.org/resolver v0.9.2 h1:sUX6LZ1eN5TzJW7L4m7HM+BvwBeWl8dYYDGVSe+AIhk=
 darvaza.org/resolver v0.9.2/go.mod h1:XWqPhrxoOKNzRuSozOwmE1M6QVqQL28jEdxylnIO8Nw=
 darvaza.org/sidecar v0.4.0 h1:wHghxzLsiT82WDBBUf34aTqtOvRBg4UbxVIJgKNXRVA=

pkg/cluster/addr.go

@@ -0,0 +1,43 @@
+package cluster
+
+import (
+	"net/netip"
+
+	"git.jpi.io/amery/jpictl/pkg/rings"
+)
+
+// RingOnePrefix returns the ring 1 subnet of this [Zone].
+func (z *Zone) RingOnePrefix() netip.Prefix {
+	subnet, err := rings.RingOnePrefix(z.RegionID(), z.ID)
+	if err != nil {
+		panic(err)
+	}
+	return subnet
+}
+
+// RingOnePrefix returns the ring 1 subnet this [Machine] belongs
+// to.
+func (m *Machine) RingOnePrefix() netip.Prefix {
+	return m.zone.RingOnePrefix()
+}
+
+// RingZeroAddress returns the ring 0 address of the [Machine]
+// if it can act as gateway.
+func (m *Machine) RingZeroAddress() (netip.Addr, bool) {
+	addr, err := rings.RingZeroAddress(m.Region(), m.Zone(), m.ID)
+	if err != nil {
+		return netip.Addr{}, false
+	}
+
+	return addr, true
+}
+
+// RingOneAddress returns the ring 1 address of the [Machine]
+func (m *Machine) RingOneAddress() netip.Addr {
+	addr, err := rings.RingOneAddress(m.Region(), m.Zone(), m.ID)
+	if err != nil {
+		panic(err)
+	}
+
+	return addr
+}

pkg/cluster/ceph.go

@@ -66,7 +66,7 @@ func (m *Cluster) GenCephConfig() (*ceph.Config, error) {
 
 	m.ForEachZone(func(z *Zone) bool {
 		for _, p := range z.GetCephMonitors() {
-			addr, _ := RingOneAddress(z.ID, p.ID)
+			addr := p.RingOneAddress()
 
 			cfg.Global.Monitors = append(cfg.Global.Monitors, p.Name)
 			cfg.Global.MonitorsAddr = append(cfg.Global.MonitorsAddr, addr)

pkg/cluster/ceph_scan.go

@@ -4,6 +4,7 @@ import (
 	"os"
 
 	"darvaza.org/slog"
+
 	"git.jpi.io/amery/jpictl/pkg/ceph"
 )
 
@@ -14,8 +15,7 @@ type cephScanTODO struct {
 
 func (todo *cephScanTODO) checkMachine(p *Machine) bool {
 	// on ceph all addresses are ring1
-	ring1, _ := RingOneAddress(p.Zone(), p.ID)
-	addr := ring1.String()
+	addr := p.RingOneAddress().String()
 
 	if _, found := todo.names[p.Name]; found {
 		// found on the TODO by name

pkg/cluster/cluster_import.go

@@ -6,16 +6,18 @@ import (
 	"os"
 
 	"gopkg.in/yaml.v3"
+
+	"git.jpi.io/amery/jpictl/pkg/rings"
 )
 
 func (m *Cluster) init(opts *ScanOptions) error {
 	for _, fn := range []func(*ScanOptions) error{
 		m.initZones,
+		m.initRegions,
 		m.scanZoneIDs,
 		m.scanSort,
 		m.scanGateways,
 		m.initCephMonitors,
-		m.initRegions,
 	} {
 		if err := fn(opts); err != nil {
 			return err
@@ -45,7 +47,7 @@ func (m *Cluster) initZones(opts *ScanOptions) error {
 
 func (m *Cluster) initZone(z *Zone, _ *ScanOptions) error {
 	var hasMissing bool
-	var lastMachineID int
+	var lastMachineID rings.NodeID
 
 	z.zones = m
 	z.logger = m
@@ -58,7 +60,7 @@ func (m *Cluster) initZone(z *Zone, _ *ScanOptions) error {
 		case p.ID == 0:
 			hasMissing = true
 		case p.ID > lastMachineID:
-			lastMachineID = z.ID
+			lastMachineID = p.ID
 		}
 
 		return false

pkg/cluster/cluster_scan.go

@@ -7,6 +7,8 @@ import (
 	"strings"
 
 	"darvaza.org/core"
+
+	"git.jpi.io/amery/jpictl/pkg/rings"
 )
 
 const (
@@ -23,9 +25,9 @@ func (m *Cluster) scan(opts *ScanOptions) error {
 	for _, fn := range []func(*ScanOptions) error{
 		m.scanDirectory,
 		m.scanMachines,
+		m.initRegions,
 		m.scanZoneIDs,
 		m.scanSort,
-		m.initRegions,
 		m.scanGateways,
 		m.scanCephMonitors,
 	} {
@@ -114,7 +116,7 @@ func (m *Cluster) scanMachines(opts *ScanOptions) error {
 
 func (m *Cluster) scanZoneIDs(_ *ScanOptions) error {
 	var hasMissing bool
-	var lastZoneID int
+	var lastZoneID rings.ZoneID
 
 	m.ForEachZone(func(z *Zone) bool {
 		switch {

pkg/cluster/env.go

@@ -6,6 +6,8 @@ import (
 	"io"
 	"sort"
 	"strings"
+
+	"git.jpi.io/amery/jpictl/pkg/rings"
 )
 
 // Env is a shell environment factory for this cluster
@@ -35,8 +37,8 @@ func (m *Cluster) Env(export bool) (*Env, error) {
 }
 
 // Zones returns the list of Zone IDs
-func (m *Env) Zones() []int {
-	var zones []int
+func (m *Env) Zones() []rings.ZoneID {
+	var zones []rings.ZoneID
 
 	m.ForEachZone(func(z *Zone) bool {
 		zones = append(zones, z.ID)
@@ -51,7 +53,7 @@ func (m *Env) Regions() []string {
 	var regions []string
 
 	m.ForEachRegion(func(r *Region) bool {
-		if r.Cluster != nil {
+		if r.IsPrimary() {
 			regions = append(regions, r.Name)
 		}
 
@@ -70,8 +72,8 @@ func (m *Env) WriteTo(w io.Writer) (int64, error) {
 		m.writeEnvVar(&buf, m.cephFSID, "FSID")
 	}
 
-	m.writeEnvVarStrings(&buf, m.Regions(), "REGIONS")
-	m.writeEnvVarInts(&buf, m.Zones(), "ZONES")
+	m.writeEnvVar(&buf, genEnvStrings(m.Regions()), "REGIONS")
+	m.writeEnvVar(&buf, genEnvInts(m.Zones()), "ZONES")
 
 	m.ForEachZone(func(z *Zone) bool {
 		m.writeEnvZone(&buf, z)
@@ -92,7 +94,7 @@ func (m *Env) writeEnvZone(w io.Writer, z *Zone) {
 
 	// ZONE{zoneID}_GW
 	gateways, _ := z.GatewayIDs()
-	m.writeEnvVarInts(w, gateways, "ZONE%v_%s", zoneID, "GW")
+	m.writeEnvVar(w, genEnvInts(gateways), "ZONE%v_%s", zoneID, "GW")
 
 	// ZONE{zoneID}_REGION
 	m.writeEnvVar(w, genEnvZoneRegion(z), "ZONE%v_%s", zoneID, "REGION")
@@ -107,32 +109,6 @@ func (m *Env) writeEnvZone(w io.Writer, z *Zone) {
 	m.writeEnvVar(w, genEnvZoneCephMonIDs(monitors), "MON%v_%s", zoneID, "ID")
 }
 
-func (m *Env) writeEnvVarInts(w io.Writer, value []int, name string, args ...any) {
-	var buf bytes.Buffer
-
-	for _, v := range value {
-		if buf.Len() > 0 {
-			_, _ = fmt.Fprint(&buf, " ")
-		}
-		_, _ = fmt.Fprintf(&buf, "%v", v)
-	}
-
-	m.writeEnvVar(w, buf.String(), name, args...)
-}
-
-func (m *Env) writeEnvVarStrings(w io.Writer, value []string, name string, args ...any) {
-	var buf bytes.Buffer
-
-	for _, v := range value {
-		if buf.Len() > 0 {
-			_, _ = fmt.Fprint(&buf, " ")
-		}
-		_, _ = fmt.Fprintf(&buf, "%s", v)
-	}
-
-	m.writeEnvVar(w, buf.String(), name, args...)
-}
-
 func (m *Env) writeEnvVar(w io.Writer, value string, name string, args ...any) {
 	var prefix string
 
@@ -155,6 +131,23 @@ func (m *Env) writeEnvVar(w io.Writer, value string, name string, args ...any) {
 	}
 }
 
+func genEnvInts[T ~int | ~uint](values []T) string {
+	var buf bytes.Buffer
+
+	for _, v := range values {
+		if buf.Len() > 0 {
+			_, _ = buf.WriteRune(' ')
+		}
+		_, _ = buf.WriteString(fmt.Sprintf("%v", v))
+	}
+
+	return buf.String()
+}
+
+func genEnvStrings(values []string) string {
+	return strings.Join(values, " ")
+}
+
 func genEnvZoneNodes(z *Zone) string {
 	if n := z.Len(); n > 0 {
 		s := make([]string, 0, n)
@@ -164,24 +157,16 @@ func genEnvZoneNodes(z *Zone) string {
 			return false
 		})
 
-		return strings.Join(s, " ")
+		return genEnvStrings(s)
 	}
 	return ""
 }
 
 func genEnvZoneRegion(z *Zone) string {
-	var region string
-
-	z.ForEachRegion(func(r *Region) bool {
-		if r.Cluster != nil {
-			region = r.Name
-			return true
-		}
-
-		return false
-	})
-
-	return region
+	if z != nil && z.region != nil {
+		return z.region.Name
+	}
+	return ""
 }
 
 func genEnvZoneCephMonNames(m Machines) string {
@@ -200,7 +185,7 @@ func genEnvZoneCephMonNames(m Machines) string {
 func genEnvZoneCephMonIPs(m Machines) string {
 	var buf strings.Builder
 	m.ForEachMachine(func(p *Machine) bool {
-		addr, _ := RingOneAddress(p.Zone(), p.ID)
+		addr := p.RingOneAddress()
 
 		if buf.Len() > 0 {
 			_, _ = buf.WriteRune(' ')

pkg/cluster/errors.go

@@ -1,6 +1,13 @@
 package cluster
 
-import "errors"
+import (
+	"errors"
+	"io/fs"
+
+	"darvaza.org/core"
+
+	"git.jpi.io/amery/jpictl/pkg/rings"
+)
 
 var (
 	// ErrInvalidName indicates the name isn't valid
@@ -14,3 +21,9 @@ var (
 	// the intended purpose
 	ErrInvalidNode = errors.New("invalid node")
 )
+
+// ErrInvalidRing returns an error indicating the [rings.RingID]
+// can't be used for the intended purpose
+func ErrInvalidRing(ringID rings.RingID) error {
+	return core.QuietWrap(fs.ErrInvalid, "invalid ring %v", ringID)
+}

pkg/cluster/hosts.go

@@ -71,14 +71,14 @@ func (p *Machine) WriteHosts() error {
 func (z *Zone) genHosts(out *hostsFile, p *Machine) {
 	var names []string
 
-	ip, _ := RingOneAddress(p.zone.ID, p.ID)
+	ip := p.RingOneAddress()
 	names = append(names, p.Name)
 
 	if p.CephMonitor {
 		names = append(names, fmt.Sprintf("%s-%s", p.zone.Name, "ceph"))
 		names = append(names, fmt.Sprintf("%s-%s", p.zone.Name, "k3s"))
 
-		if z.ID == p.zone.ID {
+		if z.Is(p.Region(), p.Zone()) {
 			names = append(names, "ceph")
 			names = append(names, "k3s")
 		}
@@ -94,7 +94,7 @@ func (z *Zone) genHosts(out *hostsFile, p *Machine) {
 	if p.IsGateway() {
 		var s string
 
-		ip, _ = RingZeroAddress(p.zone.ID, p.ID)
+		ip, _ = p.RingZeroAddress()
 		s = fmt.Sprintf("%s-%v", p.Name, 0)
 
 		entry = hostsEntry{

pkg/cluster/machine.go

@@ -3,6 +3,8 @@ package cluster
 import (
 	"net/netip"
 	"strings"
+
+	"git.jpi.io/amery/jpictl/pkg/rings"
 )
 
 // revive:disable:line-length-limit
@@ -12,7 +14,7 @@ type Machine struct {
 	zone   *Zone
 	logger `json:"-" yaml:"-"`
 
-	ID   int
+	ID   rings.NodeID
 	Name string `json:"-" yaml:"-"`
 
 	Inactive        bool         `json:"inactive,omitempty"     yaml:"inactive,omitempty"`
@@ -51,13 +53,13 @@ func (m *Machine) IsActive() bool {
 
 // IsGateway tells if the Machine is a ring0 gateway
 func (m *Machine) IsGateway() bool {
-	_, ok := m.getRingInfo(0)
+	_, ok := m.getRingInfo(rings.RingZeroID)
 	return ok
 }
 
 // SetGateway enables/disables a Machine ring0 integration
 func (m *Machine) SetGateway(enabled bool) error {
-	ri, found := m.getRingInfo(0)
+	ri, found := m.getRingInfo(rings.RingZeroID)
 	switch {
 	case !found && !enabled:
 		return nil
@@ -70,14 +72,19 @@ func (m *Machine) SetGateway(enabled bool) error {
 	}
 
 	ri.Enabled = enabled
-	return m.SyncWireguardConfig(0)
+	return m.SyncWireguardConfig(rings.RingZeroID)
 }
 
 // Zone indicates the [Zone] this machine belongs to
-func (m *Machine) Zone() int {
+func (m *Machine) Zone() rings.ZoneID {
 	return m.zone.ID
 }
 
+// Region indicates the [Region] this machine belongs to
+func (m *Machine) Region() rings.RegionID {
+	return m.zone.RegionID()
+}
+
 func (m *Machine) getPeerByName(name string) (*Machine, bool) {
 	return m.zone.zones.GetMachineByName(name)
 }

pkg/cluster/machine_rings.go

@@ -8,18 +8,26 @@ import (
 
 	"darvaza.org/core"
 
+	"git.jpi.io/amery/jpictl/pkg/rings"
 	"git.jpi.io/amery/jpictl/pkg/wireguard"
 )
 
 // GetWireguardKeys reads a wgN.key/wgN.pub files
-func (m *Machine) GetWireguardKeys(ring int) (wireguard.KeyPair, error) {
+func (m *Machine) GetWireguardKeys(ringID rings.RingID) (wireguard.KeyPair, error) {
 	var (
 		data []byte
-		err  error
 		out  wireguard.KeyPair
 	)
 
-	data, err = m.ReadFile("wg%v.key", ring)
+	ring, err := AsWireguardInterfaceID(ringID)
+	if err != nil {
+		// invalid ring
+		return out, err
+	}
+
+	keyFile, pubFile, _ := ring.Files()
+
+	data, err = m.ReadFile(keyFile)
 	if err != nil {
 		// failed to read
 		return out, err
@@ -28,11 +36,11 @@ func (m *Machine) GetWireguardKeys(ring int) (wireguard.KeyPair, error) {
 	out.PrivateKey, err = wireguard.PrivateKeyFromBase64(string(data))
 	if err != nil {
 		// bad key
-		err = core.Wrap(err, "wg%v.key", ring)
+		err = core.Wrap(err, keyFile)
 		return out, err
 	}
 
-	data, err = m.ReadFile("wg%v.pub", ring)
+	data, err = m.ReadFile(pubFile)
 	switch {
 	case os.IsNotExist(err):
 		// no wgN.pub is fine
@@ -44,7 +52,7 @@ func (m *Machine) GetWireguardKeys(ring int) (wireguard.KeyPair, error) {
 		out.PublicKey, err = wireguard.PublicKeyFromBase64(string(data))
 		if err != nil {
 			// bad key
-			err = core.Wrap(err, "wg%v.pub", ring)
+			err = core.Wrap(err, pubFile)
 			return out, err
 		}
 	}
@@ -53,8 +61,8 @@ func (m *Machine) GetWireguardKeys(ring int) (wireguard.KeyPair, error) {
 	return out, err
 }
 
-func (m *Machine) tryReadWireguardKeys(ring int) error {
-	kp, err := m.GetWireguardKeys(ring)
+func (m *Machine) tryReadWireguardKeys(ringID rings.RingID) error {
+	kp, err := m.GetWireguardKeys(ringID)
 	switch {
 	case os.IsNotExist(err):
 		// ignore
@@ -65,20 +73,25 @@ func (m *Machine) tryReadWireguardKeys(ring int) error {
 	default:
 		// import keys
 		ri := &RingInfo{
-			Ring: ring,
+			Ring: MustWireguardInterfaceID(ringID),
 			Keys: kp,
 		}
 
-		return m.applyRingInfo(ring, ri)
+		return m.applyRingInfo(ringID, ri)
 	}
 }
 
 // RemoveWireguardKeys deletes wgN.key and wgN.pub from
 // the machine's config directory
-func (m *Machine) RemoveWireguardKeys(ring int) error {
-	var err error
+func (m *Machine) RemoveWireguardKeys(ringID rings.RingID) error {
+	ring, err := AsWireguardInterfaceID(ringID)
+	if err != nil {
+		return err
+	}
 
-	err = m.RemoveFile("wg%v.pub", ring)
+	keyFile, pubFile, _ := ring.Files()
+
+	err = m.RemoveFile(pubFile)
 	switch {
 	case os.IsNotExist(err):
 		// ignore
@@ -86,7 +99,7 @@ func (m *Machine) RemoveWireguardKeys(ring int) error {
 		return err
 	}
 
-	err = m.RemoveFile("wg%v.key", ring)
+	err = m.RemoveFile(keyFile)
 	if os.IsNotExist(err) {
 		// ignore
 		err = nil
@@ -96,8 +109,13 @@ func (m *Machine) RemoveWireguardKeys(ring int) error {
 }
 
 // GetWireguardConfig reads a wgN.conf file
-func (m *Machine) GetWireguardConfig(ring int) (*wireguard.Config, error) {
-	data, err := m.ReadFile("wg%v.conf", ring)
+func (m *Machine) GetWireguardConfig(ringID rings.RingID) (*wireguard.Config, error) {
+	ring, err := AsWireguardInterfaceID(ringID)
+	if err != nil {
+		return nil, err
+	}
+
+	data, err := m.ReadFile(ring.ConfFile())
 	if err != nil {
 		return nil, err
 	}
@@ -106,7 +124,7 @@ func (m *Machine) GetWireguardConfig(ring int) (*wireguard.Config, error) {
 	return wireguard.NewConfigFromReader(r)
 }
 
-func (m *Machine) tryApplyWireguardConfig(ring int) error {
+func (m *Machine) tryApplyWireguardConfig(ring rings.RingID) error {
 	wg, err := m.GetWireguardConfig(ring)
 	switch {
 	case os.IsNotExist(err):
@@ -118,15 +136,15 @@ func (m *Machine) tryApplyWireguardConfig(ring int) error {
 	}
 }
 
-func (m *Machine) applyWireguardConfigNode(ring int, wg *wireguard.Config) error {
+func (m *Machine) applyWireguardConfigNode(ring rings.RingID, wg *wireguard.Config) error {
 	addr := wg.GetAddress()
 	if !core.IsZero(addr) {
-		zoneID, nodeID, ok := Rings[ring].Decode(addr)
+		regionID, zoneID, nodeID, ok := Rings[ring].Decode(addr)
 		if !ok {
 			return fmt.Errorf("%s: invalid address", addr)
 		}
 
-		if err := m.applyZoneNodeID(zoneID, nodeID); err != nil {
+		if err := m.applyZoneNodeID(regionID, zoneID, nodeID); err != nil {
 			return core.Wrap(err, "%s: invalid address", addr)
 		}
 	}
@@ -138,7 +156,7 @@ func (m *Machine) applyWireguardConfigNode(ring int, wg *wireguard.Config) error
 	return nil
 }
 
-func (m *Machine) applyWireguardConfig(ring int, wg *wireguard.Config) error {
+func (m *Machine) applyWireguardConfig(ring rings.RingID, wg *wireguard.Config) error {
 	if err := m.applyWireguardConfigNode(ring, wg); err != nil {
 		return err
 	}
@@ -152,7 +170,7 @@ func (m *Machine) applyWireguardConfig(ring int, wg *wireguard.Config) error {
 				WithField("subsystem", "wireguard").
 				WithField("node", m.Name).
 				WithField("peer", peer.Endpoint.Host).
-				WithField("ring", ring).
+				WithField("ring", MustWireguardInterfaceID(ring)).
 				Print("ignoring unknown endpoint")
 		case err != nil:
 			return core.Wrap(err, "peer")
@@ -162,9 +180,9 @@ func (m *Machine) applyWireguardConfig(ring int, wg *wireguard.Config) error {
 	return nil
 }
 
-func (m *Machine) getRingInfo(ring int) (*RingInfo, bool) {
+func (m *Machine) getRingInfo(ring rings.RingID) (*RingInfo, bool) {
 	for _, ri := range m.Rings {
-		if ri.Ring == ring {
+		if ri.RingID() == ring {
 			return ri, ri.Enabled
 		}
 	}
@@ -172,13 +190,13 @@ func (m *Machine) getRingInfo(ring int) (*RingInfo, bool) {
 	return nil, false
 }
 
-func (m *Machine) applyRingInfo(ring int, new *RingInfo) error {
+func (m *Machine) applyRingInfo(ring rings.RingID, new *RingInfo) error {
 	cur, _ := m.getRingInfo(ring)
 	if cur == nil {
 		// first, append
 		m.debug().
 			WithField("node", m.Name).
-			WithField("ring", ring).
+			WithField("ring", MustWireguardInterfaceID(ring)).
 			Print("found")
 		m.Rings = append(m.Rings, new)
 		return nil
@@ -188,9 +206,11 @@ func (m *Machine) applyRingInfo(ring int, new *RingInfo) error {
 	return cur.Merge(new)
 }
 
-func (m *Machine) applyWireguardInterfaceConfig(ring int, data wireguard.InterfaceConfig) error {
+func (m *Machine) applyWireguardInterfaceConfig(ring rings.RingID,
+	data wireguard.InterfaceConfig) error {
+	//
 	ri := &RingInfo{
-		Ring:    ring,
+		Ring:    MustWireguardInterfaceID(ring),
 		Enabled: true,
 		Keys: wireguard.KeyPair{
 			PrivateKey: data.PrivateKey,
@@ -200,7 +220,9 @@ func (m *Machine) applyWireguardInterfaceConfig(ring int, data wireguard.Interfa
 	return m.applyRingInfo(ring, ri)
 }
 
-func (m *Machine) applyWireguardPeerConfig(ring int, pc wireguard.PeerConfig) error {
+func (m *Machine) applyWireguardPeerConfig(ring rings.RingID,
+	pc wireguard.PeerConfig) error {
+	//
 	peer, found := m.getPeerByName(pc.Endpoint.Name())
 	switch {
 	case !found:
@@ -212,7 +234,7 @@ func (m *Machine) applyWireguardPeerConfig(ring int, pc wireguard.PeerConfig) er
 	default:
 		// apply RingInfo
 		ri := &RingInfo{
-			Ring:    ring,
+			Ring:    MustWireguardInterfaceID(ring),
 			Enabled: true,
 			Keys: wireguard.KeyPair{
 				PublicKey: pc.PublicKey,
@@ -223,21 +245,29 @@ func (m *Machine) applyWireguardPeerConfig(ring int, pc wireguard.PeerConfig) er
 	}
 }
 
-func (m *Machine) applyZoneNodeID(zoneID, nodeID int) error {
+func (m *Machine) applyZoneNodeID(regionID rings.RegionID,
+	zoneID rings.ZoneID, nodeID rings.NodeID) error {
+	//
 	switch {
-	case zoneID == 0:
+	case !regionID.Valid():
+		return fmt.Errorf("invalid %s", "regionID")
+	case !zoneID.Valid():
 		return fmt.Errorf("invalid %s", "zoneID")
-	case nodeID == 0:
+	case !nodeID.Valid():
 		return fmt.Errorf("invalid %s", "nodeID")
 	case m.ID != nodeID:
-		return fmt.Errorf("invalid %s: %v ≠ %v", "zoneID", m.ID, nodeID)
+		return fmt.Errorf("invalid %s: %v ≠ %v", "nodeID", m.ID, nodeID)
 	case m.zone.ID != 0 && m.zone.ID != zoneID:
 		return fmt.Errorf("invalid %s: %v ≠ %v", "zoneID", m.zone.ID, zoneID)
-	case m.zone.ID == 0:
-		m.zone.ID = zoneID
-	}
+	case m.Region() != regionID:
+		return fmt.Errorf("invalid %s: %v ≠ %v", "regionID", m.Region(), regionID)
+	default:
+		if m.zone.ID == 0 {
+			m.zone.ID = zoneID
+		}
 
-	return nil
+		return nil
+	}
 }
 
 func (m *Machine) setRingDefaults(ri *RingInfo) error {
@@ -259,8 +289,13 @@ func (m *Machine) setRingDefaults(ri *RingInfo) error {
 
 // RemoveWireguardConfig deletes wgN.conf from the machine's
 // config directory.
-func (m *Machine) RemoveWireguardConfig(ring int) error {
-	err := m.RemoveFile("wg%v.conf", ring)
+func (m *Machine) RemoveWireguardConfig(ringID rings.RingID) error {
+	ring, err := AsWireguardInterfaceID(ringID)
+	if err != nil {
+		return err
+	}
+
+	err = m.RemoveFile(ring.ConfFile())
 	if os.IsNotExist(err) {
 		err = nil
 	}
@@ -268,7 +303,12 @@ func (m *Machine) RemoveWireguardConfig(ring int) error {
 	return err
 }
 
-func (m *Machine) createRingInfo(ring int, enabled bool) (*RingInfo, error) {
+func (m *Machine) createRingInfo(ringID rings.RingID, enabled bool) (*RingInfo, error) {
+	ring, err := AsWireguardInterfaceID(ringID)
+	if err != nil {
+		return nil, err
+	}
+
 	keys, err := wireguard.NewKeyPair()
 	if err != nil {
 		return nil, err
@@ -280,7 +320,7 @@ func (m *Machine) createRingInfo(ring int, enabled bool) (*RingInfo, error) {
 		Keys:    keys,
 	}
 
-	err = m.applyRingInfo(ring, ri)
+	err = m.applyRingInfo(ringID, ri)
 	if err != nil {
 		return nil, err
 	}

pkg/cluster/machine_scan.go

@@ -9,6 +9,8 @@ import (
 	"time"
 
 	"darvaza.org/core"
+
+	"git.jpi.io/amery/jpictl/pkg/rings"
 )
 
 // LookupNetIP uses the DNS Resolver to get the public addresses associated
@@ -37,8 +39,8 @@ func (m *Machine) init() error {
 		return core.Wrap(err, m.Name)
 	}
 
-	for i := 0; i < RingsCount; i++ {
-		if err := m.tryReadWireguardKeys(i); err != nil {
+	for _, ring := range Rings {
+		if err := m.tryReadWireguardKeys(ring.ID); err != nil {
 			return core.Wrap(err, m.Name)
 		}
 	}
@@ -65,18 +67,18 @@ func (m *Machine) setID() error {
 		return err
 	}
 
-	m.ID = int(id)
+	m.ID = rings.NodeID(id)
 	return nil
 }
 
 // scan is called once we know about all zones and machine names
 func (m *Machine) scan(_ *ScanOptions) error {
-	for i := 0; i < RingsCount; i++ {
-		if err := m.tryApplyWireguardConfig(i); err != nil {
+	for _, ring := range Rings {
+		if err := m.tryApplyWireguardConfig(ring.ID); err != nil {
 			m.error(err).
 				WithField("subsystem", "wireguard").
 				WithField("node", m.Name).
-				WithField("ring", i).
+				WithField("ring", MustWireguardInterfaceID(ring.ID)).
 				Print()
 			return err
 		}

pkg/cluster/regions.go

@@ -3,6 +3,8 @@ package cluster
 import (
 	"bytes"
 	"path/filepath"
+
+	"git.jpi.io/amery/jpictl/pkg/rings"
 )
 
 var (
@@ -24,8 +26,15 @@ type Region struct {
 	zones []*Zone
 
 	Name    string
-	Cluster *string  `json:",omitempty" yaml:",omitempty"`
-	Regions []string `json:",omitempty" yaml:",omitempty"`
+	ID      rings.RegionID `json:",omitempty" yaml:",omitempty"`
+	Cluster *string        `json:",omitempty" yaml:",omitempty"`
+	Regions []string       `json:",omitempty" yaml:",omitempty"`
+}
+
+// IsPrimary indicates the region is primary and corresponds
+// to a kubernetes cluster.
+func (r *Region) IsPrimary() bool {
+	return r != nil && r.Cluster != nil
 }
 
 // ForEachRegion calls a function for each Region of the cluster
@@ -92,6 +101,8 @@ func (m *Cluster) initRegions(_ *ScanOptions) error {
 	}
 
 	m.sortRegions()
+	m.scanRegionID()
+	m.computeZonesRegion()
 	return nil
 }
 
@@ -210,6 +221,92 @@ func (m *Cluster) finishRegion(r *Region) {
 	r.Regions = sub
 }
 
+// revive:disable:cognitive-complexity
+func (m *Cluster) scanRegionID() {
+	// revive:enable:cognitive-complexity
+	var max rings.RegionID
+	var missing bool
+
+	// check IDs
+	ids := make(map[rings.RegionID]bool)
+	fn := func(r *Region) bool {
+		var term bool
+
+		switch {
+		case !r.IsPrimary():
+			// secondary, no ID.
+			r.ID = 0
+		case !r.ID.Valid():
+			// primary without ID
+			missing = true
+		case ids[r.ID]:
+			// duplicate
+			m.error(nil).WithField("region", r.Name).Print("duplicate ID")
+			missing = true
+			r.ID = 0
+		default:
+			ids[r.ID] = true
+
+			if r.ID > max {
+				max = r.ID
+			}
+		}
+
+		return term
+	}
+	m.ForEachRegion(fn)
+
+	if missing {
+		// assign missing IDs
+		fn := func(r *Region) bool {
+			var term bool
+
+			switch {
+			case !r.IsPrimary():
+				// ignore secondary
+			case r.ID.Valid():
+				// already has an ID
+			default:
+				r.ID = max + 1
+				max = r.ID
+			}
+
+			return term
+		}
+
+		m.ForEachRegion(fn)
+	}
+}
+
+func (m *Cluster) computeZonesRegion() {
+	fn := func(r *Region, z *Zone) {
+		if z.region != nil {
+			m.error(nil).
+				WithField("zone", z.Name).
+				WithField("region", []string{
+					z.region.Name,
+					r.Name,
+				}).
+				Print("zone in two regions")
+		} else {
+			z.region = r
+		}
+	}
+
+	m.ForEachRegion(func(r *Region) bool {
+		var term bool
+
+		if r.IsPrimary() {
+			r.ForEachZone(func(z *Zone) bool {
+				fn(r, z)
+				return term
+			})
+		}
+
+		return term
+	})
+}
+
 func (m *Cluster) getRegion(name string) (*Region, bool) {
 	for i := range m.Regions {
 		r := &m.Regions[i]

pkg/cluster/rings.go

@@ -4,31 +4,86 @@ import (
 	"fmt"
 	"io/fs"
 	"net/netip"
+	"strconv"
 
+	"git.jpi.io/amery/jpictl/pkg/rings"
 	"git.jpi.io/amery/jpictl/pkg/wireguard"
 )
 
 const (
-	// MaxZoneID indicates the highest ID allowed for a Zone
-	MaxZoneID = 0xf
-	// MaxNodeID indicates the highest Machine ID allowed within a Zone
-	MaxNodeID = 0xff - 1
-	// RingsCount indicates how many wireguard rings we have
-	RingsCount = 2
 	// RingZeroPort is the port wireguard uses for ring0
 	RingZeroPort = 51800
 	// RingOnePort is the port wireguard uses for ring1
 	RingOnePort = 51810
 )
 
+// WireguardInterfaceID represents the number in the `wg%v`
+// interface name.
+type WireguardInterfaceID uint
+
+// AsWireguardInterfaceID returns the [WireguardInterfaceID] for
+// a valid [rings.RingID].
+func AsWireguardInterfaceID(ring rings.RingID) (WireguardInterfaceID, error) {
+	switch ring {
+	case rings.RingZeroID:
+		return 0, nil
+	case rings.RingOneID:
+		return 1, nil
+	default:
+		return 0, ErrInvalidRing(ring)
+	}
+}
+
+// MustWireguardInterfaceID returns the [WireguardInterfaceID] for
+// a valid [rings.RingID], and panics if it's not.
+func MustWireguardInterfaceID(ring rings.RingID) WireguardInterfaceID {
+	id, err := AsWireguardInterfaceID(ring)
+	if err != nil {
+		panic(err)
+	}
+	return id
+}
+
+// RingID tells the [rings.RingID] of the [WireguardInterfaceID].
+func (wi WireguardInterfaceID) RingID() rings.RingID {
+	return rings.RingID(wi + 1)
+}
+
+// PubFile returns "wgN.pub"
+func (wi WireguardInterfaceID) PubFile() string {
+	return fmt.Sprintf("wg%v.pub", wi)
+}
+
+// KeyFile returns "wgN.key"
+func (wi WireguardInterfaceID) KeyFile() string {
+	return fmt.Sprintf("wg%v.key", wi)
+}
+
+// ConfFile returns "wgN.conf"
+func (wi WireguardInterfaceID) ConfFile() string {
+	return fmt.Sprintf("wg%v.conf", wi)
+}
+
+// Files returns all wgN.ext file names.
+func (wi WireguardInterfaceID) Files() (keyFile, pubFile, confFile string) {
+	prefix := "wg" + strconv.Itoa(int(wi))
+
+	return prefix + ".key", prefix + ".pub", prefix + ".conf"
+}
+
 // RingInfo contains represents the Wireguard endpoint details
 // for a Machine on a particular ring
 type RingInfo struct {
-	Ring    int
+	Ring    WireguardInterfaceID
 	Enabled bool
 	Keys    wireguard.KeyPair
 }
 
+// RingID returns the [rings.RingID] for this [RingInfo].
+func (ri *RingInfo) RingID() rings.RingID {
+	return rings.RingID(ri.Ring + 1)
+}
+
 // Merge attempts to combine two RingInfo structs
 func (ri *RingInfo) Merge(alter *RingInfo) error {
 	switch {
@@ -54,7 +109,7 @@ func (ri *RingInfo) unsafeMerge(alter *RingInfo) error {
 		ri.Enabled = true
 	}
 
-	// fill the gaps on our keypair
+	// fill the gaps on our key pair
 	if ri.Keys.PrivateKey.IsZero() {
 		ri.Keys.PrivateKey = alter.Keys.PrivateKey
 	}
@@ -79,108 +134,34 @@ func canMergeKeyPairs(p1, p2 wireguard.KeyPair) bool {
 // RingAddressEncoder provides encoder/decoder access for a particular
 // Wireguard ring
 type RingAddressEncoder struct {
-	ID     int
+	ID     rings.RingID
 	Port   uint16
-	Encode func(zoneID, nodeID int) (netip.Addr, bool)
-	Decode func(addr netip.Addr) (zoneID, nodeID int, ok bool)
+	Encode func(rings.RegionID, rings.ZoneID, rings.NodeID) (netip.Addr, error)
+	Decode func(addr netip.Addr) (rings.RegionID, rings.ZoneID, rings.NodeID, bool)
 }
 
 var (
 	// RingZero is a wg0 address encoder/decoder
 	RingZero = RingAddressEncoder{
-		ID:     0,
+		ID:     rings.RingZeroID,
 		Port:   RingZeroPort,
-		Decode: ParseRingZeroAddress,
-		Encode: RingZeroAddress,
+		Decode: rings.DecodeRingZeroAddress,
+		Encode: rings.RingZeroAddress,
 	}
 	// RingOne is a wg1 address encoder/decoder
 	RingOne = RingAddressEncoder{
-		ID:     1,
+		ID:     rings.RingOneID,
 		Port:   RingOnePort,
-		Decode: ParseRingOneAddress,
-		Encode: RingOneAddress,
+		Decode: rings.DecodeRingOneAddress,
+		Encode: rings.RingOneAddress,
 	}
 	// Rings provides indexed access to the ring address encoders
-	Rings = [RingsCount]RingAddressEncoder{
+	Rings = []RingAddressEncoder{
 		RingZero,
 		RingOne,
 	}
 )
 
-// ValidZoneID checks if the given zoneID is a valid 4 bit zone number.
-//
-// 0 is reserved, and only allowed when composing CIDRs.
-func ValidZoneID(zoneID int) bool {
-	switch {
-	case zoneID < 0 || zoneID > MaxZoneID:
-		return false
-	default:
-		return true
-	}
-}
-
-// ValidNodeID checks if the given nodeID is a valid 8 bit number.
-// nodeID is unique within a Zone.
-// 0 is reserved, and only allowed when composing CIDRs.
-func ValidNodeID(nodeID int) bool {
-	switch {
-	case nodeID < 0 || nodeID > MaxNodeID:
-		return false
-	default:
-		return true
-	}
-}
-
-// ParseRingZeroAddress extracts zone and node ID from a wg0 [netip.Addr]
-// wg0 addresses are of the form `10.0.{{zoneID}}.{{nodeID}}`
-func ParseRingZeroAddress(addr netip.Addr) (zoneID int, nodeID int, ok bool) {
-	if addr.IsValid() {
-		a4 := addr.As4()
-
-		if a4[0] == 10 && a4[1] == 0 {
-			return int(a4[2]), int(a4[3]), true
-		}
-	}
-	return 0, 0, false
-}
-
-// RingZeroAddress returns a wg0 IP address
-func RingZeroAddress(zoneID, nodeID int) (netip.Addr, bool) {
-	switch {
-	case !ValidZoneID(zoneID) || !ValidNodeID(nodeID):
-		return netip.Addr{}, false
-	default:
-		a4 := [4]uint8{10, 0, uint8(zoneID), uint8(nodeID)}
-		return netip.AddrFrom4(a4), true
-	}
-}
-
-// ParseRingOneAddress extracts zone and node ID from a wg1 [netip.Addr]
-// wg1 addresses are of the form `10.{{zoneID << 4}}.{{nodeID}}`
-func ParseRingOneAddress(addr netip.Addr) (zoneID int, nodeID int, ok bool) {
-	if addr.IsValid() {
-		a4 := addr.As4()
-
-		if a4[0] == 10 && a4[2] == 0 {
-			zoneID = int(a4[1] >> 4)
-			nodeID = int(a4[3])
-			return zoneID, nodeID, true
-		}
-	}
-	return 0, 0, false
-}
-
-// RingOneAddress returns a wg1 IP address
-func RingOneAddress(zoneID, nodeID int) (netip.Addr, bool) {
-	switch {
-	case !ValidZoneID(zoneID) || !ValidNodeID(nodeID):
-		return netip.Addr{}, false
-	default:
-		a4 := [4]uint8{10, uint8(zoneID << 4), 0, uint8(nodeID)}
-		return netip.AddrFrom4(a4), true
-	}
-}
-
 var (
 	_ MachineIterator = (*Ring)(nil)
 	_ ZoneIterator    = (*Ring)(nil)
@@ -203,14 +184,15 @@ func (r *Ring) AddPeer(p *Machine) bool {
 
 	nodeID := p.ID
 	zoneID := p.Zone()
-	addr, _ := r.Encode(zoneID, nodeID)
+	regionID := p.Region()
+	addr, _ := r.Encode(regionID, zoneID, nodeID)
 
 	rp := &RingPeer{
 		Node:       p,
 		Address:    addr,
 		PrivateKey: ri.Keys.PrivateKey,
 		PeerConfig: wireguard.PeerConfig{
-			Name:      fmt.Sprintf("%s-%v", p.Name, r.ID),
+			Name:      fmt.Sprintf("%s-%v", p.Name, ri.Ring),
 			PublicKey: ri.Keys.PublicKey,
 			Endpoint: wireguard.EndpointAddress{
 				Host: p.FullName(),
@@ -233,27 +215,27 @@ func (r *Ring) AddPeer(p *Machine) bool {
 }
 
 func (r *Ring) setRingZeroAllowedIPs(rp *RingPeer) {
-	zoneID, _, _ := r.Decode(rp.Address)
+	regionID, zoneID, _, _ := r.Decode(rp.Address)
 
 	// everyone on ring0 is a gateway to ring1
-	addr, _ := RingOneAddress(zoneID, 0)
-	rp.AllowCIDR(addr, 12)
+	subnet, _ := rings.RingOnePrefix(regionID, zoneID)
+	rp.AllowSubnet(subnet)
 
 	// peer
 	rp.AllowCIDR(rp.Address, 32)
 }
 
 func (r *Ring) setRingOneGatewayAllowedIPs(rp *RingPeer) {
-	zoneID, _, _ := r.Decode(rp.Address)
+	regionID, zoneID, _, _ := r.Decode(rp.Address)
 
 	// peer
 	rp.AllowCIDR(rp.Address, 32)
 
 	// ring1 gateways connect to all other ring1 networks
 	r.ForEachZone(func(z *Zone) bool {
-		if z.ID != zoneID {
-			addr, _ := r.Encode(z.ID, 0)
-			rp.AllowCIDR(addr, 12)
+		if !z.Is(regionID, zoneID) {
+			subnet := z.RingOnePrefix()
+			rp.AllowSubnet(subnet)
 		}
 		return false
 	})
@@ -262,7 +244,7 @@ func (r *Ring) setRingOneGatewayAllowedIPs(rp *RingPeer) {
 	r.ForEachZone(func(z *Zone) bool {
 		z.ForEachMachine(func(p *Machine) bool {
 			if p.IsGateway() {
-				addr, _ := RingZeroAddress(z.ID, p.ID)
+				addr, _ := p.RingZeroAddress()
 				rp.AllowCIDR(addr, 32)
 			}
 			return false
@@ -329,15 +311,29 @@ type RingPeer struct {
 
 // AllowCIDR allows an IP range via this peer
 func (rp *RingPeer) AllowCIDR(addr netip.Addr, bits int) {
-	cidr := netip.PrefixFrom(addr, bits)
-	rp.PeerConfig.AllowedIPs = append(rp.PeerConfig.AllowedIPs, cidr)
+	rp.AllowSubnet(netip.PrefixFrom(addr, bits))
+}
+
+// AllowSubnet allows an IP range via this peer
+func (rp *RingPeer) AllowSubnet(subnet netip.Prefix) {
+	rp.PeerConfig.AllowedIPs = append(rp.PeerConfig.AllowedIPs, subnet)
 }
 
 // NewRing composes a new Ring for Wireguard setup
-func NewRing(z ZoneIterator, m MachineIterator, ring int) (*Ring, error) {
-	r := &Ring{
-		RingAddressEncoder: Rings[ring],
-		ZoneIterator:       z,
+func NewRing(z ZoneIterator, m MachineIterator, ringID rings.RingID) (*Ring, error) {
+	var r *Ring
+	for _, ring := range Rings {
+		if ringID == ring.ID {
+			r = &Ring{
+				RingAddressEncoder: ring,
+				ZoneIterator:       z,
+			}
+			break
+		}
+	}
+
+	if r == nil {
+		return nil, ErrInvalidRing(ringID)
 	}
 
 	m.ForEachMachine(func(p *Machine) bool {

pkg/cluster/sync.go

@@ -35,13 +35,13 @@ func (m *Cluster) SyncMkdirAll() error {
 func (m *Cluster) SyncAllWireguard() error {
 	var err error
 
-	for ring := 0; ring < RingsCount; ring++ {
-		err = m.WriteWireguardKeys(ring)
+	for _, ring := range Rings {
+		err = m.WriteWireguardKeys(ring.ID)
 		if err != nil {
 			return err
 		}
 
-		err = m.SyncWireguardConfig(ring)
+		err = m.SyncWireguardConfig(ring.ID)
 		if err != nil {
 			return err
 		}

pkg/cluster/wireguard.go

@@ -3,6 +3,8 @@ package cluster
 import (
 	"io/fs"
 	"os"
+
+	"git.jpi.io/amery/jpictl/pkg/rings"
 )
 
 var (
@@ -26,22 +28,22 @@ var (
 // A WireguardConfigPruner deletes wgN.conf on all machines under
 // its scope with the specified ring disabled
 type WireguardConfigPruner interface {
-	PruneWireguardConfig(ring int) error
+	PruneWireguardConfig(ring rings.RingID) error
 }
 
 // PruneWireguardConfig removes wgN.conf files of machines with
 // the corresponding ring disabled on all zones
-func (m *Cluster) PruneWireguardConfig(ring int) error {
+func (m *Cluster) PruneWireguardConfig(ring rings.RingID) error {
 	return pruneWireguardConfig(m, ring)
 }
 
 // PruneWireguardConfig removes wgN.conf files of machines with
 // the corresponding ring disabled.
-func (z *Zone) PruneWireguardConfig(ring int) error {
+func (z *Zone) PruneWireguardConfig(ring rings.RingID) error {
 	return pruneWireguardConfig(z, ring)
 }
 
-func pruneWireguardConfig(m MachineIterator, ring int) error {
+func pruneWireguardConfig(m MachineIterator, ring rings.RingID) error {
 	var err error
 
 	m.ForEachMachine(func(p *Machine) bool {
@@ -59,7 +61,7 @@ func pruneWireguardConfig(m MachineIterator, ring int) error {
 
 // PruneWireguardConfig deletes the wgN.conf file if its
 // presence on the ring is disabled
-func (m *Machine) PruneWireguardConfig(ring int) error {
+func (m *Machine) PruneWireguardConfig(ring rings.RingID) error {
 	_, ok := m.getRingInfo(ring)
 	if !ok {
 		return m.RemoveWireguardConfig(ring)
@@ -71,16 +73,16 @@ func (m *Machine) PruneWireguardConfig(ring int) error {
 // A WireguardConfigWriter rewrites all wgN.conf on all machines under
 // its scope attached to that ring
 type WireguardConfigWriter interface {
-	WriteWireguardConfig(ring int) error
+	WriteWireguardConfig(ring rings.RingID) error
 }
 
 // WriteWireguardConfig rewrites all wgN.conf on all machines
 // attached to that ring
-func (m *Cluster) WriteWireguardConfig(ring int) error {
+func (m *Cluster) WriteWireguardConfig(ring rings.RingID) error {
 	switch ring {
-	case 0:
+	case rings.RingZeroID:
 		return writeWireguardConfig(m, m, ring)
-	case 1:
+	case rings.RingOneID:
 		var err error
 		m.ForEachZone(func(z *Zone) bool {
 			err = writeWireguardConfig(m, z, ring)
@@ -88,24 +90,24 @@ func (m *Cluster) WriteWireguardConfig(ring int) error {
 		})
 		return err
 	default:
-		return fs.ErrInvalid
+		return ErrInvalidRing(ring)
 	}
 }
 
 // WriteWireguardConfig rewrites all wgN.conf on all machines
 // on the Zone attached to that ring
-func (z *Zone) WriteWireguardConfig(ring int) error {
+func (z *Zone) WriteWireguardConfig(ring rings.RingID) error {
 	switch ring {
-	case 0:
+	case rings.RingZeroID:
 		return writeWireguardConfig(z.zones, z.zones, ring)
-	case 1:
+	case rings.RingOneID:
 		return writeWireguardConfig(z.zones, z, ring)
 	default:
-		return fs.ErrInvalid
+		return ErrInvalidRing(ring)
 	}
 }
 
-func writeWireguardConfig(z ZoneIterator, m MachineIterator, ring int) error {
+func writeWireguardConfig(z ZoneIterator, m MachineIterator, ring rings.RingID) error {
 	r, err := NewRing(z, m, ring)
 	if err != nil {
 		return err
@@ -121,7 +123,7 @@ func writeWireguardConfig(z ZoneIterator, m MachineIterator, ring int) error {
 
 // WriteWireguardConfig rewrites the wgN.conf file of this Machine
 // if enabled
-func (m *Machine) WriteWireguardConfig(ring int) error {
+func (m *Machine) WriteWireguardConfig(ring rings.RingID) error {
 	r, err := NewRing(m.zone.zones, m.zone, ring)
 	if err != nil {
 		return err
@@ -131,12 +133,17 @@ func (m *Machine) WriteWireguardConfig(ring int) error {
 }
 
 func (m *Machine) writeWireguardRingConfig(r *Ring) error {
+	ring, err := AsWireguardInterfaceID(r.ID)
+	if err != nil {
+		return err
+	}
+
 	wg, err := r.ExportConfig(m)
 	if err != nil {
 		return nil
 	}
 
-	f, err := m.CreateTruncFile("wg%v.conf", r.ID)
+	f, err := m.CreateTruncFile(ring.ConfFile())
 	if err != nil {
 		return err
 	}
@@ -149,16 +156,16 @@ func (m *Machine) writeWireguardRingConfig(r *Ring) error {
 // A WireguardConfigSyncer updates all wgN.conf on all machines under
 // its scope reflecting the state of the ring
 type WireguardConfigSyncer interface {
-	SyncWireguardConfig(ring int) error
+	SyncWireguardConfig(ring rings.RingID) error
 }
 
 // SyncWireguardConfig updates all wgN.conf files for the specified
 // ring
-func (m *Cluster) SyncWireguardConfig(ring int) error {
+func (m *Cluster) SyncWireguardConfig(ring rings.RingID) error {
 	switch ring {
-	case 0:
+	case rings.RingZeroID:
 		return syncWireguardConfig(m, m, ring)
-	case 1:
+	case rings.RingOneID:
 		var err error
 		m.ForEachZone(func(z *Zone) bool {
 			err = syncWireguardConfig(m, z, ring)
@@ -166,24 +173,24 @@ func (m *Cluster) SyncWireguardConfig(ring int) error {
 		})
 		return err
 	default:
-		return fs.ErrInvalid
+		return ErrInvalidRing(ring)
 	}
 }
 
 // SyncWireguardConfig updates all wgN.conf files for the specified
 // ring
-func (z *Zone) SyncWireguardConfig(ring int) error {
+func (z *Zone) SyncWireguardConfig(ring rings.RingID) error {
 	switch ring {
-	case 0:
+	case rings.RingZeroID:
 		return syncWireguardConfig(z.zones, z.zones, ring)
-	case 1:
+	case rings.RingOneID:
 		return syncWireguardConfig(z.zones, z, ring)
 	default:
-		return fs.ErrInvalid
+		return ErrInvalidRing(ring)
 	}
 }
 
-func syncWireguardConfig(z ZoneIterator, m MachineIterator, ring int) error {
+func syncWireguardConfig(z ZoneIterator, m MachineIterator, ring rings.RingID) error {
 	r, err := NewRing(z, m, ring)
 	if err != nil {
 		return err
@@ -203,27 +210,27 @@ func syncWireguardConfig(z ZoneIterator, m MachineIterator, ring int) error {
 
 // SyncWireguardConfig updates all wgN.conf files for the specified
 // ring
-func (m *Machine) SyncWireguardConfig(ring int) error {
+func (m *Machine) SyncWireguardConfig(ring rings.RingID) error {
 	return m.zone.SyncWireguardConfig(ring)
 }
 
 // A WireguardKeysWriter writes the Wireguard Keys for all machines
 // under its scope for the specified ring
 type WireguardKeysWriter interface {
-	WriteWireguardKeys(ring int) error
+	WriteWireguardKeys(ring rings.RingID) error
 }
 
 // WriteWireguardKeys rewrites all wgN.{key,pub} files
-func (m *Cluster) WriteWireguardKeys(ring int) error {
+func (m *Cluster) WriteWireguardKeys(ring rings.RingID) error {
 	return writeWireguardKeys(m, ring)
 }
 
 // WriteWireguardKeys rewrites all wgN.{key,pub} files on this zone
-func (z *Zone) WriteWireguardKeys(ring int) error {
+func (z *Zone) WriteWireguardKeys(ring rings.RingID) error {
 	return writeWireguardKeys(z, ring)
 }
 
-func writeWireguardKeys(m MachineIterator, ring int) error {
+func writeWireguardKeys(m MachineIterator, ring rings.RingID) error {
 	var err error
 
 	m.ForEachMachine(func(p *Machine) bool {
@@ -240,12 +247,12 @@ func writeWireguardKeys(m MachineIterator, ring int) error {
 }
 
 // WriteWireguardKeys writes the wgN.key/wgN.pub files
-func (m *Machine) WriteWireguardKeys(ring int) error {
+func (m *Machine) WriteWireguardKeys(ringID rings.RingID) error {
 	var err error
 	var key, pub string
 	var ri *RingInfo
 
-	ri, _ = m.getRingInfo(ring)
+	ri, _ = m.getRingInfo(ringID)
 	if ri != nil {
 		key = ri.Keys.PrivateKey.String()
 		pub = ri.Keys.PublicKey.String()
@@ -258,12 +265,13 @@ func (m *Machine) WriteWireguardKeys(ring int) error {
 		pub = ri.Keys.PrivateKey.Public().String()
 	}
 
-	err = m.WriteStringFile(key+"\n", "wg%v.key", ring)
+	keyFile, pubFile, _ := ri.Ring.Files()
+	err = m.WriteStringFile(key+"\n", keyFile)
 	if err != nil {
 		return err
 	}
 
-	err = m.WriteStringFile(pub+"\n", "wg%v.pub", ring)
+	err = m.WriteStringFile(pub+"\n", pubFile)
 	if err != nil {
 		return err
 	}

pkg/cluster/zones.go

@@ -2,6 +2,8 @@ package cluster
 
 import (
 	"io/fs"
+
+	"git.jpi.io/amery/jpictl/pkg/rings"
 )
 
 var (
@@ -17,9 +19,10 @@ type ZoneIterator interface {
 // affinity.
 type Zone struct {
 	zones  *Cluster
+	region *Region
 	logger `json:"-" yaml:"-"`
 
-	ID      int
+	ID      rings.ZoneID
 	Name    string
 	Regions []string `json:",omitempty" yaml:",omitempty"`
 
@@ -31,7 +34,7 @@ func (z *Zone) String() string {
 }
 
 // SetGateway configures a machine to be the zone's ring0 gateway
-func (z *Zone) SetGateway(gatewayID int, enabled bool) error {
+func (z *Zone) SetGateway(gatewayID rings.NodeID, enabled bool) error {
 	var err error
 	var found bool
 
@@ -56,8 +59,8 @@ func (z *Zone) SetGateway(gatewayID int, enabled bool) error {
 }
 
 // GatewayIDs returns the list of IDs of machines that act as ring0 gateways
-func (z *Zone) GatewayIDs() ([]int, int) {
-	var out []int
+func (z *Zone) GatewayIDs() ([]rings.NodeID, int) {
+	var out []rings.NodeID
 	z.ForEachMachine(func(p *Machine) bool {
 		if p.IsGateway() {
 			out = append(out, p.ID)
@@ -67,3 +70,38 @@ func (z *Zone) GatewayIDs() ([]int, int) {
 
 	return out, len(out)
 }
+
+// RegionID returns the primary [Region] of a [Zone].
+func (z *Zone) RegionID() rings.RegionID {
+	if z != nil && z.region != nil {
+		return z.region.ID
+	}
+	return 0
+}
+
+// Is checks if the given [rings.RegionID] and [rings.ZoneID] match
+// the [Zone].
+func (z *Zone) Is(regionID rings.RegionID, zoneID rings.ZoneID) bool {
+	switch {
+	case z.ID != zoneID:
+		return false
+	case z.RegionID() != regionID:
+		return false
+	default:
+		return true
+	}
+}
+
+// Eq checks if two [Zone]s are the same.
+func (z *Zone) Eq(z2 *Zone) bool {
+	switch {
+	case z == nil, z2 == nil:
+		return false
+	case z.ID != z2.ID:
+		return false
+	case z.RegionID() != z2.RegionID():
+		return false
+	default:
+		return true
+	}
+}

pkg/rings/decode.go

@@ -0,0 +1,122 @@
+package rings
+
+import (
+	"net/netip"
+)
+
+// DecodeAddress extracts ring address fields from a given 10.0.0.0/8
+// address.
+//
+// revive:disable:function-result-limit
+func DecodeAddress[T ~uint | NodeID](addr netip.Addr) (RingID, RegionID, ZoneID, T) {
+	// revive:enable:function-result-limit
+	if addr.IsValid() {
+		if addr.Is4In6() {
+			addr = addr.Unmap()
+		}
+
+		if addr.Is4() {
+			a4 := addr.As4()
+			return unsafeDecodeAddress[T](a4[0], a4[1], a4[2], a4[3])
+		}
+	}
+
+	return UnspecifiedRingID, 0, 0, 0
+}
+
+// revive:disable:function-result-limit
+func unsafeDecodeAddress[T ~uint | NodeID](a, b, c, d byte) (RingID, RegionID, ZoneID, T) {
+	// revive:enable:function-result-limit
+	switch {
+	case a != 10:
+		return UnspecifiedRingID, 0, 0, 0
+	case b == 0x00:
+		// 10.00.RZ.dd
+		k := RingZeroID
+		r := RegionID(c >> 4)
+		z := ZoneID(c & 0xf)
+		n := T(d)
+
+		return k, r, z, n
+	case b&0xf0 != 0:
+		// 10.Rb.cc.dd
+		k := RingThreeID
+		r := RegionID(b >> 4)
+
+		n2 := T(b & 0x0f)
+		n1 := T(c)
+		n0 := T(d)
+		n := n0 + n1<<8 + n2<<16
+
+		return k, r, 0, n
+	case c&0xf0 != 0:
+		// 10.0R.Zc.dd
+		k := RingOneID
+		r := RegionID(b)
+		z := ZoneID(c >> 4)
+
+		n1 := T(c & 0x0f)
+		n0 := T(d)
+		n := n0 + n1<<8
+
+		return k, r, z, n
+	default:
+		// 10.0R.0c.dd
+		k := RingTwoID
+		r := RegionID(b)
+
+		n1 := T(c & 0x0f)
+		n0 := T(d)
+		n := n0 + n1<<8
+
+		return k, r, 0, n
+	}
+}
+
+// DecodeRingZeroAddress attempts to extract region, zone and node identifiers
+// from a given ring 0 address.
+//
+// revive:disable:function-result-limit
+func DecodeRingZeroAddress(addr netip.Addr) (RegionID, ZoneID, NodeID, bool) {
+	// revive:enable:function-result-limit
+	k, r, z, n := DecodeAddress[NodeID](addr)
+	if k == RingZeroID {
+		return r, z, n, true
+	}
+
+	return 0, 0, 0, false
+}
+
+// DecodeRingOneAddress attempts to extract region, zone and node identifiers
+// from a given ring 1 address.
+//
+// revive:disable:function-result-limit
+func DecodeRingOneAddress(addr netip.Addr) (RegionID, ZoneID, NodeID, bool) {
+	// revive:enable:function-result-limit
+	k, r, z, n := DecodeAddress[NodeID](addr)
+	if k == RingOneID {
+		return r, z, n, true
+	}
+
+	return 0, 0, 0, false
+}
+
+// DecodeRingTwoAddress attempts to extract region and unique identifier for
+// a kubernetes service from a given ring 2 address.
+func DecodeRingTwoAddress(addr netip.Addr) (RegionID, uint, bool) {
+	k, r, _, n := DecodeAddress[uint](addr)
+	if k == RingTwoID {
+		return r, n, true
+	}
+	return 0, 0, false
+}
+
+// DecodeRingThreeAddress attempts to extract region and unique identifier for
+// a kubernetes pod from a given ring 3 address.
+func DecodeRingThreeAddress(addr netip.Addr) (RegionID, uint, bool) {
+	k, r, _, n := DecodeAddress[uint](addr)
+	if k == RingThreeID {
+		return r, n, true
+	}
+	return 0, 0, false
+}

pkg/rings/decode_test.go

@@ -0,0 +1,53 @@
+package rings
+
+import (
+	"fmt"
+	"net/netip"
+	"testing"
+)
+
+func TestDecodeRingZeroAddress(t *testing.T) {
+	RZNDecodeTest(t, "DecodeRingZeroAddress", DecodeRingZeroAddress, []RZNDecodeTestCase{
+		{1, 1, 50, MustParseAddr("10.0.17.50"), true},
+		{1, 2, 50, MustParseAddr("10.0.18.50"), true},
+		{2, 3, 1, MustParseAddr("10.0.35.1"), true},
+	})
+}
+
+func TesDecodetRingOneAddress(t *testing.T) {
+	RZNDecodeTest(t, "DecodeRingOneAddress", DecodeRingOneAddress, []RZNDecodeTestCase{
+		{1, 1, 50, MustParseAddr("10.1.16.50"), true},
+		{1, 2, 50, MustParseAddr("10.1.32.50"), true},
+		{2, 3, 300, MustParseAddr("10.2.49.44"), true},
+	})
+}
+
+type RZNDecodeTestCase struct {
+	region RegionID
+	zone   ZoneID
+	node   NodeID
+	addr   netip.Addr
+	ok     bool
+}
+
+func RZNDecodeTest(t *testing.T,
+	fnName string, fn func(netip.Addr) (RegionID, ZoneID, NodeID, bool),
+	cases []RZNDecodeTestCase) {
+	//
+	for i, tc := range cases {
+		s := fmt.Sprintf("%s(%q)", fnName, tc.addr)
+
+		r, z, n, ok := fn(tc.addr)
+
+		switch {
+		case ok != tc.ok, r != tc.region, z != tc.zone, n != tc.node:
+			t.Errorf("ERROR: [%v/%v]: %s → %v %v %v %v (expected %v %v %v %v)",
+				i, len(cases), s,
+				r, z, n, ok,
+				tc.region, tc.zone, tc.node, tc.ok)
+		default:
+			t.Logf("[%v/%v]: %s → %v %v %v %v", i, len(cases), s,
+				r, z, n, ok)
+		}
+	}
+}

pkg/rings/rings.go

@@ -3,21 +3,34 @@
 package rings
 
 import (
+	"fmt"
+	"strconv"
 	"syscall"
 
 	"darvaza.org/core"
 )
 
 const (
+	// UnspecifiedRingID is the zero value of RingID and not considered
+	// valid.
+	UnspecifiedRingID RingID = iota
+	RingZeroID               // RingZeroID is the RingID for RingZero (backbone)
+	RingOneID                // RingOneID is the RingID for RingOne (local zone)
+	RingTwoID                // RingTwoID is the RingID for RingTwo (region services)
+	RingThreeID              // RingThreeID is the RingID for RingThree (region cluster pods)
+
+	// RingMax indicates the highest [Ring] identifier
+	RingMax = RingThreeID
+
 	// RegionMax indicates the highest number that can be used for a [RegionID].
 	RegionMax = (1 << 4) - 1
 	// ZoneMax indicates the highest number that can be used for a [ZoneID].
 	ZoneMax = (1 << 4) - 1
 	// NodeMax indicates the highest number that can be used for a [NodeID].
-	NodeMax = (1 << 12) - 1
+	NodeMax = (1 << 12) - 2
 	// NodeZeroMax indicates the highest number that can be used for a [NodeID]
 	// when its a gateway connected to Ring 0 (backbone).
-	NodeZeroMax = (1 << 8) - 1
+	NodeZeroMax = (1 << 8) - 2
 
 	// RingZeroBits indicates the size of the prefix on the ring 0 (backbone) network.
 	RingZeroBits = 16
@@ -31,18 +44,41 @@ const (
 	RingThreeBits = 12
 )
 
+// RingID identifies a Ring
+type RingID int
+
+// Valid tells a [RingID] is within the valid range.
+func (n RingID) Valid() bool { return n > 0 && n <= RingMax }
+
+func (n RingID) String() string {
+	return idString(n)
+}
+
+// A Ring identifies what ring an address belongs to
+type Ring interface {
+	ID() RingID
+}
+
 // RegionID is the identifier of a region, valid between 1 and [RegionMax].
 type RegionID int
 
 // Valid tells a [RegionID] is within the valid range.
 func (n RegionID) Valid() bool { return n > 0 && n <= RegionMax }
 
+func (n RegionID) String() string {
+	return idString(n)
+}
+
 // ZoneID is the identifier of a zone within a region, valid between 1 and [ZoneMax].
 type ZoneID int
 
 // Valid tells a [ZoneID] is within the valid range.
 func (n ZoneID) Valid() bool { return n > 0 && n <= ZoneMax }
 
+func (n ZoneID) String() string {
+	return idString(n)
+}
+
 // NodeID is the identifier of a machine within a zone of a region, valid between
 // 1 and [NodeMax], but between 1 and [NodeZeroMax] if it will be a zone gateway.
 type NodeID int
@@ -53,8 +89,28 @@ func (n NodeID) Valid() bool { return n > 0 && n <= NodeMax }
 // ValidZero tells a [NodeID] is within the valid range for a gateway.
 func (n NodeID) ValidZero() bool { return n > 0 && n <= NodeZeroMax }
 
+func (n NodeID) String() string {
+	return idString(n)
+}
+
 // ErrOutOfRange is an error indicating the value of a field
 // is out of range.
 func ErrOutOfRange[T ~int | ~uint32](value T, field string) error {
 	return core.Wrap(syscall.EINVAL, "%s out of range (%v)", field, value)
 }
+
+type intID interface {
+	~int
+	Valid() bool
+}
+
+func idString[T intID](p T) string {
+	switch {
+	case p == 0:
+		return "unspecified"
+	case p.Valid():
+		return strconv.Itoa(int(p))
+	default:
+		return fmt.Sprintf("invalid (%v)", int(p))
+	}
+}