Demo L2 Announcement

This guide demonstrates Cilium’s L2 announcement feature and how it enables nodes to respond to ARP requests for LoadBalancer external IPs in a local Kubernetes cluster (Kind is used in this demo). The goal is to show how to assign external IPs to LoadBalancer services and have nodes announce those IPs on the host subnet so clients can reach services via ARP.

A presentation slide showing the word "Demo" on the left and a turquoise curved shape on the right with the text "L2 Announcement." Small copyright text "© Copyright KodeKloud" appears in the bottom-left corner.

Overview

Technologies: Cilium (L2 announcements), Kind (local cluster), Helm, kubectl.
Goal: Assign external IPs from a node subnet to LoadBalancer services and have selected nodes respond to ARP for those IPs using Cilium L2 announcements.
Key CRDs used:
- CiliumLoadBalancerIPPool: allocate external IPs for LoadBalancer services.
- CiliumL2AnnouncementPolicy: control which nodes/interfaces respond to ARP for which services.

Prerequisites

A running Kind cluster and kubectl configured to that cluster.
Helm installed and access to the Cilium Helm chart (cilium/cilium).
Docker available if using Kind node containers for debugging.

Useful references:

1. Check cluster state and prepare Cilium values

Before installing Cilium, the cluster nodes may appear NotReady because the CNI is missing:

kubectl get node
NAME                             STATUS     ROLES           AGE   VERSION
my-cluster-control-plane         NotReady   control-plane   30s   v1.32.2
my-cluster-worker                NotReady   <none>          19s   v1.32.2
my-cluster-worker2               NotReady   <none>          18s   v1.32.2

To enable L2 announcements, enable both the L2 announcement feature and kube-proxy replacement in Cilium. A typical Helm upgrade/install invocation looks like this:

helm upgrade cilium ./cilium \
  --namespace kube-system \
  --reuse-values \
  --set l2announcements.enabled=true \
  --set kubeProxyReplacement=true \
  --set k8sClientRateLimit.qps={QPS} \
  --set k8sClientRateLimit.burst={BURST} \
  --set k8sServiceHost=${API_SERVER_IP} \
  --set k8sServicePort=${API_SERVER_PORT}

When enabling kube-proxy replacement, provide the API server host and port (k8sServiceHost and k8sServicePort) so Cilium can reach the Kubernetes API. You can also edit the chart values file and set these keys before installing via Helm.

A good workflow is to fetch the default chart values, edit them, and then install:

helm show values cilium/cilium > values.yaml
# Edit values.yaml to set:
# kubeProxyReplacement: true
# l2announcements.enabled: true
# k8sServiceHost: <API_SERVER_IP>
helm install cilium cilium/cilium -n kube-system -f values.yaml

Example installation output (abbreviated):

LAST DEPLOYED: Wed Jun  4 23:58:52 2025
NAMESPACE: kube-system
STATUS: deployed
REVISION: 1
NOTES:
You have successfully installed Cilium with Hubble.
Your release version is 1.17.2.

Verify Cilium pods are running:

kubectl get pods -n kube-system

2. Deploy two simple applications with LoadBalancer services

Create a manifest named apps-and-svcs.yaml which deploys two HTTP echo applications and exposes each with a Service of type LoadBalancer. apps-and-svcs.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: app1-deployment
  labels:
    app: app1
spec:
  replicas: 1
  selector:
    matchLabels:
      app: app1
  template:
    metadata:
      labels:
        app: app1
    spec:
      containers:
      - name: app1
        image: hashicorp/http-echo
        args:
        - -listen=:80
        - -text="This is app1"
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: app1-service
  labels:
    app: myapp
spec:
  type: LoadBalancer
  selector:
    app: app1
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: app2-deployment
  labels:
    app: app2
spec:
  replicas: 1
  selector:
    matchLabels:
      app: app2
  template:
    metadata:
      labels:
        app: app2
    spec:
      containers:
      - name: app2
        image: hashicorp/http-echo
        args:
        - -listen=:80
        - -text="This is app2"
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: app2-service
  labels:
    app: myapp
spec:
  type: LoadBalancer
  selector:
    app: app2
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80

Apply the manifest:

kubectl apply -f apps-and-svcs.yaml

In a local Kind cluster, LoadBalancer services initially show EXTERNAL-IP as <pending>:

kubectl get svc
NAME           TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)        AGE
app1-service   LoadBalancer   10.96.207.254   <pending>     80:31514/TCP   5s
app2-service   LoadBalancer   10.96.157.80    <pending>     80:32546/TCP   5s
kubernetes     ClusterIP      10.96.0.1       <none>        443/TCP        9m

3. Provide external IPs to LoadBalancer services with Cilium IPAM

Create a CiliumLoadBalancerIPPool so Cilium can allocate external IPs for your services from an address block on your node subnet. In this demo the node subnet is 172.19.0.0/16 and we pick a small range: ipam.yaml:

apiVersion: "cilium.io/v2alpha1"
kind: CiliumLoadBalancerIPPool
metadata:
  name: "default-pool"
spec:
  blocks:
  - start: "172.19.0.240"
    stop: "172.19.0.250"

Apply the pool:

kubectl apply -f ipam.yaml
# ciliumloadbalancerippool.cilium.io/default-pool created

After creating the pool, services receive external IPs from that pool:

kubectl get svc
NAME           TYPE           CLUSTER-IP      EXTERNAL-IP      PORT(S)          AGE
app1-service   LoadBalancer   10.96.207.254   172.19.0.240     80:31514/TCP     4m52s
app2-service   LoadBalancer   10.96.157.80    172.19.0.241     80:32546/TCP     4m52s
kubernetes     ClusterIP      10.96.0.1       <none>           443/TCP          14m

Because these external IPs are on the same subnet as the host nodes, clients on that subnet will attempt to reach them via ARP. If no node responds to ARP for those IPs, traffic will not reach your services (curl will time out). Example failing request before L2 announcement is configured:

curl 172.19.0.240
# (no response / times out)

4. Configure the Cilium L2 Announcement policy

Create a CiliumL2AnnouncementPolicy to control which nodes and interfaces respond to ARP for which services. The example below:

Matches services labeled app: myapp
Excludes the control-plane node so only worker nodes respond
Restricts interfaces with a regex ‘^eth[0-9]+’ (matches eth0, eth1, …)
Enables both externalIPs and loadBalancerIPs

l2announce.yaml:

apiVersion: "cilium.io/v2alpha1"
kind: CiliumL2AnnouncementPolicy
metadata:
  name: l2announce-policy
spec:
  serviceSelector:
    matchLabels:
      app: myapp
  nodeSelector:
    matchExpressions:
      - key: node-role.kubernetes.io/control-plane
        operator: DoesNotExist
  interfaces:
    - "^eth[0-9]+"
  externalIPs: true
  loadBalancerIPs: true

Apply the policy:

kubectl apply -f l2announce.yaml
# ciliuml2announcementpolicy.cilium.io/l2announce-policy created

Describe the policy to confirm settings:

kubectl describe ciliuml2announcementpolicy l2announce-policy
# Name: l2announce-policy
# Spec:
#   External IPs: true
#   Interfaces: ^eth[0-9]+
#   Load Balancer IPs: true
#   Node Selector: matchExpressions: node-role.kubernetes.io/control-plane DoesNotExist
#   Service Selector: matchLabels: app=myapp

5. Which node responds for each service IP? (Leases)

Cilium coordinates which node will answer ARP for a given external IP using Lease objects. You can list the leases in the kube-system namespace:

kubectl get lease -n kube-system
NAME                                      HOLDER                 AGE
cilium-l2announce-default-app1-service    my-cluster-worker2     65s
cilium-l2announce-default-app2-service    my-cluster-worker      65s
...

The HOLDER field shows which node currently holds the lease and will therefore respond to ARP for the service IP.

6. Test connectivity and validate ARP

After the L2 announcement policy is active, clients on the same subnet can reach the LoadBalancer external IPs:

curl 172.19.0.240
curl 172.19.0.241
# "This is app2"

Verify the local ARP table shows the service IP entries mapped to the node MAC addresses:

arp -a | egrep "172.19.0.24[01]"
# ? (172.19.0.240) at 02:42:ac:13:00:04 [ether] on br-2c6b6be1a367
# ? (172.19.0.241) at 02:42:ac:13:00:03 [ether] on br-2c6b6be1a367

In Kind-based setups the MAC addresses correspond to the Docker/Kind bridge interfaces for node containers. You can inspect the node container interfaces to confirm which node IP/MAC answered ARP. Example:

docker ps
# CONTAINER ID   IMAGE                NAMES
# ... my-cluster-worker2
# ... my-cluster-worker
docker exec my-cluster-worker2 ip addr show eth0
# ... inet 172.19.0.4/16 ...
# link/ether 02:42:ac:13:00:04

The link/ether value should match the ARP mapping for the external IP owned by that node.

7. Summary and quick references

Enable l2announcements and kube-proxy replacement in Cilium (via Helm values or values.yaml).
Create a CiliumLoadBalancerIPPool to allocate external IPs on the node subnet for LoadBalancer services.
Create a CiliumL2AnnouncementPolicy to specify which services, nodes, and interfaces should respond to ARP (externalIPs and/or loadBalancerIPs).
Inspect Leases to determine which node is announcing each external IP, and validate connectivity with curl and arp.

Key resources and commands:

Resource / Object	Purpose	Example command
Cilium Helm values	Enable kube-proxy replacement and l2announcements	helm install cilium cilium/cilium -n kube-system -f values.yaml
CiliumLoadBalancerIPPool	Provide external IPs for LoadBalancer services	kubectl apply -f ipam.yaml
CiliumL2AnnouncementPolicy	Control ARP announcements per service/node/interface	kubectl apply -f l2announce.yaml
Lease objects	Show which node currently announces a service IP	kubectl get lease -n kube-system

Introduction

Cilium Overview

Installing & Configuring Cilium

Exploring Cilium

Network Policy

Service Mesh

Cluster Mesh

Observability

BGP & External Networking

Optimization

Demo L2 Announcement

Overview

Prerequisites

1. Check cluster state and prepare Cilium values

2. Deploy two simple applications with LoadBalancer services

3. Provide external IPs to LoadBalancer services with Cilium IPAM

4. Configure the Cilium L2 Announcement policy

5. Which node responds for each service IP? (Leases)

6. Test connectivity and validate ARP

7. Summary and quick references

Watch Video

​Overview

​Prerequisites

​1. Check cluster state and prepare Cilium values

​2. Deploy two simple applications with LoadBalancer services

​3. Provide external IPs to LoadBalancer services with Cilium IPAM

​4. Configure the Cilium L2 Announcement policy

​5. Which node responds for each service IP? (Leases)

​6. Test connectivity and validate ARP

​7. Summary and quick references

Watch Video

Overview

Prerequisites

1. Check cluster state and prepare Cilium values

2. Deploy two simple applications with LoadBalancer services

3. Provide external IPs to LoadBalancer services with Cilium IPAM

4. Configure the Cilium L2 Announcement policy

5. Which node responds for each service IP? (Leases)

6. Test connectivity and validate ARP

7. Summary and quick references