How gaomind/htnn works
Project type and purpose
• HTNN is a cloud-native, cross-layer networking solution built on Envoy and Istio.
• It consists of two main logical subsystems:
a. A Control Plane (the “controller” component) that runs in Kubernetes, watches custom resources (CRDs), and generates XDS/EnvoyFilter configurations.
b. A Data Plane (the “api” component) that plugs into Envoy via Go extensions to enforce network policies, plugins, and filters at runtime.
• Supporting subsystems: CRD definitions (“types”), plugin implementations, service‐registry connectors, Helm charts (“manifests”), documentation site, and test suites (unit, integration, e2e).
File structure
• Top‐level dirs:
• api – Go library implementing the data-plane API, filters, plugin state, cookie handling, proto definitions, and filter manager.
• controller – Kubernetes controller with subpackages for config, reconcilers (consumer, dynamicconfig, filterpolicy, serviceregistry), translation logic, Istio/EnvoyFilter generation, metrics, and logging.
• types – Kubernetes CRD API definitions (Go types, clientsets, deep-copy, validation).
• plugins – Example plugin host and dynamicconfigs loader, plus plugin SDK pkg, integration tests.
• manifests – Helm charts for deploying HTNN controller and gateway, Docker images, and K8s manifests (CRDs, RBAC, deployments, webhooks).
• e2e, api/tests, controller/tests, plugins/tests – Full integration and end-to-end test suites.
• site – Hugo-based documentation website.
• patch – Patches against various Istio releases.
• Key architecture patterns:
• Kubernetes Operator pattern for the control plane.
• Envoy Filter Extension for the data plane.
• Plugin framework—dynamic plugin registration via protobuf + Go runtime.
• Service Registry Adapters (Consul, Nacos).
• Deployment helpers: Helm charts, Makefile, CI workflows.
README
• Confirms HTNN’s purpose: cloud-native cross-layer networking, extensible via Go runtime, multi-cluster support.
• References documentation on dataplane support, quick start, architecture sections in the site folder.
Diagramming the architecture
• Kubernetes API Server (CRDs for Consumer, DynamicConfig, FilterPolicy, HTTPFilterPolicy, ServiceRegistry).
• HTNN Controller (with subcomponents):
• ConsumerController
• DynamicConfigController
• FilterPolicyController
• ServiceRegistryController
• Translation Engine → EnvoyFilter generator
• Service Registries (Consul, Nacos adapters).
• Envoy Proxy (Data Plane) with HTNN Go Filter extension:
• filtermanager
• consumer plugins
• dynamicconfig loader
• pluginstate
• External Services: upstream services simulated in tests, registry back-ends.
• Helm/helm-chart deployment (manifests).
• CI/CD pipelines and test harness (unit, integration, e2e).
• Controllers watch CRDs → read from Kubernetes API → call translation → update EnvoyFilter resources.
• Envoy’s EnvoyFilter CRD injected → Envoy connects to XDS server → loads HTNN filter plugin.
• Data-plane plugin orders and executes registered plugins based on config.
• ServiceRegistryController talks to Consul/Nacos to fetch service info → feeds translation.
• Plugins (Go code) invoked within the data-plane filter chain.
c. Architectural patterns & principles:
• Operator/Controller pattern for control plane reliability and reconciliation loops.
• Plugin abstraction: common plugins API, dynamic loading via code‐generated protobuf interfaces.
• Separation of concerns: translation logic separate from K8s client code, separate from filter runtime.
d. Key technologies and frameworks:
• Go modules, client-go for K8s, controller-runtime libraries.
• Envoy XDS, EnvoyFilter CRD.
• Protobuf for plugin and config definitions.
• Helm charts for deployment.
• Hugo for documentation site.
• CI via GitHub Actions, codecov, golangci-lint.