C3 AI Documentation Home

Overview of Kubernetes Routing to Applications

This documentation is meant to be a brief overview of all routing and network behaviors that can happen for an application. First refer to the Kubernetes Networking Components for C3 AI Applications topic to understand the individual Kubernetes networking components that a C3 AI application uses.

See also App.

Kubernetes routing components for applications

C3 AI applications are composed of C3 AI nodes, which are concretely pods in Kubernetes. Of these C3 AI nodes, network requests are handled by leader nodes.

Each application is backed by a single ClusterIP service, which provides a stable access point to route to any of the backing leader nodes for the application.

Each application has a single ingress object, which transcribes a set of ingress rules that dictate what URL paths get routed to what ClusterIP service. By design, having an ingress object for each application makes it easy to view all the possible routes for a given application.

An example of an ingress object for an application is provided below. Note that many of the details from the original manifest have been trimmed down for simplicity.

YAML
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.class: nginx  # Ingress provider
  name: c3  # Resource name of the ingress
  labels:
    app.kubernetes.io/managed-by: Helm
    c3__app-0: 0c30
    c3__app_id-0: 0dev-c3-c30  # Specifies that these rules are intended for the C3 AI Cluster Management Environment
spec:
  rules:
  - host: c3.dev.ai  # This rule specifies that c3.dev.ai/c3/c3/ routes to ClusterIP dev-c3-c3
    http:
      paths:
      - backend:
          service:
            name: dev-c3-c3  # Name of the ClusterIP for the C3 AI Cluster Management Environment
            port:
              number: 8888
        path: /c3/c3/
        pathType: ImplementationSpecific
      - backend:
          service:
            name: dev-c3-c3  # Catch all ingress rule routes to C3 AI Cluster Management Environment
            port:
              number: 8888
        path: /
        pathType: ImplementationSpecific

All the components above that are necessary for networking are brought up when an application is started. The diagram below illustrates the components and the routing for applications.

Network Diagram

Catch All Ingress rule

If a request path does not match any existing ingress rule, the request is forwarded to the C3 AI Cluster Management Environment. Even if an ingress rule does exist, it is not read until the ingress controller reloads its configuration. See below for more details.

Leader nodes have checks in place to drop requests if the application is not a registered application.

The catch all ingress rule exists for instances in which a request intended for another application should be processed by the C3 AI Cluster Management Environment. For example, if the request is intended for an application that is currently hibernating, the C3 AI Cluster Management Environment takes in the request and awakens the hibernating application.

Creation of AppUrls

When new AppUrls are upserted, the cluster must recognize the following:

  • New apps that are started must recognize existing AppUrls and translate them into ingress rules, if applicable
  • Existing applications must recognize newly created AppUrls and upsert ingress rules, if applicable

A flowchart for the above is illustrated below.

AppUrl Upsertion

Latency of ExternalDNS and ingress controller

Even after an AppUrl is created and the proper ingress rules are upserted, the new AppUrl does not come into effect until two conditions are met:

  • If a new host is defined, ExternalDNS must upsert an A record for the host to a DNS service.
  • If a new rule is created, the ingress controller must reload and sync configuration for the rule to be effective.

Internal URLs

Internal URLs are special AppUrls that are not exposed to the outside world but can still be used by C3 Agentic AI Platform servers to communicate with one another internally within the cluster. In Kubernetes, an example of an internal URL is the direct use of ClusterIP services without any interference of external load balancers and ingresses. A component in Kubernetes called CoreDNS is able to resolve the name of ClusterIP services to their corresponding IP addresses through DNS mapping.

For more information, refer to DNS for Services and Pods.

Routing in a single node environment (SNE)

In a single node environment (SNE), an environment can be a JVM that is hosting all applications for that environment. While there are also cases where a cluster can host all environments and applications in the same JVM, this documentation focuses on routing within a SNE; however, the logic for a cluster is similar.

In a SNE, Kubernetes pods, ClusterIP services, and ingress objects are only created when the environment is started. Subsequent applications that are started for that environment run as a thread on the same JVM as the environment. Since there are no ClusterIPs for individual applications in this mode, a request intended for an application must be transmitted to the ClusterIP service of the environment to reach the pod. Below is a diagram to illustrate this scenario.

SNE Network Diagram

AppUrl upsert logic slightly changes as ingress objects are no longer created for individual applications. In a SNE, the ingress object of the C3 AI Environment Management Application (or, C3 application of the environment) holds all the ingress rules for all applications in that environment. This allows all routes (such as ingress objects) to the pods of a given application to be clearly understood.

See also

Was this page helpful?