# Shifu turns every IoT device into a Kubernetes CRD and a pod

> Shifu is an Apache-2.0 licensed Go framework that runs a device driver as a Kubernetes pod, so HTTP, MQTT, OPC UA, RTSP, TCP socket and Siemens S7 devices appear in the cluster as custom resources. The version is still 0.x, the release cadence is weekly, and the contributor workflow needs envtest and a real API server.

**Edgenesis/shifu** — Kubernetes-native IoT gateway

- Repository: https://github.com/Edgenesis/shifu
- Website: https://shifu.dev
- Stars: 1,437 · Forks: 136
- Language: Go
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/edgenesis-shifu

## A device becomes a CRD and a pod, not a broker topic

Shifu is described as a Kubernetes native, production-grade, protocol and vendor agnostic IoT gateway, and the two key terms in the README explain its design. shifu is a Kubernetes CRD for integrating IoT devices into the cluster. DeviceShifu is a Kubernetes pod as well as the atomic unit of Shifu, and it mainly contains the driver of the device and represents a device in the cluster, which the README says you can also call the digital twin of the device.

That is a different starting point from the usual IoT gateway story. The common pattern is a broker in the middle, with a bridge process per protocol translating into MQTT topics, and a separate operations stack for those bridges. Shifu's claim, expressed in the README as let's develop APPs, not infra, is that the driver lives in the cluster next to the application, so there is no additional operations infrastructure to maintain.

The features section spells out the consequences. Kubernetes native means you develop your application while managing your devices, sparing the need for maintaining an additional O&M infrastructure. Open Platform means no vendor lock-in, and that you can deploy Shifu on the edge, from a Raspberry Pi to edge clusters, or on the cloud, with public, private and hybrid cloud all supported.

The atomic unit is the pod, and that is what makes the model work with standard tooling. A device in Shifu is a Kubernetes object, so anything that deploys workloads can deploy devices, and the same RBAC, scheduling, rollout and monitoring story applies to a camera as to a web service.

## Protocol support is a set of device shifu commands

The protocol agnostic claim is implemented as separate device shifu binaries, and the Makefile shows exactly which ones exist. The DEVICESHIFU_CMDS variable lists deviceshifu/cmdhttp, deviceshifu/cmdmqtt, deviceshifu/cmdopcua and deviceshifu/cmdsocket, and the build target compiles each of them into a binary under bin/.

The README names the protocols in scope as HTTP, MQTT, RTSP, Siemens S7, TCP socket and OPC UA, and the examples directory shows the same spread with one directory per device type: httpDeviceShifu, mqttDeviceShifu, opcuaDeviceShifu, rtspDeviceShifu, siemensPLCDeviceShifu, socketDeviceShifu and tcpDeviceShifu, plus lwM2M examples both with and without security.

The interesting part is what the build does not contain. There is no deviceshifu/cmdrtsp and no deviceshifu/cmdsiemens, which tells you that RTSP and Siemens S7 support lives in the example directories rather than in the shipped command set, or at least is not part of the default build targets. The README's stated reason for the design is that the microservice architecture of Shifu enables it to quickly adapt to new protocols, which is a claim about the deployment model rather than about a plugin interface.

For a reader, the practical question is therefore concrete: if your device speaks one of the four built protocols, there is a command for it, and if it does not, the examples are the template you would start from. The README's headline claim about connecting a proprietary-protocol camera with five lines of code points at that template.

## The build produces a CLI, a telemetry service and a controller

Beyond the device shifus, the build produces three other binaries, and they map onto the three things you do with a gateway.

The first is shifuctl, the command line tool, built from cmd/shifuctl and installable with go install.

```bash
go install ${PROJECT_ROOT}/cmd/shifuctl
```

The second is telemetryservice, which is the piece that moves device data out of the cluster, and the third is the controller itself, built separately from pkg/k8s/crd with main.go, which is the component that reconciles the shifu custom resources.

There are also HTTPSTUB_CMDS, namely httpstub/powershellstub and httpstub/sshstub, which are test doubles rather than production binaries. They exist so a device shifu can be exercised against something that behaves like a device without the hardware.

The module itself is modern Go, with go 1.26.1 in go.mod, and the direct dependencies tell you the protocol story. paho.mqtt.golang and gopcua/opcua are the MQTT and OPC UA clients, k8s.io/apimachinery and k8s.io/client-go are the Kubernetes interfaces, and gopkg.in/yaml.v3 handles the device specification files. The rest of the dependency list is where the integrations live: TDengine and MySQL and SQL Server drivers, the MinIO client, a CoAP library, pion/dtls for datagram security, cobra for the CLI, ginkgo and gomega for the test suites, and controller-runtime with knative.dev/pkg for the Kubernetes side.

The build image is versioned from a version.txt file at the root, and the repository also carries a Makefile target that builds the controller into bin/shifu-controller.

## make test needs envtest and a downloaded API server

The test target is where a contributor meets the real constraint of this project, and it is worth reading in full before you plan to contribute.

The envtest machinery is the kubebuilder approach: it downloads the control plane binaries and runs a real API server and etcd in the test, rather than mocking the Kubernetes client. The Makefile derives the version to fetch from the module file itself, with ENVTEST_K8S_VERSION computed from the k8s.io/api version in go.mod and the minor version mapped to a 1.x release, and ENVTEST_VERSION derived from the sigs.k8s.io/controller-runtime version to pick the matching release branch of the envtest setup script.

In practice, running the test suite means downloading Kubernetes test binaries on first run and starting a control plane per test package. That is heavier than a unit test suite, and it is the direct consequence of the design: the thing under test is a controller, and a controller cannot be meaningfully tested without an API server.

The rest of the tooling is more conventional. There is a fmt target and a vet target.

```bash
go fmt ./...
go vet ./...
```

There is also a golangci-lint workflow in GitHub Actions, an Azure Pipelines build definition, a codecov badge, a Go Report Card badge, and a CHANGELOG/ directory at the root. The test suite itself uses ginkgo and gomega, with testify also present in the dependencies.

## Telemetry has its own service and several backends

Moving data out of a cluster of device pods is a separate problem from talking to the devices, and Shifu treats it that way. The telemetryservice is a first-class binary in the build targets, and the examples directory shows several ways to wire it up: a plain telemetryservice, an mqttTelemetryService, a minioTelemetryService and a tdengineTelemetryService.

The backends are the interesting part, because they show what a gateway has to be good at. MinIO is object storage, TDengine is a time-series database, and MQTT is the broker-based path that Shifu's model otherwise tries to avoid needing. The dependencies confirm it, with the MinIO Go client, the TDengine driver, the MySQL driver and the SQL Server driver all present.

There is a shifu_dashboard example as well, and an mcp-demo directory, which suggests a recent interest in exposing the gateway to model-driven tooling. The examples also cover a deviceshifu directory and a driver_utils directory, which are the natural starting points for someone writing a driver for a device nobody has touched yet.

For the protocol work itself, the lwM2M examples come in two flavours, one with security and one without, and the lwm2m_gw_http and lwm2m_gw_opcua directories show the gateway sitting between LwM2M and other protocols. That is the pattern the architecture implies, a device shifu per device, with gateways composing them when a device has to be reachable through more than one protocol.

## Apache-2.0, a CNCF landscape listing, and weekly 0.x releases

The licence is Apache-2.0, and the README states that the project is distributed under the Apache 2.0 License, with the LICENSE file at the repository root. You can use, modify and redistribute it, including in commercial products, provided the licence and notice requirements are met. That is a licensing fact rather than legal advice, and it is the permissive end of the scale, which suits infrastructure software intended to sit in someone else's cluster.

The project is officially a CNCF landscape project, which is a listing rather than a certification, and the README carries the CNCF logo. The repository has a CODE_OF_CONDUCT.md, a CONTRIBUTING.md, a CLAUDE.md, and community channels including a Discord server, GitHub Discussions, an X account and a YouTube channel, with the README saying any suggestion will be deeply valued.

The release cadence is the most telling number. The recent releases are v0.106.1 on 2026-09-28, v0.107.0-rc1 on 2026-10-07 and v0.107.0 on 2026-10-12, and the last push was on 2026-10-16. That is a release candidate followed by a final within a week, and a patch release a fortnight earlier, which is a weekly-ish rhythm.

The 0.x version number is the thing to weigh against that. A pre-1.0 project can change its API, its CRD shape and its configuration format between minor versions, and the fact that the minor number is already at 107 says a lot about how fast the surface is moving. For a team planning to run this in production, the upgrade path is a migration conversation rather than a dependency bump, and the CHANGELOG directory at the root is where you would read it.

## What Shifu replaces, and what it still asks you to own

The alternative to Shifu is the gateway tier it argues against: a broker, a bridge process per protocol, a separate management stack, and a monitoring setup for all of it. The difference in approach is that Shifu does not centralise the protocols anywhere outside the cluster. The driver runs as a pod next to your application, the device is a custom resource, and the protocols are handled by small binaries you deploy like any other workload.

What that buys you is the elimination of a second operations surface. What it costs you is that you now need a Kubernetes cluster at the edge for a device fleet, that the driver is a container image you have to build and distribute, and that the control plane that reconciles those resources is a component you have to trust and keep current.

The shifu.dev documentation is organised around exactly these three jobs, with separate guides for installing Shifu, for connecting devices and for application development, plus a KillerCoda demo environment for trying it without setting up hardware. The install guide, the device case guides and the application guide are where an evaluation should start, since the README itself is a summary and points there for detail.

One thing the README does not explain is the operational cost at the edge. A Raspberry Pi running a cluster that hosts device pods and a controller is a different commitment from a container on a server, and the docs linked from the README are the place to check what the project expects of the host.

## Conclusion

Shifu fits a team that already runs Kubernetes and has a fleet of heterogeneous devices, and that would rather write one driver per device inside the cluster than maintain a separate gateway tier with its own brokers and bridges. It does not fit a small deployment without a cluster, or a team that wants a single binary to run on a device. Before adopting it, read the install guide at shifu.dev, look at the examples/ directory for the protocol closest to your hardware, and confirm you can run the envtest-backed test suite, because the make test target downloads Kubernetes test binaries rather than using a unit test double.

## FAQ

### What is Shifu and what problem does it solve?

Shifu is a Kubernetes native, protocol and vendor agnostic IoT gateway written in Go. It models a device as a shifu custom resource and a DeviceShifu pod that contains the device driver, so applications talk to devices through the cluster instead of through a separate gateway tier of brokers and bridges.

### Which device protocols does Shifu support?

The README names HTTP, MQTT, RTSP, Siemens S7, TCP socket and OPC UA. The build compiles device shifu commands for HTTP, MQTT, OPC UA and TCP socket, and the examples directory adds httpDeviceShifu, mqttDeviceShifu, opcuaDeviceShifu, rtspDeviceShifu, siemensPLCDeviceShifu, socketDeviceShifu, tcpDeviceShifu and LwM2M examples.

### How do I build Shifu from source?

The Makefile build target compiles each device shifu command into bin/, and the other build targets are shifuctl, telemetryservice and the controller, built from pkg/k8s/crd. The shifuctl CLI can also be installed with go install on the cmd/shifuctl directory, and the image version is read from version.txt.

### What does running the Shifu test suite require?

The make test target uses envtest, which downloads the kubebuilder Kubernetes test binaries and runs a real API server rather than a mock, with the version derived from the k8s.io/api and controller-runtime versions in go.mod. The tests run with the race detector and coverage output, and they use ginkgo and gomega.

### Is Shifu Apache 2.0 licensed and how often is it released?

The README states the project is distributed under the Apache 2.0 License, and it is officially a CNCF landscape project. Releases come fast, with v0.106.1 on 2026-09-28, v0.107.0-rc1 on 2026-10-07 and v0.107.0 on 2026-10-12, while the version number remains in the 0.x range.

## Sources

- [Edgenesis/shifu on GitHub](https://github.com/Edgenesis/shifu)
- [License: Apache-2.0](https://github.com/Edgenesis/shifu/blob/main/LICENSE)
- [Project website](https://shifu.dev)
- [README](https://github.com/Edgenesis/shifu/blob/main/README.md)
- [Releases](https://github.com/Edgenesis/shifu/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/edgenesis-shifu