Skip to content

bgp.md

Latest commit

 

History

History
1787 lines (1038 loc) · 83.6 KB

bgp.md

File metadata and controls

1787 lines (1038 loc) · 83.6 KB
Raw

API Reference

Packages

network.datumapis.com/v1alpha1

Package v1alpha1 contains API Schema definitions for the network.datumapis.com/v1alpha1 API group.

Resource Types

AFI

Underlying type: string

AFI is the Address Family Indicator for a BGP address family.

Validation:

  • Enum: [ipv4 ipv6 l2vpn]

Appears in:

Field Description
ipv4
ipv6
l2vpn

ASPathFilter

ASPathFilter matches BGP routes by AS path using a regex pattern.

Appears in:

Field Description Default Validation
pattern string Pattern is a regular expression matched against the AS path.
The AS path is represented as a space-separated string of ASNs.		 MaxLength: 256
MinLength: 1
matchType ASPathMatchType MatchType determines whether the pattern must match the full path
or can match a substring. Default: "contains".		 contains Enum: [full contains]

ASPathMatchType

Underlying type: string

ASPathMatchType determines how an AS path filter pattern is applied.

Validation:

  • Enum: [full contains]

Appears in:

Field Description
full ASPathMatchFull requires the pattern to match the entire AS path.
contains ASPathMatchContains requires the pattern to match a substring of the AS path.

AddressClaimRef

AddressClaimRef names the addressing-service claim an assigned address came from. It is a record, not a lookup: the addressing service is an aggregated API served on a project control-plane path and defines no CustomResourceDefinition, so no claim object exists in the cluster a shard runs in and nothing here resolves one. Reading it means addressing that project's control plane directly, with a credential a translating node is deliberately not given.

Every field is a plain string and this group depends on no addressing-service type. The shape matches that service's own opaque cross-API reference, plus the project, because a claim is namespaced within a project and a namespace name alone does not identify one from outside.

Populate it with the coordinates of the claim whose allocation produced the address written alongside it:

shardAddressIPv6: 2001:db8:f00d::100
shardAddressIPv6ClaimRef:
  project: datum-network-edge
  namespace: egress
  name: egress-shard-node-a-ipv6

The claim cannot record this relationship itself. The addressing service overwrites a claim's spec.ownerRef on create with the identity that requested it, so a claim made by a cell controller is attributed to that controller's project rather than to the shard it was made for. Attribution therefore runs in this direction only, and an operator asking which claim holds a shard's address has this field or nothing.

Appears in:

Field Description Default Validation
apiGroup string APIGroup is the group of the claim resource. ipam.miloapis.com MinLength: 1
kind string Kind is the kind of the claim resource. IPClaim MinLength: 1
project string Project is the project whose control plane serves the claim. Required:
a claim is namespaced within a project, and this reference is read from
outside every project.		 MinLength: 1
Required: {}
namespace string Namespace is the namespace holding the claim within Project. MinLength: 1
Required: {}
name string Name is the name of the claim. The addressing service derives it from
the thing being addressed, so it is stable across a shard's lifetime and
is what a replacement finds again.		 MinLength: 1
Required: {}

AddressFamily

AddressFamily is a BGP address family expressed as an AFI/SAFI pair. Valid combinations: ipv4/unicast, ipv6/unicast, l2vpn/evpn.

Appears in:

Field Description Default Validation
afi AFI AFI is the address family indicator. Enum: [ipv4 ipv6 l2vpn]
safi SAFI SAFI is the subsequent address family indicator. Enum: [unicast evpn]

AdvertisementOriginateFrom

AdvertisementOriginateFrom defines how routes are sourced from a local system resource rather than from the static Prefixes list.

Appears in:

Field Description Default Validation
type AdvertisementOriginateType Type is the source from which routes are originated. Enum: [interface kernel]
interfaceName string InterfaceName is the name of the interface to originate routes from.
Required when type is "interface".		 MinLength: 1

AdvertisementOriginateType

Underlying type: string

AdvertisementOriginateType is the source from which routes are originated.

Validation:

  • Enum: [interface kernel]

Appears in:

Field Description
interface OriginateTypeInterface originates routes from local interface addresses.
kernel OriginateTypeKernel originates routes learned from the kernel routing table.

AdvertisementPolicyRef

AdvertisementPolicyRef references a BGPPolicy by name to apply as a conditional filter before advertisement.

Appears in:

Field Description Default Validation
name string Name is the name of the BGPPolicy within the same namespace. MinLength: 1

AsPathSet

AsPathSet defines AS path manipulation operations.

Appears in:

Field Description Default Validation
prepend integer Prepend adds an ASN to the AS path N times. Maximum: 10
Minimum: 1
asn integer ASN is the AS number to prepend (used when prepend is set).
Defaults to the local ASN if not specified.
replace integer array Replace replaces the entire AS path with the given list.
Mutually exclusive with prepend.		 MaxItems: 32

BGPAdvertisement

BGPAdvertisement defines routing information to advertise from a single BGPRouter. Routes are originated from static Prefixes, redistributed routing table entries, or local interface/kernel routes. Fan-out via routerSelector is intentionally not supported to avoid ambiguous prefix attribution across multiple routers.

Field Description Default Validation
apiVersion string network.datumapis.com/v1alpha1
kind string BGPAdvertisement
kind string Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion string APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec BGPAdvertisementSpec
status BGPAdvertisementStatus

BGPAdvertisementSpec

BGPAdvertisementSpec defines the desired advertisement state. At least one of prefixes, redistribute, or originateFrom must be specified.

Appears in:

Field Description Default Validation
routerRef RouterRef RouterRef targets a single BGPRouter by name. Required: {}
addressFamily AddressFamily AddressFamily defines the AFI/SAFI for this advertisement. Required: {}
prefixes Prefix array Prefixes is the list of CIDR prefixes to advertise.
At least one of Prefixes, Redistribute, or OriginateFrom must be specified.		 MaxItems: 256
MaxLength: 64
redistribute RedistributeSource array Redistribute defines routing table sources to redistribute into BGP.
Routes matching the source type are originated without requiring explicit CIDR entries.
At least one of Prefixes, Redistribute, or OriginateFrom must be specified.		 Enum: [static connected kernel]
MaxItems: 3
originateFrom AdvertisementOriginateFrom OriginateFrom defines how routes are sourced from a local interface or kernel table.
When set, routes are originated from the specified source in addition to any static Prefixes.
At least one of Prefixes, Redistribute, or OriginateFrom must be specified.
policyRef AdvertisementPolicyRef PolicyRef references a BGPPolicy to apply as a conditional filter before advertisement.
Only routes that match the policy are originated.
communities Community array Communities is the default list of BGP communities to attach to all advertised prefixes.
Per-prefix communities in Prefixes[n].communities replace this value for individual prefixes.		 MaxItems: 64
MaxLength: 32
localPreference integer LocalPreference sets the default BGP LOCAL_PREF attribute for all advertised prefixes.
Per-prefix localPreference in Prefixes[n].localPreference overrides this value.
Only meaningful for iBGP sessions.		 Minimum: 0
vrfID integer VRFID is the 16-bit PoP-local VRF identifier this advertisement's SRv6
SID resolves into, per RFC 9800 uSID Argument addressing. Required when
Function is set.		 Maximum: 65535
Minimum: 1
function SRv6Function Function is the RFC 8986 SRv6 endpoint behavior applied when this
advertisement originates a compressed uSID. Required when VRFID is set.		 Enum: [End.DT4 End.DT6 End.DT46]

BGPAdvertisementStatus

BGPAdvertisementStatus defines the observed state of BGPAdvertisement.

Appears in:

Field Description Default Validation
observedGeneration integer ObservedGeneration is the .metadata.generation this status was computed from.
advertisedPrefixes integer AdvertisedPrefixes is the count of prefixes currently being originated.
conditions Condition array Conditions contains the standard conditions for this resource.

BGPCommunitySet

BGPCommunitySet defines a named list of BGP community values used by BGPPolicy terms to match or set communities on routes. It is referenced by name from BGPPolicyMatch.communitySetRef.

A single BGPCommunitySet holds either standard or large communities — the type is declared upfront and all entries are validated against it via CEL.

Field Description Default Validation
apiVersion string network.datumapis.com/v1alpha1
kind string BGPCommunitySet
kind string Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion string APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec BGPCommunitySetSpec
status BGPCommunitySetStatus

BGPCommunitySetSpec

BGPCommunitySetSpec defines the desired state of BGPCommunitySet.

Appears in:

Field Description Default Validation
type BGPCommunitySetType Type is the community format for all entries in this set. Enum: [standard large]
Required: {}
entries string array Entries is the list of community values.
Standard: ASN:NN, IP:NN, or well-known names (graceful-shutdown, no-export,
no-advertise, blackhole).
Large: ASN:NN:NN.		 MaxItems: 256
MinItems: 1

BGPCommunitySetStatus

BGPCommunitySetStatus defines the observed state of BGPCommunitySet.

Appears in:

Field Description Default Validation
observedGeneration integer ObservedGeneration is the .metadata.generation this status was computed from.
conditions Condition array Conditions contains the standard conditions for this resource.

BGPCommunitySetType

Underlying type: string

BGPCommunitySetType distinguishes standard from large BGP communities.

Validation:

  • Enum: [standard large]

Appears in:

Field Description
standard BGPCommunitySetTypeStandard covers ASN:NN, IP:NN, and well-known names
(graceful-shutdown, no-export, no-advertise, blackhole).
large BGPCommunitySetTypeLarge covers ASN:NN:NN large communities.

BGPMaximumPrefix

BGPMaximumPrefix defines the maximum number of routes accepted from a peer before triggering a shutdown action.

Appears in:

Field Description Default Validation
limit integer Limit is the maximum number of routes accepted from this peer. Minimum: 1
thresholdPercent integer ThresholdPercent is the percentage threshold at which a warning is
logged (e.g., 75 means warn at 75% of Limit). Range: 1-100.		 Maximum: 100
Minimum: 1
shutdownAction MaxPrefixShutdownAction ShutdownAction is the action taken when the Limit is exceeded. Enum: [warning-only restart shutdown]
Required: {}

BGPOrigin

Underlying type: string

BGPOrigin is the BGP origin attribute per RFC 4271.

Validation:

  • Enum: [igp egp incomplete]

Appears in:

Field Description
igp BGPOriginIGP indicates the route was learned via an IGP.
egp BGPOriginEGP indicates the route was learned via the EGP protocol.
incomplete BGPOriginIncomplete indicates the route origin is unknown.

BGPPeer

BGPPeer defines a BGP session to a remote peer. It binds to one or more BGPRouter instances via routerRef or routerSelector.

Field Description Default Validation
apiVersion string network.datumapis.com/v1alpha1
kind string BGPPeer
kind string Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion string APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec BGPPeerSpec
status BGPPeerStatus

BGPPeerAuthentication

BGPPeerAuthentication defines authentication configuration for a BGP peer.

Supports both secret-ref-based (MD5/TCP-AO) and plain-text passwords. The plain-text password is primarily for non-production environments.

Appears in:

Field Description Default Validation
password string Password is a plain-text authentication password.
Prefer AuthSecretRef for production deployments.

BGPPeerBFD

BGPPeerBFD defines BFD (Bidirectional Forwarding Detection) parameters for a BGP peer.

BFD provides sub-second failure detection for BGP sessions, enabling fast convergence without relying on BGP hold timers (default 90s).

Appears in:

Field Description Default Validation
enabled boolean Enabled indicates whether BFD is enabled for this peer.
minimumTx integer MinimumTx is the minimum transmission interval in microseconds.
FRR / GoBGP use microseconds — the controller converts to milliseconds
when programming the runtime. Defaults to 300000 (300ms).
minimumRx integer MinimumRx is the minimum reception interval in microseconds.
Defaults to 300000 (300ms).
detectMultiplier integer DetectMultiplier is the number of missed packets before declaring the
BFD session down. Default is 3.		 Maximum: 50
Minimum: 3
multiHop boolean MultiHop enables BFD for eBGP multi-hop sessions (RFC 5883).
Must be true when ebgpMultiHop is true.

BGPPeerGracefulRestart

BGPPeerGracefulRestart defines BGP graceful restart parameters for a peer.

Graceful restart (RFC 4724) allows a BGP speaker to restart its control plane without tearing down sessions. Routes are preserved during the restart period, preventing MAC/IP flapping in EVPN deployments.

Appears in:

Field Description Default Validation
enabled boolean Enabled indicates whether graceful restart is enabled for this peer.
restartTime integer RestartTime is the maximum time (in seconds) the peer expects the
local system to complete a graceful restart. Range: 1-1200.
Default: 120 seconds.		 Maximum: 1200
Minimum: 1

BGPPeerSpec

BGPPeerSpec defines the desired state of BGPPeer.

Appears in:

Field Description Default Validation
routerRef RouterRef RouterRef targets a single BGPRouter by name.
Mutually exclusive with routerSelector.
routerSelector RouterSelector RouterSelector targets one or more BGPRouters by label.
Mutually exclusive with routerRef.
peerASN integer PeerASN is the remote AS number. Minimum: 1
Required: {}
address string Address is the remote peer's IPv4 or IPv6 address. MinLength: 1
Required: {}
remotePort integer RemotePort is the TCP port used to establish the BGP session with
this peer. Defaults to 179 (the IANA-assigned BGP port) if unset.		 Maximum: 65535
Minimum: 1
description string Description is a human-readable label for this peer (e.g., "spine-1").
authSecretRef LocalSecretRef AuthSecretRef references a Secret in the same namespace containing the
MD5 TCP authentication password under the key "password".
addressFamilies AddressFamily array AddressFamilies defines the address families negotiated on this session. MinItems: 1
holdTime Duration HoldTime is the BGP hold timer. Must be 0 (disabled) or >= 3s.
Defaults to 90s if unset.
keepaliveTime Duration KeepaliveTime is the BGP keepalive interval. Must be <= HoldTime / 3.
Defaults to 30s if unset. Maximum is 30s; the controller enforces
the keepalive <= holdTime / 3 constraint with an Accepted=False condition.
ebgpMultiHop boolean EbgpMultiHop enables eBGP multihop when the peer is not directly connected.
When true, the TTL for BGP packets is set to 64 (vs. 1 for direct).
bfd BGPPeerBFD BFD configures Bidirectional Forwarding Detection for fast failure
detection (sub-500ms). Without BFD, convergence relies on BGP hold
timers (default 90s).
gracefulRestart BGPPeerGracefulRestart GracefulRestart configures BGP graceful restart for this peer.
Prevents route flapping during control-plane restarts.
multiSession boolean MultiSession enables BFD over MP-BGP (RFC 8935). When true, each
AFI/SAFI negotiates its own BFD session independently. When false
(default), a single BFD session covers all AFI/SAFIs.
routeMapIn string RouteMapIn is the name of a BGPPolicy term set applied to routes
received from this peer (import direction). The name must match
a BGPPolicy resource in the same namespace.
routeMapOut string RouteMapOut is the name of a BGPPolicy term set applied to routes
advertised to this peer (export direction). The name must match
a BGPPolicy resource in the same namespace.
nextHopSelf boolean NextHopSelf controls next-hop behavior for iBGP sessions.
When true, the local router's IP is used as next-hop for all
advertised routes. Common in EVPN iBGP peering.
removePrivateAS integer RemovePrivateAS strips private AS numbers (64512-65535, 4200000000-4294967294)
from the AS path on eBGP export. If set to a non-zero value, private ASNs
are replaced with the specified value before export.		 Minimum: 0
updateSource string UpdateSource is the local IP address or interface name used as the
source for the BGP TCP session. Useful when the local router has
multiple addresses or when pinning to a specific loopback.
sendCommunity SendCommunityType SendCommunity controls which BGP community attributes are propagated
to this peer. When unset, communities are not sent.		 Enum: [standard extended large both]
allowASIn integer AllowASIn allows routes that contain the local ASN in the AS_PATH
to be accepted from this peer. The value specifies the maximum number
of times the local ASN may appear. Range: 1-10.		 Maximum: 10
Minimum: 1
maximumPrefix BGPMaximumPrefix MaximumPrefix defines the maximum number of routes accepted from this
peer before triggering a shutdown action.
defaultOriginRoute OriginType DefaultOriginRoute controls default route origination for this peer.
"igp" originates a default route with IGP origin.
"egp" originates a default route with EGP origin.
"incomplete" originates a default route with incomplete origin.
Empty or unset means no default route origination.		 Enum: [igp egp incomplete]
authentication BGPPeerAuthentication Authentication configures peer authentication.
AuthSecretRef takes precedence when both are set.

BGPPeerState

Underlying type: string

BGPPeerState represents the BGP Finite State Machine state of a session.

Appears in:

Field Description
Idle
Connect
Active
OpenSent
OpenConfirm
Established

BGPPeerStatus

BGPPeerStatus defines the observed state of BGPPeer.

Appears in:

Field Description Default Validation
observedGeneration integer ObservedGeneration is the .metadata.generation this status was computed from.
sessionState BGPPeerState SessionState is the current BGP FSM state of this session.
lastEstablishedTime Time LastEstablishedTime is the timestamp of the most recent Established transition.
conditions Condition array Conditions contains the standard conditions for this resource.

BGPPolicy

BGPPolicy defines composable, ordered routing policy statements applied to a BGPRouter in a specific direction (import or export). It binds to one or more BGPRouter instances via routerRef or routerSelector.

Field Description Default Validation
apiVersion string network.datumapis.com/v1alpha1
kind string BGPPolicy
kind string Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion string APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec BGPPolicySpec
status BGPPolicyStatus

BGPPolicyAction

Underlying type: string

BGPPolicyAction is the disposition applied when a policy term matches.

Validation:

  • Enum: [permit deny]

Appears in:

Field Description
permit BGPPolicyActionPermit allows the route and optionally applies set actions.
deny BGPPolicyActionDeny drops the route. Set actions must not be specified.

BGPPolicyDirection

Underlying type: string

BGPPolicyDirection is the direction in which a BGPPolicy is applied.

Validation:

  • Enum: [import export]

Appears in:

Field Description
import BGPPolicyDirectionImport applies the policy to routes received from peers.
export BGPPolicyDirectionExport applies the policy to routes advertised to peers.

BGPPolicyMatch

BGPPolicyMatch defines the conditions under which a policy term fires.

Appears in:

Field Description Default Validation
any boolean Any matches all routes. When true, all other match fields are ignored.
addressFamilies AddressFamily array AddressFamilies constrains the match to specific AFI/SAFI combinations.
If empty, all address families are matched.		 MaxItems: 8
prefixList string array PrefixList constrains the match to routes whose prefix matches one of
the given CIDR blocks. Each entry must be a valid IPv4 or IPv6 CIDR.		 MaxItems: 256
items:MaxLength: 43
asPathFilter ASPathFilter ASPathFilter matches routes by AS path using a regex pattern.
The pattern is matched against the full AS path string (space-separated ASNs).
communityMatch string array CommunityMatch matches routes by BGP community.
Each entry is a community string in ASN:NN or IP:NN format.		 MaxItems: 32
items:MaxLength: 32
evpnRouteType EVPNRouteType array EVPNRouteType matches specific EVPN route types.
Only meaningful when l2vpn/evpn address family is configured.		 Enum: [inclusiveMulticastEthernetTag macIPAdvertisement iPPrefixAdvertisement stickyMACAddress iPv6PrefixAdvertisement]
MaxItems: 5
vni integer VNI matches routes by VNI (VXLAN Network Identifier).
Range: 0–16777215 (24-bit VNI).		 Maximum: 1.6777215e+07
Minimum: 0
macAddress string MACAddress matches MAC-IP routes (EVPN Type-2) by MAC address.
Format: colon-separated hex bytes (e.g., "aa:bb:cc:dd:ee:ff").		 Pattern: ^([0-9a-fA-F]\{2\}:)\{5\}[0-9a-fA-F]\{2\}$
ipPrefix string IPPrefix matches routes by exact IP prefix (CIDR notation). MaxLength: 43
localPreference integer LocalPreference matches routes by BGP LOCAL_PREF value. Minimum: 0
med integer MED matches routes by Multi-Exit Discriminator value. Minimum: 0

BGPPolicySetActions

BGPPolicySetActions defines mutations applied when a term matches with action "permit".

Appears in:

Field Description Default Validation
communities CommunitySet Communities defines community add/remove operations.
localPreference integer LocalPreference sets the LOCAL_PREF attribute.
Only meaningful on import (iBGP) or export to iBGP peers.		 Minimum: 0
origin BGPOrigin Origin sets the BGP origin attribute. Enum: [igp egp incomplete]
asPath AsPathSet AsPath manipulates the AS path (prepend or replace).
nextHop NextHopSet NextHop overrides the next-hop attribute.
extCommunities ExtendedCommunitySet ExtCommunities defines extended community add/remove operations.
Each entry must be in a valid extended community format (ASN:NN, IP:NN,
or type-specific like "rt:65000:100").
metric integer Metric sets the MED (Multi-Exit Discriminator) attribute. Minimum: 0
color integer Color sets the SRv6 policy color for path selection. Minimum: 0

BGPPolicySpec

BGPPolicySpec defines the desired route policy state.

Appears in:

Field Description Default Validation
routerRef RouterRef RouterRef targets a single BGPRouter by name.
Mutually exclusive with routerSelector.
routerSelector RouterSelector RouterSelector targets one or more BGPRouters by label.
Mutually exclusive with routerRef.
direction BGPPolicyDirection Direction is the policy direction: import or export. Enum: [import export]
Required: {}
terms BGPPolicyTerm array Terms is the ordered list of policy statements.
Evaluated from lowest to highest sequence number.		 MaxItems: 32
MinItems: 1

BGPPolicyStatus

BGPPolicyStatus defines the observed state of BGPPolicy.

Appears in:

Field Description Default Validation
observedGeneration integer ObservedGeneration is the .metadata.generation this status was computed from.
conditions Condition array Conditions contains the standard conditions for this resource.

BGPPolicyTerm

BGPPolicyTerm is a single ordered policy statement with match conditions and an action.

Appears in:

Field Description Default Validation
sequence integer Sequence is the evaluation order. Lower values are evaluated first.
Must be unique within the policy.		 Maximum: 65535
Minimum: 1
match BGPPolicyMatch Match defines the conditions under which this term fires.
action BGPPolicyAction Action is the disposition when this term matches. Enum: [permit deny]
set BGPPolicySetActions Set defines mutations applied when action is "permit".
Must not be set when action is "deny".

BGPPrefixListEntry

BGPPrefixListEntry defines a single entry in a named BGP prefix-list. Entries are evaluated in ascending sequence order.

Appears in:

Field Description Default Validation
sequence integer Sequence is the evaluation order for this entry. Entries with lower
sequence numbers are evaluated first. Must be unique within the list.		 Maximum: 4.294967295e+09
Minimum: 5
action BGPPolicyAction Action is the disposition when a route's prefix matches this entry. Enum: [permit deny]
Required: {}
prefix string Prefix is the IPv4 or IPv6 CIDR to match against. MinLength: 1
Required: {}
ge integer GE is the minimum prefix-length to match (greater-than-or-equal).
For example, "10.0.0.0/8 ge 16" matches 10.0.0.0/16 through 10.0.0.0/32.
When unset, the prefix-length of Prefix is the lower bound.		 Maximum: 32
Minimum: 0
le integer LE is the maximum prefix-length to match (less-than-or-equal).
For example, "10.0.0.0/8 le 24" matches 10.0.0.0/8 through 10.0.0.0/24.
When unset, the prefix-length of Prefix is the upper bound.		 Maximum: 32
Minimum: 0

BGPRouter

BGPRouter defines a logical BGP routing context. It abstracts a processing instance bound to a specific execution context (e.g., a VRF or network namespace) on a target node and acts as the primary ownership boundary for BGPPeer, BGPAdvertisement, and BGPPolicy resources.

Field Description Default Validation
apiVersion string network.datumapis.com/v1alpha1
kind string BGPRouter
kind string Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion string APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec BGPRouterSpec
status BGPRouterStatus

BGPRouterPeerSummary

BGPRouterPeerSummary summarizes BGP peer session counts.

Appears in:

Field Description Default Validation
total integer Total is the total number of configured peers.
established integer Established is the count of peers currently in the Established state.

BGPRouterPhase

Underlying type: string

BGPRouterPhase describes the lifecycle phase of a BGPRouter.

Appears in:

Field Description
Pending
Ready
Failed

BGPRouterSpec

BGPRouterSpec defines the desired state of a BGPRouter.

Appears in:

Field Description Default Validation
targetRef TargetRef TargetRef identifies the Node this router executes on. Required: {}
localASN integer LocalASN is the BGP Autonomous System Number for this router.
Must be a valid 2-byte or 4-byte ASN per RFC 6793.		 Minimum: 1
Required: {}
routerID string RouterID is a unique 32-bit identifier expressed in IPv4 dotted-decimal notation.
In an IPv6-only underlay this is a logical identifier only.		 Format: ipv4
Required: {}
addressFamilies AddressFamily array AddressFamilies defines the address families this router activates. MinItems: 1
srv6Locator string SRv6Locator is the SRv6 locator block this router owns, expressed as an
IPv6 CIDR (e.g. "2001:db8:ff01::/48"). Individual SRv6 endpoint SIDs are
host addresses within this block.
nodeID integer NodeID is this router's 16-bit slot within its PoP's SRv6Locator block,
used for RFC 9800 NEXT-CSID compression. Unique within the PoP.
The uSID carrier format reserves 0x0000 and 0xE000-0xFFFF (the latter is
Function space, not Node-ID space), leaving 0x0001-0xDFFF assignable.		 Maximum: 57343
Minimum: 1
listenPort integer ListenPort is the TCP port this router listens on for incoming BGP
peer connections. Defaults to 179 (the IANA-assigned BGP port) if unset.		 Maximum: 65535
Minimum: 1

BGPRouterStatus

BGPRouterStatus defines the observed state of a BGPRouter.

Appears in:

Field Description Default Validation
phase BGPRouterPhase Phase is the high-level lifecycle state of this router.
observedGeneration integer ObservedGeneration is the .metadata.generation this status was computed from.
peers BGPRouterPeerSummary Peers summarizes peer session counts.
conditions Condition array Conditions contains the standard conditions for this resource.

BGPVRFInstance

BGPVRFInstance configures an L2VPN EVPN VRF on matched BGPRouters. The referenced BGPRouter must have l2vpn-evpn in its addressFamilies.

Field Description Default Validation
apiVersion string network.datumapis.com/v1alpha1
kind string BGPVRFInstance
kind string Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion string APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec BGPVRFInstanceSpec
status BGPVRFInstanceStatus

BGPVRFInstanceSpec

BGPVRFInstanceSpec defines the desired VRF configuration.

Appears in:

Field Description Default Validation
routerRef RouterRef RouterRef targets a single BGPRouter by name.
Mutually exclusive with routerSelector.
routerSelector RouterSelector RouterSelector targets one or more BGPRouters by label.
Mutually exclusive with routerRef.
vrfID integer VRFID is the 16-bit PoP-local VRF identifier used for RFC 9800 uSID
Argument addressing and to derive the RFC 4364 Type 1 Route
Distinguisher ("routerID:vrfID"). Unique per (VPC, PoP). Value 0 is
reserved.		 Maximum: 65535
Minimum: 1
Required: {}
importRouteTargets RouteTarget array ImportRouteTargets is the list of BGP extended community route targets
used to import routes into this VRF.		 MaxItems: 32
MinItems: 1
exportRouteTargets RouteTarget array ExportRouteTargets is the list of BGP extended community route targets
attached to routes exported from this VRF.		 MaxItems: 32
MinItems: 1
nptv6 NPTv6Spec NPTv6 configures stateless RFC 6296 Network Prefix Translation for
this VRF: backends presenting an address within ULAPrefix are
translated, checksum-neutrally and bidirectionally, to the
corresponding address in PublicPrefix. Unset means this VRF's traffic
crosses the SRv6 fabric with its own ULA source/destination
unmodified — the common case. Keyed by this VRFID, never by address,
specifically so two VRFs may configure the identical ULAPrefix (e.g.
both using the same private range) without collision — each VRF's
mapping is independent, looked up only after this VRF's own identity
is already resolved from the SRv6 uSID Argument, never derived from
address content alone.

BGPVRFInstanceStatus

BGPVRFInstanceStatus defines the observed state of BGPVRFInstance.

Appears in:

Field Description Default Validation
conditions Condition array Conditions are top-level conditions for this BGPVRFInstance.
routers RouterStatus array Routers holds per-router reconciliation status.

Community

Underlying type: string

Community is a BGP community in ASN:NN or IP:NN format.

Validation:

  • MaxLength: 32

Appears in:

CommunitySet

CommunitySet defines community add and remove operations.

Appears in:

Field Description Default Validation
add string array Add is a list of communities to attach. MaxItems: 32
items:MaxLength: 24
remove string array Remove is a list of communities to strip. MaxItems: 32
items:MaxLength: 24

EVPNRouteType

Underlying type: string

EVPNRouteType is an EVPN route type per RFC 7432.

Validation:

  • Enum: [inclusiveMulticastEthernetTag macIPAdvertisement iPPrefixAdvertisement stickyMACAddress iPv6PrefixAdvertisement]

Appears in:

Field Description
inclusiveMulticastEthernetTag EVPNRouteTypeInclusiveMulticastEthernetTag is Type-1: Inclusive Multicast Ethernet Tag route.
macIPAdvertisement EVPNRouteTypeMACIPAdvertisement is Type-2: MAC-IP Advertisement route.
iPPrefixAdvertisement EVPNRouteTypeIPPrefixAdvertisement is Type-3: IP Prefix Advertisement route.
stickyMACAddress EVPNRouteTypeStickyMACAddress is Type-4: Sticky MAC Address route.
iPv6PrefixAdvertisement EVPNRouteTypeIPv6PrefixAdvertisement is Type-5: IPv6 Prefix Advertisement route.

EgressShard

EgressShard marks a single node as a member of the sharded, stateful egress translation tier (galactic-nat) — a component deliberately kept off the ingress load-balancer's own consistent-hash ring (see NetworkGateway): tenant egress traffic (backend -> arbitrary internet destination) is a different traffic pattern from ingress (fixed VIP, fixed backend pool) and needs its own placement ring, own per-flow state, and its own self-routing return path, entirely independent of any NetworkGateway node.

A shard serves one or both address families. NAT66 (IPv6 -> IPv6) and NAT64 (IPv6 -> IPv4, RFC 6146) are the same function — stateful egress PAT with a VRF-scoped session table — over different families, so one shard object describes both rather than there being a second, near-duplicate kind. Spec.ShardAddressIPv6 and Spec.ShardAddressIPv4 are each assigned only for the family this shard translates; a shard with no IPv4 address performs no NAT64.

Every shard owns a dedicated, publicly-routable address per family it serves, and a flow's allocated masquerade port lives within it — so a reply is delivered to the correct shard by ordinary unicast routing alone, with no hashing or cross-shard lookup on the return path at all (the "any node can determine the owning shard from the tuple alone" property, satisfied by construction rather than by a replicated hash table).

A shard is told which addresses to translate to; it does not choose them. The controller that owns a cell claims one address per family from the addressing service and writes it into this spec, which keeps the addressing-service credential off every translating node and keeps the allocation request out of the path that attaches a workload. Status reports what the node's datapath is actually programmed with, so an unclaimed address, a stale datapath, and a divergence between the two are each distinguishable.

A shard names nothing that selects it. Which shards serve which consumer intent is decided entirely by label selectors evaluated on the selecting side (see the LabelEgressShard* keys), so no consumer-facing API appears in this group and no reference points from a datapath resource back at the resource that placed traffic on it.

Field Description Default Validation
apiVersion string network.datumapis.com/v1alpha1
kind string EgressShard
kind string Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion string APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec EgressShardSpec
status EgressShardStatus

EgressShardSpec

EgressShardSpec defines the desired state of an EgressShard.

The address fields are written by the controller that owns the cell, not by the shard and not by a consumer. Each is optional: an address the addressing service has not yet handed out is absent rather than blank-but-required, so a shard object exists from the moment its node is labelled and gains its identity afterwards.

Each is also write-once, and cannot be unassigned once assigned. The datapath claims a reply by exact match against the address it translates to, so reassigning one strands the return traffic of every flow already established through it, with no drain and no dual-address grace period available to cover the change. A shard holding the wrong address is deleted and recreated instead, which breaks those flows at a moment someone chose.

A claim reference alongside an address records where that address came from, and is write-once on the same terms. It is deliberately not required with an address, in either direction. Requiring an address before a claim reference would forbid recording a claim whose allocation has not resolved yet, which is the window a restarting controller most needs to see so that it finds the claim it already made instead of making a second one. Requiring a claim reference before an address would forbid an address allocated by hand, and whether such an address may be recorded here at all is an open migration question this validation would answer by fiat. An address with no reference is therefore accepted and is unattributable, which is a fact about the allocation rather than something a schema can repair.

Appears in:

Field Description Default Validation
targetRef TargetRef TargetRef identifies the Node this shard executes on. Required: {}
shardSID string ShardSID is this shard's own SRv6 uSID, the outer destination a tenant
VRF's egress route encapsulates toward. The shard claims a packet by its
Block and Node-ID alone, the Argument carrying the tenant, so those 64
bits must be reserved for this shard and disjoint from every BGPRouter
locator: a value another node already uses silently diverts that node's
traffic.
Write-once for the same reason the addresses are: every established
flow's reply is re-encapsulated from this SID, so changing it strands
them. Operator-chosen until the addressing service hands out identifiers
of this kind.
Empty means no SID is assigned yet, and the shard claims no packet.
shardAddressIPv6 string ShardAddressIPv6 is the dedicated, publicly-routable IPv6 address this
shard translates to — every NAT66 masquerade port it allocates lives
within this address, so any node can route a reply to the owning shard
using ordinary unicast routing on it alone, with no per-flow state
lookup anywhere but that shard.
Empty means no IPv6 address is assigned to this shard.
shardAddressIPv6ClaimRef AddressClaimRef ShardAddressIPv6ClaimRef records the addressing-service claim
ShardAddressIPv6 came from — see AddressClaimRef. Set it in the same
write as the address whenever that address came from a claim.
Nothing here resolves it and no component reads it to program anything;
it is the only trail from a translating address back to the allocation
accountable for it.
shardAddressIPv4 string ShardAddressIPv4 is the dedicated, publicly-routable IPv4 address this
shard translates to, and the source an IPv4-only destination sees.
Unlike ShardAddressIPv6, reachability for it is not established by a
BGPAdvertisement into the EVPN fabric: an IPv4 reply arrives from the
internet, so the underlay or an upstream announcement must attract this
address to this node.
Empty means no IPv4 address is assigned to this shard.
shardAddressIPv4ClaimRef AddressClaimRef ShardAddressIPv4ClaimRef records the addressing-service claim
ShardAddressIPv4 came from — see AddressClaimRef. Set it in the same
write as the address whenever that address came from a claim.
Nothing here resolves it and no component reads it to program anything;
it is the only trail from a translating address back to the allocation
accountable for it.
nat64Prefix string NAT64Prefix is the IPv6 prefix whose synthesized addresses this shard
translates to IPv4 — a Datum-operated Network-Specific Prefix, shared
fabric-wide, never per-tenant. TranslateWellKnownPrefix adds the RFC 6052
Well-Known Prefix alongside it. It must be the prefix the resolver
synthesizes into; a shard translating for a different one is a
blackhole with no symptom on either side.
Set together with ShardAddressIPv4 or not at all: an address with no
prefix has nothing to translate for, and a prefix with no address has
nothing to translate into. Write-once for the same reason the addresses
are: a shard that starts translating a different prefix blackholes every
destination the resolver already synthesized into the old one.
translateWellKnownPrefix boolean TranslateWellKnownPrefix additionally translates destinations inside the
RFC 6052 Well-Known Prefix 64:ff9b::/96 to IPv4 from ShardAddressIPv4, so
clients using a public DNS64 resolver reach IPv4 destinations. Requires
NAT64Prefix.
RFC 6052 §3.1 forbids the Well-Known Prefix from representing non-global
IPv4 addresses; the implementation must refuse such destinations.
Mutable, unlike NAT64Prefix. Disabling it blackholes every destination
clients already resolved into the Well-Known Prefix until their DNS TTLs
expire.
drain boolean Drain stops this shard from taking new tenants while it keeps serving
the ones it has. Compute nodes that spread egress across a cluster's
shards give a draining shard no share of new tenant addresses, but keep
sending it every flow already pinned to it until that flow goes idle, so
established sessions finish where their translation state lives.
It changes nothing on the shard itself: the shard keeps translating,
advertising its SID and receiving replies. A shard is safe to remove
once its session count has fallen to zero. Clearing it puts the shard
back into rotation.
Compute nodes that send each tenant to a single configured shard ignore
it.

EgressShardStatus

EgressShardStatus defines the observed state of an EgressShard.

The address and prefix fields report what this node's datapath is programmed with, not what it was asked for. A value here that disagrees with the spec is a shard that has not converged; a value here with no counterpart in the spec is a shard still translating to an address nothing assigns any more.

Appears in:

Field Description Default Validation
observedGeneration integer ObservedGeneration is the .metadata.generation this status was computed from.
shardSID string ShardSID is this shard's own uSID locator — a real SRv6 uSID (unlike
the ShardAddress fields, which are plain routable addresses),
advertised into BGP the same way any other node-reachability route is
(a /128 BGPAdvertisement, no VRFID/Function) so every other node learns
a kernel SEG6 route toward it before installing a tenant VRF's egress
route against it. One SID serves both families: which translation a
packet gets is decided from the inner destination, not from a second
SID.
Reports the SID this node's datapath is programmed with, from
Spec.ShardSID.
shardAddressIPv6 string ShardAddressIPv6 is the IPv6 masquerade source this shard's datapath is
programmed with. Empty means it translates no IPv6 flow.
shardAddressIPv4 string ShardAddressIPv4 is the IPv4 masquerade source this shard's datapath is
programmed with. Empty means it performs no NAT64. Publishing it is also
what makes the underlay reachability prerequisite in
Spec.ShardAddressIPv4 checkable.
nat64Prefix string NAT64Prefix is the prefix this shard's datapath is programmed to
translate. Empty whenever ShardAddressIPv4 is empty.
translatesWellKnownPrefix boolean TranslatesWellKnownPrefix reports whether this shard's datapath is
programmed to translate the RFC 6052 Well-Known Prefix 64:ff9b::/96, from
Spec.TranslateWellKnownPrefix. False whenever ShardAddressIPv4 is empty.
conditions Condition array Conditions contains the standard conditions for this resource,
including Programmed (see ConditionTypeProgrammed).

ExtendedCommunitySet

ExtendedCommunitySet defines extended community add and remove operations.

Appears in:

Field Description Default Validation
add string array Add is a list of extended communities to attach. MaxItems: 32
items:MaxLength: 64
remove string array Remove is a list of extended communities to strip. MaxItems: 32
items:MaxLength: 64

LocalSecretRef

LocalSecretRef references a Secret within the same namespace. Cross-namespace references are not supported.

Appears in:

Field Description Default Validation
name string Name is the name of the Secret. MinLength: 1

MaxPrefixShutdownAction

Underlying type: string

MaxPrefixShutdownAction defines the action taken when a peer exceeds its maximum-prefix limit.

Validation:

  • Enum: [warning-only restart shutdown]

Appears in:

Field Description
warning-only MaxPrefixShutdownActionWarningOnly logs a warning but keeps the session up.
restart MaxPrefixShutdownActionRestart resets the BGP session when the limit is exceeded.
shutdown MaxPrefixShutdownActionShutdown tears down the BGP session when the limit is exceeded.

NPTv6Spec

NPTv6Spec is one VRF's stateless RFC 6296 prefix-translation mapping. ULAPrefix and PublicPrefix must share the same prefix length — RFC 6296 translation only ever rewrites the shared prefix, never the host bits.

Appears in:

Field Description Default Validation
ulaPrefix string ULAPrefix is this VRF's tenant-facing IPv6 ULA prefix (e.g.
"fd20:60::/64"), as presented by backends inside the VRF.		 Required: {}
publicPrefix string PublicPrefix is the externally-routable IPv6 prefix ULAPrefix
translates to/from, same prefix length as ULAPrefix.		 Required: {}

NextHopSet

NextHopSet defines next-hop attribute overrides.

Appears in:

Field Description Default Validation
self boolean Self sets the next-hop to the local router's BGP peer address.
address string Address sets the next-hop to a specific IP address.
Mutually exclusive with self.		 MaxLength: 45

OriginType

Underlying type: string

OriginType defines the BGP origin attribute values.

Validation:

  • Enum: [igp egp incomplete]

Appears in:

Field Description
igp
egp
incomplete

Prefix

Underlying type: string

Prefix is an IPv4 or IPv6 CIDR prefix.

Validation:

  • MaxLength: 64

Appears in:

RedistributeSource

Underlying type: string

RedistributeSource is a local routing table source to redistribute into BGP.

Validation:

  • Enum: [static connected kernel]

Appears in:

Field Description
static RedistributeSourceStatic redistributes statically configured routes.
connected RedistributeSourceConnected redistributes directly connected interface routes.
kernel RedistributeSourceKernel redistributes routes from the kernel routing table.

ResolvedRouterConfig

ResolvedRouterConfig holds the configuration resolved and applied to a specific router.

Appears in:

Field Description Default Validation
routerID string RouterID resolved for this router.
asNumber integer ASNumber is the AS number configured.
addressFamilies AddressFamily array AddressFamilies configured.

RouteTarget

RouteTarget is a BGP extended community in "ASN:NN" or "IP:NN" format.

Appears in:

Field Description Default Validation
value string Value is the route target extended community string.
Format: "ASN:NN" (e.g. "65000:100") or "IP:NN" (e.g. "192.0.2.1:100").		 MaxLength: 21
MinLength: 1

RouterRef

RouterRef is a direct reference to a single BGPRouter by name within the same namespace.

Appears in:

Field Description Default Validation
name string Name is the name of the BGPRouter. MinLength: 1

RouterSelector

RouterSelector selects one or more BGPRouter resources by label within the same namespace.

Appears in:

Field Description Default Validation
matchLabels object (keys:string, values:string) MatchLabels is a map of key/value label pairs to match.
matchExpressions LabelSelectorRequirement array MatchExpressions is a list of label selector requirements.

RouterStatus

RouterStatus holds per-router reconciliation status used by BGPVRFInstance.

Appears in:

Field Description Default Validation
routerName string RouterName is the name of the BGPRouter this entry describes.
conditions Condition array Conditions are the per-router conditions.
resolvedConfig ResolvedRouterConfig ResolvedConfig holds the configuration that was actually applied.

RouterTarget

RouterTarget is embedded by resources that bind to one or more BGPRouters. Exactly one of routerRef or routerSelector must be set.

Appears in:

Field Description Default Validation
routerRef RouterRef RouterRef targets a single BGPRouter by name.
Mutually exclusive with routerSelector.
routerSelector RouterSelector RouterSelector targets one or more BGPRouters by label.
Mutually exclusive with routerRef.

SAFI

Underlying type: string

SAFI is the Subsequent Address Family Indicator for a BGP address family.

Validation:

  • Enum: [unicast evpn]

Appears in:

Field Description
unicast
evpn

SRv6Function

Underlying type: string

SRv6Function is the RFC 8986 endpoint behavior applied to a decapsulated SRv6 packet, addressed via the uSID Argument space per RFC 9800.

Validation:

  • Enum: [End.DT4 End.DT6 End.DT46]

Appears in:

Field Description
End.DT4 SRv6FunctionEndDT4 decapsulates and looks up the packet in an IPv4 VRF.
End.DT6 SRv6FunctionEndDT6 decapsulates and looks up the packet in an IPv6 VRF.
End.DT46 SRv6FunctionEndDT46 decapsulates and looks up the packet in an IPv4 or
IPv6 VRF based on the inner packet's address family.

SendCommunityType

Underlying type: string

SendCommunityType controls which BGP community attributes are propagated to a peer.

Validation:

  • Enum: [standard extended large both]

Appears in:

Field Description
standard SendCommunityTypeStandard sends only standard communities (ASN:NN).
extended SendCommunityTypeExtended sends only extended communities (Type:Length:Value).
large SendCommunityTypeLarge sends only large communities (ASN:NN:NN).
both SendCommunityTypeBoth sends both standard and extended communities.

ServiceEndpoint

ServiceEndpoint publishes a platform service that can be reached through a VPC attachment. The object describes the service contract; the controller that owns the service is responsible for its health and implementation.

Field Description Default Validation
apiVersion string network.datumapis.com/v1alpha1
kind string ServiceEndpoint
kind string Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion string APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec ServiceEndpointSpec

ServiceEndpointAttachmentReference

ServiceEndpointAttachmentReference identifies the private attachment that backs a platform service endpoint.

Appears in:

Field Description Default Validation
namespace string Namespace is the namespace containing the Cloud API VPCAttachment. MinLength: 1
name string Name is the Cloud API VPCAttachment name. MinLength: 1

ServiceEndpointDeliveryMode

Underlying type: string

ServiceEndpointDeliveryMode defines the placement contract for a service.

Validation:

  • Enum: [NodeLocal PreferNodeLocal]

Appears in:

Field Description
NodeLocal ServiceEndpointDeliveryModeNodeLocal requires the endpoint's backing
attachment to be present on each node where selected consumers run.
PreferNodeLocal ServiceEndpointDeliveryModePreferNodeLocal selects a backing attachment on
the consumer's node when possible and otherwise tunnels to a ready remote
attachment while preserving the consumer source address.

ServiceEndpointReference

ServiceEndpointReference identifies a ServiceEndpoint in the policy's namespace.

Appears in:

Field Description Default Validation
name string Name is the ServiceEndpoint name. MinLength: 1

ServiceEndpointSpec

ServiceEndpointSpec defines a platform service address and its scope.

Appears in:

Field Description Default Validation
serviceClass string ServiceClass identifies the platform capability implemented by this
endpoint, for example "ipv6-egress-dns".		 MinLength: 1
Required: {}
address string Address is the stable address that consumers use to reach the service. Required: {}
port integer Port is the service port. Maximum: 65535
Minimum: 1
Required: {}
deliveryMode ServiceEndpointDeliveryMode DeliveryMode defines how a backing attachment is selected relative to a
consumer. PreferNodeLocal uses a ready attachment on the consumer's node
when one exists and otherwise falls back to a ready remote attachment.
The dataplane preserves the consumer source address. If consumers with
overlapping address space present an identical TCP or UDP five-tuple to the
same replica, it rejects the later ambiguous flow fail-closed rather than
translate the source or risk returning traffic to the wrong VPC.		 Enum: [NodeLocal PreferNodeLocal]
Required: {}
attachmentRef ServiceEndpointAttachmentReference AttachmentRef identifies the Cloud API VPCAttachment that hosts this
endpoint when the service is delivered through a private VPC path.
The network API keeps this reference opaque; the consuming controller
resolves it against the Cloud API.
attachmentSelector LabelSelector AttachmentSelector selects the Cloud API VPCAttachments that host replicas
of this endpoint. Labels used here must be assigned by the platform service
controller, not by tenants. The dataplane selects one ready replica for
each consumer according to DeliveryMode.
region string Region limits endpoint selection to a region. An empty value means the
endpoint is not region-scoped.

ServiceRouteAuthorization

ServiceRouteAuthorization bounds one network authorization episode.

Appears in:

Field Description Default Validation
validUntil Time ValidUntil is the absolute UTC deadline for requests and existing replies.
Node controllers reject deadlines more than two minutes in the future.

ServiceRouteFrontend

ServiceRouteFrontend declares the consumer-facing service address.

Appears in:

Field Description Default Validation
address string Address is translated to the ServiceEndpoint address for requests and is
restored as the source address for replies.

ServiceRouteNodeStatus

ServiceRouteNodeStatus acknowledges one node's current programmed path.

Appears in:

Field Description Default Validation
nodeName string
policyUID string
observedGeneration integer
inputDigest string
ready boolean
validUntil Time

ServiceRoutePolicy

ServiceRoutePolicy selects VPC attachments that should receive a route to a platform ServiceEndpoint. The selector is evaluated by the network control plane; Galactic compiles the selected attachments into dataplane state.

Field Description Default Validation
apiVersion string network.datumapis.com/v1alpha1
kind string ServiceRoutePolicy
kind string Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion string APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec ServiceRoutePolicySpec
status ServiceRoutePolicyStatus

ServiceRoutePolicySpec

ServiceRoutePolicySpec defines service selection and attachment eligibility.

Appears in:

Field Description Default Validation
serviceRef ServiceEndpointReference ServiceRef identifies the ServiceEndpoint in this namespace. Required: {}
consumerVPCRef ServiceRouteVPCReference ConsumerVPCRef pins authorization to the immutable lifetime of the VPC
selected by AttachmentSelector. Galactic resolves the name through the
Cloud API and requires both the live name and UID to match.
frontend ServiceRouteFrontend Frontend is the address presented inside the consumer VPC. When set,
Galactic translates it to the ServiceEndpoint address and restores it on
replies.
authorization ServiceRouteAuthorization Authorization bounds translated access independently of application leases.
Only trusted networking integration may renew this deadline.
attachmentSelector LabelSelector AttachmentSelector selects eligible VPC attachments by authoritative
labels. Labels that grant access to platform services must be assigned by
the network control plane, not by tenants.		 Required: {}
protocolPorts ServiceRouteProtocolPort array ProtocolPorts limits the traffic that the route is intended to carry.
An empty list means the endpoint's declared port and protocol are used.
region string Region limits selected attachments to a region. An empty value means the
policy applies in every region where the endpoint is available.

ServiceRoutePolicyStatus

ServiceRoutePolicyStatus contains policy conditions and fenced node reports.

Appears in:

Field Description Default Validation
observedGeneration integer ObservedGeneration is the .metadata.generation this status was computed from.
conditions Condition array Conditions contains durable acceptance and service-availability state.
nodes ServiceRouteNodeStatus array Nodes contains short-lived acknowledgments written by trusted node controllers.
Consumers require current UID, generation, input digest, and unexpired reports.

ServiceRouteProtocolPort

ServiceRouteProtocolPort identifies an allowed transport protocol and port.

Appears in:

Field Description Default Validation
port integer Port is the transport port. Maximum: 65535
Minimum: 1
Required: {}

ServiceRouteVPCReference

ServiceRouteVPCReference identifies one immutable Cloud API VPC lifetime.

Appears in:

Field Description Default Validation
name string Name is the VPC name in the policy namespace. MinLength: 1
uid string UID is the Kubernetes UID of that VPC lifetime. MinLength: 1

ServiceVIPBinding

ServiceVIPBinding drives one worker node's backend-side half of the DSR/Maglev load-balancer datapath: it tells the node which service VIP a specific local backend must be reachable on, so the backend can reply to clients directly (the "Direct Server Return" this design depends on — see NetworkGateway's doc comment). Generated, never written by users: galactic-router on each worker node writes one object per (service, VIP, backend) for every backend a NetworkService's BackendSelector places on that node, owned by the service, and the same process's per-node reconciler consumes it.

EgressKind decides which of two backend mechanisms this object drives, mirroring the same veth/tap fork the SRv6 uSID decap datapath already has (internal/plumbing/ebpf/usidmap's egress_kind field). Both mechanisms now converge on the same VIP-boundary substitution (BackendAddress:BackendPort for VIPAddress:Port at the SRv6 uSID TC-BPF boundary, usid_ingress's inbound half / usid_egress's outbound half) — required for both, not just tap, since a decapsulated ingress packet is delivered into the owning tenant's own VRF routing table, which has no route to an address bound outside that VRF (found live: see galactic's ServiceVIPBindingReconciler doc comment):

  • veth (container backend): the node ALSO binds VIPAddress on its own galactic-vip0 dummy interface (internal/plumbing/vip's Bind/Unbind/Verify in galactic) — this alone does not deliver anything to the backend pod (galactic-vip0 lives in the node's root namespace, not the tenant's VRF), but still lets the node itself verifiably answer on the VIP.
  • tap (VM backend): there is no guest-side configuration capability in this repo by design (internal/cnitap's own doc comment), so the substitution above is this kind's only delivery mechanism — the guest OS never needs to know the VIP exists at all.
Field Description Default Validation
apiVersion string network.datumapis.com/v1alpha1
kind string ServiceVIPBinding
kind string Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion string APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec ServiceVIPBindingSpec
status ServiceVIPBindingStatus

ServiceVIPBindingEgressKind

Underlying type: string

ServiceVIPBindingEgressKind mirrors usidmap's EgressKindVeth/EgressKindTap constants at the API layer — see ServiceVIPBinding's doc comment.

Validation:

  • Enum: [veth tap]

Appears in:

Field Description
veth ServiceVIPBindingEgressKindVeth selects the netns-bind mechanism.
tap ServiceVIPBindingEgressKindTap selects the transparent tap-boundary
translation mechanism.

ServiceVIPBindingSpec

ServiceVIPBindingSpec defines the desired VIP binding/translation state.

Appears in:

Field Description Default Validation
targetRef TargetRef TargetRef identifies the Node this binding applies to. Required: {}
vpcRef string VPCRef is the opaque identifier of the VPC the backend belongs to,
copied from the owning NetworkService. It names the tenant VRF the
binding's translation rows are written for, so two tenants using the
same backend address on one node never share a row.		 MinLength: 1
Required: {}
vipAddress string VIPAddress is the service VIP the backend must be reachable on. Required: {}
port integer Port is the VIP-facing port traffic arrives on. Maximum: 65535
Minimum: 1
Required: {}
backendAddress string BackendAddress is the backend's own real address (its pod-netns
address for a veth backend, or its actual guest-facing address for a
tap backend) — the VIP-boundary substitution target for both kinds
now (see EgressKind's own doc comment for why veth needs this too,
not just tap). +optional at the API level for the same reason
EgressKind itself carries no matching CEL requirement; the
reconciler validates it's set for either kind before doing anything.
backendPort integer BackendPort is the backend's own real port, paired with
BackendAddress — required for both kinds, see that field's doc
comment.		 Maximum: 65535
Minimum: 1
egressKind ServiceVIPBindingEgressKind EgressKind selects which backend mechanism this binding drives. Enum: [veth tap]
Required: {}

ServiceVIPBindingStatus

ServiceVIPBindingStatus defines the observed state of a ServiceVIPBinding.

Appears in:

Field Description Default Validation
observedGeneration integer ObservedGeneration is the .metadata.generation this status was computed from.
conditions Condition array Conditions contains the standard conditions for this resource,
including Bound (set True once internal/plumbing/vip.Verify or the
equivalent tap-translation-table check confirms the backend is
actually reachable on VIPAddress, not merely that the bind/table-write
call itself returned nil).

TargetRef

TargetRef identifies the execution target for a BGPRouter. Supported values for kind: Node.

Appears in:

Field Description Default Validation
kind string Kind is the target resource kind (e.g. Node). MinLength: 1
name string Name is the name of the target resource. MinLength: 1