Skip to main content
Mapagam

Working with Ingress

1. Creating Ingress Resource

Field Description Example
apiVersion API version of the Ingress resource networking.k8s.io/v1
kind Kind of the Kubernetes resource Ingress
metadata.name Name of the Ingress resource example-ingress
spec.rules List of rules mapping paths to services 
[
  {
    "host": "example.com",
    "http": {
      "paths": [
        {
          "path": "/",
          "pathType": "Prefix",
          "backend": {
            "service": {
              "name": "example-service",
              "port": {
                "number": 80
              }
            }
          }
        }
      ]
    }
  }
]

Example: Basic Ingress Configuration

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
spec:
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: example-service
            port:
              number: 80

2. Listing Ingress Resources

Command Description Notes
kubectl get ingress List all Ingress resources in the current namespace Alias: kubectl get ing
kubectl get ingress -A List all Ingress resources across all namespaces Useful for cluster-wide visibility
kubectl get ingress -n <namespace> List Ingress resources in a specific namespace Replace <namespace> with actual namespace name
kubectl get ingress -o wide List Ingress with additional details including IP and HOST Shows more information about the Ingress rules

Example: Listing Ingress in a specific namespace

kubectl get ingress -n production
Note: Ingress resources are namespace-scoped, so you must specify the correct namespace to view them.

3. Describing Ingress Details

Field Description Example Value
apiVersion The API version of the Ingress resource networking.k8s.io/v1
kind The type of Kubernetes resource Ingress
metadata.name The name of the Ingress resource example-ingress
metadata.namespace The namespace where the Ingress is defined default
spec.rules List of rules for routing traffic to services 
[
  {
    "host": "example.com",
    "http": {
      "paths": [
        {
          "path": "/",
          "pathType": "Prefix",
          "backend": {
            "service": {
              "name": "example-service",
              "port": {
                "number": 80
              }
            }
          }
        }
      ]
    }
  }
]
spec.ingressClassName The name of the IngressClass to use for this resource nginx
spec.tls Configuration for TLS termination 
[
  {
    "hosts": ["example.com"],
    "secretName": "tls-secret"
  }
]

Example: Describe Ingress Details

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  namespace: default
spec:
  ingressClassName: nginx
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: example-service
            port:
              number: 80
  tls:
  - hosts:
    - example.com
    secretName: tls-secret

4. Configuring Ingress Rules

Field Description Example
host Hostname for the rule. If not specified, rule applies to all hosts. example.com
path Path to match. Must start with /. /api/v1
pathType How the path should be matched. Options: Exact, Prefix, ImplementationSpecific. Prefix
backend Service and port to route traffic to. { service: { name: "my-service", port: { number: 80 } } }

Example: Basic Ingress Rule

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
spec:
  rules:
  - host: example.com
    http:
      paths:
      - path: /api/v1
        pathType: Prefix
        backend:
          service:
            name: api-service
            port:
              number: 80

Example: Multiple Paths with Different Services

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: multi-path-ingress
spec:
  rules:
  - host: example.com
    http:
      paths:
      - path: /api/v1
        pathType: Prefix
        backend:
          service:
            name: api-service
            port:
              number: 80
      - path: /web
        pathType: Prefix
        backend:
          service:
            name: web-service
            port:
              number: 80
Note: The pathType field is required in Kubernetes 1.18+. If not specified, the default value is ImplementationSpecific.

5. Setting Default Backend

Field Description Example
defaultBackend Specifies the default backend for the Ingress. If no rules match, this backend handles the request. 
{
  "service": {
    "name": "default-backend",
    "port": {
      "number": 80
    }
  }
}

Example: Default Backend Configuration

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
spec:
  defaultBackend:
    service:
      name: default-backend
      port:
        number: 80

6. Using Path Types

Path Type Description Behavior Notes
ImplementationSpecific Uses the default behavior of the Ingress controller Depends on the implementation Not recommended for portability
Prefix Matches based on the URL path prefix Matches paths that start with the specified prefix Supports wildcard matching (e.g., /api/v1/*)
Exact Matches the exact path Only matches if the path is exactly as specified Useful for specific endpoints like /healthz

Example: Ingress with Path Types

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
spec:
  rules:
  - host: example.com
    http:
      paths:
      - path: /api/v1/users
        pathType: Exact
        backend:
          service:
            name: user-service
            port:
              number: 80
      - path: /api/v1
        pathType: Prefix
        backend:
          service:
            name: api-service
            port:
              number: 80

7. Configuring TLS Termination

Field Description Example
tls.secretName Name of the Secret containing TLS certificate and key my-tls-secret
tls.hosts List of hostnames to apply TLS to ["example.com", "www.example.com"]

Example: Ingress with TLS

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-tls-ingress
spec:
  tls:
  - hosts:
    - example.com
    secretName: example-com-tls
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: example-service
            port:
              number: 443
Note: The Secret must contain keys tls.crt and tls.key.

8. Using Ingress Annotations

Annotation Values Description
ingress.kubernetes.io/rewrite-target / Specifies the path to rewrite the request to
nginx.ingress.kubernetes.io/ssl-redirect true or false Enables or disables SSL redirect for the Ingress
nginx.ingress.kubernetes.io/proxy-body-size 1m, 2g Sets the maximum body size for proxy requests
nginx.ingress.kubernetes.io/auth-type basic, digest Authentication type for the Ingress
nginx.ingress.kubernetes.io/cors-allow-origin *, https://example.com Specifies the allowed origins for CORS
nginx.ingress.kubernetes.io/limit-rps 10 Rate limit in requests per second

Example: Using Ingress Annotations

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/proxy-body-size: 2g
spec:
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: example-service
            port:
              number: 80

9. Setting Ingress Class

Property Value Description
ingressClassName nginx Name of the IngressClass to use for this Ingress resource

Example: Define Ingress with Class

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
spec:
  ingressClassName: nginx
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: example-service
            port:
              number: 80
Note: The ingressClassName field is available in Kubernetes v1.19+ and requires an IngressClass resource to exist with the matching name.

10. Installing Ingress Controllers

Controller Installation Method Notes
NGINX Ingress Controller kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.10.1/deploy/static/provider/cloud/deploy.yaml Official NGINX Ingress Controller for cloud providers
Traefik Ingress Controller kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v2.10/deploy/kubernetes/traefik.yaml Supports multiple cloud providers and edge routers
AWS Load Balancer Controller kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.7.1/deploy/iam_policy.json For AWS ALB integration with Ingress
GCP Cloud Load Balancer gcloud compute backend-services create my-backend --global Requires GCP Ingress controller setup

Example: Deploying NGINX Ingress Controller

kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.10.1/deploy/static/provider/cloud/deploy.yaml
Note: Ensure that the namespace and RBAC settings match your cluster configuration.
Warning: Some controllers require specific annotations or configurations to work with your Ingress resources.

11. Troubleshooting Ingress

Common Ingress Issues and Solutions

  1. Ingress not routing traffic to backend services
    • Check if the Ingress resource is correctly configured with the right backend service and port.
    • Verify that the service exists and is in the same namespace as the Ingress (unless using cross-namespace references).
    • Ensure that the service's selector matches the labels of the pods.
  2. 503 Service Unavailable errors
    • Confirm that the backend pods are running and healthy.
    • Check if the service is exposing the correct port that matches the Ingress backend configuration.
    • Review logs from the Ingress controller for any error messages related to backend connections.
  3. Ingress controller not starting or crashing
    • Check the Ingress controller pod logs for errors.
    • Ensure that the Ingress controller is properly installed and configured with necessary RBAC rules.
    • Validate that the Ingress controller deployment has sufficient resources (CPU, memory).
  4. SSL/TLS certificate issues
    • Verify that the TLS secret exists and contains valid certificates.
    • Ensure that the certificate is not expired or self-signed without proper trust configuration.
    • Check if the Ingress resource references the correct secret name and namespace.
Issue Possible Cause Solution
Ingress not routing traffic Incorrect backend service or port configuration Validate Ingress spec and ensure service exists with matching labels
503 errors Backend pods not ready or service port mismatch Check pod status and service port configuration
Ingress controller crash Insufficient resources or misconfiguration Review controller logs and deployment settings
TLS certificate errors Invalid or expired certificate in secret Verify and update TLS secret with valid certificate

Example: Check Ingress Controller Logs

kubectl logs -n ingress-nginx deploy/ingress-nginx-controller

Example: Verify Service and Pod Status

kubectl get svc my-service -n default
kubectl get pods -n default

Was this article helpful?

Related Cheat Sheets