Defining Ingress Rules: A Practical Guide to Path-Based Routing

Previously in this course, we discussed the core concepts of routing in Introduction to Ingress: Kubernetes Routing Explained and walked through the installation of your Ingress controller in Setting Up an Ingress Controller: A Practical Kubernetes Guide.

Now that your controller is active, this lesson focuses on the "how-to" of traffic management: writing the actual Ingress manifests that tell the controller where to send your users' requests.

Understanding Ingress Rules from First Principles

In Kubernetes, an Ingress resource is a set of rules that acts as a layer-7 load balancer. While a Service (which you learned about in The Role of Services) handles internal traffic, an Ingress rule allows you to expose multiple services under a single IP address by looking at the incoming request's host or path.

Think of the Ingress Controller as a hotel receptionist. The Service is the room number, and the Ingress Rule is the check-in list that says: "If the guest asks for /api, send them to the backend service; if they ask for /, send them to the frontend service."

Worked Example: Configuring Path-Based Routing

To demonstrate this, we will route traffic to two different services: a frontend service and an api service. We assume you have already created these services in your cluster.

Here is the manifest for a standard Ingress rule:

YAML
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: main-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  ingressClassName: nginx
  rules:
  - http:
      paths:
      - path: /api
        pathType: Prefix
        backend:
          service:
            name: api-service
            port:
              number: 80
      - path: /
        pathType: Prefix
        backend:
          service:
            name: frontend-service
            port:
              number: 80

Breakdown of the Configuration

• pathType: Prefix: This ensures that any request starting with /api (like /api/users or /api/login) is directed to the api-service.
• rewrite-target: This annotation is crucial. It tells the Nginx controller to strip the /api prefix before sending the request to your application, ensuring your app receives a clean request path.
• Order of operations: Kubernetes evaluates rules from top to bottom. Always define your more specific paths (like /api) before your catch-all paths (like /).

Hands-on Exercise

1. Create two simple deployments (or use existing ones) named frontend and backend.
2. Ensure you have two corresponding ClusterIP services.
3. Save the YAML provided above into a file named ingress.yaml.
4. Apply the manifest using kubectl apply -f ingress.yaml.
5. Verify the ingress is active by running kubectl get ingress. Check the "ADDRESS" column to ensure your controller has assigned an IP.

Common Pitfalls

• Missing Ingress Class: If your Ingress doesn't pick up an IP address, ensure your ingressClassName matches the one you used during controller installation.
• Incorrect Path Matching: Using pathType: Exact is often too restrictive. If you want /api/v1 and /api/v2 to work, use Prefix.
• Service Port Mismatch: The port defined in the Ingress must match the port defined in your Service spec, not the container's internal port.
• Annotation Conflicts: Different controllers (e.g., Nginx vs. Traefik) use different annotations. Always check the documentation for your specific controller if features like rewrites aren't working.

Frequently Asked Questions

Q: Can I use host-based routing? A: Yes. You can add a host: example.com field under the rules section to route traffic based on the domain name instead of (or in addition to) the path.

Q: Why isn't my path being rewritten correctly? A: Ensure the nginx.ingress.kubernetes.io/rewrite-target annotation is present and set to /. Without it, your application will receive the /api prefix, which might cause 404 errors if your app doesn't have an /api route defined.

Q: What happens if I don't set an Ingress class? A: In older versions of Kubernetes, this was done via an annotation. In modern versions, explicitly defining ingressClassName is the standard and prevents ambiguity in clusters with multiple controllers.

Recap

You have now learned how to define Ingress rules to manage traffic flow. By using pathType: Prefix, you can cleanly separate your frontend and backend services under a single entry point. This is the foundation of building professional-grade, scalable web architectures on Kubernetes.

Up next: Now that your traffic is flowing, we will look at how to observe the health of your cluster by Monitoring Cluster Events.