Learn Multigress - Installation & Basic Configuration

#Introduction

Theory is enough. Episode 3 is the moment where you actually install Multigress in the cluster and watch it work. We'll use Helm to deploy the components, then create the first Gateway and HTTPRoute, and finish with verifying the installation, services, and logs.

The end goal of this episode is simple: an HTTP request coming into the gateway successfully reaches a sample application named echo. If that's achieved, all the practical episodes that follow share the same foundation.

#Deploying Multigress with Helm

#Adding the Helm Repo

Multigress is distributed as an official Helm chart. First, add its repo:

helm repo add multigress https://charts.multigress.io
helm repo update

The helm repo update command pulls the latest chart metadata. Make sure there are no timeout errors — that's an early sign your network connection is healthy.

#Installing the Chart

Now install Multigress into a dedicated namespace:

helm install multigress multigress/multigress \
  --namespace multigress-system \
  --create-namespace

The --create-namespace flag creates the multigress-system namespace automatically if it doesn't exist. This process requires pulling images for the controller and data plane.

kubectl get pods -n multigress-system

Wait until all pods are Running. The multigress-controller pod is the control plane, while the multigress-proxy pod is the data plane that will process traffic.

#Installing Gateway API Resources

By default, the Gateway API CRDs are installed along with the chart. Make sure they're available:

kubectl get crd | grep gateway.networking.k8s.io

The output must show gateways.gateway.networking.k8s.io and httproutes.gateway.networking.k8s.io. If they're missing, install them manually from the official Gateway API release.

#Basic Gateway and HTTPRoute Configuration

#Creating the Sample Application

Before routing traffic, prepare a simple echo application:

kubectl create deployment echo --image=hashicorp/http-echo --replicas=2
kubectl expose deployment echo --port=80 --target-port=5678

The echo application returns a JSON payload containing the request it received — very useful for verifying routing.

#The First Gateway

Save the following manifest as gateway.yaml:

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

Apply it and check its status:

kubectl apply -f gateway.yaml
kubectl get gateway main-gateway -n multigress-system

The STATUS column must show Programmed or Ready. If it shows Accepted, the listener is valid.

#The First HTTPRoute

Now connect the gateway to the echo application. Save it as httproute.yaml:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: echo-route
spec:
  parentRefs:
    - name: main-gateway
      namespace: multigress-system
  rules:
    - backendRefs:
        - name: echo
          port: 80

This route declares: all traffic on the gateway goes to the echo Service on port 80. Apply and verify:

kubectl apply -f httproute.yaml
kubectl get httproute echo-route

Notice the Accepted: True and ResolvedRefs: True status on the route details.

#Verifying Installation, Services, and Logs

#Testing a Request Through the Gateway

Get the gateway address, then send a request using port-forwarding for simplicity:

kubectl port-forward -n multigress-system svc/multigress-proxy 8080:80
curl -s http://localhost:8080

If everything works, curl -s http://localhost:8080 will show the JSON response from the echo application. That's proof the data plane is forwarding traffic correctly.

#Checking Logs

When something goes wrong, logs are the first source you should check:

kubectl logs -n multigress-system deploy/multigress-controller --tail=50
kubectl logs -n multigress-system deploy/multigress-proxy --tail=50

The controller logs show the configuration translation process, while the proxy logs show request activity. The kubectl logs -n multigress-system deploy/multigress-controller --tail=50 pattern will be your companion throughout the series.

#Closing

Episode 3 completed the first crucial step: Multigress is installed, the first Gateway and HTTPRoute are applied, the echo application is reachable through the proxy, and you know exactly where to look when something breaks.

The key takeaways:

• Install Multigress with helm install into the multigress-system namespace.
• Make sure the Gateway API CRDs are available before using Gateway and routes.
• The Gateway declares listeners; the HTTPRoute declares traffic destinations.
• Verify with kubectl get for status and curl for functionality.
• Controller and proxy logs are your first troubleshooting tool.

In the next episode 4 we'll dive into the Gateway API & HTTPRoute — understanding GatewayClass, Gateway, HTTPRoute, TLSRoute, and ReferenceGrant, configuring host and path routing toward backend services, and integration modes with existing Services and Ingress. Make sure your episode 3 installation is still running.