Configuring the Calico Kubernetes controllers

The Calico Kubernetes controllers are deployed in a Kubernetes cluster. The different controllers monitor the Kubernetes API and perform actions based on cluster state.

• Operator
• Manifest

If you have installed Calico using the operator, see the KubeControllersConfiguration resource instead.

The controllers are primarily configured through environment variables. When running the controllers as a Kubernetes pod, this is accomplished through the pod manifest env section.

The calico/kube-controllers container

The calico/kube-controllers container includes the following controllers:

1. policy controller: watches Kubernetes network policies in the Kubernetes API, and syncs the policies to the datastore (etcd) as Calico network policies. Felix implements network policies in the dataplane.
2. namespace controller: watches namespaces and programs Calico profiles.
3. serviceaccount controller: watches service accounts and programs Calico profiles.
4. workloadendpoint controller: watches for changes to pod labels and updates Calico workload endpoints.
5. node controller: watches for the removal of Kubernetes nodes and removes corresponding data from Calico, and optionally watches for node updates to create and sync host endpoints for each node.

The Calico Kubernetes manifests run these controllers within a single pod in the calico-kube-controllers deployment.

Configuring datastore access

The datastore type can be configured via the DATASTORE_TYPE environment variable. Supported values are etcdv3 and kubernetes.

etcdv3

The Calico Kubernetes controllers support the following environment variables to configure etcd access:

The *_FILE variables are paths to the corresponding certificates/keys. As such, when the controllers are running as a Kubernetes pod, you must ensure that the files exist within the pod. This is usually done in one of two ways:

• Mount the certificates from the host. This requires that the certificates be present on the host running the controller.
• Use Kubernetes Secrets to mount the certificates into the pod as files.

kubernetes

When running the controllers as a Kubernetes pod, Kubernetes API access is configured automatically and no additional configuration is required. However, the controllers can also be configured to use an explicit kubeconfig file override to configure API access if needed.

Other configuration

note

Whenever possible, prefer configuring the kube-controllers component using the KubeControllersConfiguration API resource, Some configuration options may not be available through environment variables.

The following environment variables can be used to configure the Calico Kubernetes controllers.

About each controller

Node controller

The node controller has several functions depending on the datastore in use.

Either datastore

• Garbage collects IP addresses.
• Automatically provisions host endpoints for Kubernetes nodes.

etcdv3 only

• Garbage collects projectcalico.org/v3 Node resources when the Kubernetes node is deleted.
• Synchronizes labels between Kubernetes and Calico Node resources.

The node controller is not enabled by default if ENABLED_CONTROLLERS is not explicitly specified. However, the Calico Kubernetes manifests explicitly specify the ENABLED_CONTROLLERS and enable this controller within the calico-kube-controllers deployment.

This controller is valid when using either the etcdv3 or kubernetes datastore types.

etcdv3

To enable the node controller when using etcdv3, perform the following two steps.

1. Enable the controller in your KubeControllersConfiguration or add “node” to the list of enabled controllers in the environment for kube-controllers. For example: ENABLED_CONTROLLERS=workloadendpoint,profile,policy,node

2. Configure calico/node with a Kubernetes node reference by adding the following snippet to the environment section of the calico-node daemon set.

   - name: CALICO_K8S_NODE_REF
     valueFrom:
       fieldRef:
         fieldPath: spec.nodeName

Set SYNC_NODE_LABELS to true (enabled by default) to ensure that labels on Kubernetes node resources remain in-sync with labels on the corresponding Calico node resource. If both node resources specify a label with different values, the Kubernetes node resource takes precedence. Labels on the Calico resource that don’t exist in the Kubernetes node will remain as is.

kubernetes

To enable the node controller when using kubernetes, enable the controller in your KubeControllersConfiguration or set the list of enabled controllers in the environment for kube-controllers to node. For example: ENABLED_CONTROLLERS=node

Policy controller

The policy controller syncs Kubernetes network policies to the Calico datastore. The controller must have read access to the Kubernetes API to monitor NetworkPolicy events.

The policy controller is enabled by default if ENABLED_CONTROLLERS is not explicitly specified.

This controller is only valid when using etcd as the Calico datastore.

Workload endpoint controller

The workload endpoint controller automatically syncs Kubernetes pod label changes to the Calico datastore by updating the corresponding workload endpoints appropriately. The controller must have read access to the Kubernetes API to monitor Pod events.

The workload endpoint controller is enabled by default if ENABLED_CONTROLLERS is not explicitly specified.

This controller is only valid when using etcd as the Calico datastore.

Namespace controller

The namespace controller syncs Kubernetes namespace label changes to the Calico datastore. The controller must have read access to the Kubernetes API to monitor Namespace events.

The namespace controller is enabled by default if ENABLED_CONTROLLERS is not explicitly specified.

This controller is only valid when using etcd as the Calico datastore.

Service account controller

The service account controller syncs Kubernetes service account changes to the Calico datastore. The controller must have read access to the Kubernetes API to monitor ServiceAccount events.

The service account controller is enabled by default if ENABLED_CONTROLLERS is not explicitly specified.

This controller is only valid when using etcd as the Calico datastore.