Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?


Components of Contrail

The Contrail architecture consists of pods that perform the network configuration plane and network control plane functions, and pods that perform the network data plane functions.

  • The network configuration plane refers to the functionality that enables Contrail to manage its resources and interact with the rest of the Kubernetes control plane.

  • The network control plane represents Contrail's full-featured SDN capability. It uses BGP to communicate with other controllers and XMPP to communicate with the distributed data plane components on the worker nodes.

  • The network data plane refers to the packet transmit and receive function on every node, especially on worker nodes where the workloads reside.

The pods that perform the configuration and control plane functions reside on Kubernetes control plane nodes. The pods that perform the data plane functions reside on both Kubernetes control plane nodes and Kubernetes worker nodes.

Table 1 describes the different Contrail components.

Table 1: Contrail Components
Pod Name Where Description
Configuration Plane contrail-k8s-apiserver Control Plane Node

This pod is an aggregated API server that is the entry point for managing all Contrail resources. It is registered with the regular kube-apiserver as an APIService. The regular kube-apiserver forwards all network-related requests to the contrail-k8s-apiserver for handling.

There is one contrail-k8s-apiserver pod per Kubernetes control plane node.

contrail-k8s-controller Control Plane Node

This pod performs the Kubernetes control loop function to reconcile networking resources. It constantly monitors networking resources to make sure the actual state of a resource matches its intended state.

There is one contrail-k8s-controller pod per Kubernetes control plane node.

contrail-k8s-kubemanager Control Plane Node

This pod is the interface between Kubernetes resources and Contrail resources. It watches the kube-apiserver for changes to regular Kubernetes resources such as service and namespace and acts on any changes that affect the networking resources.

In a single-cluster deployment, there is one contrail-k8s-kubemanager pod per Kubernetes control plane node.

In a multi-cluster deployment, there is additionally one contrail-k8s-kubemanager pod for every distributed workload cluster.

Control Plane contrail-control Control Plane Node

This pod passes configuration to the worker nodes and performs route learning and distribution. It watches the kube-apiserver for anything affecting the network control plane and then communicates with its BGP peers and/or vRouter agents (over XMPP) as appropriate.

There is one contrail-control pod per Kubernetes control plane node.

Data Plane contrail-vrouter-nodes Worker Node

This pod contains the vRouter agent and the vRouter itself.

The vRouter agent acts on behalf of the local vRouter when interacting with the Contrail controller. There is one agent per node. The agent establishes XMPP sessions with two Contrail controllers to perform the following functions:

  • translates configuration from the control plane into objects that the vRouter understands
  • interfaces with the control plane for the management of routes
  • collects and exports statistics from the data plane

The vRouter provides the packet send and receive function for the co-located pods and workloads. It provides the CNI plug-in functionality.

contrail-vrouter-masters Control Plane Node This pod provides the same functionality as the contrail-vrouter-nodes pod, but resides on the control plane nodes.

The components that make up the network configuration plane and the network control plane are collectively called the Contrail controller.

Figure 1 shows these components in the context of a Kubernetes cluster. For clarity and to reduce clutter, the figure does not show the data plane pods on the Kubernetes control plane node.

Figure 1: Contrail Components Contrail Components

Starting in release 22.2, Contrail uses its own etcd database by default when running on OpenShift. In earlier releases and in all Contrail releases running on Upstream Kubernetes, Contrail uses the main Kubernetes etcd database.

The kube-apiserver is the entry point for Kubernetes REST API calls for the cluster. It directs all networking requests to the contrail-k8s-apiserver, which is the entry point for Contrail API calls. The contrail-k8s-apiserver translates incoming networking requests into REST API calls to the respective Contrail objects. In some cases, these calls may result in the Contrail controller sending XMPP messages to the vRouter agent on one or more worker nodes or sending BGP messages (not shown) to other control plane nodes or external routers. These XMPP and BGP messages are sent outside of regular Kubernetes node-to-node communications.

The contrail-k8s-kubemanager (cluster) components are only present in multi-cluster deployments. For more information on the different types of deployment, see Deployment Models.

Figure 2 shows how three control plane nodes interact. The Kubernetes components communicate with each other using REST. The Contrail controllers exchange routes with each other using iBGP, outside of the regular Kubernetes REST interface. Every control plane node is identical to every other control plane node in the cluster. Every worker node is identical to every other worker node in the cluster. For redundancy, the vRouter agents on worker nodes always establish XMPP communications with two Contrail controllers.

Figure 2: Multiple Control Plane Nodes Multiple Control Plane Nodes