Oracle Cloud Infrastructure Documentation

Setting Up the OCI Native Ingress Controller on a Kubernetes Cluster

Find out how to set up the OCI native ingress controller to implement the rules and configuration options defined in a Kubernetes ingress resource to load balance and route incoming traffic to service pods running on worker nodes in a cluster.

The OCI native ingress controller implements the rules and configuration options defined in a Kubernetes ingress resource to load balance and route incoming traffic to service pods running on worker nodes in a cluster. The OCI native ingress controller creates an OCI flexible load balancer to handle requests, and configures the OCI load balancer to route requests according to the rules defined in the ingress resource. If there are changes to the routing rules, or to other supporting resources, the OCI native ingress controller updates the load balancer configuration accordingly. The OCI native ingress controller runs as a single pod, on a randomly selected worker node in the cluster.

The OCI native ingress controller creates OCI load balancer resources as follows:

  • A load balancer for each IngressClass resource where you have specified the OCI native ingress controller as the controller.
  • A load balancer backend set for each unique Kubernetes service name and port number combination that you include in routing rules in Ingress resources in the cluster.
  • A load balancer listener for each unique port that you include in routing rules in Ingress resources in the cluster. The OCI native ingress controller determines the protocol (HTTP, HTTPS, HTTP/2) for each listener based on the ingress backend configuration.

The OCI native ingress controller adds as backends to a backend set either the pods that serve as endpoints for the respective Kubernetes service name and port, or the worker nodes on which those pods can run, depending on the CNI plugin that the cluster uses for pod networking:

  • If the cluster uses the OCI VCN-Native Pod Networking CNI plugin for pod networking, the OCI native ingress controller adds the pods as backends.
  • If the cluster uses the flannel CNI plugin for pod networking, the OCI native ingress controller adds the worker nodes as backends. In this case, the OCI native ingress controller uses the externalTrafficPolicy setting in the service's manifest to determine which worker nodes to add to the backend set, as follows:
    • If externalTrafficPolicy: Cluster, the OCI native ingress controller adds to the backend set all the worker nodes in the cluster.
    • If externalTrafficPolicy: Local, the OCI native ingress controller adds to the backend set only those worker nodes on which the service's pods have been deployed.

The OCI native ingress controller creates OCI load balancer resources subject to the normal Load Balancer service limits regarding total number of IP addresses, backend sets, listeners, and backend servers. For more information, see Limits on Load Balancing Resources.

When using the OCI native ingress controller to load balance and route incoming traffic, note the following:

  • The cluster must be running Kubernetes version 1.26, 1.27, 1.28, or 1.29.
  • The cluster must have load balancer subnet security rules configured.
  • The cluster can be using either the OCI VCN-Native Pod Networking CNI plugin or the flannel CNI plugin for pod networking. Note that if the cluster uses the flannel CNI plugin for pod networking, the OCI native ingress controller only supports backend services of type: NodePort, as specified in the service's manifest.
  • The use of instance principals to enable the OCI native ingress controller to access OCI services and resources is not supported in clusters with virtual nodes.
  • You can specify workload identity principals with enhanced clusters, but not with basic clusters.

At a high-level, the steps to set up the OCI native ingress controller are:

  • Meet the prerequisites

    Configure the cluster on which you want to deploy the OCI native ingress controller to meet the prerequisites, as follows:

    • Set up an instance principal, user principal, or workload identity principal to enable the OCI native ingress controller pod to access other Oracle Cloud Infrastructure services and resources.
    • Grant the instance principal, user principal, or workload identity principal the necessary permissions.
    • Install cert-manager on the cluster.
    • Install the Helm CLI.
    • Clone the OCI native ingress controller repository and set parameters in values.yaml.

    For more information, see Prerequisites for deploying the OCI Native Ingress Controller.

  • Deploy the OCI native ingress controller

    Deploy the OCI native ingress controller as follows:

    • Install the OCI native ingress controller.
    • Create the IngressClassParameters, IngressClass, and Ingress resources.

    For more information, see Installing the OCI Native Ingress Controller and Creating Kubernetes Ingress-Related Resources.

  • Configure the OCI native ingress controller

    You can configure the OCI native ingress controller as follows:

    • Add route rules to the Ingress resource manifest to specify how the OCI load balancer created by the OCI native ingress controller routes incoming requests. The OCI native ingress controller supports:
      • Host-based routing: Requests are routed to different backend services using rules defined for the ingress resource, based on the domain name in the request's Host header (the host to which the request was originally sent).
      • Path-based routing: Requests are routed to different backend services using rules defined for the ingress resource, based on elements in the path to which the original request was sent.
      • Default backend routing: Requests are routed to a default backend if the request does not match any of the rules defined for the ingress resource.
      See Specifying Route Rules for the OCI Native Ingress Controller.
    • Use annotations to customize the behavior of the OCI native ingress controller and the OCI load balancer that the OCI native ingress controller creates. You can use annotations to specify:
      • the OCID of an existing OCI load balancer to use, rather than creating a new one
      • a custom load balancing policy
      • a custom listener protocol
      • attributes of the load balancer health check policy
      See Customizing OCI Native Ingress Controller Behavior Using Annotations.
    • Define pod readiness gates to indicate that a pod is ready to receive traffic (provided the cluster is using the OCI VCN-Native Pod Networking CNI plugin for pod networking). See Setting Up a Pod Readiness Gate.
    • Provide support for HTTPS/TLS requests using certificates issued by the OCI Certificates service. See Adding Support for HTTPS/TLS Requests.

  • Troubleshoot the OCI native ingress controller

    Troubleshoot common problems with the OCI native ingress controller. The OCI native ingress controller identifies conflicting declarations in ingress resource manifests, and outputs validation errors in pod logs.

    For more information, see Troubleshooting the OCI Native Ingress Controller.