How to install IoT Edge on Kubernetes (Preview)

IoT Edge can integrate with Kubernetes using it as a resilient, highly available infrastructure layer. It registers an IoT Edge Custom Resource Definition (CRD) with the Kubernetes API Server. Additionally, it provides an Operator (IoT Edge agent) that reconciles cloud-managed desired state with the local cluster state.

Module lifetime is managed by the Kubernetes scheduler, which maintains module availability and chooses their placement. IoT Edge manages the edge application platform running on top, continuously reconciling the desired state specified in IoT Hub with the state on the edge cluster. The edge application model is still the familiar model based on IoT Edge modules and routes. The IoT Edge agent operator performs automatic translation to the Kubernetes natives constructs like pods, deployments, services etc.

Here is a high-level architecture diagram:

kubernetes arch

Every component of the edge deployment is scoped to a Kubernetes namespace specific to the device, making it possible to share the same cluster resources among multiple edge devices and their deployments.


IoT Edge on Kubernetes is in public preview.

Install locally for a quick test environment


  • Kubernetes 1.10 or newer. If you don't have an existing cluster setup, you can use Minikube for a local cluster environment.

  • Helm, the Kubernetes package manager.

  • kubectl for viewing and interacting with the cluster.

Setup steps

  1. Start Minikube

    minikube start
  2. Initialize the Helm server component (tiller) in your cluster

    helm init
  3. Add IoT Edge repo and update the helm installation

    helm repo add edgek8s
    helm repo update
  4. Create an IoT Hub, register an IoT Edge device, and note its connection string.

  5. Install iotedged and IoT Edge agent into your cluster

    helm install \
    --name k8s-edge1 \
    --set "deviceConnectionString=replace-with-device-connection-string" \
  6. Open the Kubernetes dashboard in the browser

    minikube dashboard

    Under the cluster namespaces, you will see one for the IoT Edge device following the convention msiot-<iothub-name>-<edgedevice-name>. The IoT Edge agent and iotedged pods should be up and running in this namespace.

  7. Add a simulated temperature sensor module using the steps in the Deploy a module section of the quickstart. IoT Edge module management is done from the IoT Hub portal just like any other IoT Edge device. Making local changes to module configuration via Kubernetes tools is not recommended as they might get overwritten.

  8. In a few seconds, refreshing the Pods page under the edge device namespace in the dashboard will list the IoT Edge hub and simulated sensor pods as running with the IoT Edge hub pod ingesting data into IoT Hub.

Clean up resources

To remove all resources created by the edge deployment, use the following command with the name used in step 5 of the previous section.

helm delete --purge k8s-edge1

Next steps

Deploy as a highly available edge gateway

The edge device in a Kubernetes cluster can be used as an IoT gateway for downstream devices. It can be configured to be resilient to node failure thus providing high availability to edge deployments. See this detailed walkthrough to use IoT Edge in this scenario.