KubeEdge Setup Guide#

A complete hands-on guide to setting up a KubeEdge cloud-edge environment, managing IoT devices, and troubleshooting common issues.

Prerequisites#

Ensure you have the required tools installed before starting:

# Verify required tools
docker --version
kubectl version --client
go version   # Optional, for building from source

You will need:

  • A Kubernetes cluster (cloud side)
  • Ubuntu/CentOS machines for edge nodes
  • Network connectivity between cloud and edge

Step 1: Prepare Your Environment#

# Set up environment variables
export KUBEEDGE_VERSION=v1.18.0
export CLOUD_MASTER_IP=<your-k8s-master-ip>
export EDGE_NODE_NAME=edge-node-01

# Clean up any previous installations
sudo systemctl stop edgecore 2>/dev/null || true
sudo systemctl stop cloudcore 2>/dev/null || true

Step 2: Install CloudCore (Cloud Side)#

# Download and install keadm
curl -L https://github.com/kubeedge/kubeedge/releases/download/${KUBEEDGE_VERSION}/keadm-${KUBEEDGE_VERSION}-linux-amd64.tar.gz | tar xz
sudo mv keadm-${KUBEEDGE_VERSION}-linux-amd64/keadm/keadm /usr/local/bin/

# Initialize CloudCore on your Kubernetes cluster
sudo keadm init \
  --advertise-address=${CLOUD_MASTER_IP} \
  --kubeedge-version=${KUBEEDGE_VERSION}

# Verify CloudCore is running
kubectl get pods -n kubeedge

Step 3: Get Token for Edge Nodes#

# Generate token for edge node registration
sudo keadm gettoken

# Output will look like:
# 27a37ef16159f7d3be8fae95d588b79b3adaaf92727b72659eb89758c66ffda2.eyJh...

Step 4: Join Edge Node#

Run the following on your edge machine:

# Download keadm on edge node
curl -L https://github.com/kubeedge/kubeedge/releases/download/${KUBEEDGE_VERSION}/keadm-${KUBEEDGE_VERSION}-linux-amd64.tar.gz | tar xz
sudo mv keadm-${KUBEEDGE_VERSION}-linux-amd64/keadm/keadm /usr/local/bin/

# Join the edge node to CloudCore
sudo keadm join \
  --cloudcore-ipport=${CLOUD_MASTER_IP}:10000 \
  --edgenode-name=${EDGE_NODE_NAME} \
  --token=<token-from-step-3> \
  --kubeedge-version=${KUBEEDGE_VERSION}

# Verify edge node is running
sudo systemctl status edgecore

Step 5: Verify Cloud-Edge Connection#

Back on the cloud side, check if the edge node is connected:

kubectl get nodes

# Expected output:
# NAME           STATUS   ROLES                  AGE   VERSION
# master         Ready    control-plane,master   1d    v1.21.0
# edge-node-01   Ready    agent,edge             5m    v1.19.3-kubeedge-v1.18.0

Step 6: Deploy Your First Edge Application#

# Create a simple nginx deployment for edge
cat << 'EOF' | kubectl apply -f -
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-edge
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx-edge
  template:
    metadata:
      labels:
        app: nginx-edge
    spec:
      nodeSelector:
        kubernetes.io/hostname: edge-node-01
      containers:
        - name: nginx
          image: nginx:alpine
          ports:
            - containerPort: 80
          resources:
            limits:
              memory: "128Mi"
              cpu: "200m"
---
apiVersion: v1
kind: Service
metadata:
  name: nginx-edge-service
spec:
  selector:
    app: nginx-edge
  ports:
    - port: 80
      targetPort: 80
  type: NodePort
EOF

Step 7: Verify Edge Deployment#

# Check if pod is running on edge node
kubectl get pods -o wide

# Test offline capability — disconnect edge node from network
# The pod should continue running locally!

# Reconnect and confirm synchronization resumes
kubectl describe node edge-node-01

Device Management with KubeEdge#

Step 1: Define a Device Model#

cat << 'EOF' | kubectl apply -f -
apiVersion: devices.kubeedge.io/v1alpha2
kind: DeviceModel
metadata:
  name: temperature-model
  namespace: default
spec:
  properties:
    - name: temperature
      description: Temperature reading in Celsius
      type:
        string:
          accessMode: ReadOnly
          defaultValue: "0"
    - name: humidity
      description: Humidity percentage
      type:
        string:
          accessMode: ReadOnly
          defaultValue: "0"
EOF

Step 2: Create a Device Instance#

cat << 'EOF' | kubectl apply -f -
apiVersion: devices.kubeedge.io/v1alpha2
kind: Device
metadata:
  name: temp-sensor-01
  namespace: default
  labels:
    model: temperature-model
    location: factory-floor
spec:
  deviceModelRef:
    name: temperature-model
  protocol:
    mqtt:
      server: tcp://localhost:1883
  nodeSelector:
    nodeSelectorTerms:
      - matchExpressions:
          - key: kubernetes.io/hostname
            operator: In
            values:
              - edge-node-01
  data:
    dataTopic: "$hw/events/device/temp-sensor-01/data/update"
    dataTopicTwin: "$hw/events/device/temp-sensor-01/twin/update"
EOF

Step 3: Deploy a Device Monitor Application#

cat << 'EOF' | kubectl apply -f -
apiVersion: apps/v1
kind: Deployment
metadata:
  name: temperature-monitor
spec:
  replicas: 1
  selector:
    matchLabels:
      app: temperature-monitor
  template:
    metadata:
      labels:
        app: temperature-monitor
    spec:
      nodeSelector:
        kubernetes.io/hostname: edge-node-01
      containers:
        - name: monitor
          image: eclipse-mosquitto:latest
          command: ["/bin/sh", "-c"]
          args:
            - |
              while true; do
                mosquitto_pub -h localhost \
                  -t '$hw/events/device/temp-sensor-01/data/update' \
                  -m '{"temperature":"$(( RANDOM % 40 + 10 ))","humidity":"$(( RANDOM % 100 ))"}'
                sleep 30
              done
          resources:
            limits:
              memory: "64Mi"
              cpu: "100m"
EOF

Advanced: Multi-Cloud Edge Setup#

# Deploy CloudCore on AWS
keadm init --advertise-address=<aws-ip>

# Connect edge nodes from different providers
keadm join --cloudcore-ipport=<aws-ip>:10000 --edgenode-name=azure-edge
keadm join --cloudcore-ipport=<aws-ip>:10000 --edgenode-name=gcp-edge
keadm join --cloudcore-ipport=<aws-ip>:10000 --edgenode-name=onprem-edge

Advanced: Edge AI / ML Deployment#

apiVersion: apps/v1
kind: Deployment
metadata:
  name: edge-ai-inference
spec:
  template:
    spec:
      nodeSelector:
        kubernetes.io/hostname: edge-gpu-node
      containers:
        - name: tensorflow-serving
          image: tensorflow/serving:latest-gpu
          resources:
            limits:
              nvidia.com/gpu: 1

Troubleshooting Common Issues#

Issue 1: Edge Node Not Connecting#

# Check CloudCore logs
kubectl logs -n kubeedge deployment/cloudcore

# Check EdgeCore logs on edge node
sudo journalctl -u edgecore.service -f

# Verify network connectivity
curl -k https://<cloudcore-ip>:10000/readyz

# Reset and rejoin if needed
sudo keadm reset
sudo keadm join --cloudcore-ipport=<ip>:10000 --token=<new-token>

Issue 2: Device Not Reporting Data#

# Check device twin status
kubectl describe device temp-sensor-01

# Verify MQTT broker connectivity
mosquitto_sub -h localhost -t '$hw/events/device/+/twin/update'

# Check device mapper logs
kubectl logs -n kubeedge deployment/device-mapper

# Test device protocol manually
mosquitto_pub -h localhost \
  -t '$hw/events/device/temp-sensor-01/data/update' \
  -m '{"temperature":"25"}'

Issue 3: Pod Not Scheduling to Edge#

# Check node labels and selectors
kubectl get nodes --show-labels

# Inspect pod spec for nodeSelector issues
kubectl describe pod <pod-name>

# Check for resource constraints
kubectl describe node <edge-node-name>

# Check for taints and tolerations
kubectl describe node <edge-node-name> | grep -i taint

Issue 4: MQTT Messages Not Flowing#

# Test MQTT connectivity
mosquitto_pub -h <broker-ip> -t test/topic -m "hello"
mosquitto_sub -h <broker-ip> -t test/topic

# Check EventBus logs
sudo journalctl -u eventbus.service -f

# Verify device mapper configuration
kubectl get devicemodel,device -o wide

Development Environment Setup#

# Clone the KubeEdge repository
git clone https://github.com/kubeedge/kubeedge.git
cd kubeedge

# Install Go dependencies
go mod download

# Build all components
make all

# Run unit tests
make test

# Build specific components
make cloudcore
make edgecore
make keadm

# Run integration and e2e tests
make test-integration
make e2e-test
make device-test

Key Repository Directories#

DirectoryPurpose
/cloudCloudCore components (cloud-side logic)
/edgeEdgeCore components (edge-side logic)
/keadmAdministration tools
/pkgShared packages and utilities
/testsTest suites and integration tests
/docsDocumentation and proposals
/stagingStaging area for new features

Useful Resources#

ResourceLink
Official Docshttps://kubeedge.io/docs/
GitHub Repositoryhttps://github.com/kubeedge/kubeedge
Installation Guidehttps://kubeedge.io/docs/setup/install-with-keadm/
Device Managementhttps://kubeedge.io/docs/developer/device_crd/
Troubleshootinghttps://kubeedge.io/docs/troubleshooting/troubleshooting/
Architecture Overviewhttps://kubeedge.io/docs/architecture/overview/
Community Slackhttps://kubeedge.slack.com
Contributing Guidehttps://github.com/kubeedge/kubeedge/blob/master/CONTRIBUTING.md
Backward Keep Track of Mac Installation Workflow Forward