github.com/cilium/cilium@v1.16.2/Documentation/installation/k8s-install-kops.rst (about)

     1  .. only:: not (epub or latex or html)
     2  
     3      WARNING: You are looking at unreleased Cilium documentation.
     4      Please use the official rendered version released here:
     5      https://docs.cilium.io
     6  
     7  .. _kops_guide:
     8  .. _k8s_install_kops:
     9  
    10  ***********************
    11  Installation using Kops
    12  ***********************
    13  
    14  As of kops 1.9 release, Cilium can be plugged into kops-deployed
    15  clusters as the CNI plugin. This guide provides steps to create a Kubernetes
    16  cluster on AWS using kops and Cilium as the CNI plugin. Note, the kops
    17  deployment will automate several deployment features in AWS by default,
    18  including AutoScaling, Volumes, VPCs, etc.
    19  
    20  Kops offers several out-of-the-box configurations of Cilium including :ref:`kubeproxy-free`,
    21  :ref:`ipam_eni`, and dedicated etcd cluster for Cilium. This guide will just go through a basic setup.
    22  
    23  
    24  Prerequisites
    25  =============
    26  
    27  * `aws cli <https://aws.amazon.com/cli/>`_
    28  * `kubectl <https://kubernetes.io/docs/tasks/tools/install-kubectl/>`_
    29  * aws account with permissions:
    30    * AmazonEC2FullAccess
    31    * AmazonRoute53FullAccess
    32    * AmazonS3FullAccess
    33    * IAMFullAccess
    34    * AmazonVPCFullAccess
    35  
    36  
    37  Installing kops
    38  ===============
    39  
    40  .. tabs::
    41    .. group-tab:: Linux
    42  
    43      .. code-block:: shell-session
    44  
    45          curl -LO https://github.com/kubernetes/kops/releases/download/$(curl -s https://api.github.com/repos/kubernetes/kops/releases/latest | grep tag_name | cut -d '"' -f 4)/kops-linux-amd64
    46          chmod +x kops-linux-amd64
    47          sudo mv kops-linux-amd64 /usr/local/bin/kops
    48  
    49    .. group-tab:: MacOS
    50  
    51      .. code-block:: shell-session
    52  
    53          brew update && brew install kops
    54  
    55  
    56  Setting up IAM Group and User
    57  =============================
    58  
    59  Assuming you have all the prerequisites, run the following commands to create
    60  the kops user and group:
    61  
    62  .. code-block:: shell-session
    63  
    64          $ # Create IAM group named kops and grant access
    65          $ aws iam create-group --group-name kops
    66          $ aws iam attach-group-policy --policy-arn arn:aws:iam::aws:policy/AmazonEC2FullAccess --group-name kops
    67          $ aws iam attach-group-policy --policy-arn arn:aws:iam::aws:policy/AmazonRoute53FullAccess --group-name kops
    68          $ aws iam attach-group-policy --policy-arn arn:aws:iam::aws:policy/AmazonS3FullAccess --group-name kops
    69          $ aws iam attach-group-policy --policy-arn arn:aws:iam::aws:policy/IAMFullAccess --group-name kops
    70          $ aws iam attach-group-policy --policy-arn arn:aws:iam::aws:policy/AmazonVPCFullAccess --group-name kops
    71          $ aws iam create-user --user-name kops
    72          $ aws iam add-user-to-group --user-name kops --group-name kops
    73          $ aws iam create-access-key --user-name kops
    74  
    75  
    76  kops requires the creation of a dedicated S3 bucket in order to store the
    77  state and representation of the cluster. You will need to change the bucket
    78  name and provide your unique bucket name (for example a reverse of FQDN added
    79  with short description of the cluster). Also make sure to use the region where
    80  you will be deploying the cluster.
    81  
    82  .. code-block:: shell-session
    83  
    84          $ aws s3api create-bucket --bucket prefix-example-com-state-store --region us-west-2 --create-bucket-configuration LocationConstraint=us-west-2
    85          $ export KOPS_STATE_STORE=s3://prefix-example-com-state-store
    86  
    87  The above steps are sufficient for getting a working cluster installed. Please
    88  consult `kops aws documentation
    89  <https://kops.sigs.k8s.io/getting_started/install/>`_ for more
    90  detailed setup instructions.
    91  
    92  
    93  Cilium Prerequisites
    94  ====================
    95  
    96  * Ensure the :ref:`admin_system_reqs` are met, particularly the Linux kernel
    97    and key-value store versions.
    98  
    99  The default AMI satisfies the minimum kernel version required by Cilium, which is
   100  what we will use in this guide.
   101  
   102  
   103  Creating a Cluster
   104  ==================
   105  
   106  * Note that you will need to specify the ``--master-zones`` and ``--zones`` for
   107    creating the master and worker nodes. The number of master zones should be
   108    * odd (1, 3, ...) for HA. For simplicity, you can just use 1 region.
   109  * To keep things simple when following this guide, we will use a gossip-based cluster.
   110    This means you do not have to create a hosted zone upfront.  cluster ``NAME`` variable
   111    must end with ``k8s.local`` to use the gossip  protocol. If creating multiple clusters
   112    using the same kops user, then make the cluster name unique by adding a prefix such as 
   113    ``com-company-emailid-``.
   114  
   115  
   116  .. code-block:: shell-session
   117  
   118          $ export NAME=com-company-emailid-cilium.k8s.local
   119          $ kops create cluster --state=${KOPS_STATE_STORE} --node-count 3 --topology private --master-zones us-west-2a,us-west-2b,us-west-2c --zones us-west-2a,us-west-2b,us-west-2c --networking cilium --cloud-labels "Team=Dev,Owner=Admin" ${NAME} --yes
   120  
   121  
   122  You may be prompted to create a ssh public-private key pair.
   123  
   124  .. code-block:: shell-session
   125  
   126          $ ssh-keygen
   127  
   128  
   129  (Please see :ref:`appendix_kops`)
   130  
   131  .. include:: k8s-install-validate.rst
   132  
   133  .. _appendix_kops:
   134  
   135  
   136  Deleting a Cluster
   137  ==================
   138  
   139  To undo the dependencies and other deployment features in AWS from the kops
   140  cluster creation, use kops to destroy a cluster *immediately* with the
   141  parameter ``--yes``:
   142  
   143  .. code-block:: shell-session
   144  
   145          $ kops delete cluster ${NAME} --yes
   146  
   147  
   148  Further reading on using Cilium with Kops
   149  =========================================
   150  * See the `kops networking documentation <https://kops.sigs.k8s.io/networking/cilium/>`_ for more information on the 
   151    configuration options kops offers.
   152  * See the `kops cluster spec documentation <https://pkg.go.dev/k8s.io/kops/pkg/apis/kops?tab=doc#CiliumNetworkingSpec>`_ for a comprehensive list of all the options
   153  
   154  
   155  Appendix: Details of kops flags used in cluster creation
   156  ========================================================
   157  
   158  The following section explains all the flags used in create cluster command.
   159  
   160  * ``--state=${KOPS_STATE_STORE}`` : KOPS uses an S3 bucket to store the state of your cluster and representation of your cluster
   161  * ``--node-count 3`` : No. of worker nodes in the kubernetes cluster.
   162  * ``--topology private`` : Cluster will be created with private topology, what that means is all masters/nodes will be launched in a private subnet in the VPC
   163  * ``--master-zones eu-west-1a,eu-west-1b,eu-west-1c`` : The 3 zones ensure the HA of master nodes, each belonging in a different Availability zones.
   164  * ``--zones eu-west-1a,eu-west-1b,eu-west-1c`` : Zones where the worker nodes will be deployed
   165  * ``--networking cilium`` : Networking CNI plugin to be used - cilium. You can also use ``cilium-etcd``, which will use a dedicated etcd cluster as key/value store instead of CRDs.
   166  * ``--cloud-labels "Team=Dev,Owner=Admin"`` :  Labels for your cluster that will be applied to your instances
   167  * ``${NAME}`` : Name of the cluster. Make sure the name ends with k8s.local for a gossip based cluster