DOCSEARCHbyAlgolia
Submit Docs

Kong Ingress Controller (KIC) Documentation

repository·main·Indexed 25 days ago

https://github.com/kong/kubernetes-ingress-controller

The Kong Ingress Controller (KIC) manages Kong Gateway traffic within Kubernetes using native resources like Ingress and the Gateway API. It supports declarative configuration of plugins, health checking, and load balancing via Custom Resource Definitions (CRDs) such as KongPlugin, KongClusterPlugin, and KongConsumer. KIC provides native support for TCP, UDP, TLS, gRPC, and HTTP/HTTPS traffic, and can be deployed via Helm or the Kong Operator.

Tokens
14.6K
Snippets
20
Records
76
Agent score
77%

What's inside Kong Ingress Controller

  1. Overview of Kong Ingress Controller features

    main

    The Kong Ingress Controller (KIC) provides several key capabilities for managing traffic in Kubernetes:

    • Gateway API Support: Native support for TCP, UDP, TLS, gRPC, and HTTP/HTTPS traffic using the official successor to Ingress resources.
    • Ingress Support: Traditional Kubernetes Ingress resource support.
    • Declarative Configuration: Use Kubernetes-native CRDs to configure all Kong features.
    • Automated Scaling: Automatically manage and scale multiple replicas of Kong Gateway for high availability.
    • Health Checking and Load Balancing: Supports both active and passive health-checks to load balance requests across pods.
    • Plugin Management: Enhanced API management via plugins for authentication, request/response transformations, rate-limiting, and more.

  2. Overview of the Kong Kubernetes Testing Framework (KTF)

    main

    The Kong Kubernetes Testing Framework (KTF) is a Golang-based testing framework designed to standardize and simplify integration and end-to-end (e2e) testing for Kong Kubernetes components. It replaces legacy bash and curl scripts with a prescriptive, highly expressive Go environment.

    Core Capabilities:

    • Cluster Provisioning: Automatically provisions testing clusters using tools like kind, minikube, or GKE.
    • Component Deployment: Handles deployment of Kubernetes components (e.g., via helm, metallb) and Kong-specific configurations (e.g., Proxy-only, Proxy with KIC, or specific version matrices).
    • Object Generation: Provides generators to quickly create default Kubernetes objects such as Service, Deployment, etc.
    • Mocking: Includes support for mocking the Kong Admin API (implemented in pkg/kong/fake_admin_api.go).

  3. Compare Traditional and Combined Routes

    main

    KIC offers two strategies for generating Kong routes from Ingress or HTTPRoute resources. The choice affects configuration size and naming, but not the actual request routing logic.

    Traditional Routes

    • Strategy: Creates a unique Kong route for every individual path/rule in an Ingress or HTTPRoute.
    • Pros: Simple and predictable.
    • Cons: Results in a large number of routes, which can impact performance during configuration updates in large environments.
    • Naming Scheme: <namespace>.<name>.<rule index><path index> (e.g., default.httpbin.00).

    Combined Routes

    • Strategy: Consolidates routes that share the same service and hostname.
    • Pros: Reduces the total number of routes and the overall configuration size.
    • Cons: Changes the number and names of routes. This will cause disconnects in monitoring (Prometheus metrics), logging, and third-party tools that rely on specific route names or IDs.
    • Naming Scheme: <namespace>.<name>.<service>.<hostname>.<port> (e.g., default.httpbin.httpbin.ing.example.80).

    HTTPRoute Combination Rules

    HTTPRoutes are more expressive than Ingresses. Rules cannot be combined if they use different:

    • Filters
    • Header matches
    • Query parameter matches

    If two HTTPRoute rules use the same set of services in their backendRefs, Combined mode will generate a single Kong service containing endpoints from both services.

    # Example Ingress that would be consolidated by Combined Routes
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example
spec:
  ingressClassName: kong
  rules:
  - host: "ingress.example"
    http:
      paths:
      - path: /one
        pathType: Prefix
        backend:
          service:
            name: red
            port:
              number: 80
      - path: /two
        pathType: Prefix
        backend:
          service:
            name: red
            port:
              number: 80
      - path: /three
        pathType: Prefix
        backend:
          service:
            name: blue
            port:
              number: 80

  4. KIC v2.x Architecture: Modular Controllers

    main

    The KIC architecture has transitioned from a monolithic v1.x design to a more modular approach using the Kubebuilder SDK and controller-runtime.

    While the entire stack is not yet a collection of fully independent microservices, the upfront Kubernetes controllers are now modular. Each resource type utilizes an independent reconciler. This modularity is achieved by separating problem domains into specific libraries or servers connected via abstract interfaces and types, allowing for better maintainability and scalability.

  5. Use ConfigPatch to inject Secret values into plugins

    main

    A ConfigPatch is a JSON patch (RFC6902) used to add values from a Kubernetes Secret into the generated configuration of a KongPlugin or KongClusterPlugin.

    It is functionally equivalent to the following operation: {"op": "add", "path": <JSON-Pointer-Path>, "value": <Value-from-Secret>}.

    Fields

    • path: A JSON-Pointer value (RFC6901) that specifies the location within the target configuration where the value should be added.
    • valueFrom: A ConfigSource that references the specific key in a Secret from which the value should be retrieved.

  6. Use KongServiceFacade to create multiple Kong Services for one Kubernetes Service

    main

    The KongServiceFacade resource allows you to create separate Kong Services for a single Kubernetes Service. This is useful when you want to point multiple "virtual" Kong Services to the same Kubernetes backend but apply different configurations to each, such as different sets of plugins or different load balancing algorithms.

    To ensure the Kong Ingress Controller reconciles a KongServiceFacade, you must include the kubernetes.io/ingress.class annotation with a value matching the controller's ingressClass (which defaults to kong).

    It can be used as a backend for a Kubernetes Ingress via the backend.resource field in the Ingress specification.

  7. Configure Active and Passive Health Checks

    main

    Kong supports both active and passive health checks for upstreams via KongUpstreamHealthcheck.

    • Active Health Checks: Kong proactively probes targets using specified protocols (HTTP, HTTPS, TCP, gRPC, or gRPCS).
    • Passive Health Checks: Kong monitors real traffic and interprets responses (e.g., HTTP status codes or TCP connection success) to determine target health.

  8. KIC Architecture: Transition to Kubebuilder and controller-runtime

    main

    The Kong Ingress Controller (KIC) has undergone a major re-architecture to move away from legacy controller patterns (inherited from the Nginx Ingress Controller) toward a modern architecture based on the Kubebuilder SDK and controller-runtime.

    Key Architectural Changes

    • Decoupled Controllers: Functionality is now broken down into separate controllers for each supported Kubernetes API (e.g., KongIngress, TCPIngress, etc.), rather than a single monolithic controller.
    • Standardized Machinery: By using Kubebuilder, KIC leverages standardized automation for:
      • API schemas
      • Controller reconciliation machinery
      • Custom Resource Definition (CRD) management
      • Kustomize configurations
      • RBAC security
      • controller-manager CLI and flags
    • Improved Observability: The re-architecture provides better logging and event status delineation, allowing operators to identify which specific API or controller is responsible for specific logs or events.
    • Feature Gates: The new architecture supports feature gates, allowing KIC to introduce experimental or newer Kubernetes APIs without making them immediately available to all users, facilitating a smoother path toward the Gateway API.

  9. How Kong Gateway API unmanaged mode works

    main

    The Kong Ingress Controller (KIC) implements the Gateway API in unmanaged mode. In this mode, the Gateway resource acts as a reflection of the existing Kubernetes Service object used by the Kong Gateway deployment.

    Instead of the user manually defining Addresses and Listeners in the Gateway resource, the KIC Gateway controller derives these values from the Kong Gateway's Service. Any updates to the Service (e.g., via a Helm upgrade changing ports or protocols) will trigger a reconciliation that updates the Gateway resource automatically.

    Note: Direct manual manipulation of the Gateway object in unmanaged mode will be overwritten by the controller to match the Service specification.

    kind: Gateway
apiVersion: gateway.networking.k8s.io/v1alpha2
metadata:
  annotations:
    konghq.com/gateway-unmanaged: "true"
  name: project-1-ingress
spec:
  gatewayClassName: default-match-example
  listeners:
  - name: http
    protocol: HTTP
    port: 80

  10. Configure Sticky Sessions with KongUpstreamStickySessions

    main

    Sticky sessions ensure that requests from the same client are routed to the same backend target using cookies.

    Requirement: This feature requires Kong Enterprise Gateway and the KongUpstreamPolicySpec.algorithm must be set to sticky-sessions (which implies setting hash_on to none).

    | Field | Description |
| --- | --- |
| `cookie` _string_ | Cookie is the name of the cookie to use for sticky sessions. Kong will generate this cookie if it doesn't exist in the request. |
| `cookiePath` _string_ | CookiePath is the path to set in the cookie. |

  11. Use dynamic configuration in KongPlugin and KongClusterPlugin

    main

    To avoid hard-coding values in KongPlugin and KongClusterPlugin resources, you can use the configFrom field. This allows you to derive individual configuration values from Kubernetes ConfigMap or Secret resources, or provide literal values and interpolated strings.

    When using configFrom, values defined there can override values found in the standard config block. The Kong Ingress Controller will automatically react to updates in the referenced ConfigMap or Secret objects to re-apply the configuration.

    apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: plugin-one
config:
  bar: hello-world
configFrom:
  - name: foo
    value: 100

  - name: bar
    value: goodbye-world # override value found in config.bar

  - name: widget
    value:
      object:
        values: supported

  12. Understand Feature Gates and Maturity Stages

    main

    The Kong Ingress Controller (KIC) uses Feature Gates to manage the lifecycle of new functionality. Features follow maturity stages similar to upstream Kubernetes:

    • Alpha: Experimental functionality. Warning: Alpha features may be deprecated or removed in any consecutive minor release without notice. There are no guarantees of availability.
    • Beta: Features that are more stable but still subject to change or removal.
    • GA (Generally Available): Stable features that are part of the main documentation and supported.

    To avoid service disruption, it is recommended to only use features that have reached GA status. For Alpha or Beta features, always monitor the CHANGELOG and engage with the community.