Skip to content

API-DOCS.md

Latest commit

 

History

History
725 lines (372 loc) · 28.3 KB

API-DOCS.md

File metadata and controls

725 lines (372 loc) · 28.3 KB
Raw

API Reference

Packages

frrk8s.metallb.io/v1beta1

Package v1alpha1 contains API Schema definitions for the frrk8s v1alpha1 API group

Resource Types

AddressFamily

Underlying type: string

AddressFamily specifies an address family for BGP neighbor activation.

Validation:

  • Enum: [unicast evpn]

Appears in:

Field Description
unicast
evpn

Advertise

Appears in:

Field Description Default Validation
allowed AllowedOutPrefixes Allowed is is the list of prefixes allowed to be propagated to
this neighbor. They must match the prefixes defined in the router.
nextHop NextHop NextHop sets the BGP next-hop address to advertise with prefixes
sent to this neighbor.		 Optional: {}
withLocalPref LocalPrefPrefixes array PrefixesWithLocalPref is a list of prefixes that are associated to a local
preference when being advertised. The prefixes associated to a given local pref
must be in the prefixes allowed to be advertised.		 Optional: {}
withCommunity CommunityPrefixes array PrefixesWithCommunity is a list of prefixes that are associated to a
bgp community when being advertised. The prefixes associated to a given local pref
must be in the prefixes allowed to be advertised.		 Optional: {}

AdvertisePrefixType

Underlying type: string

AdvertisePrefixType specifies a prefix type to advertise as EVPN type-5 routes.

Validation:

  • Enum: [unicast]

Appears in:

Field Description
unicast

AllowAsInMode

Underlying type: string

AllowAsInMode specifies whether routes with the local AS in the path are accepted from a neighbor.

Validation:

  • Enum: [ none origin 1 2 3 4 5 6 7 8 9 10]

Appears in:

Field Description
none
origin

AllowedInPrefixes

Appears in:

Field Description Default Validation
prefixes PrefixSelector array

AllowedOutPrefixes

Appears in:

Field Description Default Validation
prefixes string array

BFDProfile

BFDProfile is the configuration related to the BFD protocol associated to a BGP session.

Appears in:

Field Description Default Validation
name string The name of the BFD Profile to be referenced in other parts
of the configuration.
receiveInterval integer The minimum interval that this system is capable of
receiving control packets in milliseconds.
Defaults to 300ms.		 Maximum: 60000
Minimum: 10
Optional: {}
transmitInterval integer The minimum transmission interval (less jitter)
that this system wants to use to send BFD control packets in
milliseconds. Defaults to 300ms		 Maximum: 60000
Minimum: 10
Optional: {}
detectMultiplier integer Configures the detection multiplier to determine
packet loss. The remote transmission interval will be multiplied
by this value to determine the connection loss detection timer.		 Maximum: 255
Minimum: 2
Optional: {}
echoInterval integer Configures the minimal echo receive transmission
interval that this system is capable of handling in milliseconds.
Defaults to 50ms		 Maximum: 60000
Minimum: 10
Optional: {}
echoMode boolean Enables or disables the echo transmission mode.
This mode is disabled by default, and not supported on multi
hops setups.		 Optional: {}
passiveMode boolean Mark session as passive: a passive session will not
attempt to start the connection and will wait for control packets
from peer before it begins replying.		 Optional: {}
minimumTtl integer For multi hop sessions only: configure the minimum
expected TTL for an incoming BFD control packet.		 Maximum: 254
Minimum: 1
Optional: {}

BGPConfig

BGPConfig is the configuration related to the BGP protocol.

Appears in:

Field Description Default Validation
routers Router array Routers is the list of routers we want FRR to configure (one per VRF). MaxItems: 50
Optional: {}
bfdProfiles BFDProfile array BFDProfiles is the list of bfd profiles to be used when configuring the neighbors. Optional: {}

BGPSessionState

BGPSessionState exposes the status of a BGP Session from the FRR instance running on the node.

Field Description Default Validation
apiVersion string frrk8s.metallb.io/v1beta1
kind string BGPSessionState
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec BGPSessionStateSpec
status BGPSessionStateStatus

BGPSessionStateSpec

BGPSessionStateSpec defines the desired state of BGPSessionState.

Appears in:

BGPSessionStateStatus

BGPSessionStateStatus defines the observed state of BGPSessionState.

Appears in:

Field Description Default Validation
bgpStatus string
bfdStatus string
node string
peer string
vrf string

CommunityPrefixes

CommunityPrefixes is a list of prefixes associated to a community.

Appears in:

Field Description Default Validation
prefixes string array Prefixes is the list of prefixes associated to the community. Format: cidr
MinItems: 1
community string Community is the community associated to the prefixes.

DynamicASNMode

Underlying type: string

Appears in:

Field Description
internal
external

EVPNConfig

EVPNConfig contains configuration related to EVPN.

Appears in:

Field Description Default Validation
advertiseVNIs VNIAdvertisement AdvertiseVNIs controls how VNIs are advertised to EVPN neighbors.
- "Disabled": No VNI advertisements
- "All": Avertise all VNIs
Note: Can only be provided for router instances with EVPN neighbors.		 Enum: [Disabled All]
Optional: {}
advertiseSVI boolean AdvertiseSVI enables advertising the SVI IP/MAC as a type-2 route. Optional: {}
l2vnis L2VNI array L2VNIs contains configuration for Layer 2 VNIs.
Note: Can only be provided for router instances with EVPN neighbors.		 MaxItems: 10
Optional: {}
l3vni L3VNI L3VNI contains configuration for the Layer 3 VNI.
Note: Can only be provided for router instances with no neighbors.
This is a temporary limitation until proper EVPN prefix filtering is implemented.		 Optional: {}

ExportRouteTarget

Underlying type: string

ExportRouteTarget defines a BGP Extended Community for route filtering on export. Does NOT support wildcard matching (wildcards are only valid for import).

Validation:

  • MaxLength: 21

Appears in:

FRRConfiguration

FRRConfiguration is a piece of FRR configuration.

Field Description Default Validation
apiVersion string frrk8s.metallb.io/v1beta1
kind string FRRConfiguration
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec FRRConfigurationSpec
status FRRConfigurationStatus

FRRConfigurationSpec

FRRConfigurationSpec defines the desired state of FRRConfiguration.

Appears in:

Field Description Default Validation
bgp BGPConfig BGP is the configuration related to the BGP protocol. Optional: {}
raw RawConfig Raw is a snippet of raw frr configuration that gets appended to the
one rendered translating the type safe API.		 Optional: {}
nodeSelector LabelSelector NodeSelector limits the nodes that will attempt to apply this config.
When specified, the configuration will be considered only on nodes
whose labels match the specified selectors.
When it is not specified all nodes will attempt to apply this config.		 Optional: {}

FRRConfigurationStatus

FRRConfigurationStatus defines the observed state of FRRConfiguration.

Appears in:

FRRK8sConfiguration

FRRK8sConfiguration holds the FRR Operator configuration with global settings for the K8s and FRR.

Field Description Default Validation
apiVersion string frrk8s.metallb.io/v1beta1
kind string FRRK8sConfiguration
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec FRRK8sConfigurationSpec
status FRRK8sConfigurationStatus

FRRK8sConfigurationSpec

FRRK8sConfigurationSpec defines the desired state of FRRK8sConfiguration.

Appears in:

Field Description Default Validation
logLevel string LogLevel sets the logging verbosity for the FRR-K8s components at runtime.
When configured, this value overrides the defaults established by the --log-level CLI flag.
Valid values are: all, debug, info, warn, error, none.		 Enum: [all debug info warn error none]
Optional: {}

FRRK8sConfigurationStatus

FRRK8sConfigurationStatus defines the observed state of FRRK8sConfiguration.

Appears in:

FRRNodeState

FRRNodeState exposes the status of the FRR instance running on each node.

Field Description Default Validation
apiVersion string frrk8s.metallb.io/v1beta1
kind string FRRNodeState
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec FRRNodeStateSpec
status FRRNodeStateStatus

FRRNodeStateSpec

FRRNodeStateSpec defines the desired state of FRRNodeState.

Appears in:

FRRNodeStateStatus

FRRNodeStateStatus defines the observed state of FRRNodeState.

Appears in:

Field Description Default Validation
runningConfig string RunningConfig represents the current FRR running config, which is the configuration the FRR instance is currently running with.
lastConversionResult string LastConversionResult is the status of the last translation between the FRRConfigurations resources and FRR's configuration, contains "success" or an error.
lastReloadResult string LastReloadResult represents the status of the last configuration update operation by FRR, contains "success" or an error.

Import

Import represents the possible imported VRFs to a given router.

Appears in:

Field Description Default Validation
vrf string Vrf is the vrf we want to import from Optional: {}

ImportRouteTarget

Underlying type: string

ImportRouteTarget defines a BGP Extended Community for route filtering on import. Supports wildcard matching with "" as the global administrator (e.g., ":100").

Validation:

  • MaxLength: 21

Appears in:

L2VNI

L2VNI represents a Layer 2 VNI configuration.

Appears in:

Field Description Default Validation
vni integer VNI is the VXLAN Network Identifier (1-16777215). Maximum: 1.6777215e+07
Minimum: 1
Required: {}
rd RouteDistinguisher RD is the route distinguisher for this VNI.
Format: A.B.C.D:MN|EF:OPQR|GHJK:MN (e.g., "65000:100" or "192.0.2.1:100")		 MaxLength: 21
Optional: {}
importRTs ImportRouteTarget array ImportRTs is the list of route targets to import.
Format: A.B.C.D:MN|EF:OPQR|GHJK:MN|:MN|:OPQR (e.g., "65000:100", "192.0.2.1:100", "*:100")		 MaxItems: 100
MaxLength: 21
Optional: {}
exportRTs ExportRouteTarget array ExportRTs is the list of route targets to export.
Format: A.B.C.D:MN|EF:OPQR|GHJK:MN (e.g., "65000:100", "192.0.2.1:100")		 MaxItems: 100
MaxLength: 21
Optional: {}

L3VNI

L3VNI represents a Layer 3 VNI configuration.

Appears in:

Field Description Default Validation
vni integer VNI is the VXLAN Network Identifier (1-16777215). Maximum: 1.6777215e+07
Minimum: 1
Required: {}
rd RouteDistinguisher RD is the route distinguisher for this VNI.
Format: A.B.C.D:MN|EF:OPQR|GHJK:MN (e.g., "65000:100" or "192.0.2.1:100")		 MaxLength: 21
Optional: {}
importRTs ImportRouteTarget array ImportRTs is the list of route targets to import.
Format: A.B.C.D:MN|EF:OPQR|GHJK:MN|:MN|:OPQR (e.g., "65000:100", "192.0.2.1:100", "*:100")		 MaxItems: 100
MaxLength: 21
Optional: {}
exportRTs ExportRouteTarget array ExportRTs is the list of route targets to export.
Format: A.B.C.D:MN|EF:OPQR|GHJK:MN (e.g., "65000:100", "192.0.2.1:100")		 MaxItems: 100
MaxLength: 21
Optional: {}
advertisePrefixes AdvertisePrefixType array AdvertisePrefixes controls which prefixes to advertise as EVPN type-5 routes.
- "unicast": advertise the unicast prefixes of the router.		 Enum: [unicast]
MaxItems: 1
MinItems: 1
Required: {}

LocalPrefPrefixes

LocalPrefPrefixes is a list of prefixes associated to a local preference.

Appears in:

Field Description Default Validation
prefixes string array Prefixes is the list of prefixes associated to the local preference. Format: cidr
MinItems: 1
localPref integer LocalPref is the local preference associated to the prefixes.

Neighbor

Neighbor represents a BGP Neighbor we want FRR to connect to.

Appears in:

Field Description Default Validation
asn integer ASN is the AS number to use for the local end of the session.
ASN and DynamicASN are mutually exclusive and one of them must be specified.		 Format: int64
Maximum: 4.294967295e+09
Minimum: 0
Optional: {}
dynamicASN DynamicASNMode DynamicASN detects the AS number to use for the local end of the session
without explicitly setting it via the ASN field. Limited to:
internal - if the neighbor's ASN is different than the router's the connection is denied.
external - if the neighbor's ASN is the same as the router's the connection is denied.
ASN and DynamicASN are mutually exclusive and one of them must be specified.		 Enum: [internal external]
Optional: {}
sourceaddress string SourceAddress is the IPv4 or IPv6 source address to use for the BGP
session to this neighbour, may be specified as either an IP address
directly or as an interface name		 Optional: {}
address string Address is the IP address to establish the session with. Optional: {}
interface string Interface is the node interface over which the unnumbered BGP peering will
be established. No API validation takes place as that string value
represents an interface name on the host and if user provides an invalid
value, only the actual BGP session will not be established.
Address and Interface are mutually exclusive and one of them must be specified.
Note: when enabling unnumbered, the neighbor will be enabled for both
IPv4 and IPv6 address families.		 Optional: {}
port integer Port is the port to dial when establishing the session.
Defaults to 179.		 Maximum: 16384
Minimum: 0
Optional: {}
password string Password to be used for establishing the BGP session.
Password and PasswordSecret are mutually exclusive.		 Optional: {}
passwordSecret SecretReference PasswordSecret is name of the authentication secret for the neighbor.
the secret must be of type "kubernetes.io/basic-auth", and created in the
same namespace as the frr-k8s daemon. The password is stored in the
secret as the key "password".
Password and PasswordSecret are mutually exclusive.		 Optional: {}
holdTime Duration HoldTime is the requested BGP hold time, per RFC4271.
Defaults to 180s.		 Optional: {}
keepaliveTime Duration KeepaliveTime is the requested BGP keepalive time, per RFC4271.
Defaults to 60s.		 Optional: {}
connectTime Duration Requested BGP connect time, controls how long BGP waits between connection attempts to a neighbor. Optional: {}
ebgpMultiHop boolean EBGPMultiHop indicates if the BGPPeer is multi-hops away. Optional: {}
bfdProfile string BFDProfile is the name of the BFD Profile to be used for the BFD session associated
to the BGP session. If not set, the BFD session won't be set up.		 Optional: {}
enableGracefulRestart boolean EnableGracefulRestart allows BGP peer to continue to forward data packets along
known routes while the routing protocol information is being restored. If
the session is already established, the configuration will have effect
after reconnecting to the peer		 Optional: {}
toAdvertise Advertise ToAdvertise represents the list of prefixes to advertise to the given neighbor
and the associated properties. Only applies to IPv4 and IPv6 unicast address families.		 Optional: {}
toReceive Receive ToReceive represents the list of prefixes to receive from the given neighbor.
Only applies to IPv4 and IPv6 unicast address families.		 Optional: {}
disableMP boolean DisableMP is no longer used and has no effect.
Use DualStackAddressFamily instead to enable the neighbor for both IPv4 and IPv6 address families.
Deprecated: This field is ignored. Use DualStackAddressFamily instead.		 false Optional: {}
dualStackAddressFamily boolean To set if we want to enable the neighbor not only for the ipfamily related to its session,
but also the other one. This allows to advertise/receive IPv4 prefixes over IPv6 sessions and vice versa.		 false Optional: {}
localASN integer LocalASN allows advertising a different AS number to the peer using BGP's
local-as feature. When set, FRR will advertise this ASN to the peer
via "neighbor local-as no-prepend replace-as", overriding
the router-level ASN for this specific session.
Note: this field is only applicable to eBGP sessions (where the peer ASN differs
from the router ASN). Setting it on an iBGP session is rejected.		 Format: int64
Maximum: 4.294967295e+09
Minimum: 1
Optional: {}
allowAsIn AllowAsInMode AllowAsIn controls whether routes with the local AS number in the AS path
are accepted from this neighbor for the enabled address families.
This is useful in hub-and-spoke or route-leaking topologies where the
same AS number may appear multiple times in the path.
Possible values:
- "" (empty, default): routes with the local AS in the path are rejected.
Does not reject other AllowAsIn values targeting the same neighbor.
- "none": routes with the local AS in the path are rejected.
Rejects other AllowAsIn values targeting the same neighbor.
- "origin": routes are accepted only if the local AS appears as the origin (last AS in the path).
- "1"-"10": routes are accepted with up to this many occurrences of the local AS in the path.
When multiple configurations target the same neighbor, any combination of
values resolves to the least restrictive, except "none" which rejects
all other values.		 Enum: [ none origin 1 2 3 4 5 6 7 8 9 10]
Optional: {}
addressFamilies AddressFamily array AddressFamilies specifies which address families to activate this neighbor for.
Supported values: "unicast" (IPv4/IPv6 unicast based on neighbor IP), "evpn" (L2VPN EVPN).		 [unicast] Enum: [unicast evpn]
MaxItems: 2
Optional: {}

NextHop

NextHop sets the BGP next-hop address for advertised prefixes.

Appears in:

Field Description Default Validation
ipv4 string IPv4 is the next-hop address to advertise with IPv4 prefixes. Format: ipv4
Optional: {}
ipv6 string IPv6 is the next-hop address to advertise with IPv6 prefixes. Format: ipv6
Optional: {}

PrefixSelector

PrefixSelector is a filter of prefixes to receive.

Appears in:

Field Description Default Validation
prefix string Format: cidr
le integer The prefix length modifier. This selector accepts any matching prefix with length
less or equal the given value.		 Maximum: 128
Minimum: 1
ge integer The prefix length modifier. This selector accepts any matching prefix with length
greater or equal the given value.		 Maximum: 128
Minimum: 1

RawConfig

RawConfig is a snippet of raw frr configuration that gets appended to the rendered configuration.

WARNING: The RawConfig feature is UNSUPPORTED and intended ONLY FOR EXPERIMENTATION. It should not be used in production environments. This feature is provided as-is without any guarantees of stability, compatibility, or support. Use at your own risk.

Appears in:

Field Description Default Validation
priority integer Priority is the order with this configuration is appended to the
bottom of the rendered configuration. A higher value means the
raw config is appended later in the configuration file.
rawConfig string Config is a raw FRR configuration to be appended to the configuration
rendered via the k8s api.

Receive

Receive represents a list of prefixes to receive from the given neighbor.

Appears in:

Field Description Default Validation
allowed AllowedInPrefixes Allowed is the list of prefixes allowed to be received from
this neighbor.		 Optional: {}

RouteDistinguisher

Underlying type: string

RouteDistinguisher defines an 8-byte BGP identifier.

Validation:

  • MaxLength: 21

Appears in:

Router

Router represent a neighbor router we want FRR to connect to.

Appears in:

Field Description Default Validation
asn integer ASN is the AS number to use for the local end of the session. Format: int64
Maximum: 4.294967295e+09
Minimum: 0
id string ID is the BGP router ID Optional: {}
vrf string VRF is the host vrf used to establish sessions from this router. Optional: {}
neighbors Neighbor array Neighbors is the list of neighbors we want to establish BGP sessions with. Optional: {}
prefixes string array Prefixes is the list of prefixes we want to advertise from this router instance. Optional: {}
imports Import array Imports is the list of imported VRFs we want for this router / vrf. Optional: {}
evpn EVPNConfig EVPN specific configuration for the router. Optional: {}

SecretReference

SecretReference represents a Secret Reference. It has enough information to retrieve secret in any namespace.

Appears in:

Field Description Default Validation
name string name is unique within a namespace to reference a secret resource. Optional: {}
namespace string namespace defines the space within which the secret name must be unique. Optional: {}

VNIAdvertisement

Underlying type: string

VNIAdvertisement defines how VNIs are advertised in EVPN.

Validation:

  • Enum: [Disabled All]

Appears in:

Field Description
Disabled VNIAdvertisementDisabled disables VNI advertisement.
All VNIAdvertisementAll enables advertisement of all VNIs.

VNIProperties

VNIProperties contains common properties for all VNI types.

Appears in:

Field Description Default Validation
rd RouteDistinguisher RD is the route distinguisher for this VNI.
Format: A.B.C.D:MN|EF:OPQR|GHJK:MN (e.g., "65000:100" or "192.0.2.1:100")		 MaxLength: 21
Optional: {}
importRTs ImportRouteTarget array ImportRTs is the list of route targets to import.
Format: A.B.C.D:MN|EF:OPQR|GHJK:MN|:MN|:OPQR (e.g., "65000:100", "192.0.2.1:100", "*:100")		 MaxItems: 100
MaxLength: 21
Optional: {}
exportRTs ExportRouteTarget array ExportRTs is the list of route targets to export.
Format: A.B.C.D:MN|EF:OPQR|GHJK:MN (e.g., "65000:100", "192.0.2.1:100")		 MaxItems: 100
MaxLength: 21
Optional: {}