Skip to content
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
    • Kong Konnect
    • Kong Mesh
    • Plugin Hub
    • decK
    • Kubernetes Ingress Controller
    • Insomnia
    • Kuma

    • Docs contribution guidelines
  • Plugin Hub
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kubernetes Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 2.8.x (latest)
  • 2.7.x
  • 2.6.x
  • 2.5.x
  • 2.4.x
  • 2.3.x
  • 2.2.x
  • 2.1.x
  • 2.0.x
  • 1.3.x
  • 1.2.x
  • 1.1.x
  • 1.0.x
    • FAQ
    • Changelog
    • Architecture
    • Custom Resources
    • Deployment Methods
    • Kong for Kubernetes with Kong Enterprise
    • High-Availability and Scaling
    • Resource Classes
    • Security
    • Ingress Resource API Versions
    • Kong Ingress on Minikube
    • Kong for Kubernetes
    • Kong for Kubernetes Enterprise
    • Kong for Kubernetes with Kong Enterprise
    • Kong Ingress on AKS
    • Kong Ingress on EKS
    • Kong Ingress on GKE
    • Admission Controller
    • Getting Started with KIC
    • Upgrading from KIC 1.3.x
    • Getting Started using Istio
      • Using the KongPlugin Resource
      • Using the KongIngress Resource
      • Using KongConsumer and Credential Resources
      • Using the KongClusterPlugin Resource
      • Using the TCPIngress Resource
      • Using the UDPIngress Resource
    • Using the ACL and JWT Plugins
    • Using cert-manager with Kong
    • Configuring a Fallback Service
    • Using an External Service
    • Configuring HTTPS Redirects for Services
    • Using Redis for Rate Limiting
    • Integrate KIC with Prometheus/Grafana
    • Configuring Circuit-Breaker and Health-Checking
    • Setting up a Custom Plugin
    • Using Ingress with gRPC
    • Setting up Upstream mTLS
    • Exposing a TCP-based Service
    • Exposing a UDP-based Service
    • Using the mTLS Auth Plugin
    • Configuring Custom Entities
    • Using the OpenID Connect Plugin
    • Rewriting Hosts and Paths
    • Preserving Client IP Address
    • KIC Annotations
    • CLI Arguments
    • Custom Resource Definitions
    • Plugin Compatibility
    • Version Compatibility
    • Troubleshooting
    • Prometheus Metrics

github-edit-pageEdit this page

report-issueReport an issue

enterprise-switcher-iconSwitch to OSS

On this page
  • Introduction
  • Paths
    • networking.k8s.io/v1beta1
    • networking.k8s.io/v1
  • Ingress class
  • Hostnames
  • Backend types
Kubernetes Ingress Controller
2.0.x
  • Home
  • Kubernetes Ingress Controller
  • Concepts
  • Ingress v1 and v1beta1 Differences
You are browsing documentation for an outdated version. See the latest documentation here.

Ingress v1 and v1beta1 Differences

Introduction

Kubernetes 1.19 introduced a new networking.k8s.io/v1 API for the Ingress resource. It standardizes common practices and clarifies implementation requirements that were previously up to individual controller vendors. This document covers those changes as they relate to Kubernetes Ingress Controller and provides sample equivalent networking.k8s.io/v1beta1 and networking.k8s.io/v1 resources for comparison.

Paths

Both Ingress v1beta1 and v1 HTTP rules require a path, which represents a URI path. Although v1beta1 had specified that paths were POSIX regular expressions and enforced this, in practice most controllers used other other implementations that did not match the specification. v1 seeks to reduce confusion by introducing several path types and lifting restrictions on regular expression grammars used by controllers.

networking.k8s.io/v1beta1

The controller passes paths directly to Kong and relies on its path handling logic. The Kong proxy treats paths as a prefix unless they include characters not allowed in RFC 3986 paths, in which case the proxy assumes they are a regular expression, and does not treat slashes as special characters. For example, the prefix /foo can match any of the following:

/foo
/foo/
/foobar
/foo/bar

networking.k8s.io/v1

Although v1 Ingresses provide path types with more clearly-defined logic, the controller must still create Kong routes and work within the Kong proxy’s routing logic. As such, the controller translates Ingress rule paths to create Kong routes that match one of the following specifications: Exact, Prefix, or ImplementationSpecific.

Exact

If pathType is Exact, the controller creates a Kong route with a regular expression that matches the rule path only. For example, an exact rule for /foo in an Ingress translates to a Kong route with a /foo$ regular expression path.

Prefix

If pathType is Prefix, the controller creates a Kong route with two path criteria. For example, /foo will create a route with a /foo$ regular expression and /foo/ plain path.

ImplementationSpecific

The controller leaves ImplementationSpecific path rules entirely up to the Kong router. It creates a route with the exact same path string as the Ingress rule.

Both Prefix and Exact paths modify the paths you provide, and those modifications may interfere with user-provided regular expressions. If you are using your own regular expressions in paths, use ImplementationSpecific to avoid unexpected behavior.

Ingress class

Ingress class indicates which resources an ingress controller should process. It provides a means to separate out configuration intended for other controllers or other instances of the Kubernetes Ingress Controller.

In v1beta1, ingress class was handled informally using kubernetes.io/ingress.class annotations. v1 introduces a new IngressClass resource which provides richer information about the controller. v1 Ingresses are bound to a class via their ingressClassName field.

For example, consider this v1beta1 Ingress:

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: example-ingress
  annotations:
    kubernetes.io/ingress.class: "kong"
spec:
  rules:
  - host: example.com
    http:
      paths:
      - path: /test
        backend:
          serviceName: echo
          servicePort: 80

Its ingress class annotation is set to kong, and ingress controllers set to process kong class Ingresses will process it.

In v1, the equivalent configuration declares a kong IngressClass resource whose metadata.name field indicates the class name. The ingressClassName value of the Ingress object must match the value of the name field in the IngressClass metadata:

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: kong
spec:
  controller: ingress-controllers.konghq.com/kong
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
spec:
  ingressClassName: kong
  rules:
  - http:
      paths:
      - path: /testpath
        pathType: Prefix
        backend:
          service:
            name: test
            port:
              number: 80

Hostnames

Ingress v1 formally codifies support for wildcard hostnames. v1beta1 Ingresses did not reject wildcard hostnames, however, and Kong had existing support for them.

As such, while the v1beta1 specification did not officially support wildcard hostnames, you can use wildcard hostnames with either version. Setting a hostname like *.example.com will match requests for both foo.example.com and bar.example.com with either v1 or v1beta1 Ingresses.

Backend types

Ingress v1 introduces support for backends other than Kubernetes Services through resource backends.

Kong does not support any dedicated resource backend configurations, though it does have support for Routes without Services in some cases (for example, when using the AWS Lambda plugin). For these routes, you should create a placeholder Kubernetes Service for them, using an ExternalName Service with an RFC 2606 invalid hostname, e.g. kong.invalid. You can use these placeholder services with either v1 or v1beta1 Ingresses.

Thank you for your feedback.
Was this page useful?
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2023