From b45a5f5dc532b9024e07077fbc248301c7f5369a Mon Sep 17 00:00:00 2001 From: Kevin Quinn Date: Tue, 10 May 2022 12:23:15 +0100 Subject: [PATCH] TELCODOCS-506 Creating first commit MetalLB CRDs handled by MetalLB and new layout TELCODOCS-506 updates based on review 4 --- _topic_maps/_topic_map.yml | 8 +- .../metallb-installing-using-web-console.adoc | 35 ++++ .../nw-metalLB-basic-upgrade-operator.adoc | 64 +++++++ modules/nw-metalLB-monitor-upgrading.adoc | 53 ++++++ modules/nw-metallb-addresspool-cr.adoc | 78 ++------ ...ertise-address-pool-with-bgp-advanced.adoc | 96 ++++++++++ ...tallb-advertise-address-pool-with-bgp.adoc | 65 +++++++ modules/nw-metallb-bfdprofile-cr.adoc | 1 + modules/nw-metallb-bgp-limitations.adoc | 24 --- modules/nw-metallb-bgp.adoc | 9 +- modules/nw-metallb-bgpadvertisement-cr.adoc | 78 ++++++++ modules/nw-metallb-bgppeer-cr.adoc | 10 + modules/nw-metallb-community-cr.adoc | 57 ++++++ .../nw-metallb-configure-address-pool.adoc | 23 +-- modules/nw-metallb-configure-bfdprofle.adoc | 1 + ...-configure-bgp-advertisement-advanced.adoc | 23 +++ ...w-metallb-configure-bgp-advertisement.adoc | 10 + modules/nw-metallb-configure-bgppeer.adoc | 3 +- ...configure-community-bgp-advertisement.adoc | 113 +++++++++++ ...allb-configure-l2-advertisement-label.adoc | 71 +++++++ ...nw-metallb-configure-l2-advertisement.adoc | 64 +++++++ ...lb-configure-specificpools-to-bgppeer.adoc | 178 ++++++++++++++++++ modules/nw-metallb-configure-svc.adoc | 4 + modules/nw-metallb-example-addresspool.adoc | 74 +------- modules/nw-metallb-example-bgppeer.adoc | 1 + modules/nw-metallb-extern-traffic-pol.adoc | 9 + .../nw-metallb-installing-operator-cli.adoc | 84 ++++----- modules/nw-metallb-l2padvertisement-cr.adoc | 46 +++++ modules/nw-metallb-layer2.adoc | 6 + modules/nw-metallb-levels.adoc | 36 ++++ modules/nw-metallb-loglevel.adoc | 164 ++++++++++++++++ .../nw-metallb-operator-custom-resources.adoc | 35 ++-- .../nw-metallb-operator-initial-config.adoc | 7 +- modules/nw-metallb-software-components.adoc | 6 +- modules/nw-metallb-troubleshoot-bfd.adoc | 2 +- modules/nw-metallb-troubleshoot-bgp.adoc | 2 +- modules/nw-metallb-when-metallb.adoc | 1 + ...lb-operators-from-a-cluster-using-cli.adoc | 56 ++++++ ...tors-from-a-cluster-using-web-console.adoc | 31 +++ .../about-advertising-ipaddresspool.adoc | 45 +++++ networking/metallb/about-metallb.adoc | 14 +- .../metallb/metalb-upgrading-operator.adoc | 37 ++++ .../metallb-configure-address-pools.adoc | 9 +- .../metallb-configure-bfd-profiles.adoc | 1 + .../metallb/metallb-configure-bgp-peers.adoc | 7 +- .../metallb-configure-community-alias.adoc | 15 ++ .../metallb/metallb-operator-install.adoc | 19 +- .../metallb/metallb-troubleshoot-support.adoc | 13 +- 48 files changed, 1511 insertions(+), 277 deletions(-) create mode 100644 modules/metallb-installing-using-web-console.adoc create mode 100644 modules/nw-metalLB-basic-upgrade-operator.adoc create mode 100644 modules/nw-metalLB-monitor-upgrading.adoc create mode 100644 modules/nw-metallb-advertise-address-pool-with-bgp-advanced.adoc create mode 100644 modules/nw-metallb-advertise-address-pool-with-bgp.adoc create mode 100644 modules/nw-metallb-bgpadvertisement-cr.adoc create mode 100644 modules/nw-metallb-community-cr.adoc create mode 100644 modules/nw-metallb-configure-bgp-advertisement-advanced.adoc create mode 100644 modules/nw-metallb-configure-bgp-advertisement.adoc create mode 100644 modules/nw-metallb-configure-community-bgp-advertisement.adoc create mode 100644 modules/nw-metallb-configure-l2-advertisement-label.adoc create mode 100644 modules/nw-metallb-configure-l2-advertisement.adoc create mode 100644 modules/nw-metallb-configure-specificpools-to-bgppeer.adoc create mode 100644 modules/nw-metallb-l2padvertisement-cr.adoc create mode 100644 modules/nw-metallb-levels.adoc create mode 100644 modules/nw-metallb-loglevel.adoc create mode 100644 modules/olm-deleting-metallb-operators-from-a-cluster-using-cli.adoc create mode 100644 modules/olm-deleting-metallb-operators-from-a-cluster-using-web-console.adoc create mode 100644 networking/metallb/about-advertising-ipaddresspool.adoc create mode 100644 networking/metallb/metalb-upgrading-operator.adoc create mode 100644 networking/metallb/metallb-configure-community-alias.adoc diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index e466c19a37..481e9c1f7f 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -1222,15 +1222,21 @@ Topics: File: about-metallb - Name: Installing the MetalLB Operator File: metallb-operator-install + - Name: Upgrading the MetalLB Operator + File: metalb-upgrading-operator - Name: Configuring MetalLB address pools File: metallb-configure-address-pools + - Name: Advertising the IP address pools + File: about-advertising-ipaddresspool - Name: Configuring MetalLB BGP peers File: metallb-configure-bgp-peers + - Name: Advertising an IP address pool using the community alias + File: metallb-configure-community-alias - Name: Configuring MetalLB BFD profiles File: metallb-configure-bfd-profiles - Name: Configuring services to use MetalLB File: metallb-configure-services - - Name: MetalLB troubleshooting and support + - Name: MetalLB logging, troubleshooting, and support File: metallb-troubleshoot-support - Name: Associating secondary interfaces metrics to network attachments File: associating-secondary-interfaces-metrics-to-network-attachments diff --git a/modules/metallb-installing-using-web-console.adoc b/modules/metallb-installing-using-web-console.adoc new file mode 100644 index 0000000000..a83d800995 --- /dev/null +++ b/modules/metallb-installing-using-web-console.adoc @@ -0,0 +1,35 @@ +// Module included in the following assemblies: +// +// * networking/metallb/metallb-operator-install.adoc + +:_content-type: PROCEDURE +[id="installing-the-metallb-operator-using-web-console_{context}"] += Installing the MetalLB Operator from the OperatorHub using the web console + +As a cluster administrator, you can install the MetalLB Operator by using the {product-title} web console. + +.Prerequisites + +* Log in as a user with `cluster-admin` privileges. + +.Procedure + +. In the {product-title} web console, navigate to *Operators* -> *OperatorHub*. + +. Search for the MetalLB Operator, then click *Install*. + +. On the *Install Operator* page, accept the defaults and click *Install*. + +.Verification + +. To confirm that the installation is successful: + +.. Navigate to the *Operators* -> *Installed Operators* page. + +.. Check that the Operator is installed in the `openshift-operators` namespace and that its status is `Succeeded`. + +. If the Operator is not installed successfully, check the status of the Operator and review the logs: + +.. Navigate to the *Operators* -> *Installed Operators* page and inspect the `Status` column for any errors or failures. + +.. Navigate to the *Workloads* -> *Pods* page and check the logs in any pods in the `openshift-operators` project that are reporting issues. diff --git a/modules/nw-metalLB-basic-upgrade-operator.adoc b/modules/nw-metalLB-basic-upgrade-operator.adoc new file mode 100644 index 0000000000..153da7a34c --- /dev/null +++ b/modules/nw-metalLB-basic-upgrade-operator.adoc @@ -0,0 +1,64 @@ +// Module included in the following assemblies: +// +// * networking/metallb/metallb-upgrading-operator.adoc + +:_content-type: PROCEDURE + +[id="upgrading-metallb-operator_{context}"] += Upgrading the MetalLB Operator + + +.Prerequisites + +* Access the cluster as a user with the `cluster-admin` role. + +.Procedure + +. Verify that the `metallb-system` namespace still exists: ++ +[source,terminal] +---- +$ oc get namespaces | grep metallb-system +---- ++ +.Example output +[source,terminal] +---- +metallb-system Active 31m +---- + +. Verify the `metallb` custom resource still exists: ++ +[source,terminal] +---- +$ oc get metallb -n metallb-system +---- ++ +.Example output +[source,terminal] +---- +NAME AGE +metallb 33m +---- + +. Follow the guidance in "Installing from OperatorHub using the CLI" to install the latest {product-version} version of the MetalLB Operator. ++ +[NOTE] +==== +When installing the latest {product-version} version of the MetalLB Operator, you must install the Operator to the same namespace it was previously installed to. +==== + +. Verify the upgraded version of the Operator is now the {product-version} version. ++ +[source,terminal] +---- +$ oc get csv -n metallb-system +---- ++ +.Example output +[source,terminal] +---- +NAME DISPLAY VERSION REPLACES PHASE +metallb-operator.4.11.0-202207051316 MetalLB Operator 4.11.0-202207051316 Succeeded +---- + diff --git a/modules/nw-metalLB-monitor-upgrading.adoc b/modules/nw-metalLB-monitor-upgrading.adoc new file mode 100644 index 0000000000..008de862c6 --- /dev/null +++ b/modules/nw-metalLB-monitor-upgrading.adoc @@ -0,0 +1,53 @@ +// Module included in the following assemblies: +// +// * networking/metallb/metallb-upgrading-operator.adoc + +:_content-type: PROCEDURE + +[id="metalLB-operator-monitoring-upgrade-status_{context}"] += Monitoring upgrade status +The best way to monitor the MetalLB Operator upgrade status is to watch the `ClusterServiceVersion` (CSV) `PHASE`. +You can also monitor the CSV conditions in the web console or by running the `oc get csv` command. + +[NOTE] +==== +The `PHASE` and conditions values are approximations that are based on available information. +==== + +.Prerequisites + +* Access the cluster as a user with the `cluster-admin` role. + +* Install the OpenShift CLI (`oc`). + +.Procedure + +. Run the following command: ++ +[source,terminal] +---- +$ oc get csv +---- + +. Review the output, checking the `PHASE` field. For example: ++ +[source,terminal] +---- +VERSION REPLACES PHASE +4.11.0 metallb-operator.4.10-nnnnnnnnnnnn Installing +4.10.0 Replacing +---- + +. Run `get csv` again to verify the output: ++ +[source,terminal] +---- +$ oc get csv +---- ++ +.Example output +[source,terminal] +---- +NAME DISPLAY VERSION REPLACES PHASE +metallb-operator.4.11-nnnnnnnnnnnn MetalLB 4.11.0 metallb-operator.v4.10.0 Succeeded +---- diff --git a/modules/nw-metallb-addresspool-cr.adoc b/modules/nw-metallb-addresspool-cr.adoc index 4cb162a4d4..67cb61c044 100644 --- a/modules/nw-metallb-addresspool-cr.adoc +++ b/modules/nw-metallb-addresspool-cr.adoc @@ -1,14 +1,19 @@ - -:_content-type: CONCEPT // Module included in the following assemblies: // // * networking/metallb/metallb-configure-address-pools.adoc -[id="nw-metallb-addresspool-cr_{context}"] -= About the address pool custom resource -The fields for the address pool custom resource are described in the following table. +:_content-type: REFERENCE +[id="nw-metallb-ipaddresspool-cr_{context}"] += About the IPAddressPool custom resource -.MetalLB address pool custom resource +[NOTE] +==== +The address pool custom resource definition (CRD) and API documented in "Load balancing with MetalLB" in {product-title} 4.10 can still be used in {product-version}. However, the enhanced functionality associated with advertising the `IPAddressPools` with layer 2 or the BGP protocol is not supported when using the address pool CRD. +==== + +The fields for the `IPAddressPool` custom resource are described in the following table. + +.MetalLB IPAddressPool pool custom resource [cols="1,1,3a", options="header"] |=== @@ -27,10 +32,15 @@ The names `doc-example`, `silver`, and `gold` are used throughout the documentat |Specifies the namespace for the address pool. Specify the same namespace that the MetalLB Operator uses. -|`spec.protocol` +|`metadata.label` |`string` -|Specifies the protocol for announcing the load balancer IP address to peer nodes. -Specify `layer2` or `bgp`. +|Optional: Specifies the key value pair assigned to the `IPAddressPool`. This can be referenced by the `ipAddressPoolSelectors` in the `BGPAdvertisement` and `L2Advertisement` CRD to associate the `IPAddressPool` with the advertisement + +|`spec.addresses` +|`string` +|Specifies a list of IP addresses for MetalLB Operator to assign to services. +You can specify multiple ranges in a single pool; they will all share the same settings. +Specify each range in CIDR notation or as starting and ending IP addresses separated with a hyphen. |`spec.autoAssign` |`boolean` @@ -38,54 +48,4 @@ Specify `layer2` or `bgp`. Specify `false` if you want explicitly request an IP address from this pool with the `metallb.universe.tf/address-pool` annotation. The default value is `true`. -|`spec.addresses` -|`array` -|Specifies a list of IP addresses for MetalLB to assign to services. -You can specify multiple ranges in a single pool. -Specify each range in CIDR notation or as starting and ending IP addresses separated with a hyphen. - -|`spec.bgpAdvertisements` -|`object` -|Optional: By default, BGP mode advertises each allocated load-balancer IP address to the configured peers with no additional BGP attributes. -The peer routers receive one `/32` route for each service IP address, with the BGP local preference set to zero and no BGP communities. -Use this field to create custom advertisements. - -|=== - -The fields for the `bgpAdvertisements` object are defined in the following table: - -.BGP advertisements configuration -[cols="1,1,3a", options="header"] -|=== - -|Field -|Type -|Description - -|`aggregationLength` -|`integer` -|Optional: Specifies the number of bits to include in a 32-bit CIDR mask. -To aggregate the routes that the speaker advertises to BGP peers, the mask is applied to the routes for several service IP addresses and the speaker advertises the aggregated route. -For example, with an aggregation length of `24`, the speaker can aggregate several `10.0.1.x/32` service IP addresses and advertise a single `10.0.1.0/24` route. - -|`aggregationLengthV6` -|`integer` -|Optional: Specifies the number of bits to include in a 128-bit CIDR mask. -For example, with an aggregation length of `124`, the speaker can aggregate several `fc00:f853:0ccd:e799::x/128` service IP addresses and advertise a single `fc00:f853:0ccd:e799::0/124` route. - -|`community` -|`array` -|Optional: Specifies one or more BGP communities. -Each community is specified as two 16-bit values separated by the colon character. -Well-known communities must be specified as 16-bit values: - -* `NO_EXPORT`: `65535:65281` -* `NO_ADVERTISE`: `65535:65282` -* `NO_EXPORT_SUBCONFED`: `65535:65283` - -|`localPref` -|`integer` -|Optional: Specifies the local preference for this advertisement. -This BGP attribute applies to BGP sessions within the Autonomous System. - |=== diff --git a/modules/nw-metallb-advertise-address-pool-with-bgp-advanced.adoc b/modules/nw-metallb-advertise-address-pool-with-bgp-advanced.adoc new file mode 100644 index 0000000000..9c767cc314 --- /dev/null +++ b/modules/nw-metallb-advertise-address-pool-with-bgp-advanced.adoc @@ -0,0 +1,96 @@ +// Module included in the following assemblies: +// +// * networking/metallb/about-advertising-ipaddresspool.adoc + +:_content-type: PROCEDURE +[id="nw-metallb-advertise-an-advanced-address-pool-configuration-bgp_{context}"] += Example 2: Advertise an advanced address pool configuration with BGP + +Configure MetalLB as follows so that the `IPAddressPool` is advertised with the BGP protocol. + +.Prerequisites + +* Install the OpenShift CLI (`oc`). + +* Log in as a user with `cluster-admin` privileges. + +.Procedure + +. Create an IP address pool. + +.. Create a file, such as `ipaddresspool.yaml`, with content like the following example: ++ +[source,yaml] +---- +apiVersion: metallb.io/v1beta1 +kind: IPAddressPool +metadata: + namespace: metallb-system + name: doc-example-bgp-adv + labels: + zone: east +spec: + addresses: + - 203.0.113.200/30 + - fc00:f853:ccd:e799::/124 + autoAssign: false +---- + +.. Apply the configuration for the IP address pool: ++ +[source,terminal] +---- +$ oc apply -f ipaddresspool.yaml +---- + +. Create a BGP advertisement. + +.. Create a file, such as `bgpadvertisement1.yaml`, with content like the following example: ++ +[source,yaml] +---- +apiVersion: metallb.io/v1beta1 +kind: BGPAdvertisement +metadata: + name: bgpadvertisement-adv-1 + namespace: metallb-system +spec: + ipAddressPools: + - doc-example-bgp-adv + - communities: + - 65535:65282 + aggregationLength: 32 + localPref: 100 +---- + +.. Apply the configuration: ++ +[source,terminal] +---- +$ oc apply -f bgpadvertisement1.yaml +---- + +.. Create a file, such as `bgpadvertisement2.yaml`, with content like the following example: ++ +[source,yaml] +---- +apiVersion: metallb.io/v1beta1 +kind: BGPAdvertisement +metadata: + name: bgpadvertisement-adv-2 + namespace: metallb-system +spec: + ipAddressPools: + - doc-example-bgp-adv + - communities: + - 8000:800 + aggregationLength: 30 + aggregationLengthV6: 124 +---- + +.. Apply the configuration: ++ +[source,terminal] +---- +$ oc apply -f bgpadvertisement2.yaml +---- diff --git a/modules/nw-metallb-advertise-address-pool-with-bgp.adoc b/modules/nw-metallb-advertise-address-pool-with-bgp.adoc new file mode 100644 index 0000000000..5d6d342063 --- /dev/null +++ b/modules/nw-metallb-advertise-address-pool-with-bgp.adoc @@ -0,0 +1,65 @@ +// Module included in the following assemblies: +// +// * networking/metallb/about-advertising-ipaddresspool.adoc + +:_content-type: PROCEDURE + +[id="nw-metallb-advertise-a-basic-address-pool-configuration-bgp_{context}"] += Example 1: Advertise a basic address pool configuration with BGP + +Configure MetalLB as follows so that the `IPAddressPool` is advertised with the BGP protocol. + +.Prerequisites + +* Install the OpenShift CLI (`oc`). + +* Log in as a user with `cluster-admin` privileges. + +.Procedure + +. Create an IP address pool. + +.. Create a file, such as `ipaddresspool.yaml`, with content like the following example: ++ +[source,yaml] +---- +apiVersion: metallb.io/v1beta1 +kind: IPAddressPool +metadata: + namespace: metallb-system + name: doc-example-bgp-basic +spec: + addresses: + - 203.0.113.200/30 + - fc00:f853:ccd:e799::/124 +---- + +.. Apply the configuration for the IP address pool: ++ +[source,terminal] +---- +$ oc apply -f ipaddresspool.yaml +---- + +. Create a BGP advertisement. + +.. Create a file, such as `bgpadvertisement.yaml`, with content like the following example: ++ +[source,yaml] +---- +apiVersion: metallb.io/v1beta1 +kind: BGPAdvertisement +metadata: + name: bgpadvertisement-basic + namespace: metallb-system +spec: + ipAddressPools: + - doc-example-bgp-basic +---- + +.. Apply the configuration: ++ +[source,terminal] +---- +$ oc apply -f bgpadvertisement.yaml +---- \ No newline at end of file diff --git a/modules/nw-metallb-bfdprofile-cr.adoc b/modules/nw-metallb-bfdprofile-cr.adoc index 2ae74280ad..aa82d97ffe 100644 --- a/modules/nw-metallb-bfdprofile-cr.adoc +++ b/modules/nw-metallb-bfdprofile-cr.adoc @@ -2,6 +2,7 @@ // // * networking/metallb/metallb-configure-bfd-profiles.adoc +:_content-type: REFERENCE [id="nw-metallb-bfdprofile-cr_{context}"] = About the BFD profile custom resource diff --git a/modules/nw-metallb-bgp-limitations.adoc b/modules/nw-metallb-bgp-limitations.adoc index 03dc56c3d1..6c972156ad 100644 --- a/modules/nw-metallb-bgp-limitations.adoc +++ b/modules/nw-metallb-bgp-limitations.adoc @@ -18,30 +18,6 @@ However, you can anticipate that a change in the number of `speaker` pods affect To avoid or reduce the likelihood of a service interruption, you can specify a node selector when you add a BGP peer. By limiting the number of nodes that start BGP sessions, a fault on a node that does not have a BGP session has no affect on connections to the service. -[id="nw-metallb-bgp-limitations-communities-values_{context}"] -== Communities are specified as 16-bit values - -Communities are specified as part of an address pool custom resource and are specified as 16-bit values separated by a colon. -For example, to specify that load balancer IP addresses are advertised with the well-known `NO_ADVERTISE` community attribute, use notation like the following: - -[source,yaml] ----- -apiVersion: metallb.io/v1beta1 -kind: AddressPool -metadata: - name: doc-example-no-advertise - namespace: metallb-system -spec: - protocol: bgp - addresses: - - 192.168.1.100-192.168.1.255 - bgpAdvertisements: - - communities: - - 65535:65282 ----- - -The limitation that communities are only specified as 16-bit values is a difference with the community-supported implementation of MetalLB that supports a `bgp-communities` field and readable names for BGP communities. - [id="nw-metallb-bgp-limitations-single-asn_{context}"] == Support for a single ASN and a single router ID only diff --git a/modules/nw-metallb-bgp.adoc b/modules/nw-metallb-bgp.adoc index 047631ad24..3d11151aae 100644 --- a/modules/nw-metallb-bgp.adoc +++ b/modules/nw-metallb-bgp.adoc @@ -2,10 +2,11 @@ // // * networking/metallb/about-metallb.adoc +:_content-type: CONCEPT [id="nw-metallb-bgp_{context}"] = MetalLB concepts for BGP mode -In BGP mode, each `speaker` pod advertises the load balancer IP address for a service to each BGP peer. +In BGP mode, by default each `speaker` pod advertises the load balancer IP address for a service to each BGP peer. It is also possible to advertise the IPs coming from a given pool to a specific set of peers by adding an optional list of BGP peers. BGP peers are commonly network routers that are configured to use the BGP protocol. When a router receives traffic for the load balancer IP address, the router picks one of the nodes with a `speaker` pod that advertised the IP address. The router sends the traffic to that node. @@ -45,11 +46,9 @@ However, you can configure MetalLB to start BGP sessions with peers that belong * All the nodes with a `speaker` pod that advertises the load balancer IP address can receive traffic for the service. -** If the external traffic policy for the service is set to `cluster`, then all the `speaker` pods advertise the `203.0.113.200` load balancer IP address and all the nodes with a `speaker` pod can receive traffic for the service. -At least one endpoint for the service must be in the `Ready` condition. The host prefix is advertised to the router peer only if the external traffic policy is set to `cluster`. +** If the external traffic policy for the service is set to `cluster`, all the nodes where a speaker pod is running advertise the `203.0.113.200` load balancer IP address and all the nodes with a `speaker` pod can receive traffic for the service. The host prefix is advertised to the router peer only if the external traffic policy is set to cluster. -** If the external traffic policy for the service is set to `local`, then only the `speaker` pods that are on the same node as an endpoint in the `Ready` condition for the service can advertise the load balancer IP address. Only those nodes can receive traffic for the service. -In the preceding graphic, nodes 2 and 3 would advertise `203.0.113.200`. +** If the external traffic policy for the service is set to `local`, then all the nodes where a `speaker` pod is running and at least an endpoint of the service is running can advertise the `203.0.113.200` load balancer IP address. Only those nodes can receive traffic for the service. In the preceding graphic, nodes 2 and 3 would advertise `203.0.113.200`. * You can configure MetalLB to control which `speaker` pods start BGP sessions with specific BGP peers by specifying a node selector when you add a BGP peer custom resource. diff --git a/modules/nw-metallb-bgpadvertisement-cr.adoc b/modules/nw-metallb-bgpadvertisement-cr.adoc new file mode 100644 index 0000000000..d1574c2ba6 --- /dev/null +++ b/modules/nw-metallb-bgpadvertisement-cr.adoc @@ -0,0 +1,78 @@ +// Module included in the following assemblies: +// +// * networking/metallb/about-advertising-ipaddresspool.adoc + +:_content-type: REFERENCE +[id="nw-metallb-bgpadvertisement-cr_{context}"] += About the BGPAdvertisement custom resource + +The fields for the `BGPAdvertisements` object are defined in the following table: + +.BGPAdvertisements configuration +[cols="1,1,3a", options="header"] +|=== + +|Field +|Type +|Description + +|`metadata.name` +|`string` +|Specifies the name for the BGP advertisement. + +|`metadata.namespace` +|`string` +|Specifies the namespace for the BGP advertisement. +Specify the same namespace that the MetalLB Operator uses. + +|`spec.aggregationLength` +|`integer` +|Optional: Specifies the number of bits to include in a 32-bit CIDR mask. +To aggregate the routes that the speaker advertises to BGP peers, the mask is applied to the routes for several service IP addresses and the speaker advertises the aggregated route. +For example, with an aggregation length of `24`, the speaker can aggregate several `10.0.1.x/32` service IP addresses and advertise a single `10.0.1.0/24` route. + +|`spec.aggregationLengthV6` +|`integer` +|Optional: Specifies the number of bits to include in a 128-bit CIDR mask. +For example, with an aggregation length of `124`, the speaker can aggregate several `fc00:f853:0ccd:e799::x/128` service IP addresses and advertise a single `fc00:f853:0ccd:e799::0/124` route. + +|`spec.communities` +|`string` +|Optional: Specifies one or more BGP communities. +Each community is specified as two 16-bit values separated by the colon character. +Well-known communities must be specified as 16-bit values: + +* `NO_EXPORT`: `65535:65281` +* `NO_ADVERTISE`: `65535:65282` +* `NO_EXPORT_SUBCONFED`: `65535:65283` ++ +[NOTE] +==== +You can also use community objects that are created along with the strings. +==== + +|`spec.localPref` +|`integer` +|Optional: Specifies the local preference for this advertisement. +This BGP attribute applies to BGP sessions within the Autonomous System. + +|`spec.ipAddressPools` +|`string` +|Optional: The list of `IPAddressPools` to advertise with this advertisement, selected by name. + +|`spec.ipAddressPoolSelectors` +|`string` +|Optional: A selector for the `IPAddressPools` that gets advertised with this advertisement. This is for associating the `IPAddressPool` to the advertisement based on the label assigned to the `IPAddressPool` instead of the name itself. If no `IPAddressPool` is selected by this or by the list, the advertisement is applied to all the `IPAddressPools`. + +|`spec.nodeSelectors` +|`string` +|Optional: `NodeSelectors` allows to limit the nodes to announce as next hops for the load balancer IP. When empty, all the nodes are announced as next hops. +[NOTE] +==== +The functionality this supports is Technology Preview only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. +==== + +|`spec.peers` +|`string` +|Optional: Peers limits the BGP peer to advertise the IPs of the selected pools to. When empty, the load balancer IP is announced to all the BGP peers configured. +|=== diff --git a/modules/nw-metallb-bgppeer-cr.adoc b/modules/nw-metallb-bgppeer-cr.adoc index 09841332a6..fa2e99c93f 100644 --- a/modules/nw-metallb-bgppeer-cr.adoc +++ b/modules/nw-metallb-bgppeer-cr.adoc @@ -2,6 +2,7 @@ // // * networking/metallb/metallb-configure-bgp-peers.adoc +:_content-type: REFERENCE [id="nw-metallb-bgppeer-cr_{context}"] = About the BGP peer custom resource @@ -70,6 +71,10 @@ If you specify this field, you must specify the same value in every BGP peer cus |`string` |Optional: Specifies the MD5 password to send to the peer for routers that enforce TCP MD5 authenticated BGP sessions. +|`spec.passwordSecret` +|`string` +|Optional: Specifies name of the authentication secret for the BGP Peer. The secret must live in the `metallb` namespace and be of type basic-auth. + |`spec.bfdProfile` |`string` |Optional: Specifies the name of a BFD profile. @@ -86,3 +91,8 @@ This field applies to _external BGP_. External BGP is the term that is used to describe when a BGP peer belongs to a different Autonomous System. |=== + +[NOTE] +==== +The `passwordSecret` field is mutually exclusive with the `password` field, and contains a reference to a secret containing the password to use. Setting both fields results in a failure of the parsing. +==== diff --git a/modules/nw-metallb-community-cr.adoc b/modules/nw-metallb-community-cr.adoc new file mode 100644 index 0000000000..b8edd95033 --- /dev/null +++ b/modules/nw-metallb-community-cr.adoc @@ -0,0 +1,57 @@ +// Module included in the following assemblies: +// +// * networking/metallb/metallb-configure-community-alias.adoc + +:_content-type: REFERENCE +[id="nw-metallb-community-cr_{context}"] += About the community custom resource + +The `community` custom resource is a collection of aliases for communities. Users can define named aliases to be used when advertising `ipAddressPools` using the `BGPAdvertisement`. The fields for the `community` custom resource are described in the following table. + +[NOTE] +==== +The `community` CRD applies only to BGPAdvertisement. +==== + + +.MetalLB community custom resource +[cols="1,1,3a", options="header"] +|=== + +|Field +|Type +|Description + +|`metadata.name` +|`string` +|Specifies the name for the `community`. + +|`metadata.namespace` +|`string` +|Specifies the namespace for the `community`. +Specify the same namespace that the MetalLB Operator uses. + +|`spec.communities` +|`string` +|Specifies a list of IP addresses for MetalLB to assign to services. +You can specify multiple ranges in a single pool, they will all share the same settings. +Specify each range in CIDR notation or as starting and ending IP addresses separated with a hyphen. + +|=== + +.CommunityAlias +[cols="1,1,3a", options="header"] +|=== + +|Field +|Type +|Description + +|`name` +|`string` +|The name of the alias for the `community`. + +|`value` +|`string` +|The BGP `community` value corresponding to the given name. +|=== \ No newline at end of file diff --git a/modules/nw-metallb-configure-address-pool.adoc b/modules/nw-metallb-configure-address-pool.adoc index 0d4bb8677b..f18ea8cd36 100644 --- a/modules/nw-metallb-configure-address-pool.adoc +++ b/modules/nw-metallb-configure-address-pool.adoc @@ -12,27 +12,29 @@ As a cluster administrator, you can add address pools to your cluster to control .Procedure -. Create a file, such as `addresspool.yaml`, with content like the following example: +. Create a file, such as `ipaddresspool.yaml`, with content like the following example: + [source,yaml] ---- -apiVersion: metallb.io/v1alpha1 -kind: AddressPool +apiVersion: metallb.io/v1beta1 +kind: IPAddressPool metadata: namespace: metallb-system name: doc-example + labels: <1> + zone: east spec: - protocol: layer2 addresses: - 203.0.113.1-203.0.113.10 - 203.0.113.65-203.0.113.75 ---- +<1> This label assigned to the `IPAddressPool` can be referenced by the `ipAddressPoolSelectors` in the `BGPAdvertisement` CRD to associate the `IPAddressPool` with the advertisement. -. Apply the configuration for the address pool: +. Apply the configuration for the IP address pool: + [source,terminal] ---- -$ oc apply -f addresspool.yaml +$ oc apply -f ipaddresspool.yaml ---- .Verification @@ -41,7 +43,7 @@ $ oc apply -f addresspool.yaml + [source,terminal] ---- -$ oc describe -n metallb-system addresspool doc-example +$ oc describe -n metallb-system IPAddressPool doc-example ---- + .Example output @@ -49,10 +51,10 @@ $ oc describe -n metallb-system addresspool doc-example ---- Name: doc-example Namespace: metallb-system -Labels: +Labels: zone=east Annotations: -API Version: metallb.io/v1alpha1 -Kind: AddressPool +API Version: metallb.io/v1beta1 +Kind: IPAddressPool Metadata: ... Spec: @@ -60,7 +62,6 @@ Spec: 203.0.113.1-203.0.113.10 203.0.113.65-203.0.113.75 Auto Assign: true - Protocol: layer2 Events: ---- diff --git a/modules/nw-metallb-configure-bfdprofle.adoc b/modules/nw-metallb-configure-bfdprofle.adoc index aa6f6c9965..6421eaf440 100644 --- a/modules/nw-metallb-configure-bfdprofle.adoc +++ b/modules/nw-metallb-configure-bfdprofle.adoc @@ -2,6 +2,7 @@ // // * networking/metallb/metallb-configure-bfd-profiles.adoc +:_content-type: PROCEDURE [id="nw-metallb-configure-bfdprofile_{context}"] = Configuring a BFD profile diff --git a/modules/nw-metallb-configure-bgp-advertisement-advanced.adoc b/modules/nw-metallb-configure-bgp-advertisement-advanced.adoc new file mode 100644 index 0000000000..5855fedb6b --- /dev/null +++ b/modules/nw-metallb-configure-bgp-advertisement-advanced.adoc @@ -0,0 +1,23 @@ +// Module included in the following assemblies: +// +// * networking/metallb/about-advertising-ipaddresspool.adoc + +:_content-type: CONCEPT +[id="nw-metallb-configure-BGP-advertisement-advanced-use-case_{context}"] += Configuring MetalLB with a BGP advertisement and an advanced use case + +Configure MetalLB as follows so that MetalLB assigns IP addresses to load-balancer services in the ranges between `203.0.113.200` and `203.0.113.203` and between `fc00:f853:ccd:e799::0` and `fc00:f853:ccd:e799::f`. + +To explain the two BGP advertisements, consider an instance when MetalLB assigns the IP address of `203.0.113.200` to a service. +With that IP address as an example, the speaker advertises two routes to BGP peers: + +* `203.0.113.200/32`, with `localPref` set to `100` and the community set to the numeric value of the `NO_ADVERTISE` community. +This specification indicates to the peer routers that they can use this route but they should not propagate information about this route to BGP peers. + +* `203.0.113.200/30`, aggregates the load-balancer IP addresses assigned by MetalLB into a single route. +MetalLB advertises the aggregated route to BGP peers with the community attribute set to `8000:800`. +BGP peers propagate the `203.0.113.200/30` route to other BGP peers. +When traffic is routed to a node with a speaker, the `203.0.113.200/32` route is used to forward the traffic into the cluster and to a pod that is associated with the service. + +As you add more services and MetalLB assigns more load-balancer IP addresses from the pool, peer routers receive one local route, `203.0.113.20x/32`, for each service, as well as the `203.0.113.200/30` aggregate route. +Each service that you add generates the `/30` route, but MetalLB deduplicates the routes to one BGP advertisement before communicating with peer routers. \ No newline at end of file diff --git a/modules/nw-metallb-configure-bgp-advertisement.adoc b/modules/nw-metallb-configure-bgp-advertisement.adoc new file mode 100644 index 0000000000..5d48378622 --- /dev/null +++ b/modules/nw-metallb-configure-bgp-advertisement.adoc @@ -0,0 +1,10 @@ +// Module included in the following assemblies: +// +// * networking/metallb/about-advertising-ipaddresspool.adoc + +:_content-type: CONCEPT +[id="nw-metallb-configure-BGP-advertisement-basic-use-case_{context}"] += Configuring MetalLB with a BGP advertisement and a basic use case + +Configure MetalLB as follows so that the the peer BGP routers receive one `203.0.113.200/32` route and one `fc00:f853:ccd:e799::1/128` route for each load-balancer IP address that MetalLB assigns to a service. +Because the `localPref` and `communities` fields are not specified, the routes are advertised with `localPref` set to zero and no BGP communities. \ No newline at end of file diff --git a/modules/nw-metallb-configure-bgppeer.adoc b/modules/nw-metallb-configure-bgppeer.adoc index 984d9b9739..a04fbd8919 100644 --- a/modules/nw-metallb-configure-bgppeer.adoc +++ b/modules/nw-metallb-configure-bgppeer.adoc @@ -2,6 +2,7 @@ // // * networking/metallb/metallb-configure-bgp-peers.adoc +:_content-type: PROCEDURE [id="nw-metallb-configure-bgppeer_{context}"] = Configuring a BGP peer @@ -13,7 +14,7 @@ As a cluster administrator, you can add a BGP peer custom resource to exchange r * Log in as a user with `cluster-admin` privileges. -* Configure a MetalLB address pool that specifies `bgp` for the `spec.protocol` field. +* Configure MetalLB with a BGP advertisement. .Procedure diff --git a/modules/nw-metallb-configure-community-bgp-advertisement.adoc b/modules/nw-metallb-configure-community-bgp-advertisement.adoc new file mode 100644 index 0000000000..de1118e58d --- /dev/null +++ b/modules/nw-metallb-configure-community-bgp-advertisement.adoc @@ -0,0 +1,113 @@ +// Module included in the following assemblies: +// +// * networking/metallb/metallb-configure-community-alias.adoc + +:_content-type: PROCEDURE +[id="nw-metallb-configure-BGP-advertisement-community-alias_{context}"] += Configuring MetalLB with a BGP advertisement and community alias + +Configure MetalLB as follows so that the `IPAddressPool` is advertised with the BGP protocol and the community alias set to the numeric value of the NO_ADVERTISE community. + +In the following example, the peer BGP router `doc-example-peer-community` receives one `203.0.113.200/32` route and one `fc00:f853:ccd:e799::1/128` route for each load-balancer IP address that MetalLB assigns to a service. A community alias is configured with the `NO_ADVERTISE` community. + +.Prerequisites + +* Install the OpenShift CLI (`oc`). + +* Log in as a user with `cluster-admin` privileges. + + +.Procedure + +. Create an IP address pool. + +.. Create a file, such as `ipaddresspool.yaml`, with content like the following example: ++ +[source,yaml] +---- +apiVersion: metallb.io/v1beta1 +kind: IPAddressPool +metadata: + namespace: metallb-system + name: doc-example-bgp-community +spec: + addresses: + - 203.0.113.200/30 + - fc00:f853:ccd:e799::/124 +---- + +.. Apply the configuration for the IP address pool: ++ +[source,terminal] +---- +$ oc apply -f ipaddresspool.yaml +---- + +. Create a community alias named `community1`. ++ +[source,yaml] +---- +apiVersion: metallb.io/v1beta1 +kind: Community +metadata: + name: community1 + namespace: metallb-system +spec: + communities: + - name: NO_ADVERTISE + - value: '65535:65282' +---- + +. Create a BGP peer named `doc-example-bgp-peer`. + +.. Create a file, such as `bgppeer.yaml`, with content like the following example: ++ +[source,yaml] +---- +apiVersion: metallb.io/v1beta1 +kind: BGPPeer +metadata: + namespace: metallb-system + name: doc-example-bgp-peer +spec: + peerAddress: 10.0.0.1 + peerASN: 64501 + myASN: 64500 + routerID: 10.10.10.10 +---- + +.. Apply the configuration for the BGP peer: ++ +[source,terminal] +---- +$ oc apply -f bgppeer.yaml +---- + +. Create a BGP advertisement with the community alias. + +.. Create a file, such as `bgpadvertisement.yaml`, with content like the following example: ++ +[source,yaml] +---- +apiVersion: metallb.io/v1beta1 +kind: BGPAdvertisement +metadata: + name: bgp-community-sample + namespace: metallb-system +spec: + aggregationLength: 32 + aggregationLengthV6: 128 + communities: + - community1 + ipAddressPools: + - doc-example-bgp-community + peers: + - doc-example-peer +---- + +.. Apply the configuration: ++ +[source,terminal] +---- +$ oc apply -f bgpadvertisement.yaml +---- \ No newline at end of file diff --git a/modules/nw-metallb-configure-l2-advertisement-label.adoc b/modules/nw-metallb-configure-l2-advertisement-label.adoc new file mode 100644 index 0000000000..be83f5fefc --- /dev/null +++ b/modules/nw-metallb-configure-l2-advertisement-label.adoc @@ -0,0 +1,71 @@ +// Module included in the following assemblies: +// +// * networking/metallb/about-advertising-ipaddresspool.adoc + +:_content-type: PROCEDURE +[id="nw-metallb-configure-with-L2-advertisement-label_{context}"] += Configuring MetalLB with a L2 advertisement and label + +The `ipAddressPoolSelectors` field in the `BGPAdvertisement` and `L2Advertisement` custom resource definitions is used to associate the `IPAddressPool` to the advertisement based on the label assigned to the `IPAddressPool` instead of the name itself. + +This example shows how to configure MetalLB so that the `IPAddressPool` is advertised with the L2 protocol by configuring the `ipAddressPoolSelectors` field. + +.Prerequisites + +* Install the OpenShift CLI (`oc`). + +* Log in as a user with `cluster-admin` privileges. + +.Procedure + +. Create an IP address pool. + +.. Create a file, such as `ipaddresspool.yaml`, with content like the following example: ++ +[source,yaml] +---- +apiVersion: metallb.io/v1beta1 +kind: IPAddressPool +metadata: + namespace: metallb-system + name: doc-example-l2-label + labels: + zone: east +spec: + addresses: + - 172.31.249.87/32 +---- + +.. Apply the configuration for the IP address pool: ++ +[source,terminal] +---- +$ oc apply -f ipaddresspool.yaml +---- + +. Create a L2 advertisement advertising the IP using `ipAddressPoolSelectors`. + +.. Create a file, such as `l2advertisement.yaml`, with content like the following example: ++ +[source,yaml] +---- +apiVersion: metallb.io/v1beta1 +kind: L2Advertisement +metadata: + name: l2advertisement-label + namespace: metallb-system +spec: + ipAddressPoolSelectors: + - matchExpressions: + - key: zone + operator: In + values: + - east +---- + +.. Apply the configuration: ++ +[source,terminal] +---- +$ oc apply -f l2advertisement.yaml +---- diff --git a/modules/nw-metallb-configure-l2-advertisement.adoc b/modules/nw-metallb-configure-l2-advertisement.adoc new file mode 100644 index 0000000000..973a1e509f --- /dev/null +++ b/modules/nw-metallb-configure-l2-advertisement.adoc @@ -0,0 +1,64 @@ +// Module included in the following assemblies: +// +// * networking/metallb/about-advertising-ipaddresspool.adoc + +:_content-type: PROCEDURE +[id="nw-metallb-configure-with-L2-advertisement_{context}"] += Configuring MetalLB with an L2 advertisement + +Configure MetalLB as follows so that the `IPAddressPool` is advertised with the L2 protocol. + +.Prerequisites + +* Install the OpenShift CLI (`oc`). + +* Log in as a user with `cluster-admin` privileges. + +.Procedure + +. Create an IP address pool. + +.. Create a file, such as `ipaddresspool.yaml`, with content like the following example: ++ +[source,yaml] +---- +apiVersion: metallb.io/v1beta1 +kind: IPAddressPool +metadata: + namespace: metallb-system + name: doc-example-l2 +spec: + addresses: + - 4.4.4.0/24 + autoAssign: false +---- + +.. Apply the configuration for the IP address pool: ++ +[source,terminal] +---- +$ oc apply -f ipaddresspool.yaml +---- + +. Create a L2 advertisement. + +.. Create a file, such as `l2advertisement.yaml`, with content like the following example: ++ +[source,yaml] +---- +apiVersion: metallb.io/v1beta1 +kind: L2Advertisement +metadata: + name: l2advertisement + namespace: metallb-system +spec: + ipAddressPools: + - doc-example-l2 +---- + +.. Apply the configuration: ++ +[source,terminal] +---- +$ oc apply -f l2advertisement.yaml +---- diff --git a/modules/nw-metallb-configure-specificpools-to-bgppeer.adoc b/modules/nw-metallb-configure-specificpools-to-bgppeer.adoc new file mode 100644 index 0000000000..29ade78dfb --- /dev/null +++ b/modules/nw-metallb-configure-specificpools-to-bgppeer.adoc @@ -0,0 +1,178 @@ +// Module included in the following assemblies: +// +// * networking/metallb/metallb-configure-bgp-peers.adoc + +:_content-type: PROCEDURE +[id="nw-metallb-example-assign-specific-address-pools-specific-bgp-peers_{context}"] += Configure a specific set of BGP peers for a given address pool + +This procedure illustrates how to: + +* Configure a set of address pools (`pool1` and `pool2`). +* Configure a set of BGP peers (`peer1` and `peer2`). +* Configure BGP advertisement to assign `pool1` to `peer1` and `pool2` to `peer2`. + +.Prerequisites + +* Install the OpenShift CLI (`oc`). + +* Log in as a user with `cluster-admin` privileges. + +.Procedure + +. Create address pool `pool1`. + +.. Create a file, such as `ipaddresspool1.yaml`, with content like the following example: ++ +[source,yaml] +---- +apiVersion: metallb.io/v1beta1 +kind: IPAddressPool +metadata: + namespace: metallb-system + name: pool1 +spec: + addresses: + - 4.4.4.100-4.4.4.200 + - 2001:100:4::200-2001:100:4::400 +---- + +.. Apply the configuration for the IP address pool `pool1`: ++ +[source,terminal] +---- +$ oc apply -f ipaddresspool1.yaml +---- + +. Create address pool `pool2`. + +.. Create a file, such as `ipaddresspool2.yaml`, with content like the following example: ++ +[source,yaml] +---- +apiVersion: metallb.io/v1beta1 +kind: IPAddressPool +metadata: + namespace: metallb-system + name: pool2 +spec: + addresses: + - 5.5.5.100-5.5.5.200 + - 2001:100:5::200-2001:100:5::400 +---- + +.. Apply the configuration for the IP address pool `pool2`: ++ +[source,terminal] +---- +$ oc apply -f ipaddresspool2.yaml +---- +. Create BGP `peer1`. + +.. Create a file, such as `bgppeer1.yaml`, with content like the following example: ++ +[source,yaml] +---- +apiVersion: metallb.io/v1beta1 +kind: BGPPeer +metadata: + namespace: metallb-system + name: peer1 +spec: + peerAddress: 10.0.0.1 + peerASN: 64501 + myASN: 64500 + routerID: 10.10.10.10 +---- + +.. Apply the configuration for the BGP peer: ++ +[source,terminal] +---- +$ oc apply -f bgppeer1.yaml +---- + +. Create BGP `peer2`. + +.. Create a file, such as `bgppeer2.yaml`, with content like the following example: ++ +[source,yaml] +---- +apiVersion: metallb.io/v1beta1 +kind: BGPPeer +metadata: + namespace: metallb-system + name: peer2 +spec: + peerAddress: 10.0.0.2 + peerASN: 64501 + myASN: 64500 + routerID: 10.10.10.10 +---- + +.. Apply the configuration for the BGP peer2: ++ +[source,terminal] +---- +$ oc apply -f bgppeer2.yaml +---- + +. Create BGP advertisement 1. + +.. Create a file, such as `bgpadvertisement1.yaml`, with content like the following example: ++ +[source,yaml] +---- +apiVersion: metallb.io/v1beta1 +kind: BGPAdvertisement +metadata: + name: bgpadvertisement-1 + namespace: metallb-system +spec: + ipAddressPools: + - pool1 + peers: + - peer1 + - communities: + - 65535:65282 + aggregationLength: 32 + aggregationLengthV6: 128 + localPref: 100 +---- + +.. Apply the configuration: ++ +[source,terminal] +---- +$ oc apply -f bgpadvertisement1.yaml +---- + +. Create BGP advertisement 2. + +.. Create a file, such as `bgpadvertisement2.yaml`, with content like the following example: ++ +[source,yaml] +---- +apiVersion: metallb.io/v1beta1 +kind: BGPAdvertisement +metadata: + name: bgpadvertisement-2 + namespace: metallb-system +spec: + ipAddressPools: + - pool2 + peers: + - peer2 + - communities: + - 65535:65282 + aggregationLength: 32 + aggregationLengthV6: 128 + localPref: 100 +---- + +.. Apply the configuration: ++ +[source,terminal] +---- +$ oc apply -f bgpadvertisement2.yaml +---- diff --git a/modules/nw-metallb-configure-svc.adoc b/modules/nw-metallb-configure-svc.adoc index 70a0ce7711..a13da551b6 100644 --- a/modules/nw-metallb-configure-svc.adoc +++ b/modules/nw-metallb-configure-svc.adoc @@ -1,3 +1,7 @@ +// Module included in the following assemblies: +// +// * networking/metallb/nw-metalb-configure-svc.adoc + :_content-type: PROCEDURE [id="nw-metallb-configure-svc_{context}"] = Configuring a service with MetalLB diff --git a/modules/nw-metallb-example-addresspool.adoc b/modules/nw-metallb-example-addresspool.adoc index 18f8628460..b4d7974ed2 100644 --- a/modules/nw-metallb-example-addresspool.adoc +++ b/modules/nw-metallb-example-addresspool.adoc @@ -13,12 +13,11 @@ You can combine CIDR notation with the notation that uses a hyphen to separate l [source,yaml] ---- apiVersion: metallb.io/v1beta1 -kind: AddressPool +kind: IPAddressPool metadata: name: doc-example-cidr namespace: metallb-system spec: - protocol: layer2 addresses: - 192.168.100.0/24 - 192.168.200.0/24 @@ -33,12 +32,11 @@ When you add a service, you can request a specific IP address from the pool or y [source,yaml] ---- apiVersion: metallb.io/v1beta1 -kind: AddressPool +kind: IPAddressPool metadata: name: doc-example-reserved namespace: metallb-system spec: - protocol: layer2 addresses: - 10.0.100.0/28 autoAssign: false @@ -55,78 +53,12 @@ The `spec.ipFamilies` and `spec.ipFamilyPolicy` fields control how IP addresses [source,yaml] ---- apiVersion: metallb.io/v1beta1 -kind: AddressPool +kind: IPAddressPool metadata: name: doc-example-combined namespace: metallb-system spec: - protocol: layer2 addresses: - 10.0.100.0/28 - 2002:2:2::1-2002:2:2::100 ---- - -== Example: Simple address pool with BGP mode - -For BGP mode, you must set the `protocol` field set to `bgp`. -Other address pool custom resource fields, such as `autoAssign`, also apply to BGP mode. - -In the following example, the peer BGP routers receive one `203.0.113.200/32` route and one `fc00:f853:ccd:e799::1/128` route for each load-balancer IP address that MetalLB assigns to a service. -Because the `localPref` and `communities` fields are not specified, the routes are advertised with `localPref` set to zero and no BGP communities. - -[source,yaml] ----- -apiVersion: metallb.io/v1beta1 -kind: AddressPool -metadata: - name: doc-example-bgp - namespace: metallb-system -spec: - protocol: bgp - addresses: - - 203.0.113.200/30 - - fc00:f853:ccd:e799::/124 ----- - -== Example: BGP mode with custom advertisement - -You can specify sophisticated custom advertisements. - -[source,yaml] ----- -apiVersion: metallb.io/v1beta1 -kind: AddressPool -metadata: - name: doc-example-bgp-adv - namespace: metallb-system -spec: - protocol: bgp - addresses: - - 203.0.113.200/30 - - fc00:f853:ccd:e799::/124 - bgpAdvertisements: - - communities: - - 65535:65282 - aggregationLength: 32 - localPref: 100 - - communities: - - 8000:800 - aggregationLength: 30 - aggregationLengthV6: 124 ----- - -In the preceding example, MetalLB assigns IP addresses to load-balancer services in the ranges between `203.0.113.200` and `203.0.113.203` and between `fc00:f853:ccd:e799::0` and `fc00:f853:ccd:e799::f`. - -To explain the two BGP advertisements, consider an instance when MetalLB assigns the IP address of `203.0.113.200` to a service. -With that IP address as an example, the speaker advertises two routes to BGP peers: - -* `203.0.113.200/32`, with `localPref` set to `100` and the community set to the numeric value of the well-known `NO_ADVERTISE` community. -This specification indicates to the peer routers that they can use this route but they should not propagate information about this route to BGP peers. - -* `203.0.113.200/30`, aggregates the load-balancer IP addresses assigned by MetalLB into a single route. -MetalLB advertises the aggregated route to BGP peers with the community attribute set to `8000:800`. -BGP peers propagate the `203.0.113.200/30` route to other BGP peers. -When traffic is routed to a node with a speaker, the `203.0.113.200/32` route is used to forward the traffic into the cluster and to a pod that is associated with the service. - -As you add more services and MetalLB assigns more load-balancer IP addresses from the pool, peer routers receive one local route, `203.0.113.20x/32`, for each service, as well as the `203.0.113.200/30` aggregate route. -Each service that you add generates the `/30` route, but MetalLB deduplicates the routes to one BGP advertisement before communicating with peer routers. diff --git a/modules/nw-metallb-example-bgppeer.adoc b/modules/nw-metallb-example-bgppeer.adoc index 7ea1178a02..0f722b59ee 100644 --- a/modules/nw-metallb-example-bgppeer.adoc +++ b/modules/nw-metallb-example-bgppeer.adoc @@ -2,6 +2,7 @@ // // * networking/metallb/metallb-configure-bgp-peers.adoc +:_content-type: PROCEDURE [id="nw-metallb-example-bgppeer_{context}"] = Example BGP peer configurations diff --git a/modules/nw-metallb-extern-traffic-pol.adoc b/modules/nw-metallb-extern-traffic-pol.adoc index 06f387d2de..2089879e0a 100644 --- a/modules/nw-metallb-extern-traffic-pol.adoc +++ b/modules/nw-metallb-extern-traffic-pol.adoc @@ -25,3 +25,12 @@ Pods for the service on additional nodes act as replicas in case failover is nee This policy does not affect the client IP address. Application pods can determine the client IP address from the incoming connections. +[NOTE] +==== +The following information is important when configuring the external traffic policy in BGP mode. + +Although MetalLB advertises the load balancer IP address from all the eligible nodes, the number of nodes loadbalancing the service can be limited by the capacity of the router to establish equal-cost multipath (ECMP) routes. If the number of nodes advertising the IP is greater than the ECMP group limit of the router, the router will use less nodes than the ones advertising the IP. + +For example, if the external traffic policy is set to `local` and the router has an ECMP group limit set to 16 and the pods implementing a LoadBalancer service are deployed on 30 nodes, this would result in pods deployed on 14 nodes not receiving any traffic. In this situation, it would be preferable to set the external traffic policy for the service to `cluster`. +==== + diff --git a/modules/nw-metallb-installing-operator-cli.adoc b/modules/nw-metallb-installing-operator-cli.adoc index c4158d0484..fb7712863d 100644 --- a/modules/nw-metallb-installing-operator-cli.adoc +++ b/modules/nw-metallb-installing-operator-cli.adoc @@ -6,31 +6,19 @@ [id="nw-metallb-installing-operator-cli_{context}"] = Installing from OperatorHub using the CLI -Instead of using the {product-title} web console, you can install an Operator from OperatorHub using the CLI. Use the `oc` command to create or update a `Subscription` object. +Instead of using the {product-title} web console, you can install an Operator from OperatorHub using the CLI. You can use the OpenShift CLI (`oc`) to install the MetalLB Operator. + +It is recommended that when using the CLI you install the Operator in the `metallb-system` namespace. .Prerequisites +* A cluster installed on bare-metal hardware. * Install the OpenShift CLI (`oc`). - * Log in as a user with `cluster-admin` privileges. .Procedure -. Confirm that the MetalLB Operator is available: -+ -[source,terminal] ----- -$ oc get packagemanifests -n openshift-marketplace metallb-operator ----- -+ -.Example output -[source,terminal] ----- -NAME CATALOG AGE -metallb-operator Red Hat Operators 9h ----- - -. Create the `metallb-system` namespace: +. Create a namespace for the MetalLB Operator by entering the following command: + [source,terminal] ---- @@ -42,14 +30,7 @@ metadata: EOF ---- -. Optional: To ensure BGP and BFD metrics appear in Prometheus, you can label the namespace as in the following command: -+ -[source,terminal] ----- -$ oc label ns metallb-system "openshift.io/cluster-monitoring=true" ----- - -. Create an Operator group custom resource in the namespace: +. Create an Operator group custom resource (CR) in the namespace: + [source,terminal] ---- @@ -59,9 +40,6 @@ kind: OperatorGroup metadata: name: metallb-operator namespace: metallb-system -spec: - targetNamespaces: - - metallb-system EOF ---- @@ -79,34 +57,41 @@ NAME AGE metallb-operator 14m ---- -. Subscribe to the MetalLB Operator. - -.. Run the following command to get the {product-title} major and minor version. You use the values to set the `channel` value in the next -step. +. Create a `Subscription` CR: +.. Define the `Subscription` CR and save the YAML file, for example, `metallb-sub.yaml`: + -[source,terminal] +[source,yaml] ---- -$ OC_VERSION=$(oc version -o yaml | grep openshiftVersion | \ - grep -o '[0-9]*[.][0-9]*' | head -1) ----- - -.. To create a subscription custom resource for the Operator, enter the following command: -+ -[source,terminal] ----- -$ cat << EOF| oc apply -f - apiVersion: operators.coreos.com/v1alpha1 kind: Subscription metadata: name: metallb-operator-sub - namespace: metallb-system + namespace: metallb-system spec: - channel: "${OC_VERSION}" + channel: stable name: metallb-operator - source: redhat-operators + source: redhat-operators <1> sourceNamespace: openshift-marketplace -EOF ---- +<1> You must specify the `redhat-operators` value. + +.. To create the `Subscription` CR, run the following command: ++ +[source,terminal] +---- +$ oc create -f metallb-sub.yaml +---- + +. Optional: To ensure BGP and BFD metrics appear in Prometheus, you can label the namespace as in the following command: ++ +[source,terminal] +---- +$ oc label ns metallb-system "openshift.io/cluster-monitoring=true" +---- + +.Verification + +The verification steps assume the MetalLB Operator is installed in the `metallb-system` namespace. . Confirm the install plan is in the namespace: + @@ -121,6 +106,11 @@ $ oc get installplan -n metallb-system NAME CSV APPROVAL APPROVED install-wzg94 metallb-operator.{product-version}.0-nnnnnnnnnnnn Automatic true ---- ++ +[NOTE] +==== +Installation of the Operator might take a few seconds. +==== . To verify that the Operator is installed, enter the following command: + @@ -135,4 +125,4 @@ $ oc get clusterserviceversion -n metallb-system \ ---- Name Phase metallb-operator.{product-version}.0-nnnnnnnnnnnn Succeeded ----- +---- \ No newline at end of file diff --git a/modules/nw-metallb-l2padvertisement-cr.adoc b/modules/nw-metallb-l2padvertisement-cr.adoc new file mode 100644 index 0000000000..929a53231b --- /dev/null +++ b/modules/nw-metallb-l2padvertisement-cr.adoc @@ -0,0 +1,46 @@ +// Module included in the following assemblies: +// +// * networking/metallb/about-advertising-ipaddresspool.adoc + +:_content-type: REFERENCE +[id="nw-metallb-l2padvertisement-cr_{context}"] += About the L2Advertisement custom resource + +The fields for the `l2Advertisements` object are defined in the following table: + +.L2 advertisements configuration +[cols="1,1,3a", options="header"] +|=== + +|Field +|Type +|Description + +|`metadata.name` +|`string` +|Specifies the name for the L2 advertisement. + +|`metadata.namespace` +|`string` +|Specifies the namespace for the L2 advertisement. +Specify the same namespace that the MetalLB Operator uses. + +|`spec.ipAddressPools` +|`string` +|Optional: The list of `IPAddressPools` to advertise with this advertisement, selected by name. + +|`spec.ipAddressPoolSelectors` +|`string` +|Optional: A selector for the `IPAddressPools` that gets advertised with this advertisement. This is for associating the `IPAddressPool` to the advertisement based on the label assigned to the `IPAddressPool` instead of the name itself. If no `IPAddressPool` is selected by this or by the list, the advertisement is applied to all the `IPAddressPools`. + +|`spec.nodeSelectors` +|`string` +|Optional: `NodeSelectors` limits the nodes to announce as next hops for the load balancer IP. When empty, all the nodes are announced as next hops. + +[NOTE] +==== +Limiting the nodes to announce as next hops is Technology Preview only. For more information about Technology Preview support, see link:https://access.redhat.com/support/offerings/techpreview/[Technology Preview Features Support Scope]. +] +==== + +|=== diff --git a/modules/nw-metallb-layer2.adoc b/modules/nw-metallb-layer2.adoc index a32932002d..a8f89e1cb0 100644 --- a/modules/nw-metallb-layer2.adoc +++ b/modules/nw-metallb-layer2.adoc @@ -2,6 +2,8 @@ // // * networking/metallb/about-metallb.adoc +:_content-type: CONCEPT + [id="nw-metallb-layer2_{context}"] = MetalLB concepts for layer 2 mode @@ -41,6 +43,10 @@ The `speaker` pod that announces the external IP address must be on the same nod * Client traffic is routed to the host network and connects to the `192.168.100.200` IP address. After traffic enters the node, the service proxy sends the traffic to the application pod on the same node or another node according to the external traffic policy that you set for the service. +** If the external traffic policy for the service is set to `cluster`, the node that advertises the `192.168.100.200` load balancer IP address is selected from the nodes where a `speaker` pod is running. Only that node can receive traffic for the service. + +** If the external traffic policy for the service is set to `local`, the node that advertises the `192.168.100.200` load balancer IP address is selected from the nodes where a `speaker` pod is running and at least an endpoint of the service. Only that node can receive traffic for the service. In the preceding graphic, either node 1 or 3 would advertise `192.168.100.200`. + * If node 1 becomes unavailable, the external IP address fails over to another node. On another node that has an instance of the application pod and service endpoint, the `speaker` pod begins to announce the external IP address, `192.168.100.200` and the new node receives the client traffic. In the diagram, the only candidate is node 3. diff --git a/modules/nw-metallb-levels.adoc b/modules/nw-metallb-levels.adoc new file mode 100644 index 0000000000..8d3fc6975c --- /dev/null +++ b/modules/nw-metallb-levels.adoc @@ -0,0 +1,36 @@ +// Module included in the following assemblies: +// Epic CNF-3274 (4.11) +// * networking/metallb/metallb-troubleshoot-support.adoc + +:_content-type: REFERENCE + +[id="frr-log-levels_{context}"] += FRRouting (FRR) log levels + +The following table describes the FRR logging levels. + +.Log levels +[cols="30%,70%",options="header"] +|=== +| Log level | Description + +| `all` +a| +Supplies all logging information for all logging levels. +| `debug` +a| +Information that is diagnostically helpful to people. Set to `debug` to give detailed troubleshooting information. +| `info` +| +Provides information that always should be logged but under normal circumstances does not require user intervention. This is the default logging level. +| `warn` +| +Anything that can potentially cause inconsistent `MetalLB` behaviour. Usually `MetalLB` automatically recovers from this type of error. + +| `error` +a| +Any error that is fatal to the functioning of `MetalLB`. These errors usually require administrator intervention to fix. + +| `none` +|Turn off all logging. +|=== diff --git a/modules/nw-metallb-loglevel.adoc b/modules/nw-metallb-loglevel.adoc new file mode 100644 index 0000000000..799c21b15e --- /dev/null +++ b/modules/nw-metallb-loglevel.adoc @@ -0,0 +1,164 @@ +// Module included in the following assemblies: +// +// * networking/metallb/metallb-troubleshoot-support.adoc + +:_content-type: PROCEDURE + +[id="nw-metallb-setting-metalb-logging-levels_{context}"] += Setting the MetalLB logging levels + +MetalLB uses FRRouting (FRR) in a container with the default setting of `info` generates a lot of logging. You can control the verbosity of the logs generated by setting the `logLevel` as illustrated in this example. + +Gain a deeper insight into MetalLB by setting the `logLevel` to `debug` as follows: + +.Prerequisites + +* You have access to the cluster as a user with the `cluster-admin` role. + +* You have installed the OpenShift CLI (`oc`). + +.Procedure + +. Create a file, such as `setdebugloglevel.yaml`, with content like the following example: ++ +[source,yaml] +---- +apiVersion: metallb.io/v1beta1 +kind: MetalLB +metadata: + name: metallb + namespace: metallb-system +spec: + logLevel: debug + nodeSelector: + node-role.kubernetes.io/worker: "" +---- + +. Apply the configuration: ++ +[source,terminal] +---- +$ oc replace -f setdebugloglevel.yaml +---- ++ +[NOTE] +==== +Use `oc replace` as the understanding is the `metallb` CR is already created and here you are changing the log level. +==== + +. Display the names of the `speaker` pods: ++ +[source,terminal] +---- +$ oc get -n metallb-system pods -l component=speaker +---- ++ +.Example output +[source,text] +---- +NAME READY STATUS RESTARTS AGE +speaker-2m9pm 4/4 Running 0 9m19s +speaker-7m4qw 3/4 Running 0 19s +speaker-szlmx 4/4 Running 0 9m19s +---- ++ +[NOTE] +==== +Speaker and controller pods are recreated to ensure the updated logging level is applied. The logging level is modified for all the components of MetalLB. +==== + +. View the `speaker` logs: ++ +[source,terminal] +---- +$ oc logs -n metallb-system speaker-7m4qw -c speaker +---- ++ +.Example output +---- +{"branch":"main","caller":"main.go:92","commit":"3d052535","goversion":"gc / go1.17.1 / amd64","level":"info","msg":"MetalLB speaker starting (commit 3d052535, branch main)","ts":"2022-05-17T09:55:05Z","version":""} +{"caller":"announcer.go:110","event":"createARPResponder","interface":"ens4","level":"info","msg":"created ARP responder for interface","ts":"2022-05-17T09:55:05Z"} +{"caller":"announcer.go:119","event":"createNDPResponder","interface":"ens4","level":"info","msg":"created NDP responder for interface","ts":"2022-05-17T09:55:05Z"} +{"caller":"announcer.go:110","event":"createARPResponder","interface":"tun0","level":"info","msg":"created ARP responder for interface","ts":"2022-05-17T09:55:05Z"} +{"caller":"announcer.go:119","event":"createNDPResponder","interface":"tun0","level":"info","msg":"created NDP responder for interface","ts":"2022-05-17T09:55:05Z"} +I0517 09:55:06.515686 95 request.go:665] Waited for 1.026500832s due to client-side throttling, not priority and fairness, request: GET:https://172.30.0.1:443/apis/operators.coreos.com/v1alpha1?timeout=32s +{"Starting Manager":"(MISSING)","caller":"k8s.go:389","level":"info","ts":"2022-05-17T09:55:08Z"} +{"caller":"speakerlist.go:310","level":"info","msg":"node event - forcing sync","node addr":"10.0.128.4","node event":"NodeJoin","node name":"ci-ln-qb8t3mb-72292-7s7rh-worker-a-vvznj","ts":"2022-05-17T09:55:08Z"} +{"caller":"service_controller.go:113","controller":"ServiceReconciler","enqueueing":"openshift-kube-controller-manager-operator/metrics","epslice":"{\"metadata\":{\"name\":\"metrics-xtsxr\",\"generateName\":\"metrics-\",\"namespace\":\"openshift-kube-controller-manager-operator\",\"uid\":\"ac6766d7-8504-492c-9d1e-4ae8897990ad\",\"resourceVersion\":\"9041\",\"generation\":4,\"creationTimestamp\":\"2022-05-17T07:16:53Z\",\"labels\":{\"app\":\"kube-controller-manager-operator\",\"endpointslice.kubernetes.io/managed-by\":\"endpointslice-controller.k8s.io\",\"kubernetes.io/service-name\":\"metrics\"},\"annotations\":{\"endpoints.kubernetes.io/last-change-trigger-time\":\"2022-05-17T07:21:34Z\"},\"ownerReferences\":[{\"apiVersion\":\"v1\",\"kind\":\"Service\",\"name\":\"metrics\",\"uid\":\"0518eed3-6152-42be-b566-0bd00a60faf8\",\"controller\":true,\"blockOwnerDeletion\":true}],\"managedFields\":[{\"manager\":\"kube-controller-manager\",\"operation\":\"Update\",\"apiVersion\":\"discovery.k8s.io/v1\",\"time\":\"2022-05-17T07:20:02Z\",\"fieldsType\":\"FieldsV1\",\"fieldsV1\":{\"f:addressType\":{},\"f:endpoints\":{},\"f:metadata\":{\"f:annotations\":{\".\":{},\"f:endpoints.kubernetes.io/last-change-trigger-time\":{}},\"f:generateName\":{},\"f:labels\":{\".\":{},\"f:app\":{},\"f:endpointslice.kubernetes.io/managed-by\":{},\"f:kubernetes.io/service-name\":{}},\"f:ownerReferences\":{\".\":{},\"k:{\\\"uid\\\":\\\"0518eed3-6152-42be-b566-0bd00a60faf8\\\"}\":{}}},\"f:ports\":{}}}]},\"addressType\":\"IPv4\",\"endpoints\":[{\"addresses\":[\"10.129.0.7\"],\"conditions\":{\"ready\":true,\"serving\":true,\"terminating\":false},\"targetRef\":{\"kind\":\"Pod\",\"namespace\":\"openshift-kube-controller-manager-operator\",\"name\":\"kube-controller-manager-operator-6b98b89ddd-8d4nf\",\"uid\":\"dd5139b8-e41c-4946-a31b-1a629314e844\",\"resourceVersion\":\"9038\"},\"nodeName\":\"ci-ln-qb8t3mb-72292-7s7rh-master-0\",\"zone\":\"us-central1-a\"}],\"ports\":[{\"name\":\"https\",\"protocol\":\"TCP\",\"port\":8443}]}","level":"debug","ts":"2022-05-17T09:55:08Z"} +---- + +. View the FRR logs: ++ +[source,terminal] +---- +$ oc logs -n metallb-system speaker-7m4qw -c frr +---- ++ +.Example output +---- +Started watchfrr +2022/05/17 09:55:05 ZEBRA: client 16 says hello and bids fair to announce only bgp routes vrf=0 +2022/05/17 09:55:05 ZEBRA: client 31 says hello and bids fair to announce only vnc routes vrf=0 +2022/05/17 09:55:05 ZEBRA: client 38 says hello and bids fair to announce only static routes vrf=0 +2022/05/17 09:55:05 ZEBRA: client 43 says hello and bids fair to announce only bfd routes vrf=0 +2022/05/17 09:57:25.089 BGP: Creating Default VRF, AS 64500 +2022/05/17 09:57:25.090 BGP: dup addr detect enable max_moves 5 time 180 freeze disable freeze_time 0 +2022/05/17 09:57:25.090 BGP: bgp_get: Registering BGP instance (null) to zebra +2022/05/17 09:57:25.090 BGP: Registering VRF 0 +2022/05/17 09:57:25.091 BGP: Rx Router Id update VRF 0 Id 10.131.0.1/32 +2022/05/17 09:57:25.091 BGP: RID change : vrf VRF default(0), RTR ID 10.131.0.1 +2022/05/17 09:57:25.091 BGP: Rx Intf add VRF 0 IF br0 +2022/05/17 09:57:25.091 BGP: Rx Intf add VRF 0 IF ens4 +2022/05/17 09:57:25.091 BGP: Rx Intf address add VRF 0 IF ens4 addr 10.0.128.4/32 +2022/05/17 09:57:25.091 BGP: Rx Intf address add VRF 0 IF ens4 addr fe80::c9d:84da:4d86:5618/64 +2022/05/17 09:57:25.091 BGP: Rx Intf add VRF 0 IF lo +2022/05/17 09:57:25.091 BGP: Rx Intf add VRF 0 IF ovs-system +2022/05/17 09:57:25.091 BGP: Rx Intf add VRF 0 IF tun0 +2022/05/17 09:57:25.091 BGP: Rx Intf address add VRF 0 IF tun0 addr 10.131.0.1/23 +2022/05/17 09:57:25.091 BGP: Rx Intf address add VRF 0 IF tun0 addr fe80::40f1:d1ff:feb6:5322/64 +2022/05/17 09:57:25.091 BGP: Rx Intf add VRF 0 IF veth2da49fed +2022/05/17 09:57:25.091 BGP: Rx Intf address add VRF 0 IF veth2da49fed addr fe80::24bd:d1ff:fec1:d88/64 +2022/05/17 09:57:25.091 BGP: Rx Intf add VRF 0 IF veth2fa08c8c +2022/05/17 09:57:25.091 BGP: Rx Intf address add VRF 0 IF veth2fa08c8c addr fe80::6870:ff:fe96:efc8/64 +2022/05/17 09:57:25.091 BGP: Rx Intf add VRF 0 IF veth41e356b7 +2022/05/17 09:57:25.091 BGP: Rx Intf address add VRF 0 IF veth41e356b7 addr fe80::48ff:37ff:fede:eb4b/64 +2022/05/17 09:57:25.092 BGP: Rx Intf add VRF 0 IF veth1295c6e2 +2022/05/17 09:57:25.092 BGP: Rx Intf address add VRF 0 IF veth1295c6e2 addr fe80::b827:a2ff:feed:637/64 +2022/05/17 09:57:25.092 BGP: Rx Intf add VRF 0 IF veth9733c6dc +2022/05/17 09:57:25.092 BGP: Rx Intf address add VRF 0 IF veth9733c6dc addr fe80::3cf4:15ff:fe11:e541/64 +2022/05/17 09:57:25.092 BGP: Rx Intf add VRF 0 IF veth336680ea +2022/05/17 09:57:25.092 BGP: Rx Intf address add VRF 0 IF veth336680ea addr fe80::94b1:8bff:fe7e:488c/64 +2022/05/17 09:57:25.092 BGP: Rx Intf add VRF 0 IF vetha0a907b7 +2022/05/17 09:57:25.092 BGP: Rx Intf address add VRF 0 IF vetha0a907b7 addr fe80::3855:a6ff:fe73:46c3/64 +2022/05/17 09:57:25.092 BGP: Rx Intf add VRF 0 IF vethf35a4398 +2022/05/17 09:57:25.092 BGP: Rx Intf address add VRF 0 IF vethf35a4398 addr fe80::40ef:2fff:fe57:4c4d/64 +2022/05/17 09:57:25.092 BGP: Rx Intf add VRF 0 IF vethf831b7f4 +2022/05/17 09:57:25.092 BGP: Rx Intf address add VRF 0 IF vethf831b7f4 addr fe80::f0d9:89ff:fe7c:1d32/64 +2022/05/17 09:57:25.092 BGP: Rx Intf add VRF 0 IF vxlan_sys_4789 +2022/05/17 09:57:25.092 BGP: Rx Intf address add VRF 0 IF vxlan_sys_4789 addr fe80::80c1:82ff:fe4b:f078/64 +2022/05/17 09:57:26.094 BGP: 10.0.0.1 [FSM] Timer (start timer expire). +2022/05/17 09:57:26.094 BGP: 10.0.0.1 [FSM] BGP_Start (Idle->Connect), fd -1 +2022/05/17 09:57:26.094 BGP: Allocated bnc 10.0.0.1/32(0)(VRF default) peer 0x7f807f7631a0 +2022/05/17 09:57:26.094 BGP: sendmsg_zebra_rnh: sending cmd ZEBRA_NEXTHOP_REGISTER for 10.0.0.1/32 (vrf VRF default) +2022/05/17 09:57:26.094 BGP: 10.0.0.1 [FSM] Waiting for NHT +2022/05/17 09:57:26.094 BGP: bgp_fsm_change_status : vrf default(0), Status: Connect established_peers 0 +2022/05/17 09:57:26.094 BGP: 10.0.0.1 went from Idle to Connect +2022/05/17 09:57:26.094 BGP: 10.0.0.1 [FSM] TCP_connection_open_failed (Connect->Active), fd -1 +2022/05/17 09:57:26.094 BGP: bgp_fsm_change_status : vrf default(0), Status: Active established_peers 0 +2022/05/17 09:57:26.094 BGP: 10.0.0.1 went from Connect to Active +2022/05/17 09:57:26.094 ZEBRA: rnh_register msg from client bgp: hdr->length=8, type=nexthop vrf=0 +2022/05/17 09:57:26.094 ZEBRA: 0: Add RNH 10.0.0.1/32 type Nexthop +2022/05/17 09:57:26.094 ZEBRA: 0:10.0.0.1/32: Evaluate RNH, type Nexthop (force) +2022/05/17 09:57:26.094 ZEBRA: 0:10.0.0.1/32: NH has become unresolved +2022/05/17 09:57:26.094 ZEBRA: 0: Client bgp registers for RNH 10.0.0.1/32 type Nexthop +2022/05/17 09:57:26.094 BGP: VRF default(0): Rcvd NH update 10.0.0.1/32(0) - metric 0/0 #nhops 0/0 flags 0x6 +2022/05/17 09:57:26.094 BGP: NH update for 10.0.0.1/32(0)(VRF default) - flags 0x6 chgflags 0x0 - evaluate paths +2022/05/17 09:57:26.094 BGP: evaluate_paths: Updating peer (10.0.0.1(VRF default)) status with NHT +2022/05/17 09:57:30.081 ZEBRA: Event driven route-map update triggered +2022/05/17 09:57:30.081 ZEBRA: Event handler for route-map: 10.0.0.1-out +2022/05/17 09:57:30.081 ZEBRA: Event handler for route-map: 10.0.0.1-in +2022/05/17 09:57:31.104 ZEBRA: netlink_parse_info: netlink-listen (NS 0) type RTM_NEWNEIGH(28), len=76, seq=0, pid=0 +2022/05/17 09:57:31.104 ZEBRA: Neighbor Entry received is not on a VLAN or a BRIDGE, ignoring +2022/05/17 09:57:31.105 ZEBRA: netlink_parse_info: netlink-listen (NS 0) type RTM_NEWNEIGH(28), len=76, seq=0, pid=0 +2022/05/17 09:57:31.105 ZEBRA: Neighbor Entry received is not on a VLAN or a BRIDGE, ignoring +---- diff --git a/modules/nw-metallb-operator-custom-resources.adoc b/modules/nw-metallb-operator-custom-resources.adoc index e020d80e55..94327b343d 100644 --- a/modules/nw-metallb-operator-custom-resources.adoc +++ b/modules/nw-metallb-operator-custom-resources.adoc @@ -12,36 +12,35 @@ When you add a `MetalLB` custom resource to the cluster, the MetalLB Operator de The Operator only supports a single instance of the custom resource. If the instance is deleted, the Operator removes MetalLB from the cluster. -`AddressPool`:: +`IPAddressPool`:: MetalLB requires one or more pools of IP addresses that it can assign to a service when you add a service of type `LoadBalancer`. -When you add an `AddressPool` custom resource to the cluster, the MetalLB Operator configures MetalLB so that it can assign IP addresses from the pool. -An address pool includes a list of IP addresses. +An `IPAddressPool` includes a list of IP addresses. The list can be a single IP address that is set using a range, such as 1.1.1.1-1.1.1.1, a range specified in CIDR notation, a range specified as a starting and ending address separated by a hyphen, or a combination of the three. -An address pool requires a name. +An `IPAddressPool` requires a name. The documentation uses names like `doc-example`, `doc-example-reserved`, and `doc-example-ipv6`. -An address pool specifies whether MetalLB can automatically assign IP addresses from the pool or whether the IP addresses are reserved for services that explicitly specify the pool by name. -An address pool specifies whether MetalLB uses layer 2 protocols to advertise the IP addresses, or whether the BGP protocol is used. +An `IPAddressPool` assigns IP addresses from the pool. +`L2Advertisement` and `BGPAdvertisement` custom resources enable the advertisement of a given IP from a given pool. ++ +[NOTE] +==== +A single `IPAddressPool` can be referenced by a L2 advertisement and a BGP advertisement. +==== + `BGPPeer`:: The BGP peer custom resource identifies the BGP router for MetalLB to communicate with, the AS number of the router, the AS number for MetalLB, and customizations for route advertisement. MetalLB advertises the routes for service load-balancer IP addresses to one or more BGP peers. -The service load-balancer IP addresses are specified with `AddressPool` custom resources that set the `protocol` field to `bgp`. `BFDProfile`:: The BFD profile custom resource configures Bidirectional Forwarding Detection (BFD) for a BGP peer. BFD provides faster path failure detection than BGP alone provides. -After you add the `MetalLB` custom resource to the cluster and the Operator deploys MetalLB, the MetalLB software components, `controller` and `speaker`, begin running. +`L2Advertisement`:: +The L2Advertisement custom resource advertises an IP coming from an `IPAddressPool` using the L2 protocol. -The Operator includes validating webhooks for the `AddressPool` and `BGPPeer` custom resources. -The webhook for the address pool custom resource performs the following checks: that the address pool name is unique. +`BGPAdvertisement`:: +The BGPAdvertisement custom resource advertises an IP coming from an `IPAddressPool` using the BGP protocol. -* Address pool names must be unique. -* IP address ranges do not overlap with an existing address pool. -* If the address pool includes a `bgpAdvertisement` field, the `protocol` field must be set to `bgp`. +After you add the `MetalLB` custom resource to the cluster and the Operator deploys MetalLB, the `controller` and `speaker` MetalLB software components begin running. -The webhook for the BGP peer custom resource performs the following checks: - -* If the BGP peer name matches an existing peer, the IP address for the peer must be unique. -* If the `keepaliveTime` field is specified, the `holdTime` field must be specified and the keep-alive duration must be less than the hold time. -* The `myASN` field must be the same for all BGP peers. +MetalLB validates all relevant custom resources. diff --git a/modules/nw-metallb-operator-initial-config.adoc b/modules/nw-metallb-operator-initial-config.adoc index da382178c0..523c06feec 100644 --- a/modules/nw-metallb-operator-initial-config.adoc +++ b/modules/nw-metallb-operator-initial-config.adoc @@ -16,8 +16,11 @@ After you install the Operator, you need to configure a single instance of a Met * Install the MetalLB Operator. + .Procedure +This procedure assumes the MetalLB Operator is installed in the `metallb-system` namespace. If you installed using the web console substitute `openshift-operators` for the namespace. + . Create a single instance of a MetalLB custom resource: + [source,terminal] @@ -35,7 +38,7 @@ EOF Confirm that the deployment for the MetalLB controller and the daemon set for the MetalLB speaker are running. -. Check that the deployment for the controller is running: +. Verify that the deployment for the controller is running: + [source,terminal] ---- @@ -49,7 +52,7 @@ NAME READY UP-TO-DATE AVAILABLE AGE controller 1/1 1 1 11m ---- -. Check that the daemon set for the speaker is running: +. Verify that the daemon set for the speaker is running: + [source,terminal] ---- diff --git a/modules/nw-metallb-software-components.adoc b/modules/nw-metallb-software-components.adoc index c530cea149..41c697c86c 100644 --- a/modules/nw-metallb-software-components.adoc +++ b/modules/nw-metallb-software-components.adoc @@ -7,7 +7,7 @@ When you install the MetalLB Operator, the `metallb-operator-controller-manager` deployment starts a pod. The pod is the implementation of the Operator. -The pod monitors for changes to the `MetalLB` custom resource and `AddressPool` custom resources. +The pod monitors for changes to all the relevant resources. When the Operator starts an instance of MetalLB, it starts a `controller` deployment and a `speaker` daemon set. @@ -28,9 +28,7 @@ The `speaker` uses Address Resolution Protocol (ARP) to announce IPv4 addresses For BGP mode, after the `controller` allocates an IP address for the service, each `speaker` pod advertises the load balancer IP address with its BGP peers. You can configure which nodes start BGP sessions with BGP peers. -+ -Refer to the concepts for layer 2 mode and BGP mode for more information. -+ + Requests for the load balancer IP address are routed to the node with the `speaker` that announces the IP address. After the node receives the packets, the service proxy routes the packets to an endpoint for the service. The endpoint can be on the same node in the optimal case, or it can be on another node. diff --git a/modules/nw-metallb-troubleshoot-bfd.adoc b/modules/nw-metallb-troubleshoot-bfd.adoc index 41052519e5..bea4dee797 100644 --- a/modules/nw-metallb-troubleshoot-bfd.adoc +++ b/modules/nw-metallb-troubleshoot-bfd.adoc @@ -21,7 +21,7 @@ As a cluster administrator, if you need to troubleshoot BFD configuration issues + [source,terminal] ---- -$ oc get -n metallb-system pods -l app.kubernetes.io/component=speaker +$ oc get -n metallb-system pods -l component=speaker ---- + .Example output diff --git a/modules/nw-metallb-troubleshoot-bgp.adoc b/modules/nw-metallb-troubleshoot-bgp.adoc index 041625ef77..3823796b86 100644 --- a/modules/nw-metallb-troubleshoot-bgp.adoc +++ b/modules/nw-metallb-troubleshoot-bgp.adoc @@ -20,7 +20,7 @@ As a cluster administrator, if you need to troubleshoot BGP configuration issues + [source,terminal] ---- -$ oc get -n metallb-system pods -l app.kubernetes.io/component=speaker +$ oc get -n metallb-system pods -l component=speaker ---- + .Example output diff --git a/modules/nw-metallb-when-metallb.adoc b/modules/nw-metallb-when-metallb.adoc index f80f42a2ef..225d23ac4a 100644 --- a/modules/nw-metallb-when-metallb.adoc +++ b/modules/nw-metallb-when-metallb.adoc @@ -2,6 +2,7 @@ // // * networking/metallb/about-metallb.adoc +:_content-type: CONCEPT [id="nw-metallb-when-metallb_{context}"] = When to use MetalLB diff --git a/modules/olm-deleting-metallb-operators-from-a-cluster-using-cli.adoc b/modules/olm-deleting-metallb-operators-from-a-cluster-using-cli.adoc new file mode 100644 index 0000000000..4c57d19727 --- /dev/null +++ b/modules/olm-deleting-metallb-operators-from-a-cluster-using-cli.adoc @@ -0,0 +1,56 @@ +// Module included in the following assemblies: +// +// * operators/metallb/metallb-upgrading-operator.adoc + +:_content-type: PROCEDURE +[id="olm-deleting-metallb-operator-from-a-cluster-using-cli_{context}"] += Deleting MetalLB Operator from a cluster using the CLI + +Cluster administrators can delete installed Operators from a selected namespace by using the CLI. + +.Prerequisites + +- Access to an {product-title} cluster using an account with +`cluster-admin` permissions. +- `oc` command installed on workstation. + +.Procedure + +. Check the current version of the subscribed MetalLB Operator in the `currentCSV` field: ++ +[source,terminal] +---- +$ oc get subscription metallb-operator -n metallb-system -o yaml | grep currentCSV +---- ++ +.Example output +[source,terminal] +---- + currentCSV: metallb-operator.4.10.0-202207051316 +---- + +. Delete the subscription: ++ +[source,terminal] +---- +$ oc delete subscription metallb-operator -n metallb-system +---- ++ +.Example output +[source,terminal] +---- +subscription.operators.coreos.com "metallb-operator" deleted +---- + +. Delete the CSV for the Operator in the target namespace using the `currentCSV` value from the previous step: ++ +[source,terminal] +---- +$ oc delete clusterserviceversion metallb-operator.4.10.0-202207051316 -n metallb-system +---- ++ +.Example output +[source,terminal] +---- +clusterserviceversion.operators.coreos.com "metallb-operator.4.10.0-202207051316" deleted +---- diff --git a/modules/olm-deleting-metallb-operators-from-a-cluster-using-web-console.adoc b/modules/olm-deleting-metallb-operators-from-a-cluster-using-web-console.adoc new file mode 100644 index 0000000000..3dd965c779 --- /dev/null +++ b/modules/olm-deleting-metallb-operators-from-a-cluster-using-web-console.adoc @@ -0,0 +1,31 @@ +// Module included in the following assemblies: +// +// * operators/metallb/metallb-upgrading-operator.adoc + +:_content-type: PROCEDURE +[id="olm-deleting-metallb-operator-from-a-cluster-using-web-console_{context}"] += Deleting the MetalLB Operator from a cluster using the web console + +Cluster administrators can delete installed Operators from a selected namespace by using the web console. + +.Prerequisites + +- Access to an {product-title} cluster web console using an account with +`cluster-admin` permissions. + +.Procedure + +. Navigate to the *Operators* → *Installed Operators* page. + +. Search for the MetalLB Operator. Then, click on it. + +. On the right side of the *Operator Details* page, select *Uninstall Operator* from the *Actions* drop-down menu. ++ +An *Uninstall Operator?* dialog box is displayed. + +. Select *Uninstall* to remove the Operator, Operator deployments, and pods. Following this action, the Operator stops running and no longer receives updates. ++ +[NOTE] +==== +This action does not remove resources managed by the Operator, including custom resource definitions (CRDs) and custom resources (CRs). Dashboards and navigation items enabled by the web console and off-cluster resources that continue to run might need manual clean up. To remove these after uninstalling the Operator, you might need to manually delete the Operator CRDs. +==== diff --git a/networking/metallb/about-advertising-ipaddresspool.adoc b/networking/metallb/about-advertising-ipaddresspool.adoc new file mode 100644 index 0000000000..a04fff53c6 --- /dev/null +++ b/networking/metallb/about-advertising-ipaddresspool.adoc @@ -0,0 +1,45 @@ +:_content-type: ASSEMBLY +[id="about-advertise-for-ipaddress-pools"] += About advertising for the IP address pools +include::_attributes/common-attributes.adoc[] +:context: about-advertising-ip-address-pool + +toc::[] + +You can configure MetalLB so that the IP address is advertised with layer 2 protocols, the BGP protocol, or both. +With layer 2, MetalLB provides a fault-tolerant external IP address. With BGP, MetalLB provides fault-tolerance for the external IP address and load balancing. + +MetalLB supports advertising using L2 and BGP for the same set of IP addresses. + +MetalLB provides the flexibility to assign address pools to specific BGP peers effectively to a subset of nodes on the network. This allows for more complex configurations, for example facilitating the isolation of nodes or the segmentation of the network. + +// BGP advertisement custom resource +include::modules/nw-metallb-bgpadvertisement-cr.adoc[leveloffset=+1] + +// Configure MetalLB with a BGP advertisement +include::modules/nw-metallb-configure-bgp-advertisement.adoc[leveloffset=+1] + +// Advertise MetalLB with a BGP advertisement +include::modules/nw-metallb-advertise-address-pool-with-bgp.adoc[leveloffset=+2] + +// Configure MetalLB with a BGP advertisement +include::modules/nw-metallb-configure-bgp-advertisement-advanced.adoc[leveloffset=+1] + +// Advertise MetalLB with a BGP advertisement + +include::modules/nw-metallb-advertise-address-pool-with-bgp-advanced.adoc[leveloffset=+2] + +// L2 advertisement custom resource +include::modules/nw-metallb-l2padvertisement-cr.adoc[leveloffset=+1] + +// Configure MetalLB with a L2 advertisement +include::modules/nw-metallb-configure-l2-advertisement.adoc[leveloffset=+1] + +// Configure MetalLB with a L2 advertisement using label +include::modules/nw-metallb-configure-l2-advertisement-label.adoc[leveloffset=+1] + +[role="_additional-resources"] +[id="additional-resources_about-advertiseipaddress"] +== Additional resources + +* xref:../../networking/metallb/metallb-configure-community-alias.adoc#metallb-configure-community-alias[Configuring a community alias]. diff --git a/networking/metallb/about-metallb.adoc b/networking/metallb/about-metallb.adoc index 6804df23de..8476db03cc 100644 --- a/networking/metallb/about-metallb.adoc +++ b/networking/metallb/about-metallb.adoc @@ -9,14 +9,6 @@ toc::[] As a cluster administrator, you can add the MetalLB Operator to your cluster so that when a service of type `LoadBalancer` is added to the cluster, MetalLB can add an external IP address for the service. The external IP address is added to the host network for your cluster. -You can configure MetalLB so that the IP address is advertised with layer 2 protocols. -With layer 2, MetalLB provides a fault-tolerant external IP address. - -You can configure MetalLB so that the IP address is advertised with the BGP protocol. -With BGP, MetalLB provides fault-tolerance for the external IP address and load balancing. - -MetalLB supports providing layer 2 for some IP addresses and BGP for other IP addresses. - // When to deploy MetalLB include::modules/nw-metallb-when-metallb.adoc[leveloffset=+1] @@ -26,15 +18,15 @@ include::modules/nw-metallb-operator-custom-resources.adoc[leveloffset=+1] // MetalLB software components include::modules/nw-metallb-software-components.adoc[leveloffset=+1] +// External traffic policy, common to layer 2 and BGP +include::modules/nw-metallb-extern-traffic-pol.adoc[leveloffset=+1] + // Layer 2 include::modules/nw-metallb-layer2.adoc[leveloffset=+1] // BGP include::modules/nw-metallb-bgp.adoc[leveloffset=+1] -// External traffic policy, common to layer 2 and BGP -include::modules/nw-metallb-extern-traffic-pol.adoc[leveloffset=+1] - [id="limitations-and-restrictions_{context}"] == Limitations and restrictions diff --git a/networking/metallb/metalb-upgrading-operator.adoc b/networking/metallb/metalb-upgrading-operator.adoc new file mode 100644 index 0000000000..89a2cfcf3f --- /dev/null +++ b/networking/metallb/metalb-upgrading-operator.adoc @@ -0,0 +1,37 @@ +:_content-type: ASSEMBLY +[id="metallb-operator-upgrade"] += Upgrading the MetalLB Operator +include::_attributes/common-attributes.adoc[] +:context: metallb-operator-upgrade + +toc::[] + +The automatic upgrade procedure does not work as expected from {product-title} 4.10 and earlier. A summary of the upgrade procedure is as follows: + +. Delete the previously installed Operator version for example 4.10. Ensure that the namespace and the `metallb` custom resource are not removed. + +. Install the 4.11 version of the Operator using the CLI. Install the 4.11 version of the Operator in the same namespace that the previously installed Operator version was installed to. + +[NOTE] +==== +This procedure does not apply to automatic z-stream updates of the MetalLB Operator, which follow the standard straightforward method. +==== + +For detailed steps to upgrade the Operator, see the guidance that follows. + +//Delete metallb using web console +include::modules/olm-deleting-metallb-operators-from-a-cluster-using-web-console.adoc[leveloffset=+1] + +//Delete metallb using cli +include::modules/olm-deleting-metallb-operators-from-a-cluster-using-cli.adoc[leveloffset=+1] + +//Upgrade the Operator +include::modules/nw-metalLB-basic-upgrade-operator.adoc[leveloffset=+1] + +[id="additional-resources"] +== Additional resources + +* xref:../../operators/admin/olm-deleting-operators-from-cluster.adoc#olm-deleting-operators-from-a-cluster[Deleting Operators from a cluster] + +* xref:metallb-operator-install.adoc#metallb-operator-install[Installing the MetalLB Operator] + diff --git a/networking/metallb/metallb-configure-address-pools.adoc b/networking/metallb/metallb-configure-address-pools.adoc index 207c485c80..75bbfea202 100644 --- a/networking/metallb/metallb-configure-address-pools.adoc +++ b/networking/metallb/metallb-configure-address-pools.adoc @@ -7,7 +7,7 @@ include::_attributes/common-attributes.adoc[] toc::[] As a cluster administrator, you can add, modify, and delete address pools. -The MetalLB Operator uses the address pool custom resources to set the IP addresses that MetalLB can assign to services. +The MetalLB Operator uses the address pool custom resources to set the IP addresses that MetalLB can assign to services. The namespace used in the examples assume the namespace is `metallb-system`. // Address pool custom resource include::modules/nw-metallb-addresspool-cr.adoc[leveloffset=+1] @@ -18,10 +18,15 @@ include::modules/nw-metallb-configure-address-pool.adoc[leveloffset=+1] // Examples include::modules/nw-metallb-example-addresspool.adoc[leveloffset=+1] +[role="_additional-resources"] +[id="additional-resources_metallb-configure-address-pools"] +== Additional resources + +* xref:../../networking/metallb/about-advertising-ipaddresspool.adoc#nw-metallb-configure-with-L2-advertisement-label_about-advertising-ip-address-pool[Configuring MetalLB with an L2 advertisement and label]. + [id="next-steps_{context}"] == Next steps * For BGP mode, see xref:../../networking/metallb/metallb-configure-bgp-peers.adoc#metallb-configure-bgp-peers[Configuring MetalLB BGP peers]. * xref:../../networking/metallb/metallb-configure-services.adoc#metallb-configure-services[Configuring services to use MetalLB]. - diff --git a/networking/metallb/metallb-configure-bfd-profiles.adoc b/networking/metallb/metallb-configure-bfd-profiles.adoc index 760b53776b..a4ff0cda2f 100644 --- a/networking/metallb/metallb-configure-bfd-profiles.adoc +++ b/networking/metallb/metallb-configure-bfd-profiles.adoc @@ -1,3 +1,4 @@ +:_content-type: ASSEMBLY [id="metallb-configure-bfd-profiles"] = Configuring MetalLB BFD profiles include::_attributes/common-attributes.adoc[] diff --git a/networking/metallb/metallb-configure-bgp-peers.adoc b/networking/metallb/metallb-configure-bgp-peers.adoc index eed4ca923b..9ca3edd1b9 100644 --- a/networking/metallb/metallb-configure-bgp-peers.adoc +++ b/networking/metallb/metallb-configure-bgp-peers.adoc @@ -1,3 +1,4 @@ +:_content-type: ASSEMBLY [id="metallb-configure-bgp-peers"] = Configuring MetalLB BGP peers include::_attributes/common-attributes.adoc[] @@ -19,9 +20,8 @@ include::modules/nw-metallb-bgppeer-cr.adoc[leveloffset=+1] // Add a BGP peer include::modules/nw-metallb-configure-bgppeer.adoc[leveloffset=+1] -.Next steps - -* Configure a MetalLB address pool that specifies `bgp` for the `spec.protocol` field. +// Add a BGP peer +include::modules/nw-metallb-configure-specificpools-to-bgppeer.adoc[leveloffset=+1] // Examples include::modules/nw-metallb-example-bgppeer.adoc[leveloffset=+1] @@ -30,4 +30,3 @@ include::modules/nw-metallb-example-bgppeer.adoc[leveloffset=+1] == Next steps * xref:../../networking/metallb/metallb-configure-services.adoc#metallb-configure-services[Configuring services to use MetalLB] - diff --git a/networking/metallb/metallb-configure-community-alias.adoc b/networking/metallb/metallb-configure-community-alias.adoc new file mode 100644 index 0000000000..177b9e6010 --- /dev/null +++ b/networking/metallb/metallb-configure-community-alias.adoc @@ -0,0 +1,15 @@ +:_content-type: ASSEMBLY +[id="metallb-configure-community-alias"] += Configuring community alias +include::_attributes/common-attributes.adoc[] +:context: configure-community-alias + +toc::[] + +As a cluster administrator, you can configure a community alias and use it across different advertisements. + +// Address pool custom resource +include::modules/nw-metallb-community-cr.adoc[leveloffset=+1] + +// Configure advertisement with community alias +include::modules/nw-metallb-configure-community-bgp-advertisement.adoc[leveloffset=+1] diff --git a/networking/metallb/metallb-operator-install.adoc b/networking/metallb/metallb-operator-install.adoc index b3aca763ed..107cbdb749 100644 --- a/networking/metallb/metallb-operator-install.adoc +++ b/networking/metallb/metallb-operator-install.adoc @@ -8,18 +8,11 @@ toc::[] As a cluster administrator, you can add the MetallB Operator so that the Operator can manage the lifecycle for an instance of MetalLB on your cluster. -The installation procedures use the `metallb-system` namespace. -You can install the Operator and configure custom resources in a different namespace. -The Operator starts MetalLB in the same namespace that the Operator is installed in. - MetalLB and IP failover are incompatible. If you configured IP failover for your cluster, perform the steps to xref:../../networking/configuring-ipfailover.adoc#nw-ipfailover-remove_configuring-ipfailover[remove IP failover] before you install the Operator. + // Install the Operator with console -:filter-type: metallb -:filter-operator: MetalLB -include::modules/olm-installing-from-operatorhub-using-web-console.adoc[leveloffset=+1] -:!filter-type: -:!filter-operator: +include::modules/metallb-installing-using-web-console.adoc[leveloffset=+1] // Install the Operator with CLI include::modules/nw-metallb-installing-operator-cli.adoc[leveloffset=+1] @@ -31,11 +24,13 @@ include::modules/nw-metallb-operator-initial-config.adoc[leveloffset=+1] include::modules/nw-metallb-operator-limit-speaker-to-nodes.adoc[leveloffset=+2] [role="_additional-resources"] -.Additional resources +[id="additional-resources_metallb-operator-install"] +== Additional resources -* For more information about node selectors, see xref:../../nodes/scheduling/nodes-scheduler-node-selectors.adoc#nodes-scheduler-node-selectors[Placing pods on specific nodes using node selectors]. -* For more information about taints and tolerations, see xref:../../nodes/scheduling/nodes-scheduler-taints-tolerations.adoc#nodes-scheduler-taints-tolerations-about[Understanding taints and tolerations]. +* xref:../../nodes/scheduling/nodes-scheduler-node-selectors.adoc#nodes-scheduler-node-selectors[Placing pods on specific nodes using node selectors]. +* xref:../../nodes/scheduling/nodes-scheduler-taints-tolerations.adoc#nodes-scheduler-taints-tolerations-about[Understanding taints and tolerations]. +[id="next-steps_{context}"] == Next steps * xref:../../networking/metallb/metallb-configure-address-pools.adoc#metallb-configure-address-pools[Configuring MetalLB address pools] diff --git a/networking/metallb/metallb-troubleshoot-support.adoc b/networking/metallb/metallb-troubleshoot-support.adoc index a809035b0f..6139e588b0 100644 --- a/networking/metallb/metallb-troubleshoot-support.adoc +++ b/networking/metallb/metallb-troubleshoot-support.adoc @@ -1,11 +1,18 @@ -[id="metallb-troubleshoot-support"] -= MetalLB troubleshooting and support +:_content-type: ASSEMBLY +[id="metallb-logging-troubleshooting-support"] += MetalLB logging, troubleshooting, and support include::_attributes/common-attributes.adoc[] :context: metallb-troubleshoot-support toc::[] -In the event that you need to troubleshoot MetalLB configuration, refer to the following sections for commonly used commands. +If you need to troubleshoot MetalLB configuration, see the following sections for commonly used commands. + +// Set logging level +include::modules/nw-metallb-loglevel.adoc[leveloffset=+1] + +// Log level descriptions +include::modules/nw-metallb-levels.adoc[leveloffset=+2] // Troubleshooting BGP issues include::modules/nw-metallb-troubleshoot-bgp.adoc[leveloffset=+1]