From 378bab2f968c2878ca7e4bfa7f4f34b4f0a88d97 Mon Sep 17 00:00:00 2001 From: Alejandro Mery Date: Sat, 25 May 2024 21:15:50 +0000 Subject: [PATCH 1/6] rings: introduce RegionID, ZoneID and NodeID and a Valid() method to check if their value is within the valid range. Signed-off-by: Alejandro Mery --- pkg/rings/rings.go | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/pkg/rings/rings.go b/pkg/rings/rings.go index 01f2ce7..0f1e8a4 100644 --- a/pkg/rings/rings.go +++ b/pkg/rings/rings.go @@ -1,3 +1,37 @@ // Package rings provides logic to work with the four rings // of a cluster package rings + +const ( + // 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 + // 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 +) + +// 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 } + +// 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 } + +// 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 + +// Valid tells a [NodeID] is within the valid range. +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 } -- 2.17.1 From 52e1195139fa835c14832ded675ee56a9f543569 Mon Sep 17 00:00:00 2001 From: Alejandro Mery Date: Sat, 25 May 2024 21:21:31 +0000 Subject: [PATCH 2/6] rings: introduce generic ErrOutOfRange() factory Signed-off-by: Alejandro Mery --- pkg/rings/rings.go | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/pkg/rings/rings.go b/pkg/rings/rings.go index 0f1e8a4..6569105 100644 --- a/pkg/rings/rings.go +++ b/pkg/rings/rings.go @@ -2,6 +2,12 @@ // of a cluster package rings +import ( + "syscall" + + "darvaza.org/core" +) + const ( // RegionMax indicates the highest number that can be used for a [RegionID]. RegionMax = (1 << 4) - 1 @@ -35,3 +41,9 @@ 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 } + +// 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) +} -- 2.17.1 From 394a84c3ab11a8d1f5b0ab886e594a4cb2a6de00 Mon Sep 17 00:00:00 2001 From: Alejandro Mery Date: Sat, 25 May 2024 21:22:33 +0000 Subject: [PATCH 3/6] rings: RingOnePrefix()/RingOneAddress() Ring one designates the (virtual) local network of a zone within a region. Signed-off-by: Alejandro Mery --- pkg/rings/encode.go | 51 +++++++++++++++++++++++++++++++++++++ pkg/rings/encode_test.go | 54 ++++++++++++++++++++++++++++++++++++++++ pkg/rings/rings.go | 3 +++ 3 files changed, 108 insertions(+) create mode 100644 pkg/rings/encode.go create mode 100644 pkg/rings/encode_test.go diff --git a/pkg/rings/encode.go b/pkg/rings/encode.go new file mode 100644 index 0000000..41d1062 --- /dev/null +++ b/pkg/rings/encode.go @@ -0,0 +1,51 @@ +package rings + +import "net/netip" + +// RingOnePrefix represents a (virtual) local network of a zone. +// +// Ring 1 is `10.(region_id).(zone_id << 4).(node_id)/20` network +// grouped under what would be Ring 2 for region_id 0. +// There are 12 bits worth of nodes but nodes under 255 are special +// as they also get a slot on Ring 0. +func RingOnePrefix(region RegionID, zone ZoneID) (cidr netip.Prefix, err error) { + switch { + case !region.Valid(): + err = ErrOutOfRange(region, "region") + case !zone.Valid(): + err = ErrOutOfRange(zone, "zone") + default: + addr := unsafeRingOneAddress(region, zone, 0) + cidr = netip.PrefixFrom(addr, RingOneBits) + } + return cidr, err +} + +// RingOneAddress returns a Ring 1 address for a particular node. +// +// A ring 1 address is `10.(region_id).(zone_id << 4).(node_id)/20` +// but the node_id can take up to 12 bits. +func RingOneAddress(region RegionID, zone ZoneID, node NodeID) (addr netip.Addr, err error) { + switch { + case !region.Valid(): + err = ErrOutOfRange(region, "region") + case !zone.Valid(): + err = ErrOutOfRange(zone, "zone") + case !node.Valid(): + err = ErrOutOfRange(node, "node") + default: + addr = unsafeRingOneAddress(region, zone, node) + } + return addr, err +} + +func unsafeRingOneAddress(region RegionID, zone ZoneID, node NodeID) netip.Addr { + r := uint(region) + z := uint(zone) + n := uint(node) + + n1 := n >> 8 + n0 := n >> 0 + + return AddrFrom4(10, r, z<<4+n1, n0) +} diff --git a/pkg/rings/encode_test.go b/pkg/rings/encode_test.go new file mode 100644 index 0000000..b0dcb24 --- /dev/null +++ b/pkg/rings/encode_test.go @@ -0,0 +1,54 @@ +package rings + +import ( + "fmt" + "net/netip" + "testing" +) + +func TestRingOneAddress(t *testing.T) { + RZNTest(t, "RingOneAddress", RingOneAddress, []RZNTestCase{ + {1, 1, 50, MustParseAddr("10.1.16.50")}, + {1, 2, 50, MustParseAddr("10.1.32.50")}, + {2, 3, 300, MustParseAddr("10.2.49.44")}, + {1, 20, 50, netip.Addr{}}, + }) +} + +type RZNTestCase struct { + region RegionID + zone ZoneID + node NodeID + addr netip.Addr +} + +func RZNTest(t *testing.T, + fnName string, fn func(RegionID, ZoneID, NodeID) (netip.Addr, error), + cases []RZNTestCase) { + // + for i, tc := range cases { + s := fmt.Sprintf("%s(%v, %v, %v)", fnName, + tc.region, + tc.zone, + tc.node, + ) + + addr, err := fn(tc.region, tc.zone, tc.node) + + switch { + case !tc.addr.IsValid(): + // expect error + if err != nil { + t.Logf("[%v/%v]: %s → %s", i, len(cases), s, err) + } else { + t.Errorf("ERROR: [%v/%v]: %s → %s (expected %s)", i, len(cases), s, addr, "error") + } + case err != nil: + t.Errorf("ERROR: [%v/%v]: %s → %s (expected %s)", i, len(cases), s, err, tc.addr) + case addr.Compare(tc.addr) != 0: + t.Errorf("ERROR: [%v/%v]: %s → %s (expected %s)", i, len(cases), s, addr, tc.addr) + default: + t.Logf("[%v/%v]: %s → %s", i, len(cases), s, addr) + } + } +} diff --git a/pkg/rings/rings.go b/pkg/rings/rings.go index 6569105..18b46a2 100644 --- a/pkg/rings/rings.go +++ b/pkg/rings/rings.go @@ -18,6 +18,9 @@ const ( // 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 + + // RingOneBits indicates the size of the prefix on the ring 1 (lan) network. + RingOneBits = 20 ) // RegionID is the identifier of a region, valid between 1 and [RegionMax]. -- 2.17.1 From 0f177acf57166b7f5750614cb5d9c0653cdba463 Mon Sep 17 00:00:00 2001 From: Alejandro Mery Date: Sat, 25 May 2024 21:23:58 +0000 Subject: [PATCH 4/6] rings: RingZeroPrefix()/RingZeroAddress() Ring zero corresponds to the backbone that connects all zones. Signed-off-by: Alejandro Mery --- pkg/rings/encode.go | 44 ++++++++++++++++++++++++++++++++++++++++ pkg/rings/encode_test.go | 9 ++++++++ pkg/rings/rings.go | 2 ++ 3 files changed, 55 insertions(+) diff --git a/pkg/rings/encode.go b/pkg/rings/encode.go index 41d1062..d33197d 100644 --- a/pkg/rings/encode.go +++ b/pkg/rings/encode.go @@ -2,6 +2,43 @@ package rings import "net/netip" +// RingZeroPrefix represents the backbone that connects gateways +// of the different Ring 1 networks. +// +// The ring 0 network corresponds to what would be ring 2 for region_id 0. +// 10.0.0.0-10.0.255.255 +func RingZeroPrefix(region RegionID, zone ZoneID) (cidr netip.Prefix, err error) { + switch { + case !region.Valid(): + err = ErrOutOfRange(region, "region") + case !zone.Valid(): + err = ErrOutOfRange(zone, "zone") + default: + addr := unsafeRingZeroAddress(region, zone, 0) + cidr = netip.PrefixFrom(addr, RingZeroBits) + } + + return cidr, err +} + +// RingZeroAddress returns a Ring 0 address for a particular node. +// +// A ring 0 address looks like 10.0.(region_id << 4 + zone_id).(node_id)/20 +func RingZeroAddress(region RegionID, zone ZoneID, node NodeID) (addr netip.Addr, err error) { + switch { + case !region.Valid(): + err = ErrOutOfRange(region, "region") + case !zone.Valid(): + err = ErrOutOfRange(zone, "zone") + case !node.ValidZero(): + err = ErrOutOfRange(node, "node") + default: + addr = unsafeRingZeroAddress(region, zone, node) + } + + return addr, err +} + // RingOnePrefix represents a (virtual) local network of a zone. // // Ring 1 is `10.(region_id).(zone_id << 4).(node_id)/20` network @@ -39,6 +76,13 @@ func RingOneAddress(region RegionID, zone ZoneID, node NodeID) (addr netip.Addr, return addr, err } +func unsafeRingZeroAddress(region RegionID, zone ZoneID, node NodeID) netip.Addr { + r := uint(region) + z := uint(zone) + n := uint(node) + + return AddrFrom4(10, 0, r<<4+z, n) +} func unsafeRingOneAddress(region RegionID, zone ZoneID, node NodeID) netip.Addr { r := uint(region) z := uint(zone) diff --git a/pkg/rings/encode_test.go b/pkg/rings/encode_test.go index b0dcb24..0b404fc 100644 --- a/pkg/rings/encode_test.go +++ b/pkg/rings/encode_test.go @@ -6,6 +6,15 @@ import ( "testing" ) +func TestRingZeroAddress(t *testing.T) { + RZNTest(t, "RingZeroAddress", RingZeroAddress, []RZNTestCase{ + {1, 1, 50, MustParseAddr("10.0.17.50")}, + {1, 2, 50, MustParseAddr("10.0.18.50")}, + {2, 3, 1, MustParseAddr("10.0.35.1")}, + {2, 3, 300, netip.Addr{}}, + }) +} + func TestRingOneAddress(t *testing.T) { RZNTest(t, "RingOneAddress", RingOneAddress, []RZNTestCase{ {1, 1, 50, MustParseAddr("10.1.16.50")}, diff --git a/pkg/rings/rings.go b/pkg/rings/rings.go index 18b46a2..a02bd09 100644 --- a/pkg/rings/rings.go +++ b/pkg/rings/rings.go @@ -19,6 +19,8 @@ const ( // when its a gateway connected to Ring 0 (backbone). NodeZeroMax = (1 << 8) - 1 + // RingZeroBits indicates the size of the prefix on the ring 0 (backbone) network. + RingZeroBits = 16 // RingOneBits indicates the size of the prefix on the ring 1 (lan) network. RingOneBits = 20 ) -- 2.17.1 From 6142d0f7f060777a7686372868d447ab08dce460 Mon Sep 17 00:00:00 2001 From: Alejandro Mery Date: Sat, 25 May 2024 21:26:35 +0000 Subject: [PATCH 5/6] rings: RingThreePrefix() Ring 3 corresponds to the pods of the kubernetes cluster of a region Signed-off-by: Alejandro Mery --- pkg/rings/encode.go | 25 +++++++++++++++++++++++++ pkg/rings/rings.go | 3 +++ 2 files changed, 28 insertions(+) diff --git a/pkg/rings/encode.go b/pkg/rings/encode.go index d33197d..f8cd089 100644 --- a/pkg/rings/encode.go +++ b/pkg/rings/encode.go @@ -76,6 +76,21 @@ func RingOneAddress(region RegionID, zone ZoneID, node NodeID) (addr netip.Addr, return addr, err } +// RingThreePrefix returns the subnet corresponding to +// the pods of a cluster. +// +// Ring 3 is a `10.(region_id << 4).0.0/12` network +func RingThreePrefix(region RegionID) (subnet netip.Prefix, err error) { + switch { + case !region.Valid(): + err = ErrOutOfRange(region, "region") + default: + addr := unsafeRingThreeAddress(region, 0) + subnet = netip.PrefixFrom(addr, RingThreeBits) + } + return subnet, err +} + func unsafeRingZeroAddress(region RegionID, zone ZoneID, node NodeID) netip.Addr { r := uint(region) z := uint(zone) @@ -93,3 +108,13 @@ func unsafeRingOneAddress(region RegionID, zone ZoneID, node NodeID) netip.Addr return AddrFrom4(10, r, z<<4+n1, n0) } + +func unsafeRingThreeAddress(region RegionID, n uint) netip.Addr { + r := uint(region) + + n2 := n >> 16 + n1 := n >> 8 + n0 := n >> 0 + + return AddrFrom4(10, r<<4+n2, n1, n0) +} diff --git a/pkg/rings/rings.go b/pkg/rings/rings.go index a02bd09..99f8a6d 100644 --- a/pkg/rings/rings.go +++ b/pkg/rings/rings.go @@ -23,6 +23,9 @@ const ( RingZeroBits = 16 // RingOneBits indicates the size of the prefix on the ring 1 (lan) network. RingOneBits = 20 + // RingThreeBits indicates the size of the prefix on the ring 3 (pods) network + // of the kubernetes cluster of a region. + RingThreeBits = 12 ) // RegionID is the identifier of a region, valid between 1 and [RegionMax]. -- 2.17.1 From 72a2468a10385849fd8a4f821bc7858a524e66c0 Mon Sep 17 00:00:00 2001 From: Alejandro Mery Date: Sat, 25 May 2024 21:30:31 +0000 Subject: [PATCH 6/6] rings: RingTwoPrefix() Ring 2 is the service network shared by all kubernetes clusters. Signed-off-by: Alejandro Mery --- pkg/rings/encode.go | 25 +++++++++++++++++++++++++ pkg/rings/rings.go | 3 +++ 2 files changed, 28 insertions(+) diff --git a/pkg/rings/encode.go b/pkg/rings/encode.go index f8cd089..7a083eb 100644 --- a/pkg/rings/encode.go +++ b/pkg/rings/encode.go @@ -76,6 +76,22 @@ func RingOneAddress(region RegionID, zone ZoneID, node NodeID) (addr netip.Addr, return addr, err } +// RingTwoPrefix represents the services of a cluster +// +// Ring 2 subnets are of the form `10.(region_id).0.0/20`, +// using the address space that would belong to the ring 3 +// region_id 0. +func RingTwoPrefix(region RegionID) (cidr netip.Prefix, err error) { + switch { + case !region.Valid(): + err = ErrOutOfRange(region, "region") + default: + addr := unsafeRingTwoAddress(region, 0) + cidr = netip.PrefixFrom(addr, RingTwoBits) + } + return cidr, err +} + // RingThreePrefix returns the subnet corresponding to // the pods of a cluster. // @@ -109,6 +125,15 @@ func unsafeRingOneAddress(region RegionID, zone ZoneID, node NodeID) netip.Addr return AddrFrom4(10, r, z<<4+n1, n0) } +func unsafeRingTwoAddress(region RegionID, n uint) netip.Addr { + r := uint(region) + + n1 := n >> 8 + n0 := n >> 0 + + return AddrFrom4(10, r, n1, n0) +} + func unsafeRingThreeAddress(region RegionID, n uint) netip.Addr { r := uint(region) diff --git a/pkg/rings/rings.go b/pkg/rings/rings.go index 99f8a6d..646014d 100644 --- a/pkg/rings/rings.go +++ b/pkg/rings/rings.go @@ -23,6 +23,9 @@ const ( RingZeroBits = 16 // RingOneBits indicates the size of the prefix on the ring 1 (lan) network. RingOneBits = 20 + // RingTwoBits indicates the size of the prefix on the ring 2 (services) network + // of all kubernetes clusters. + RingTwoBits = 20 // RingThreeBits indicates the size of the prefix on the ring 3 (pods) network // of the kubernetes cluster of a region. RingThreeBits = 12 -- 2.17.1