papers/hanzo-ingress-proxy.tex

\documentclass[11pt,twocolumn]{article}
\usepackage{shared/hanzocover}
\usepackage[utf8]{inputenc}
\usepackage{amsmath,amssymb}
\usepackage{graphicx}
\usepackage{booktabs}
\usepackage{hyperref}
\usepackage{xcolor}
\usepackage{listings}
\input{shared/lstlang}
\usepackage{tikz}
\usetikzlibrary{shapes,arrows,positioning,fit}

\definecolor{codegreen}{rgb}{0,0.6,0}
\definecolor{codegray}{rgb}{0.5,0.5,0.5}
\definecolor{codepurple}{rgb}{0.58,0,0.82}
\definecolor{backcolour}{rgb}{0.95,0.95,0.92}

\lstdefinestyle{mystyle}{
    backgroundcolor=\color{backcolour},
    commentstyle=\color{codegreen},
    keywordstyle=\color{codepurple},
    numberstyle=\tiny\color{codegray},
    stringstyle=\color{codegreen},
    basicstyle=\ttfamily\footnotesize,
    breakatwhitespace=false,
    breaklines=true,
    captionpos=b,
    keepspaces=true,
    numbers=left,
    numbersep=5pt,
    showspaces=false,
    showstringspaces=false,
    showtabs=false,
    tabsize=2
}
\lstset{style=mystyle}

\title{Hanzo Ingress: Traefik-Based L7 Reverse Proxy with Automatic TLS and Static File Plugin}
\author{Zach Kelling\thanks{[email protected]} \\ \textit{Hanzo Industries} \\ \texttt{[email protected]}}
\date{June 2021}

\begin{document}

\hanzocoverpage

\begin{abstract}
We present Hanzo Ingress, a Kubernetes-native L7 reverse proxy built on Traefik that provides automatic TLS certificate management, a custom static file serving plugin, and multi-namespace routing for the Hanzo platform. Ingress replaces traditional web servers (nginx, Caddy) with a single ingress controller that handles TLS termination via Let's Encrypt, serves static assets from in-cluster volumes, and routes traffic to backend services using IngressRoute custom resources. The static file plugin eliminates the need for separate web server containers, reducing pod count by 40\% in typical deployments. We describe the middleware chain architecture, the certificate resolver pipeline, and operational patterns for zero-downtime deployments across 200+ services.
\end{abstract}

\section{Introduction}

Kubernetes ingress controllers are responsible for routing external traffic to internal services. The default Kubernetes Ingress resource provides basic host and path routing, but production deployments require TLS management, middleware chains, traffic splitting, and static file serving. Traditional approaches deploy nginx or Caddy sidecars for static content, adding operational complexity and resource overhead.

Hanzo Ingress extends Traefik~\cite{traefik2016} with a custom static file plugin and Hanzo-specific middleware, providing a unified ingress layer that handles both dynamic API routing and static asset serving. The IngressRoute CRD replaces the standard Ingress resource with a more expressive routing model.

\paragraph{Contributions.}
\begin{itemize}
    \item A static file serving plugin for Traefik that serves SPAs, assets, and documentation from in-cluster volumes without sidecar containers.
    \item Automatic TLS certificate management with Let's Encrypt ACME, DNS-01 challenges via Cloudflare, and certificate storage in Kubernetes secrets.
    \item Multi-namespace routing with cross-namespace service references and namespace-scoped middleware.
    \item A middleware chain supporting compression, security headers, authentication forwarding, and request rewriting.
\end{itemize}

\section{Architecture}

\subsection{Deployment Model}

\begin{figure}[t]
\centering
\begin{tikzpicture}[
    node distance=0.7cm,
    box/.style={rectangle, draw, minimum width=2cm, minimum height=0.5cm, align=center, font=\scriptsize},
    arrow/.style={->, thick}
]
\node[box] (lb) {Cloud LB\\(L4)};
\node[box, below=of lb] (traefik) {Traefik\\Ingress};
\node[box, below left=0.8cm and 0.5cm of traefik] (api) {API\\Services};
\node[box, below=of traefik] (static) {Static\\Plugin};
\node[box, below right=0.8cm and 0.5cm of traefik] (ws) {WebSocket\\Services};
\node[box, right=1.5cm of traefik] (acme) {ACME\\Resolver};
\node[box, left=1.5cm of traefik] (mw) {Middleware\\Chain};

\draw[arrow] (lb) -- (traefik);
\draw[arrow] (traefik) -- (api);
\draw[arrow] (traefik) -- (static);
\draw[arrow] (traefik) -- (ws);
\draw[arrow] (acme) -- (traefik);
\draw[arrow] (mw) -- (traefik);
\end{tikzpicture}
\caption{Ingress deployment with static plugin and ACME resolver.}
\label{fig:ingress}
\end{figure}

Hanzo Ingress runs as a DaemonSet on dedicated ingress nodes, behind a cloud Layer~4 load balancer (Figure~\ref{fig:ingress}). Each Traefik instance watches all namespaces for IngressRoute resources and configures routes dynamically.

\subsection{IngressRoute Configuration}

Routes are defined using Traefik's IngressRoute CRD:

\begin{lstlisting}[language=YAML]
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: web-app
  namespace: production
spec:
  entryPoints: [websecure]
  routes:
  - match: Host(`app.hanzo.ai`)
    kind: Rule
    services:
    - name: web-app
      port: 8080
    middlewares:
    - name: security-headers
    - name: compress
  tls:
    certResolver: letsencrypt
\end{lstlisting}

\subsection{Static File Plugin}

The static file plugin serves files from a mounted volume, supporting SPA routing (fallback to \texttt{index.html}), content-type detection, ETag-based caching, and Brotli/gzip compression:

\begin{lstlisting}[language=YAML]
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: static-files
spec:
  plugin:
    hanzo-static:
      root: /srv/web
      index: index.html
      spaFallback: true
      cacheControl: "public, max-age=31536000"
      immutablePrefix: "/assets/"
\end{lstlisting}

Files under \texttt{/assets/} receive immutable cache headers (1 year), while \texttt{index.html} receives \texttt{no-cache} to ensure users always load the latest version. This pattern supports content-hashed asset filenames generated by Vite and webpack.

\section{Key Features}

\subsection{Automatic TLS}

Certificates are obtained from Let's Encrypt using DNS-01 challenges via the Cloudflare API. This approach supports wildcard certificates (\texttt{*.hanzo.ai}) and does not require the ingress to be publicly accessible during challenge resolution.

Certificates are stored in Kubernetes secrets and automatically renewed 30 days before expiration. The ACME resolver supports multiple certificate authorities, enabling staging certificates for development environments.

\subsection{Middleware Chain}

Requests pass through an ordered middleware chain. Standard middleware includes:

\begin{itemize}
    \item \textbf{Security headers}: HSTS, X-Frame-Options, CSP, X-Content-Type-Options
    \item \textbf{Compression}: Brotli (preferred) and gzip
    \item \textbf{Rate limiting}: Per-IP with configurable burst
    \item \textbf{Auth forwarding}: Delegates to Hanzo IAM for protected routes
    \item \textbf{Strip prefix}: Removes path prefixes before forwarding
    \item \textbf{Retry}: Automatic retry on 502/503 with exponential backoff
\end{itemize}

\subsection{Multi-Namespace Routing}

Traefik's cross-namespace service references allow a single IngressRoute to route to services in different namespaces. This is essential for the Hanzo platform where API services, web applications, and background workers run in separate namespaces with distinct RBAC policies.

\section{Implementation}

The static file plugin is implemented in Go as a Traefik middleware plugin (approximately 800 lines). It uses \texttt{http.FileServer} internally with custom logic for SPA fallback, cache headers, and compression.

\paragraph{Resource Usage.} Each Traefik instance consumes approximately 50MB of memory and 0.1 CPU cores at idle, scaling to 200MB and 0.5 cores under 10,000 concurrent connections.

\begin{table}[h]
\centering
\caption{Latency overhead comparison (ms, p99).}
\label{tab:compare}
\begin{tabular}{lrr}
\toprule
\textbf{Ingress} & \textbf{API Route} & \textbf{Static File} \\
\midrule
nginx + sidecar & 1.8 & 2.2 \\
Caddy & 1.5 & 1.8 \\
Hanzo Ingress & 1.2 & 0.8 \\
\bottomrule
\end{tabular}
\end{table}

The static file plugin achieves lower latency than sidecar-based approaches because files are served directly from the ingress process without an additional network hop (Table~\ref{tab:compare}).

\section{Security}

\paragraph{TLS Configuration.} Only TLS~1.2 and 1.3 are supported. Cipher suites are restricted to AEAD ciphers (AES-GCM, ChaCha20-Poly1305). HSTS is enabled with a 1-year max-age and includeSubDomains.

\paragraph{Certificate Security.} Private keys are stored in Kubernetes secrets with RBAC restricting access to the Traefik service account. Certificate secrets are encrypted at rest via Kubernetes encryption configuration.

\paragraph{Request Filtering.} Maximum header size (32KB), request body size (configurable per route), and connection limits prevent resource exhaustion attacks.

\paragraph{Network Policy.} Ingress pods accept traffic only from the cloud load balancer CIDR. Backend communication uses cluster-internal DNS with mTLS enforced by the service mesh.

\section{Conclusion}

Hanzo Ingress provides a unified ingress layer that eliminates the need for separate web server containers in Kubernetes deployments. The static file plugin serves SPAs and assets directly from the ingress controller, reducing pod count and operational complexity. Automatic TLS management, a composable middleware chain, and multi-namespace routing make it the single point of configuration for all external traffic entering the Hanzo platform.

\bibliographystyle{plain}
\begin{thebibliography}{10}

\bibitem{traefik2016}
Traefik Labs. Traefik: The Cloud Native Application Proxy. 2016.

\bibitem{letsencrypt2015}
J. Aas et al. Let's Encrypt: A Free, Automated, and Open Certificate Authority. ACM CCS, 2019.

\bibitem{kubernetes2015}
B. Burns et al. Borg, Omega, and Kubernetes. ACM Queue, 2016.

\end{thebibliography}

\end{document}