--- title: "Configuring the Calico Kubernetes controllers" description: "Reference for kube-controllers configuration in Calico Open Source covering environment variables and KubeControllersConfiguration options." product: "Calico Open Source" version: "3.32 (latest)" section: "Reference" canonical_url: "https://docs.tigera.io/calico/latest/reference/kube-controllers/configuration" --- # 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. **Tab: Operator** If you have installed Calico using the operator, see the [KubeControllersConfiguration](https://docs.tigera.io/calico/latest/reference/resources/kubecontrollersconfig.md) resource instead. **Tab: Manifest** 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 data plane. 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: | Environment | Description | Schema | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | | `ETCD_ENDPOINTS` | Comma-delimited list of etcd endpoints to connect to. Example: `http://10.0.0.1:2379,http://10.0.0.2:2379`. | string | | `ETCD_DISCOVERY_SRV` | Domain name to discover etcd endpoints via SRV records. Mutually exclusive with `ETCD_ENDPOINTS`. Example: `example.com` | string | | `ETCD_CA_CERT_FILE` | Path to the file containing the root certificate of the CA that issued the etcd server certificate. Configures the Kubernetes controllers to trust the signature on the certificates provided by the etcd server. To disable authentication of the server by the Kubernetes controllers, set the value to `none`. | path | | `ETCD_CERT_FILE` | Path to the file containing the client certificate issued to the Kubernetes controllers. Enables the Kubernetes controllers to participate in mutual TLS authentication and identify themselves to the etcd server. Example: `/etc/kube-controllers/cert.pem` | path | | `ETCD_KEY_FILE` | Path to the file containing the private key of the Kubernetes controllers' client certificate. Enables the Kubernetes controllers to participate in mutual TLS authentication and identify themselves to the etcd server. Example: `/etc/kube-controllers/key.pem` | path | 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](https://kubernetes.io/docs/concepts/configuration/secret/) to mount the certificates into the pod as files. #### kubernetes When running the controllers as a Kubernetes pod, Kubernetes API access is [configured automatically](https://kubernetes.io/docs/tasks/access-application-cluster/access-cluster/#accessing-the-api-from-a-pod) and no additional configuration is required. However, the controllers can also be configured to use an explicit [kubeconfig](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) file override to configure API access if needed. | Environment | Description | Schema | | ------------ | ------------------------------------------------------------------ | ------ | | `KUBECONFIG` | Path to a Kubernetes kubeconfig file mounted within the container. | path | ### Other configuration > **SECONDARY:** Whenever possible, prefer configuring the kube-controllers component using the [KubeControllersConfiguration](https://docs.tigera.io/calico/latest/reference/resources/kubecontrollersconfig.md) 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. | Environment | Description | Schema | Default | | --------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------- | ----------------------------------------------------- | | `DATASTORE_TYPE` | Which datastore type to use | etcdv3, kubernetes | kubernetes | | `ENABLED_CONTROLLERS` | Which controllers to run | namespace, node, policy, serviceaccount, workloadendpoint | policy,namespace,serviceaccount,workloadendpoint,node | | `LOG_LEVEL` | Minimum log level to be displayed. | debug, info, warning, error | info | | `KUBECONFIG` | Path to a kubeconfig file for Kubernetes API access | path | | | `SYNC_NODE_LABELS` | When enabled, Kubernetes node labels will be copied to Calico node objects. | boolean | true | | `AUTO_HOST_ENDPOINTS` | When set to enabled, automatically create a host endpoint for each node. | enabled, disabled | disabled | | `COMPACTION_PERIOD` | Compact the etcd database on this interval. Set to "0" to disable. | [duration](https://golang.org/pkg/time/#ParseDuration) | 10m | ## 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](https://docs.tigera.io/calico/latest/reference/resources/kubecontrollersconfig.md) 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. ```yaml - 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](https://docs.tigera.io/calico/latest/reference/resources/kubecontrollersconfig.md) 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.