docs: add BYOCNI as preferred option in AKS instructions

Following up on the previous commit: we add documentation related to the new AKS BYOCNI capabilities, and recommend it as the preferred installation method for AKS clusters. Since users might still want to use the integration offered by Azure IPAM, we elect to keep both the older Azure IPAM-based AKS installation method and the new BYOCNI-based installation method in the documentation. Signed-off-by: Nicolas Busseneau <nicolas@isovalent.com>
cilium · Jun 21, 2022 · d8259c1 · d8259c1
1 parent 05fff61
commit d8259c1
Show file tree

Hide file tree

Showing 5 changed files with 113 additions and 7 deletions.
diff --git a/Documentation/concepts/networking/ipam/azure.rst b/Documentation/concepts/networking/ipam/azure.rst
@@ -10,6 +10,10 @@
 Azure IPAM
 ##########
 
+.. note::
+
+   Azure IPAM is not compatible with AKS clusters created in BYOCNI mode.
+
 The Azure IPAM allocator is specific to Cilium deployments running in the Azure
 cloud and performs IP allocation based on `Azure Private IP addresses
 <https://docs.microsoft.com/en-us/azure/virtual-network/private-ip-addresses>`__.

diff --git a/Documentation/gettingstarted/k8s-install-default.rst b/Documentation/gettingstarted/k8s-install-default.rst
@@ -56,7 +56,52 @@ to create a Kubernetes cluster locally or using a managed Kubernetes service:
 
           Please make sure to read and understand the documentation page on :ref:`taint effects and unmanaged pods<taint_effects>`.
 
-    .. group-tab:: AKS
+    .. group-tab:: AKS (BYOCNI)
+
+       .. note::
+
+          BYOCNI is the preferred way to run Cilium on AKS, however integration
+          with the Azure stack via the :ref:`Azure IPAM<ipam_azure>` is not
+          available. If you require Azure IPAM, refer to the AKS (Azure IPAM)
+          installation.
+
+       The following commands create a Kubernetes cluster using `Azure
+       Kubernetes Service <https://docs.microsoft.com/en-us/azure/aks/>`_ with
+       no CNI plugin pre-installed (BYOCNI). See `Azure Cloud CLI
+       <https://docs.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest>`_
+       for instructions on how to install ``az`` and prepare your account, and
+       the `Bring your own CNI documentation
+       <https://docs.microsoft.com/en-us/azure/aks/use-byo-cni?tabs=azure-cli>`_
+       for more details about BYOCNI prerequisites / implications.
+
+       .. note::
+
+          BYOCNI requires the ``aks-preview`` CLI extension with version >=
+          0.5.55, which itself requires an ``az`` CLI version >= 2.32.0 .
+
+       .. code-block:: bash
+
+           export NAME="$(whoami)-$RANDOM"
+           export AZURE_RESOURCE_GROUP="${NAME}-group"
+           az group create --name "${AZURE_RESOURCE_GROUP}" -l westus2
+
+           # Create AKS cluster
+           az aks create \
+             --resource-group "${AZURE_RESOURCE_GROUP}" \
+             --name "${NAME}" \
+             --network-plugin none
+
+           # Get the credentials to access the cluster with kubectl
+           az aks get-credentials --resource-group "${AZURE_RESOURCE_GROUP}" --name "${NAME}"
+
+    .. group-tab:: AKS (Azure IPAM)
+
+       .. note::
+
+          :ref:`Azure IPAM<ipam_azure>` offers integration with the Azure stack
+          but is not the preferred way to run Cilium on AKS. If you do not
+          require Azure IPAM, we recommend you to switch to the AKS (BYOCNI)
+          installation.
 
        The following commands create a Kubernetes cluster using `Azure
        Kubernetes Service <https://docs.microsoft.com/en-us/azure/aks/>`_. See
@@ -264,9 +309,21 @@ You can install Cilium on any Kubernetes cluster. Pick one of the options below:
 
            cilium install
 
-    .. group-tab:: AKS
+    .. group-tab:: AKS (BYOCNI)
+
+       .. include:: requirements-aks-byocni.rst
+
+       **Install Cilium:**
+
+       Install Cilium into the AKS cluster:
+
+       .. code-block:: shell-session
+
+           cilium install --azure-resource-group "${AZURE_RESOURCE_GROUP}"
+
+    .. group-tab:: AKS (Azure IPAM)
 
-       .. include:: requirements-aks.rst
+       .. include:: requirements-aks-azure-ipam.rst
 
        **Install Cilium:**
 

diff --git a/Documentation/gettingstarted/k8s-install-helm.rst b/Documentation/gettingstarted/k8s-install-helm.rst
@@ -81,9 +81,24 @@ Install Cilium
        * Reconfigure kubelet to run in CNI mode
        * Mount the eBPF filesystem
 
-    .. group-tab:: AKS
+    .. group-tab:: AKS (BYOCNI)
 
-       .. include:: requirements-aks.rst
+       .. include:: requirements-aks-byocni.rst
+
+       **Install Cilium:**
+
+       Deploy Cilium release via Helm:
+
+       .. parsed-literal::
+
+          helm install cilium |CHART_RELEASE| \\
+            --namespace kube-system \\
+            --set aksbyocni.enabled=true \\
+            --set nodeinit.enabled=true
+
+    .. group-tab:: AKS (Azure IPAM)
+
+       .. include:: requirements-aks-azure-ipam.rst
 
        **Create a Service Principal:**
 

diff --git a/...ation/gettingstarted/requirements-aks.rst → ...ngstarted/requirements-aks-azure-ipam.rst b/...ation/gettingstarted/requirements-aks.rst → ...ngstarted/requirements-aks-azure-ipam.rst
@@ -1,5 +1,6 @@
-To install Cilium on `Azure Kubernetes Service (AKS) <https://docs.microsoft.com/en-us/azure/aks/>`_,
-perform the following steps:
+To install Cilium on `Azure Kubernetes Service (AKS) <https://docs.microsoft.com/en-us/azure/aks/>`_
+with Azure integration via :ref:`Azure IPAM<ipam_azure>`, perform the following
+steps:
 
 **Default Configuration:**
 
@@ -9,6 +10,12 @@ Datapath        IPAM                Datastore
 Direct Routing  Azure IPAM          Kubernetes CRD
 =============== =================== ==============
 
+.. note::
+
+   :ref:`Azure IPAM<ipam_azure>` offers integration with the Azure stack but is
+   not the preferred way to run Cilium on AKS. If you do not require Azure IPAM,
+   we recommend you to switch to the AKS (BYOCNI) installation.
+
 .. tip::
 
    If you want to chain Cilium on top of the Azure CNI, refer to the guide

diff --git a/Documentation/gettingstarted/requirements-aks-byocni.rst b/Documentation/gettingstarted/requirements-aks-byocni.rst
@@ -0,0 +1,23 @@
+To install Cilium on `Azure Kubernetes Service (AKS) <https://docs.microsoft.com/en-us/azure/aks/>`_
+in `Bring your own CNI <https://docs.microsoft.com/en-us/azure/aks/use-byo-cni?tabs=azure-cli>`_
+mode, perform the following steps:
+
+**Default Configuration:**
+
+=============== =================== ==============
+Datapath        IPAM                Datastore
+=============== =================== ==============
+Encapsulation   Cluster Pool        Kubernetes CRD
+=============== =================== ==============
+
+.. note::
+
+   BYOCNI is the preferred way to run Cilium on AKS, however integration with
+   the Azure stack via the :ref:`Azure IPAM<ipam_azure>` is not available. If
+   you require Azure IPAM, refer to the AKS (Azure IPAM) installation.
+
+**Requirements:**
+
+* The AKS cluster must be created with ``--network-plugin none`` (BYOCNI). See
+  the `Bring your own CNI documentation <https://docs.microsoft.com/en-us/azure/aks/use-byo-cni?tabs=azure-cli>`_
+  for more details about BYOCNI prerequisites / implications.