Installation using Kubespray

The guide is to use Kubespray for creating an AWS Kubernetes cluster running Cilium as the CNI. The guide uses:

Please consult Kubespray Prerequisites and Cilium System Requirements.

Installing Kubespray

$ git clone --branch v2.6.0

Install dependencies from requirements.txt

$ cd kubespray
$ sudo pip install -r requirements.txt

Infrastructure Provisioning

We will use Terraform for provisioning AWS infrastructure.

Configure AWS credentials

Export the variables for your AWS credentials

export AWS_ACCESS_KEY_ID="www"
export AWS_SSH_KEY_NAME="yyy"

Configure Terraform Variables

We will start by specifying the infrastructure needed for the Kubernetes cluster.

$ cd contrib/terraform/aws
$ cp contrib/terraform/aws/terraform.tfvars.example terraform.tfvars

Open the file and change any defaults particularly, the number of master, etcd, and worker nodes. You can change the master and etcd number to 1 for deployments that don’t need high availability. By default, this tutorial will create:

  • VPC with 2 public and private subnets

  • Bastion Hosts and NAT Gateways in the Public Subnet

  • Three of each (masters, etcd, and worker nodes) in the Private Subnet

  • AWS ELB in the Public Subnet for accessing the Kubernetes API from the internet

  • Terraform scripts using CoreOS as base image.

Example terraform.tfvars file:

#Global Vars
aws_cluster_name = "kubespray"

#VPC Vars
aws_vpc_cidr_block = "XXX.XXX.192.0/18"
aws_cidr_subnets_private = ["XXX.XXX.192.0/20","XXX.XXX.208.0/20"]
aws_cidr_subnets_public = ["XXX.XXX.224.0/20","XXX.XXX.240.0/20"]

#Bastion Host
aws_bastion_size = "t2.medium"

#Kubernetes Cluster

aws_kube_master_num = 3
aws_kube_master_size = "t2.medium"

aws_etcd_num = 3
aws_etcd_size = "t2.medium"

aws_kube_worker_num = 3
aws_kube_worker_size = "t2.medium"

#Settings AWS ELB

aws_elb_api_port = 6443
k8s_secure_api_port = 6443
kube_insecure_apiserver_address = ""

Apply the configuration

terraform init to initialize the following modules




$ terraform init

Once initialized , execute:

$ terraform plan -out=aws_kubespray_plan

This will generate a file, aws_kubespray_plan, depicting an execution plan of the infrastructure that will be created on AWS. To apply, execute:

$ terraform init
$ terraform apply "aws_kubespray_plan"

Terraform automatically creates an Ansible Inventory file at inventory/hosts.

Installing Kubernetes cluster with Cilium as CNI

Kubespray uses Ansible as its substrate for provisioning and orchestration. Once the infrastructure is created, you can run the Ansible playbook to install Kubernetes and all the required dependencies. Execute the below command in the kubespray clone repo, providing the correct path of the AWS EC2 ssh private key in ansible_ssh_private_key_file=<path to EC2 SSH private key file>

We recommend using the latest released Cilium version by passing the variable when running the ansible-playbook command. For example, you could add the following flag to the command below: -e cilium_version=v1.11.0.

$ ansible-playbook -i ./inventory/hosts ./cluster.yml -e ansible_user=core -e bootstrap_os=coreos -e kube_network_plugin=cilium -b --become-user=root --flush-cache  -e ansible_ssh_private_key_file=<path to EC2 SSH private key file>

If you are interested in configuring your Kubernetes cluster setup, you should consider copying the sample inventory. Then, you can edit the variables in the relevant file in the group_vars directory.

$ cp -r inventory/sample inventory/my-inventory
$ cp ./inventory/hosts ./inventory/my-inventory/hosts
$ echo 'cilium_version: "v1.11.0"' >> ./inventory/my-inventory/group_vars/k8s_cluster/k8s-net-cilium.yml
$ ansible-playbook -i ./inventory/my-inventory/hosts ./cluster.yml -e ansible_user=core -e bootstrap_os=coreos -e kube_network_plugin=cilium -b --become-user=root --flush-cache -e ansible_ssh_private_key_file=<path to EC2 SSH private key file>

Validate Cluster

To check if cluster is created successfully, ssh into the bastion host with the user core.

$ # Get information about the basiton host
$ cat ssh-bastion.conf
$ ssh -i ~/path/to/ec2-key-file.pem core@public_ip_of_bastion_host

Execute the commands below from the bastion host. If kubectl isn’t installed on the bastion host, you can login to the master node to test the below commands. You may need to copy the private key to the bastion host to access the master node.

Validate the Installation


Make sure you install cilium-cli v0.15.0 or later. The rest of instructions do not work with older versions of cilium-cli. To confirm the cilium-cli version that’s installed in your system, run:

cilium version --client

See Cilium CLI upgrade notes for more details.

Install the latest version of the Cilium CLI. The Cilium CLI can be used to install Cilium, inspect the state of a Cilium installation, and enable/disable various features (e.g. clustermesh, Hubble).

if [ "$(uname -m)" = "aarch64" ]; then CLI_ARCH=arm64; fi
curl -L --fail --remote-name-all${CILIUM_CLI_VERSION}/cilium-linux-${CLI_ARCH}.tar.gz{,.sha256sum}
sha256sum --check cilium-linux-${CLI_ARCH}.tar.gz.sha256sum
sudo tar xzvfC cilium-linux-${CLI_ARCH}.tar.gz /usr/local/bin
rm cilium-linux-${CLI_ARCH}.tar.gz{,.sha256sum}

To validate that Cilium has been properly installed, you can run

$ cilium status --wait
/¯¯\__/¯¯\    Cilium:         OK
\__/¯¯\__/    Operator:       OK
/¯¯\__/¯¯\    Hubble:         disabled
\__/¯¯\__/    ClusterMesh:    disabled

DaemonSet         cilium             Desired: 2, Ready: 2/2, Available: 2/2
Deployment        cilium-operator    Desired: 2, Ready: 2/2, Available: 2/2
Containers:       cilium-operator    Running: 2
                  cilium             Running: 2
Image versions    cilium    2
                  cilium-operator 2

Run the following command to validate that your cluster has proper network connectivity:

$ cilium connectivity test
ℹ️  Monitor aggregation detected, will skip some flow validation steps
✨ [k8s-cluster] Creating namespace for connectivity check...
📋 Test Report
✅ 69/69 tests successful (0 warnings)


The connectivity test may fail to deploy due to too many open files in one or more of the pods. If you notice this error, you can increase the inotify resource limits on your host machine (see Pod errors due to “too many open files”).

Congratulations! You have a fully functional Kubernetes cluster with Cilium. 🎉

Delete Cluster

$ cd contrib/terraform/aws
$ terraform destroy