Skip to content

Commit 6486c01

Browse files
author
mikemckiernan
authored
Merge pull request #34728 from mikemckiernan/feat-metallb
OSDOCS-2174: MetalLB Operator and load balancer
2 parents 1a5d352 + 5b75ff4 commit 6486c01

23 files changed

+942
-1
lines changed

‎_topic_map.yml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1089,6 +1089,17 @@ Topics:
10891089
Distros: openshift-enterprise,openshift-origin
10901090
- Name: Load balancing on OpenStack
10911091
File: load-balancing-openstack
1092+
- Name: Load balancing with MetalLB
1093+
Dir: metallb
1094+
Topics:
1095+
- Name: About MetalLB and the MetalLB Operator
1096+
File: about-metallb
1097+
- Name: Installing the MetalLB Operator
1098+
File: metallb-operator-install
1099+
- Name: Configuring MetalLB address pools
1100+
File: metallb-configure-address-pools
1101+
- Name: Configuring services to use MetalLB
1102+
File: metallb-configure-services
10921103
- Name: Associating secondary interfaces metrics to network attachments
10931104
File: associating-secondary-interfaces-metrics-to-network-attachments
10941105
---

‎images/nw-metallb-layer2.png‎

105 KB
Loading

‎modules/nw-metallb-addresspool-cr.adoc‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
[id="nw-metallb-addresspool-cr_{context}"]
2+
= About the address pool custom resource
3+
4+
The fields for the address pool custom resource are described in the following table.
5+
6+
.MetalLB address pool custom resource
7+
[cols="1,1,3", options="header"]
8+
|===
9+
10+
|Field
11+
|Type
12+
|Description
13+
14+
|`metadata.name`
15+
|`string`
16+
|Specifies the name for the address pool.
17+
When you add a service, you can specify this pool name in the `metallb.universe.tf/address-pool` annotation to select an IP address from a specific pool.
18+
The names `doc-example`, `silver`, and `gold` are used throughout the documentation.
19+
20+
|`metadata.namespace`
21+
|`string`
22+
|Specifies the namespace for the address pool.
23+
Specify the same namespace that the MetalLB Operator uses.
24+
25+
|`spec.protocol`
26+
|`string`
27+
|Specifies the protocol for announcing the load balancer IP address to peer nodes.
28+
The only supported value is `layer2`.
29+
30+
|`spec.autoAssign`
31+
|`boolean`
32+
|Optional: Specifies whether MetalLB automatically assigns IP addresses from this pool.
33+
Specify `false` if you want explicitly request an IP address from this pool with the `metallb.universe.tf/address-pool` annotation.
34+
The default value is `true`.
35+
36+
|`spec.addresses`
37+
|`array`
38+
|Specifies a list of IP addresses for MetalLB to assign to services.
39+
You can specify multiple ranges in a single pool.
40+
Specify each range in CIDR notation or as starting and ending IP addresses separated with a hyphen.
41+
42+
|===
43+
44+
////
45+
.Address pool object
46+
[source,yaml]
47+
----
48+
apiVersion: metallb.io/v1alpha1
49+
kind: AddressPool
50+
metadata:
51+
name: <pool_name> <.>
52+
namespace: metallb-system <.>
53+
spec:
54+
protocol: <protocol_type> <.>
55+
autoAssign: true <.>
56+
addresses: <.>
57+
- <range_or_CIDR>
58+
...
59+
----
60+
<.> Specify the name for the address pool. When you add a service, you can specify this pool name in the `metallb.universe.tf/address-pool` annotation to select an IP address from a specific pool.
61+
62+
<.> Specify the namespace for the address pool.
63+
64+
<.> Specify the protocol for announcing the load balancer IP address to peer nodes. The only supported value is `layer2`.
65+
66+
<.> Optional: Specify whether MetalLB automatically assigns IP addresses from this pool. 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`.
67+
68+
<.> Specify 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.
69+
////

‎modules/nw-metallb-configure-address-pool.adoc‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
[id="nw-metallb-configure-address-pool_{context}"]
2+
= Configuring an address pool
3+
4+
As a cluster administrator, you can add address pools to your cluster to control the IP addresses that MetaLLB can assign to load-balancer services.
5+
6+
.Prerequisites
7+
8+
* Install the OpenShift CLI (`oc`).
9+
10+
* Log in as a user with `cluster-admin` privileges.
11+
12+
.Procedure
13+
14+
. Create a file, such as `addresspool.yaml`, with content like the following example:
15+
+
16+
[source,yaml]
17+
----
18+
apiVersion: metallb.io/v1alpha1
19+
kind: AddressPool
20+
metadata:
21+
namespace: metallb-system
22+
name: doc-example
23+
spec:
24+
protocol: layer2
25+
addresses:
26+
- 203.0.113.1-203.0.113.10
27+
- 203.0.113.65-203.0.113.75
28+
----
29+
30+
. Apply the configuration for the address pool:
31+
+
32+
[source,terminal]
33+
----
34+
$ oc apply -f addresspool.yaml
35+
----
36+
37+
.Verification
38+
39+
* View the address pool:
40+
+
41+
[source,terminal]
42+
----
43+
$ oc describe -n metallb-system addresspool doc-example
44+
----
45+
+
46+
.Example output
47+
[source,terminal]
48+
----
49+
Name: doc-example
50+
Namespace: metallb-system
51+
Labels: <none>
52+
Annotations: <none>
53+
API Version: metallb.io/v1alpha1
54+
Kind: AddressPool
55+
Metadata:
56+
...
57+
Spec:
58+
Addresses:
59+
203.0.113.1-203.0.113.10
60+
203.0.113.65-203.0.113.75
61+
Auto Assign: true
62+
Protocol: layer2
63+
Events: <none>
64+
----
65+
66+
Confirm that the address pool name, such as `doc-example`, and the IP address ranges appear in the output.

‎modules/nw-metallb-configure-svc.adoc‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
[id="nw-metallb-configure-svc_{context}"]
2+
= Configuring a service with MetalLB
3+
4+
You can configure a load-balancing service to use an external IP address from an address pool.
5+
6+
.Prerequisites
7+
8+
* Install the OpenShift CLI (`oc`).
9+
10+
* Install the MetalLB Operator and start MetalLB.
11+
12+
* Configure at least one address pool.
13+
14+
* Configure your network to route traffic from the clients to the host network for the cluster.
15+
16+
.Procedure
17+
18+
. Create a `<service_name>.yaml` file. In the file, ensure that the `spec.type` field is set to `LoadBalancer`.
19+
+
20+
Refer to the examples for information about how to request the external IP address that MetalLB assigns to the service.
21+
22+
. Create the service:
23+
+
24+
[source,terminal]
25+
----
26+
$ oc apply -f <service_name>.yaml
27+
----
28+
+
29+
.Example output
30+
[source,terminal]
31+
----
32+
service/<service_name> created
33+
----
34+
35+
.Verification
36+
37+
* Describe the service:
38+
+
39+
[source,terminal]
40+
----
41+
$ oc describe service <service_name>
42+
----
43+
+
44+
.Example output
45+
----
46+
Name: <service_name>
47+
Namespace: default
48+
Labels: <none>
49+
Annotations: metallb.universe.tf/address-pool: doc-example <.>
50+
Selector: app=service_name
51+
Type: LoadBalancer <.>
52+
IP Family Policy: SingleStack
53+
IP Families: IPv4
54+
IP: 10.105.237.254
55+
IPs: 10.105.237.254
56+
LoadBalancer Ingress: 192.168.100.5 <.>
57+
Port: <unset> 80/TCP
58+
TargetPort: 8080/TCP
59+
NodePort: <unset> 30550/TCP
60+
Endpoints: 10.244.0.50:8080
61+
Session Affinity: None
62+
External Traffic Policy: Cluster
63+
Events: <.>
64+
Type Reason Age From Message
65+
---- ------ ---- ---- -------
66+
Normal nodeAssigned 32m (x2 over 32m) metallb-speaker announcing from node "<node_name>"
67+
----
68+
<.> The annotation is present if you request an IP address from a specific pool.
69+
<.> The service type must indicate `LoadBalancer`.
70+
<.> The load-balancer ingress field indicates the external IP address if the service is assigned correctly.
71+
<.> The events field indicates the node name that is assigned to announce the external IP address.
72+
If you experience an error, the events field indicates the reason for the error.

‎modules/nw-metallb-example-addresspool.adoc‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
[id="nw-metallb-example-addresspool_{context}"]
2+
= Example address pool configurations
3+
4+
== Example: IPv4 and CIDR ranges
5+
6+
You can specify a range of IP addresses in CIDR notation.
7+
You can combine CIDR notation with the notation that uses a hyphen to separate lower and upper bounds.
8+
9+
[source,yaml]
10+
----
11+
apiVersion: metallb.io/v1beta1
12+
kind: AddressPool
13+
metadata:
14+
name: doc-example-cidr
15+
namespace: metallb-system
16+
spec:
17+
protocol: layer2
18+
addresses:
19+
- 192.168.100.0/24
20+
- 192.168.200.0/24
21+
- 192.168.255.1-192.168.255.5
22+
----
23+
24+
== Example: Reserve IP addresses
25+
26+
You can set the `autoAssign` field to `false` to prevent MetalLB from automatically assigning the IP addresses from the pool.
27+
When you add a service, you can request a specific IP address from the pool or you can specify the pool name in an annotation to request any IP address from the pool.
28+
29+
30+
[source,yaml]
31+
----
32+
apiVersion: metallb.io/v1beta1
33+
kind: AddressPool
34+
metadata:
35+
name: doc-example-reserved
36+
namespace: metallb-system
37+
spec:
38+
protocol: layer2
39+
addresses:
40+
- 10.0.100.0/28
41+
autoAssign: false
42+
----
43+
44+
== Example: IPv6 address pool
45+
46+
You can add address pools that use IPv6.
47+
The following example shows a single IPv6 range.
48+
However, you can specify multiple ranges in the `addresses` list, just like several IPv4 examples.
49+
50+
[source,yaml]
51+
----
52+
apiVersion: metallb.io/v1beta1
53+
kind: AddressPool
54+
metadata:
55+
name: doc-example-ipv6
56+
namespace: metallb-system
57+
spec:
58+
protocol: layer2
59+
addresses:
60+
- 2002:2:2::1-2002:2:2::100
61+
----

‎modules/nw-metallb-infra-considerations.adoc‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
[id="nw-metallb-infra-considerations_{context}"]
2+
= Infrastructure considerations for MetalLB
3+
4+
MetalLB is primarily useful for on-premise, bare metal installations because these installations do not include a native load-balancer capability.
5+
In addition to bare metal installations, installations of {product-title} on some infrastructures might not include a native load-balancer capability.
6+
For example, the following infrastructures might benefit from adding the MetalLB Operator:
7+
8+
* Bare metal
9+
10+
* VMware vSphere
11+
12+
* {rh-virtualization-first}
13+
14+
* {rh-openstack-first} when it is installed without Octavia
15+
16+
MetalLB Operator and MetalLB are supported with the OpenShift SDN and OVN-Kubernetes network providers.

0 commit comments

Comments
 (0)