Use PorterLB in Layer 2 Mode

This document demonstrates how to use PorterLB in Layer 2 mode to expose a Service backed by two Pods. The Eip, Deployment and Service described in this document are examples only and you need to customize the commands and YAML configurations based on your requirements.

Prerequisites

  • You need to prepare a Kubernetes cluster where PorterLB has been installed. All Kubernetes cluster nodes must be on the same Layer 2 network (under the same router).
  • You need to prepare a client machine, which is used to verify whether PorterLB functions properly in Layer 2 mode. The client machine needs to be on the same network as the Kubernetes cluster nodes.
  • The Layer 2 mode requires your infrastructure environment to allow anonymous ARP/NDP packets. If PorterLB is installed in a cloud-based Kubernetes cluster for testing, you need to confirm with your cloud vendor whether anonymous ARP/NDP packets are allowed. If not, the Layer 2 mode cannot be used.

This document uses the following devices as an example:

Device NameIP AddressMAC AddressDescription
master1192.168.0.252:54:22:a3:9a:d9Kubernetes cluster master
worker-p001192.168.0.352:54:22:3a:e6:6eKubernetes cluster worker 1
worker-p002192.168.0.452:54:22:37:6c:7bKubernetes cluster worker 2
i-f3fozos0192.168.0.552:54:22:fa:b9:3bClient machine

Step 1: Enable strictARP for kube-proxy

In Layer 2 mode, you need to enable strictARP for kube-proxy so that all NICs in the Kubernetes cluster stop answering ARP requests from other NICs and PorterLB handles ARP requests instead.

  1. Log in to the Kubernetes cluster and run the following command to edit the kube-proxy ConfigMap:

    1. kubectl edit configmap kube-proxy -n kube-system

  2. In the kube-proxy ConfigMap YAML configuration, set data.config.conf.ipvs.strictARP to true.

    1. ipvs:
    2.   strictARP: true

  3. Run the following command to restart kube-proxy:

    1. kubectl rollout restart daemonset kube-proxy -n kube-system

Step 2: Specify the NIC Used for PorterLB

If the node where PorterLB is installed has multiple NICs, you need to specify the NIC used for PorterLB in Layer 2 mode. You can skip this step if the node has only one NIC.

In this example, the master1 node where PorterLB is installed has two NICs (eth0 192.168.0.2 and eth1 192.168.1.2), and eth0 192.168.0.2 will be used for PorterLB.

Run the following command to annotate master1 to specify the NIC:

  1. kubectl annotate nodes master1 layer2.porter.kubesphere.io/v1alpha1="192.168.0.2"

Step 3: Create an Eip Object

The Eip object functions as an IP address pool for PorterLB.

  1. Run the following command to create a YAML file for the Eip object:

    1. vi porter-layer2-eip.yaml

  2. Add the following information to the YAML file:

    1. apiVersion: network.kubesphere.io/v1alpha2
    2. kind: Eip
    3. metadata:
    4.   name: porter-layer2-eip
    5. spec:
    6.   address: 192.168.0.91-192.168.0.100
    7.   interface: eth0
    8.   protocol: layer2

    NOTE

    • The IP addresses specified in spec:address must be on the same network segment as the Kubernetes cluster nodes.

    • For details about the fields in the Eip YAML configuration, see Configure IP Address Pools Using Eip.

  3. Run the following command to create the Eip object:

    1. kubectl apply -f porter-layer2-eip.yaml

Step 4: Create a Deployment

The following creates a Deployment of two Pods using the luksa/kubia image. Each Pod returns its own Pod name to external requests.

  1. Run the following command to create a YAML file for the Deployment:

    1. vi porter-layer2.yaml

  2. Add the following information to the YAML file:

    1. apiVersion: apps/v1
    2. kind: Deployment
    3. metadata:
    4.   name: porter-layer2
    5. spec:
    6.   replicas: 2
    7.   selector:
    8.     matchLabels:
    9.       app: porter-layer2
    10.   template:
    11.     metadata:
    12.       labels:
    13.         app: porter-layer2
    14.     spec:
    15.       containers:
    16.         - image: luksa/kubia
    17.           name: kubia
    18.           ports:
    19.             - containerPort: 8080

  3. Run the following command to create the Deployment:

    1. kubectl apply -f porter-layer2.yaml

Step 5: Create a Service

  1. Run the following command to create a YAML file for the Service:

    1. vi porter-layer2-svc.yaml

  2. Add the following information to the YAML file:

    1. kind: Service
    2. apiVersion: v1
    3. metadata:
    4.   name: porter-layer2-svc
    5.   annotations:
    6.     lb.kubesphere.io/v1alpha1: porter
    7.     protocol.porter.kubesphere.io/v1alpha1: layer2
    8.     eip.porter.kubesphere.io/v1alpha2: porter-layer2-eip
    9. spec:
    10.   selector:
    11.     app: porter-layer2
    12.   type: LoadBalancer
    13.   ports:
    14.     - name: http
    15.       port: 80
    16.       targetPort: 8080
    17.   externalTrafficPolicy: Cluster

    NOTE

    • You must set spec:type to LoadBalancer.
    • The lb.kubesphere.io/v1alpha1: porter annotation specifies that the Service uses PorterLB.
    • The protocol.porter.kubesphere.io/v1alpha1: layer2 annotation specifies that PorterLB is used in Layer 2 mode.
    • The eip.porter.kubesphere.io/v1alpha2: porter-layer2-eip annotation specifies the Eip object used by PorterLB. If this annotation is not configured, PorterLB automatically uses the first available Eip object that matches the protocol. You can also delete this annotation and add the spec:loadBalancerIP field (for example, spec:loadBalancerIP: 192.168.0.91) to assign a specific IP address to the Service.
    • If spec:externalTrafficPolicy is set to Cluster (default value), PorterLB randomly selects a node from all Kubernetes cluster nodes to handle Service requests. Pods on other nodes can also be reached over kube-proxy.
    • If spec:externalTrafficPolicy is set to Local, PorterLB randomly selects a node that contains a Pod in the Kubernetes cluster to handle Service requests. Only Pods on the selected node can be reached.

  3. Run the following command to create the Service:

    1. kubectl apply -f porter-layer2-svc.yaml

Step 6: Verify PorterLB in Layer 2 Mode

The following verifies whether PorterLB functions properly.

  1. In the Kubernetes cluster, run the following command to obtain the external IP address of the Service:

    1. kubectl get svc porter-layer2-svc

    service-ip

  2. In the Kubernetes cluster, run the following command to obtain the IP addresses of the cluster nodes:

    1. kubectl get nodes -o wide

    node-ips

  3. In the Kubernetes cluster, run the following command to check the nodes of the Pods:

    1. kubectl get po

    pod-nodes

    NOTE

    In this example, the Pods are automatically assigned to different nodes. You can manually assign Pods to different nodes.

  4. On the client machine, run the following commands to ping the Service IP address and check the IP neighbors:

    1. ping 192.168.0.91
    1. ip neigh

    ip-neigh

    In the output of the ip neigh command, the MAC address of the Service IP address 192.168.0.91 is the same as that of worker-p001 192.168.0.3. Therefore, PorterLB has mapped the Service IP address to the MAC address of worker-p001.

  5. On the client machine, run the following command to access the Service:

    1. curl 192.168.0.91

    If spec:externalTrafficPolicy in the Service YAML configuration is set to Cluster, both Pods can be reached.

    service-cluster

    If spec:externalTrafficPolicy in the Service YAML configuration is set to Local, only the Pod on the node selected by PorterLB can be reached.

    service-local

Last modified March 31, 2021: Relocated files to adapt to localization and changed links. (6b5fcb1)