.. only:: not (epub or latex or html)

WARNING: You are looking at unreleased Cilium documentation.
Please use the official rendered version released here:
https://docs.cilium.io

.. _admin_install_daemonset: .. _k8s_install_etcd:

Installation with external etcd

This guide walks you through the steps required to set up Cilium on Kubernetes using an external etcd. Use of an external etcd provides better performance and is suitable for larger environments.

Should you encounter any issues during the installation, please refer to the :ref:troubleshooting_k8s section and/or seek help on Cilium Slack_.

When do I need to use a kvstore?

Unlike the section :ref:k8s_quick_install, this guide explains how to configure Cilium to use an external kvstore such as etcd. If you are unsure whether you need to use a kvstore at all, the following is a list of reasons when to use a kvstore:

If you are running in an environment where you observe a high overhead in state propagation caused by Kubernetes events.
If you do not want Cilium to store state in Kubernetes custom resources (CRDs).
If you run a cluster with more pods and more nodes than the ones tested in the :ref:scalability_guide.

.. _ds_deploy:

.. include:: requirements-intro.rst

You will also need an external etcd version 3.4.0 or higher.

Kvstore and Cilium dependency

When using an external kvstore, it's important to break the circular dependency between Cilium and kvstore. If kvstore pods are running within the same cluster and are using a pod network then kvstore relies on Cilium. However, Cilium also relies on the kvstore, which creates a circular dependency. There are two recommended ways of breaking this dependency:

Deploy kvstore outside of cluster or on separately managed cluster.
Deploy kvstore pods with a host network, by specifying hostNetwork: true in the pod spec.

Configure Cilium

When using an external kvstore, the address of the external kvstore needs to be configured in the ConfigMap. Download the base YAML and configure it with :term:Helm:

.. include:: k8s-install-download-release.rst

Deploy Cilium release via Helm:

.. cilium-helm-install:: :namespace: kube-system :set: etcd.enabled=true "etcd.endpoints[0]=http://etcd-endpoint1:2379" "etcd.endpoints[1]=http://etcd-endpoint2:2379" "etcd.endpoints[2]=http://etcd-endpoint3:2379"

If you do not want Cilium to store state in Kubernetes custom resources (CRDs), consider setting identityAllocationMode::

--set identityAllocationMode=kvstore

Optional: Configure the SSL certificates

Create a Kubernetes secret with the root certificate authority, and client-side key and certificate of etcd:

.. code-block:: shell-session

kubectl create secret generic -n kube-system cilium-etcd-secrets \
    --from-file=etcd-client-ca.crt=ca.crt \
    --from-file=etcd-client.key=client.key \
    --from-file=etcd-client.crt=client.crt

Adjust the helm template generation to enable SSL for etcd and use https instead of http for the etcd endpoint URLs:

.. cilium-helm-install:: :namespace: kube-system :set: etcd.enabled=true etcd.ssl=true "etcd.endpoints[0]=https://etcd-endpoint1:2379" "etcd.endpoints[1]=https://etcd-endpoint2:2379" "etcd.endpoints[2]=https://etcd-endpoint3:2379"

.. include:: k8s-install-validate.rst

.. include:: next-steps.rst