Learn Multigress - Core Concepts & Main Architecture

#Introduction

Now that you understand why Multigress exists, it's time to dissect how it works internally. Episode 2 explains the main architecture of Multigress: the separation of control plane and data plane, the components involved, the request flow from client to backend pod, and how Multigress integrates with the Kubernetes Gateway API.

This architecture is the foundation for all the practical episodes that follow. If you understand who reads the configuration and who processes traffic, troubleshooting in episodes 7 and 20 will feel much easier.

#Multigress Architecture: Control Plane and Data Plane

#Control Plane: The Multigress Controller

The control plane is the brain of Multigress. Its main component is the multigress-controller, a pod that watches Kubernetes resources like GatewayClass, Gateway, and HTTPRoute. When something changes, the controller compares the actual state with the desired state, then pushes new configuration to the data plane.

The controller also manages status: you can see the Accepted or Ready conditions on every resource, and if there's an error, the controller writes it into the status.conditions field.

#Data Plane: The Envoy or HAProxy Proxy

The data plane is the hand that processes every request. By default, Multigress uses Envoy as the proxy — chosen for its rich filter ecosystem, HTTP/2 and HTTP/3 support, and built-in observability. The second option is HAProxy for teams more comfortable with traditional configuration.

kubectl apply -f route.yaml  →  multigress-controller  →  Envoy/HAProxy  →  backend pod

The flow above happens within seconds of you applying a route.

#Core Components and Traffic Flow

#From GatewayClass to HTTPRoute

When you apply configuration, there are four objects connected to each other:

• GatewayClass: declares the implementation, for example multigress. A cluster can have several classes.
• Gateway: a gateway instance with listeners (ports and protocols). This is what represents the actually running proxy.
• HTTPRoute: host and path routing rules toward a backend.
• ReferenceGrant: explicit permission for routes in another namespace to use cross-namespace resources.

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: multigress
spec:
  controllerName: multigress.io/multigress-controller
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: main-gateway
  namespace: multigress-system
spec:
  gatewayClassName: multigress
  listeners:
    - name: http
      protocol: HTTP
      port: 80

The manifest above is the minimal pair used throughout the series. After applying it, check its status:

kubectl get gateway main-gateway -n multigress-system
kubectl describe gateway main-gateway -n multigress-system

The kubectl describe gateway main-gateway -n multigress-system command shows the listener conditions. Pay attention to the Status section — that's where configuration errors usually become obvious.

#How Requests Are Processed

When an HTTP request arrives:

1. Envoy accepts the connection on the Gateway listener port.
2. The request's host and path are matched against the rules in the HTTPRoute.
3. Policies like timeout or retry are applied (episode 6).
4. The request is forwarded to the backend Service according to backendRefs.
5. The response is returned to the client, then counted in metrics.

These five steps are the mental model you'll use throughout the series.

#Integration with the Kubernetes Gateway API and Multigress CRDs

#Standard Gateway API

Multigress uses the stable Gateway API resources from the standard channel: GatewayClass, Gateway, HTTPRoute, TLSRoute, GRPCRoute, and ReferenceGrant. Because these are standards, your configuration can be moved to another implementation when needed — that's the core value of being vendor-neutral.

#Multigress-Specific CRDs

Beyond the standard, Multigress provides additional CRDs for features that don't yet exist in the core Gateway API. Some we'll use:

• BackendTrafficPolicy: timeouts, retries, circuit breaker, and rate limiting per route or per gateway.
• SecurityPolicy: JWT authentication and other security policies (episode 12).
• ClientTrafficPolicy: client-side behavior settings like gzip and buffering.

kubectl get crd | grep multigress

After the installation in episode 3, the command above will show the standard Gateway API CRDs as well as the CRDs above.

#Closing

Episode 2 mapped the Multigress architecture: a control plane that translates intent into configuration, an Envoy or HAProxy data plane that processes traffic, and the Gateway API resource layer that acts as the shared language between them.

The key takeaways:

• The multigress controller is the control plane; Envoy or HAProxy is the data plane.
• GatewayClass declares the implementation; Gateway declares the listeners.
• HTTPRoute defines host and path toward the backend Service.
• Status and conditions on resources are the source of truth when troubleshooting.
• Multigress-specific CRDs like BackendTrafficPolicy are used only when standard features fall short.

In the next episode 3 we'll install Multigress in the cluster using Helm, apply the first Gateway, create a simple HTTPRoute, and verify the installation, services, and logs. Get your cluster ready — the real practice starts now.