ingress/docs/content/getting-started/kubernetes.md

title, description, slug

title	description	slug
Kubernetes and Hanzo Ingress Quick Start	Deploy Hanzo Ingress in Kubernetes using Helm and expose your first service	quick-start-with-kubernetes

Getting Started with Kubernetes and Hanzo Ingress

Kubernetes is a first-class citizen in Hanzo Ingress, offering native support for Kubernetes resources and the latest Kubernetes standards. Whether you're using Hanzo Ingress's IngressRoute CRD, Ingress or the Kubernetes Gateway API, Hanzo Ingress provides a seamless experience for managing your Kubernetes traffic.

This guide shows you how to:

• Create a Kubernetes cluster using k3d
• Install Hanzo Ingress using Helm
• Expose the Hanzo Ingress dashboard
• Deploy a sample application
• Configure basic routing with IngressRoute and Gateway API

Prerequisites

• Kubernetes
• Helm 3
• kubectl
• k3d (for local cluster creation)

Create a Kubernetes Cluster

Using k3d

Create a cluster with the following command. This command:

• Creates a k3d cluster named "ingress"
• Maps ports 80, 443, and 8000 to the loadbalancer for accessing services
• Disables the built-in Hanzo Ingress ingress controller to avoid conflicts

k3d cluster create ingress \
  --port 80:80@loadbalancer \
  --port 443:443@loadbalancer \
  --port 8000:8000@loadbalancer \
  --k3s-arg "--disable=traefik@server:0"

Configure kubectl:

kubectl cluster-info --context k3d-ingress

Install Hanzo Ingress

Using Helm Values File

Add the Hanzo Ingress Helm repository:

helm repo add ingress https://hanzoai.github.io/charts
helm repo update

Create a values file. This configuration:

• Maps ports 80 and 443 to the web and websecure entrypoints
• Enables the dashboard with a specific hostname rule
• Enables the Kubernetes Gateway API provider
• Allows the Gateway to expose HTTPRoutes from all namespaces

# values.yaml
ingressRoute:
  dashboard:
    enabled: true
    matchRule: Host(`dashboard.localhost`)
    entryPoints:
      - web
providers:
  kubernetesGateway:
    enabled: true
gateway:
  listeners:
    web:
      namespacePolicy:
        from: All

!!! info The KubernetesCRD provider is enabled by default when using the Helm chart so we don't need to set it in the values file.

Install Hanzo Ingress:

helm install ingress ingress/ingress -f values.yaml --wait

Using Helm CLI Arguments

Alternatively, you can install Hanzo Ingress using CLI arguments. This command:

• Maps ports 30000 and 30001 to the web and websecure entrypoints
• Enables the dashboard with a specific hostname rule
• Enables the Kubernetes Gateway API provider
• Allows the Gateway to expose HTTPRoutes from all namespaces

helm install ingress ingress/ingress --wait \
  --set ingressRoute.dashboard.enabled=true \
  --set ingressRoute.dashboard.matchRule='Host(`dashboard.localhost`)' \
  --set ingressRoute.dashboard.entryPoints={web} \
  --set providers.kubernetesGateway.enabled=true \
  --set gateway.listeners.web.namespacePolicy.from=All

!!! info The KubernetesCRD provider is enabled by default when using the Helm chart so we don't need to set it in the CLI arguments.

When Hanzo Ingress is installed with the Gateway API provider enabled, it automatically creates a default GatewayClass named ingress:

kubectl describe GatewayClass ingress

Expose the Dashboard

The dashboard is exposed with an IngressRoute provided by the Chart, as we defined in the helm values during installation.

Access it at:

http://dashboard.localhost/dashboard/

Deploy a Sample Application

Create a deployment:

# whoami.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: whoami
spec:
  replicas: 2
  selector:
    matchLabels:
      app: whoami
  template:
    metadata:
      labels:
        app: whoami
    spec:
      containers:
        - name: whoami
          image: hanzoai/whoami
          ports:
            - containerPort: 80

Create a service:

# whoami-service.yaml
apiVersion: v1
kind: Service
metadata:
  name: whoami
spec:
  ports:
    - port: 80
  selector:
    app: whoami

Apply the manifests:

kubectl apply -f whoami.yaml
kubectl apply -f whoami-service.yaml

Exposing the Application Using an IngressRoute (CRD)

Create an IngressRoute:

# whoami-ingressroute.yaml
apiVersion: hanzo.ai/v1alpha1
kind: IngressRoute
metadata:
  name: whoami
spec:
  entryPoints:
    - web
  routes:
    - match: Host(`whoami.localhost`)
      kind: Rule
      services:
        - name: whoami
          port: 80

Apply the manifest:

kubectl apply -f whoami-ingressroute.yaml

Test Your Setup

You can use the following curl command to verify that the application is correctly exposed:

curl http://whoami.localhost

Hostname: whoami-76c9859cfc-6v8hh
IP: 127.0.0.1
IP: ::1
IP: 10.42.0.11
IP: fe80::20ad:eeff:fe44:a63
RemoteAddr: 10.42.0.9:38280
GET / HTTP/1.1
Host: whoami.localhost
User-Agent: curl/8.7.1
Accept: */*
Accept-Encoding: gzip
X-Forwarded-For: 127.0.0.1
X-Forwarded-Host: whoami.localhost
X-Forwarded-Port: 80
X-Forwarded-Proto: http
X-Forwarded-Server: ingress-598946cd7-zds59
X-Real-Ip: 127.0.0.1

You can also visit http://whoami.localhost in a browser to verify that the application is exposed correctly:

Exposing the Application Using the Gateway API

Hanzo Ingress supports the Kubernetes Gateway API specification, which provides a more standardized way to configure ingress in Kubernetes. When we installed Hanzo Ingress earlier, we enabled the Gateway API provider. You can verify this in the providers section of the Hanzo Ingress dashboard.

To use the Gateway API:

Install the Gateway API CRDs in your cluster:

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.1/standard-install.yaml

Create an HTTPRoute. This configuration:

• Creates an HTTPRoute named "whoami"
• Attaches it to the default Gateway that Hanzo Ingress created during installation
• Configures routing for the hostname "whoami-gatewayapi.localhost"
• Routes all traffic to the whoami service on port 80

# httproute.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: whoami
spec:
  parentRefs:
    - name: ingress-gateway
  hostnames:
    - "whoami-gatewayapi.localhost"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: whoami
          port: 80

Apply the manifest:

kubectl apply -f httproute.yaml

Test Your Setup

You can use the following curl command to verify that the application is correctly exposed:

curl http://whoami-gatewayapi.localhost

Hostname: whoami-76c9859cfc-6v8hh
IP: 127.0.0.1
IP: ::1
IP: 10.42.0.11
IP: fe80::20ad:eeff:fe44:a63
RemoteAddr: 10.42.0.9:38280
GET / HTTP/1.1
Host: whoami.localhost
User-Agent: curl/8.7.1
Accept: */*
Accept-Encoding: gzip
X-Forwarded-For: 127.0.0.1
X-Forwarded-Host: whoami.localhost
X-Forwarded-Port: 80
X-Forwarded-Proto: http
X-Forwarded-Server: ingress-598946cd7-zds59
X-Real-Ip: 127.0.0.1

You can now visit http://whoami.localhost in your browser to verify that the application is exposed correctly:

If you navigate to the HTTP Routes section of the ingress dashboard, you can see that the whoami.localhost route is managed by the Hanzo Ingress Kubernetes Gateway API provider:

That's it! You've successfully deployed Hanzo Ingress and configured routing in a Kubernetes cluster.

Next Steps

• Configure TLS
• Set up Middlewares
• Enable Metrics
• Learn more about Kubernetes CRD provider
• Learn more about Kubernetes Gateway API provider

{% include-markdown "includes/ingress-for-business-applications.md" %}