From 37571d2fd3ed306ff9ee5120f01bbabf4c5306ac Mon Sep 17 00:00:00 2001 From: dfitzmau Date: Mon, 19 Jan 2026 12:04:12 +0000 Subject: [PATCH] OSDOCS-16863-3: CQA for MetalLB Ingress and Route Configuration --- modules/accept-any-ip-address.adoc | 28 ++++ modules/nw-metallb-configure-svc.adoc | 31 ++-- modules/nw-metallb-frr-configurations.adoc | 19 +-- .../nw-metallb-frr-k8s-configuration-crd.adoc | 146 +++++++---------- ...frr-k8s-merge-multiple-configurations.adoc | 21 +-- modules/request-ip-address-from-pool.adoc | 32 ++++ modules/request-specific-ip-address.adoc | 44 +++++ modules/share-specific-ip-address.adoc | 69 ++++++++ .../metallb/metallb-configure-services.adoc | 155 +----------------- .../metallb/metallb-frr-k8s.adoc | 11 +- 10 files changed, 278 insertions(+), 278 deletions(-) create mode 100644 modules/accept-any-ip-address.adoc create mode 100644 modules/request-ip-address-from-pool.adoc create mode 100644 modules/request-specific-ip-address.adoc create mode 100644 modules/share-specific-ip-address.adoc diff --git a/modules/accept-any-ip-address.adoc b/modules/accept-any-ip-address.adoc new file mode 100644 index 0000000000..dae7677041 --- /dev/null +++ b/modules/accept-any-ip-address.adoc @@ -0,0 +1,28 @@ +// Module included in the following assemblies: +// +// * /networking/ingress_load_balancing/metallb/metallb-configure-services.adoc + +:_mod-docs-content-type: REFERENCE +[id="accept-any-ip-address_{context}"] += Accept any IP address + +[role="_abstract"] +To automatically allocate IP addresses to services without manual specification, configure MetalLB address pools to permit automatic assignment. MetalLB dynamically assigns available addresses from these pools, ensuring seamless service deployment and network connectivity. + +.Example service YAML for accepting any IP address +[source,yaml] +---- +apiVersion: v1 +kind: Service +metadata: + name: +spec: + selector: + : + ports: + - port: 8080 + targetPort: 8080 + protocol: TCP + type: LoadBalancer +---- + diff --git a/modules/nw-metallb-configure-svc.adoc b/modules/nw-metallb-configure-svc.adoc index 8820d3d89b..716943239c 100644 --- a/modules/nw-metallb-configure-svc.adoc +++ b/modules/nw-metallb-configure-svc.adoc @@ -6,21 +6,19 @@ [id="nw-metallb-configure-svc_{context}"] = Configuring a service with MetalLB -You can configure a load-balancing service to use an external IP address from an address pool. +[role="_abstract"] +To expose an application to external network traffic, configure a load-balancing service. MetalLB assigns an external IP address from a configured address pool, ensuring that your application is reachable from outside the cluster. .Prerequisites -* Install the OpenShift CLI (`oc`). - +* Install the {oc-first}. * Install the MetalLB Operator and start MetalLB. - * Configure at least one address pool. - * Configure your network to route traffic from the clients to the host network for the cluster. .Procedure -. Create a `.yaml` file. In the file, ensure that the `spec.type` field is set to `LoadBalancer`. +. Create a `.yaml` file. In the file, set the `spec.type` parameter to `LoadBalancer`. + Refer to the examples for information about how to request the external IP address that MetalLB assigns to the service. @@ -51,27 +49,30 @@ $ oc describe service Name: Namespace: default Labels: -Annotations: metallb.io/address-pool: doc-example <1> +Annotations: metallb.io/address-pool: doc-example Selector: app=service_name -Type: LoadBalancer <2> +Type: LoadBalancer IP Family Policy: SingleStack IP Families: IPv4 IP: 10.105.237.254 IPs: 10.105.237.254 -LoadBalancer Ingress: 192.168.100.5 <3> +LoadBalancer Ingress: 192.168.100.5 Port: 80/TCP TargetPort: 8080/TCP NodePort: 30550/TCP Endpoints: 10.244.0.50:8080 Session Affinity: None External Traffic Policy: Cluster -Events: <4> +Events: Type Reason Age From Message ---- ------ ---- ---- ------- Normal nodeAssigned 32m (x2 over 32m) metallb-speaker announcing from node "" ---- -<1> The annotation is present if you request an IP address from a specific pool. -<2> The service type must indicate `LoadBalancer`. -<3> The load-balancer ingress field indicates the external IP address if the service is assigned correctly. -<4> The events field indicates the node name that is assigned to announce the external IP address. -If you experience an error, the events field indicates the reason for the error. ++ +where: ++ +`Annotations`:: Specifies the annotation that is present if you request an IP address from a specific pool. +`Type`:: Specifies the service type that must indicate `LoadBalancer`. +`LoadBalancer Ingress`:: Specifies the indicates the external IP address if the service is assigned correctly. +`Events`:: Specifies the events parameter that indicates the node name that is assigned to announce the external IP address. If you experience an error, the events parameter indicates the reason for the error. + diff --git a/modules/nw-metallb-frr-configurations.adoc b/modules/nw-metallb-frr-configurations.adoc index a449e8e715..d2b2a0ac6c 100644 --- a/modules/nw-metallb-frr-configurations.adoc +++ b/modules/nw-metallb-frr-configurations.adoc @@ -3,14 +3,13 @@ // * networking/metallb/metallb-frr-k8s.adoc :_mod-docs-content-type: REFERENCE -[id="nw-metallb-configuring-frr-k8s-configuratons_{context}"] +[id="nw-metallb-configuring-frr-k8s-configurations_{context}"] = FRR configurations -You can create multiple `FRRConfiguration` CRs to use `FRR` services in `MetalLB`. -`MetalLB` generates an `FRRConfiguration` object which `FRR-K8s` merges with all other configurations that all users have created. +[role="_abstract"] +You can create multiple `FRRConfiguration` CRs to use `FRR` services in `MetalLB`. -For example, you can configure `FRR-K8s` to receive all of the prefixes advertised by a given neighbor. -The following example configures `FRR-K8s` to receive all of the prefixes advertised by a `BGPPeer` with host `172.18.0.5`: +`MetalLB` generates an `FRRConfiguration` object which `FRR-K8s` merges with all other configurations that all users have created. For example, you can configure `FRR-K8s` to receive all of the prefixes advertised by a given neighbor. The following example configures `FRR-K8s` to receive all of the prefixes advertised by a `BGPPeer` with host `172.18.0.5`: .Example FRRConfiguration CR [source,yaml] @@ -30,11 +29,10 @@ spec: toReceive: allowed: mode: all +# ... ---- -You can also configure FRR-K8s to always block a set of prefixes, regardless of the configuration applied. -This can be useful to avoid routes towards the pods or `ClusterIPs` CIDRs that might result in cluster malfunctions. -The following example blocks the set of prefixes `192.168.1.0/24`: +You can also configure FRR-K8s to always block a set of prefixes, regardless of the configuration applied. This can be useful to avoid routes going to pods or `ClusterIPs` CIDRs that might result in cluster malfunctions. The following example blocks the set of prefixes `192.168.1.0/24`: .Example MetalLB CR [source,yaml] @@ -49,9 +47,10 @@ spec: frrk8sConfig: alwaysBlock: - 192.168.1.0/24 +# ... ---- -You can set `FRR-K8s` to block the `Cluster Network` CIDR and `Service Network` CIDR. -You can view the values for these CIDR address specifications by running the following command: + +You can set `FRR-K8s` to block the `clusterNetwork` CIDR and `serviceNetwork` CIDR. You can view the values for these CIDR address specifications by running the following command: [source,terminal] ---- diff --git a/modules/nw-metallb-frr-k8s-configuration-crd.adoc b/modules/nw-metallb-frr-k8s-configuration-crd.adoc index 98b90e0365..cf96afdabf 100644 --- a/modules/nw-metallb-frr-k8s-configuration-crd.adoc +++ b/modules/nw-metallb-frr-k8s-configuration-crd.adoc @@ -6,13 +6,14 @@ [id="nw-metallb-frrconfiguration-crd_{context}"] = Configuring the FRRConfiguration CRD -The following section provides reference examples that use the `FRRConfiguration` custom resource (CR). +[role="_abstract"] +To customize routing behavior beyond standard MetalLB capabilities, configure the `FRRConfiguration` custom resource (CR). -[id="nw-metallb-frrconfiguration-crd-routers_{context}"] -== The routers field +The following reference examples demonstrate how to define specific FRRouting (FRR) parameters to enable advanced services, such as receiving routes: -You can use the `routers` field to configure multiple routers, one for each Virtual Routing and Forwarding (VRF) resource. -For each router, you must define the Autonomous System Number (ASN). +The `routers` parameter:: + +You can use the `routers` parameter to configure multiple routers, one for each Virtual Routing and Forwarding (VRF) resource. For each router, you must define the Autonomous System Number (ASN). You can also define a list of Border Gateway Protocol (BGP) neighbors to connect to, as in the following example: @@ -36,13 +37,12 @@ spec: - address: 172.18.0.6 asn: 4200000000 port: 179 +# ... ---- -[id="nw-metallb-frrconfiguration-crd-toadvertise_{context}"] -== The toAdvertise field +The `toAdvertise` parameter:: -By default, `FRR-K8s` does not advertise the prefixes configured as part of a router configuration. -In order to advertise them, you use the `toAdvertise` field. +By default, `FRR-K8s` does not advertise the prefixes configured as part of a router configuration. To advertise the prefixes, you use the `toAdvertise` parameter. You can advertise a subset of the prefixes, as in the following example: @@ -65,13 +65,14 @@ spec: port: 180 toAdvertise: allowed: - prefixes: <1> + prefixes: - 192.168.2.0/24 prefixes: - 192.168.2.0/24 - 192.169.2.0/24 +# ... ---- -<1> Advertises a subset of prefixes. +* `allowed.prefixes`: Advertises a subset of prefixes. The following example shows you how to advertise all of the prefixes: @@ -94,18 +95,17 @@ spec: port: 180 toAdvertise: allowed: - mode: all <1> + mode: all prefixes: - 192.168.2.0/24 - 192.169.2.0/24 +# ... ---- -<1> Advertises all prefixes. +* `allowed.mode`: Advertises all prefixes. -[id="nw-metallb-frrconfiguration-crd-toreceive_{context}"] -== The toReceive field +The `toReceive` parameter:: -By default, `FRR-K8s` does not process any prefixes advertised by a neighbor. -You can use the `toReceive` field to process such addresses. +By default, `FRR-K8s` does not process any prefixes advertised by a neighbor. You can use the `toReceive` parameter to process such addresses. You can configure for a subset of the prefixes, as in this example: @@ -130,10 +130,11 @@ spec: prefixes: - prefix: 192.168.1.0/24 - prefix: 192.169.2.0/24 - ge: 25 <1> - le: 28 <1> + ge: 25 + le: 28 +# ... ---- -<1> The prefix is applied if the prefix length is less than or equal to the `le` prefix length and greater than or equal to the `ge` prefix length. +* `prefixes`: The prefix is applied if the prefix length is less than or equal to the `le` prefix length and greater than or equal to the `ge` prefix length. The following example configures FRR to handle all the prefixes announced: @@ -156,13 +157,12 @@ spec: toReceive: allowed: mode: all +# ... ---- -[id="nw-metallb-frrconfiguration-crd-bgp_{context}"] -== The bgp field +The `bgp` parameter:: -You can use the `bgp` field to define various `BFD` profiles and associate them with a neighbor. -In the following example, `BFD` backs up the `BGP` session and `FRR` can detect link failures: +You can use the `bgp` parameter to define various `BFD` profiles and associate them with a neighbor. In the following example, `BFD` backs up the `BGP` session and `FRR` can detect link failures: .Example FRRConfiguration CR [source,yaml] @@ -183,13 +183,13 @@ spec: bfdProfile: defaultprofile bfdProfiles: - name: defaultprofile +# ... ---- -[id="nw-metallb-frrconfiguration-crd-nodeselector_{context}"] -== The nodeSelector field +The `nodeSelector` parameter:: By default, `FRR-K8s` applies the configuration to all nodes where the daemon is running. -You can use the `nodeSelector` field to specify the nodes to which you want to apply the configuration. For example: +You can use the `nodeSelector` parameter to specify the nodes to which you want to apply the configuration. For example: .Example FRRConfiguration CR [source,yaml] @@ -206,12 +206,12 @@ spec: nodeSelector: labelSelector: foo: "bar" +# ... ---- -[id="nw-metallb-frrconfiguration-crd-interface_{context}"] -== The interface field +The `interface` parameter:: -You can use the `interface` field to configure unnumbered BGP peering by using the following example configuration: +You can use the `interface` parameter to configure unnumbered BGP peering by using the following example configuration: .Example `FRRConfiguration` CR [source,yaml] @@ -233,7 +233,7 @@ spec: - asn: 64512 bfdProfile: simple disableMP: false - interface: net10 <1> + interface: net10 port: 179 toAdvertise: allowed: @@ -245,25 +245,24 @@ spec: mode: filtered prefixes: - 5.5.5.5/32 +# ... ---- -<1> Activates unnumbered BGP peering. +* `neighbors.interface`: Activates unnumbered BGP peering. [NOTE] ==== -To use the `interface` field, you must establish a point-to-point, layer 2 connection between the two BGP peers. -You can use unnumbered BGP peering with IPv4, IPv6, or dual-stack, but you must enable IPv6 RAs (Router Advertisements). -Each interface is limited to one BGP connection. +To use the `interface` parameter, you must establish a point-to-point, layer 2 connection between the two BGP peers. You can use unnumbered BGP peering with IPv4, IPv6, or dual-stack, but you must enable IPv6 RAs (Router Advertisements). Each interface is limited to one BGP connection. -If you use this field, you cannot specify a value in the `spec.bgp.routers.neighbors.address` field. +If you use this parameter, you cannot specify a value in the `spec.bgp.routers.neighbors.address` parameter. ==== -The fields for the `FRRConfiguration` custom resource are described in the following table: +The parameters for the `FRRConfiguration` custom resource are described in the following table: .MetalLB FRRConfiguration custom resource [cols="1,1,3a", options="header"] |=== -|Field +|Parameter |Type |Description @@ -281,7 +280,7 @@ The fields for the `FRRConfiguration` custom resource are described in the follo |`spec.bgp.routers.vrf` |`string` -|Specifies the host vrf used to establish sessions from this router. +|Specifies the host VRF used to establish sessions from this router. |`spec.bgp.routers.neighbors` |`array` @@ -289,54 +288,40 @@ The fields for the `FRRConfiguration` custom resource are described in the follo |`spec.bgp.routers.neighbors.asn` |`integer` -|Specifies the ASN to use for the remote end of the session. -If you use this field, you cannot specify a value in the `spec.bgp.routers.neighbors.dynamicASN` field. +|Specifies the ASN to use for the remote end of the session. If you use this parameter, you cannot specify a value in the `spec.bgp.routers.neighbors.dynamicASN` parameter. |`spec.bgp.routers.neighbors.dynamicASN` |`string` |Detects the ASN to use for the remote end of the session without explicitly setting it. -Specify `internal` for a neighbor with the same ASN, or `external` for a neighbor with a different ASN. -If you use this field, you cannot specify a value in the `spec.bgp.routers.neighbors.asn` field. +Specify `internal` for a neighbor with the same ASN, or `external` for a neighbor with a different ASN. If you use this parameter, you cannot specify a value in the `spec.bgp.routers.neighbors.asn` parameter. |`spec.bgp.routers.neighbors.address` |`string` -|Specifies the IP address to establish the session with. -If you use this field, you cannot specify a value in the `spec.bgp.routers.neighbors.interface` field. +|Specifies the IP address to establish the session with. If you use this parameter, you cannot specify a value in the `spec.bgp.routers.neighbors.interface` parameter. |`spec.bgp.routers.neighbors.interface` |`string` -|Specifies the interface name to use when establishing a session. -Use this field to configure unnumbered BGP peering. -There must be a point-to-point, layer 2 connection between the two BGP peers. -You can use unnumbered BGP peering with IPv4, IPv6, or dual-stack, but you must enable IPv6 RAs (Router Advertisements). -Each interface is limited to one BGP connection. +|Specifies the interface name to use when establishing a session. Use this parameter to configure unnumbered BGP peering. There must be a point-to-point, layer 2 connection between the two BGP peers. You can use unnumbered BGP peering with IPv4, IPv6, or dual-stack, but you must enable IPv6 RAs (Router Advertisements). Each interface is limited to one BGP connection. |`spec.bgp.routers.neighbors.port` |`integer` -|Specifies the port to dial when establishing the session. -Defaults to 179. +|Specifies the port to dial when establishing the session. Defaults to `179`. |`spec.bgp.routers.neighbors.password` |`string` -|Specifies the password to use for establishing the BGP session. -`Password` and `PasswordSecret` are mutually exclusive. +|Specifies the password to use for establishing the BGP session. `Password` and `PasswordSecret` are mutually exclusive. |`spec.bgp.routers.neighbors.passwordSecret` |`string` -|Specifies the name of the authentication secret for the neighbor. -The secret must be of type "kubernetes.io/basic-auth", and in the same namespace as the FRR-K8s daemon. -The key "password" stores the password in the secret. -`Password` and `PasswordSecret` are mutually exclusive. +|Specifies the name of the authentication secret for the neighbor. The secret must be of type "kubernetes.io/basic-auth", and in the same namespace as the FRR-K8s daemon. The key "password" stores the password in the secret. `Password` and `PasswordSecret` are mutually exclusive. |`spec.bgp.routers.neighbors.holdTime` |`duration` -|Specifies the requested BGP hold time, per RFC4271. -Defaults to 180s. +|Specifies the requested BGP hold time, per RFC4271. Defaults to 180s. |`spec.bgp.routers.neighbors.keepaliveTime` |`duration` -|Specifies the requested BGP keepalive time, per RFC4271. -Defaults to `60s`. +|Specifies the requested BGP keepalive time, per RFC4271. Defaults to `60s`. |`spec.bgp.routers.neighbors.connectTime` |`duration` @@ -344,12 +329,11 @@ Defaults to `60s`. |`spec.bgp.routers.neighbors.ebgpMultiHop` |`boolean` -|Indicates if the BGPPeer is multi-hops away. +|Indicates if the BGPPeer is a multi-hop away. |`spec.bgp.routers.neighbors.bfdProfile` |`string` -|Specifies the name of the BFD Profile to use for the BFD session associated with the BGP session. -If not set, the BFD session is not set up. +|Specifies the name of the BFD Profile to use for the BFD session associated with the BGP session. If not set, the BFD session is not set up. |`spec.bgp.routers.neighbors.toAdvertise.allowed` |`array` @@ -357,19 +341,15 @@ If not set, the BFD session is not set up. |`spec.bgp.routers.neighbors.toAdvertise.allowed.prefixes` |`string array` -|Specifies the list of prefixes to advertise to a neighbor. -This list must match the prefixes that you define in the router. +|Specifies the list of prefixes to advertise to a neighbor. This list must match the prefixes that you define in the router. |`spec.bgp.routers.neighbors.toAdvertise.allowed.mode` |`string` -|Specifies the mode to use when handling the prefixes. -You can set to `filtered` to allow only the prefixes in the prefixes list. -You can set to `all` to allow all the prefixes configured on the router. +|Specifies the mode to use when handling the prefixes. You can set to `filtered` to allow only the prefixes in the prefixes list. You can set to `all` to allow all the prefixes configured on the router. |`spec.bgp.routers.neighbors.toAdvertise.withLocalPref` |`array` -|Specifies the prefixes associated with an advertised local preference. -You must specify the prefixes associated with a local preference in the prefixes allowed to be advertised. +|Specifies the prefixes associated with an advertised local preference. You must specify the prefixes associated with a local preference in the prefixes allowed to be advertised. |`spec.bgp.routers.neighbors.toAdvertise.withLocalPref.prefixes` |`string array` @@ -381,8 +361,7 @@ You must specify the prefixes associated with a local preference in the prefixes |`spec.bgp.routers.neighbors.toAdvertise.withCommunity` |`array` -|Specifies the prefixes associated with an advertised BGP community. -You must include the prefixes associated with a local preference in the list of prefixes that you want to advertise. +|Specifies the prefixes associated with an advertised BGP community. You must include the prefixes associated with a local preference in the list of prefixes that you want to advertise. |`spec.bgp.routers.neighbors.toAdvertise.withCommunity.prefixes` |`string array` @@ -406,9 +385,7 @@ You must include the prefixes associated with a local preference in the list of |`spec.bgp.routers.neighbors.toReceive.allowed.mode` |`string` -|Specifies the mode to use when handling the prefixes. -When set to `filtered`, only the prefixes in the `prefixes` list are allowed. -When set to `all`, all the prefixes configured on the router are allowed. +|Specifies the mode to use when handling the prefixes. When set to `filtered`, only the prefixes in the `prefixes` list are allowed. When set to `all`, all the prefixes configured on the router are allowed. |`spec.bgp.routers.neighbors.disableMP` |`boolean` @@ -420,7 +397,7 @@ When set to `all`, all the prefixes configured on the router are allowed. |`spec.bgp.bfdProfiles` |`array` -|Specifies the list of bfd profiles to use when configuring the neighbors. +|Specifies the list of BFD profiles to use when configuring the neighbors. |`spec.bgp.bfdProfiles.name` |`string` @@ -438,18 +415,15 @@ Defaults to `300ms`. |`spec.bgp.bfdProfiles.detectMultiplier` |`integer` -|Configures the detection multiplier to determine packet loss. -To determine the connection loss-detection timer, multiply the remote transmission interval by this value. +|Configures the detection multiplier to determine packet loss. To determine the connection loss-detection timer, multiply the remote transmission interval by this value. |`spec.bgp.bfdProfiles.echoInterval` |`integer` -|Configures the minimal echo receive transmission-interval that this system can handle, in milliseconds. -Defaults to `50ms`. +|Configures the minimal echo receive transmission-interval that this system can handle, in milliseconds. Defaults to `50ms`. |`spec.bgp.bfdProfiles.echoMode` |`boolean` -|Enables or disables the echo transmission mode. -This mode is disabled by default, and not supported on multihop setups. +|Enables or disables the echo transmission mode. This mode is disabled by default, and not supported on multihop setups. |`spec.bgp.bfdProfiles.passiveMode` |`boolean` @@ -462,9 +436,7 @@ Configures the minimum expected TTL for an incoming BFD control packet. |`spec.nodeSelector` |`string` -|Limits the nodes that attempt to apply this configuration. -If specified, only those nodes whose labels match the specified selectors attempt to apply the configuration. -If it is not specified, all nodes attempt to apply this configuration. +|Limits the nodes that attempt to apply this configuration. If specified, only those nodes whose labels match the specified selectors attempt to apply the configuration. If it is not specified, all nodes attempt to apply this configuration. |`status` |`string` diff --git a/modules/nw-metallb-frr-k8s-merge-multiple-configurations.adoc b/modules/nw-metallb-frr-k8s-merge-multiple-configurations.adoc index d9439e2a58..6ef6ff805e 100644 --- a/modules/nw-metallb-frr-k8s-merge-multiple-configurations.adoc +++ b/modules/nw-metallb-frr-k8s-merge-multiple-configurations.adoc @@ -6,12 +6,10 @@ [id="nw-metallb-frr-k8s-merge-multiple-configurations_{context}"] = How FRR-K8s merges multiple configurations -In a case where multiple users add configurations that select the same node, `FRR-K8s` merges the configurations. -Each configuration can only extend others. -This means that it is possible to add a new neighbor to a router, or to advertise an additional prefix to a neighbor, but not possible to remove a component added by another configuration. +[role="_abstract"] +FRR-K8s uses an additive merge strategy when multiple users configure the same node. By using FRR-K8s, you can extend existing configurations, such as adding neighbors or prefixes, but prevent the removal of components defined by other sources. -[id="nw-metallb-frr-k8s-merge-multiple-configuration-conflicts_{context}"] -== Configuration conflicts +Configuration conflicts:: Certain configurations can cause conflicts, leading to errors, for example: @@ -21,17 +19,16 @@ Certain configurations can cause conflicts, leading to errors, for example: When the daemon finds an invalid configuration for a node, it reports the configuration as invalid and reverts to the previous valid `FRR` configuration. -[id="nw-metallb-frr-k8s-merge-multiple-configurations-merging_{context}"] -== Merging +Merging:: -When merging, it is possible to do the following actions: +When merging, iyou can complete the following actions: -* Extend the set of IPs that you want to advertise to a neighbor. -* Add an extra neighbor with its set of IPs. -* Extend the set of IPs to which you want to associate a community. +* Extend the set of IP addresses that you want to advertise to a neighbor. +* Add an extra neighbor with its set of IP addresses. +* Extend the set of IP addresses to which you want to associate a community. * Allow incoming routes for a neighbor. -Each configuration must be self contained. This means, for example, that it is not possible to allow prefixes that are not defined in the router section by leveraging prefixes coming from another configuration. +Each configuration must be self contained. This means, for example, that you cannot allow prefixes that are not defined in the router section by leveraging prefixes coming from another configuration. If the configurations to be applied are compatible, merging works as follows: diff --git a/modules/request-ip-address-from-pool.adoc b/modules/request-ip-address-from-pool.adoc new file mode 100644 index 0000000000..a3a8b086fb --- /dev/null +++ b/modules/request-ip-address-from-pool.adoc @@ -0,0 +1,32 @@ +// Module included in the following assemblies: +// +// * /networking/ingress_load_balancing/metallb/metallb-configure-services.adoc + +:_mod-docs-content-type: REFERENCE +[id="request-ip-address-from-pool_{context}"] += Request an IP address from a specific pool + +[role="_abstract"] +To ensure predictable network endpoints, control how MetalLB assigns IP addresses to services of type `LoadBalancer`. Requesting specific addresses or pools ensures that your applications receive valid IP assignments that align with your specific network addressing plan. + +.Example service YAML for an IP address from a specific pool +[source,yaml] +---- +apiVersion: v1 +kind: Service +metadata: + name: + annotations: + metallb.io/address-pool: +spec: + selector: + : + ports: + - port: 8080 + targetPort: 8080 + protocol: TCP + type: LoadBalancer +---- + +If the address pool that you specify for `` does not exist, MetalLB attempts to assign an IP address from any pool that permits automatic assignment. + diff --git a/modules/request-specific-ip-address.adoc b/modules/request-specific-ip-address.adoc new file mode 100644 index 0000000000..a29bd33e9d --- /dev/null +++ b/modules/request-specific-ip-address.adoc @@ -0,0 +1,44 @@ +// Module included in the following assemblies: +// +// * /networking/ingress_load_balancing/metallb/metallb-configure-services.adoc + +:_mod-docs-content-type: REFERENCE +[id="request-specific-ip-address_{context}"] += Request a specific IP address + +[role="_abstract"] +To assign a specific, static IP address to a service, configure the `spec.loadBalancerIP` parameter in the service specification. + +MetalLB attempts to assign the requested address from the configured address pools, ensuring that your service is reachable at a designated, static network endpoint. If the requested IP address is not within any range, MetalLB reports a warning. + +.Example service YAML for a specific IP address +[source,yaml] +---- +apiVersion: v1 +kind: Service +metadata: + name: + annotations: + metallb.io/address-pool: +spec: + selector: + : + ports: + - port: 8080 + targetPort: 8080 + protocol: TCP + type: LoadBalancer + loadBalancerIP: +---- + +If MetalLB cannot assign the requested IP address, the `EXTERNAL-IP` for the service reports `` and running `oc describe service ` includes an event like the following example: + +.Example event when MetalLB cannot assign a requested IP address +[source,terminal] +---- + ... +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Warning AllocationFailed 3m16s metallb-controller Failed to allocate IP for "default/invalid-request": "4.3.2.1" is not allowed in config +---- diff --git a/modules/share-specific-ip-address.adoc b/modules/share-specific-ip-address.adoc new file mode 100644 index 0000000000..3ec8a4f397 --- /dev/null +++ b/modules/share-specific-ip-address.adoc @@ -0,0 +1,69 @@ +// Module included in the following assemblies: +// +// * /networking/ingress_load_balancing/metallb/metallb-configure-services.adoc + +:_mod-docs-content-type: REFERENCE +[id="share-specific-ip-address_{context}"] += Share a specific IP address + +[role="_abstract"] +To colocate multiple services on a single IP address, apply the `metallb.io/allow-shared-ip` annotation to your service specifications. Configuring this annotation authorizes MetalLB to assign the same IP to multiple services, enabling efficient address usage while distinguishing traffic by port. + +By default, services do not share IP addresses. + +[source,yaml] +---- +apiVersion: v1 +kind: Service +metadata: + name: service-http + annotations: + metallb.io/address-pool: doc-example + metallb.io/allow-shared-ip: "web-server-svc" +spec: + ports: + - name: http + port: 80 + protocol: TCP + targetPort: 8080 + selector: + : + type: LoadBalancer + loadBalancerIP: 172.31.249.7 +# ... +--- +apiVersion: v1 +kind: Service +metadata: + name: service-https + annotations: + metallb.io/address-pool: doc-example + metallb.io/allow-shared-ip: "web-server-svc" +spec: + ports: + - name: https + port: 443 + protocol: TCP + targetPort: 8080 + selector: + : + type: LoadBalancer + loadBalancerIP: 172.31.249.7 +# ... +---- + +where: + +`metallb.io/allow-shared-ip`:: Specifies the same value for the `metallb.io/allow-shared-ip` annotation. This value is referred to as the _sharing key_. +`name.port`:: Specifies different port numbers for the services. +`spec.selector`:: Specifies identical pod selectors if you must specify `externalTrafficPolicy: local` so the services send traffic to the same set of pods. If you use the `cluster` external traffic policy, then the pod selectors do not need to be identical. +`spec.loadBalancerIP`:: Optional parameter. If you specify the three preceding items, MetalLB might colocate the services on the same IP address. To ensure that services share an IP address, specify the IP address to share. + +By default, Kubernetes does not allow multiprotocol load balancer services. This limitation would normally make it impossible to run a service like DNS that needs to listen on both TCP and UDP. To work around this limitation of Kubernetes with MetalLB, create two services: + +* For one service, specify TCP and for the second service, specify UDP. + +* In both services, specify the same pod selector. + +* Specify the same sharing key and `spec.loadBalancerIP` value to colocate the TCP and UDP services on the same IP address. + diff --git a/networking/ingress_load_balancing/metallb/metallb-configure-services.adoc b/networking/ingress_load_balancing/metallb/metallb-configure-services.adoc index 11bd6e2616..53d2bc11c5 100644 --- a/networking/ingress_load_balancing/metallb/metallb-configure-services.adoc +++ b/networking/ingress_load_balancing/metallb/metallb-configure-services.adoc @@ -6,158 +6,15 @@ include::_attributes/common-attributes.adoc[] toc::[] -As a cluster administrator, when you add a service of type `LoadBalancer`, you can control how MetalLB assigns an IP address. +[role="_abstract"] +To ensure predictable network endpoints, control how MetalLB assigns IP addresses to services of type `LoadBalancer`. Requesting specific addresses or pools ensures that your applications receive valid IP assignments that align with your specific network addressing plan. -// Request a specific IP address -[id="request-specific-ip-address_{context}"] -== Request a specific IP address +include::modules/request-specific-ip-address.adoc[leveloffset=+1] -Like some other load-balancer implementations, MetalLB accepts the `spec.loadBalancerIP` field in the service specification. +include::modules/request-ip-address-from-pool.adoc[leveloffset=+1] -If the requested IP address is within a range from any address pool, MetalLB assigns the requested IP address. -If the requested IP address is not within any range, MetalLB reports a warning. +include::modules/accept-any-ip-address.adoc[leveloffset=+1] -.Example service YAML for a specific IP address -[source,yaml] ----- -apiVersion: v1 -kind: Service -metadata: - name: - annotations: - metallb.io/address-pool: -spec: - selector: - : - ports: - - port: 8080 - targetPort: 8080 - protocol: TCP - type: LoadBalancer - loadBalancerIP: ----- +include::modules/share-specific-ip-address.adoc[leveloffset=+1] -If MetalLB cannot assign the requested IP address, the `EXTERNAL-IP` for the service reports `` and running `oc describe service ` includes an event like the following example. - -.Example event when MetalLB cannot assign a requested IP address -[source,terminal] ----- - ... -Events: - Type Reason Age From Message - ---- ------ ---- ---- ------- - Warning AllocationFailed 3m16s metallb-controller Failed to allocate IP for "default/invalid-request": "4.3.2.1" is not allowed in config ----- - -[id="request-ip-address-from-pool_{context}"] -== Request an IP address from a specific pool - -To assign an IP address from a specific range, but you are not concerned with the specific IP address, then you can use the `metallb.io/address-pool` annotation to request an IP address from the specified address pool. - -.Example service YAML for an IP address from a specific pool -[source,yaml] ----- -apiVersion: v1 -kind: Service -metadata: - name: - annotations: - metallb.io/address-pool: -spec: - selector: - : - ports: - - port: 8080 - targetPort: 8080 - protocol: TCP - type: LoadBalancer ----- - -If the address pool that you specify for `` does not exist, MetalLB attempts to assign an IP address from any pool that permits automatic assignment. - -[id="accept-any-ip-address_{context}"] -== Accept any IP address - -By default, address pools are configured to permit automatic assignment. -MetalLB assigns an IP address from these address pools. - -To accept any IP address from any pool that is configured for automatic assignment, no special annotation or configuration is required. - -.Example service YAML for accepting any IP address -[source,yaml] ----- -apiVersion: v1 -kind: Service -metadata: - name: -spec: - selector: - : - ports: - - port: 8080 - targetPort: 8080 - protocol: TCP - type: LoadBalancer ----- - -[id="share-specific-ip-address_{context}"] -== Share a specific IP address - -By default, services do not share IP addresses. -However, if you need to colocate services on a single IP address, you can enable selective IP sharing by adding the `metallb.io/allow-shared-ip` annotation to the services. - -[source,yaml] ----- -apiVersion: v1 -kind: Service -metadata: - name: service-http - annotations: - metallb.io/address-pool: doc-example - metallb.io/allow-shared-ip: "web-server-svc" <1> -spec: - ports: - - name: http - port: 80 <2> - protocol: TCP - targetPort: 8080 - selector: - : <3> - type: LoadBalancer - loadBalancerIP: 172.31.249.7 <4> ---- -apiVersion: v1 -kind: Service -metadata: - name: service-https - annotations: - metallb.io/address-pool: doc-example - metallb.io/allow-shared-ip: "web-server-svc" -spec: - ports: - - name: https - port: 443 - protocol: TCP - targetPort: 8080 - selector: - : - type: LoadBalancer - loadBalancerIP: 172.31.249.7 ----- -<1> Specify the same value for the `metallb.io/allow-shared-ip` annotation. This value is referred to as the _sharing key_. -<2> Specify different port numbers for the services. -<3> Specify identical pod selectors if you must specify `externalTrafficPolicy: local` so the services send traffic to the same set of pods. If you use the `cluster` external traffic policy, then the pod selectors do not need to be identical. -<4> Optional: If you specify the three preceding items, MetalLB might colocate the services on the same IP address. To ensure that services share an IP address, specify the IP address to share. - -By default, Kubernetes does not allow multiprotocol load balancer services. -This limitation would normally make it impossible to run a service like DNS that needs to listen on both TCP and UDP. -To work around this limitation of Kubernetes with MetalLB, create two services: - -* For one service, specify TCP and for the second service, specify UDP. - -* In both services, specify the same pod selector. - -* Specify the same sharing key and `spec.loadBalancerIP` value to colocate the TCP and UDP services on the same IP address. - -// Configuring a service with MetalLB include::modules/nw-metallb-configure-svc.adoc[leveloffset=+1] diff --git a/networking/ingress_load_balancing/metallb/metallb-frr-k8s.adoc b/networking/ingress_load_balancing/metallb/metallb-frr-k8s.adoc index a78390c1f4..d7b6577688 100644 --- a/networking/ingress_load_balancing/metallb/metallb-frr-k8s.adoc +++ b/networking/ingress_load_balancing/metallb/metallb-frr-k8s.adoc @@ -6,17 +6,18 @@ include::_attributes/common-attributes.adoc[] toc::[] -FRRouting (FRR) is a free, open source internet routing protocol suite for Linux and UNIX platforms. -`FRR-K8s` is a Kubernetes based DaemonSet that exposes a subset of the `FRR` API in a Kubernetes-compliant manner. -As a cluster administrator, you can use the `FRRConfiguration` custom resource (CR) to access some of the FRR services not provided by MetalLB, for example, receiving routes. -`MetalLB` generates the `FRR-K8s` configuration corresponding to the MetalLB configuration applied. +[role="_abstract"] +To access advanced routing services not natively provided by MetalLB, configure the `FRRConfiguration` custom resource (CR). Defining the CR exposes specific FRRouting (FRR) capabilities and extends the routing functionality of your cluster beyond standard MetalLB advertisements. + +FRRouting (FRR) is a free, open-source internet routing protocol suite for Linux and UNIX platforms. `FRR-K8s` is a Kubernetes-based DaemonSet that exposes a subset of the `FRR` API in a Kubernetes-compliant manner. `MetalLB` generates the `FRR-K8s` configuration corresponding to the MetalLB configuration applied. image::695_OpenShift_MetalLB_FRRK8s_integration_0624.png[MetalLB integration with FRR] [WARNING] ==== -When configuring Virtual Route Forwarding (VRF) users must change their VRFs to a table ID lower than 1000 as higher than 1000 is reserved for {product-title}. +When configuring Virtual Route Forwarding (VRF), you must change the VRFs to a table ID lower than `1000` as higher than `1000` is reserved for {product-title}. ==== + // FRR configurations include::modules/nw-metallb-frr-configurations.adoc[leveloffset=+1]