{"id":2074,"date":"2021-03-30T20:55:29","date_gmt":"2021-03-30T17:55:29","guid":{"rendered":"https:\/\/upcloud.com\/global\/us\/resources\/tutorials\/deploy-kubernetes-using-kubespray\/"},"modified":"2026-04-23T13:57:12","modified_gmt":"2026-04-23T12:57:12","slug":"deploy-kubernetes-using-kubespray","status":"publish","type":"tutorial","link":"https:\/\/upcloud.com\/global\/resources\/tutorials\/deploy-kubernetes-using-kubespray\/","title":{"rendered":"How to deploy Kubernetes using Kubespray"},"content":{"rendered":"\n

Kubernetes is an open-source orchestration system that automates the process of deploying and maintaining containerized applications. It gives you the mechanism to schedule and run containers on clusters of several physical and\/or virtual machines. For more information please read the official Kubernetes documentation<\/a>.<\/p>\n\n\n\n\n\n

Kubespray<\/a> is a composition of Ansible playbooks, inventory, provisioning tools, and domain knowledge for generic OS\/Kubernetes cluster configuration management tasks. It provides a highly available cluster, composable attributes and support for the most popular Linux distributions. It has become the de-facto production-ready Kubernetes installer that is trusted throughout the cloud-native community (10k stars on GitHub).<\/p>\n\n\n\n

In this tutorial, we\u2019ll show the steps required to deploy a Kubernetes cluster on UpCloud using Kubespray. The tutorial assumes that you have basic knowledge about Kubernetes and the different terminologies that comes with it but the steps are easy enough for beginners to follow along as well.<\/p>\n\n\n\n

Setting up prerequisites<\/h2>\n\n\n\n

In principle, the steps in this guide can be divided into the following two main procedures which are required in order to set up a new Kubernetes cluster.<\/p>\n\n\n\n

    \n
  1. Create the infrastructure<\/li>\n\n\n\n
  2. Deploy Kubernetes<\/li>\n<\/ol>\n\n\n\n

    Before delving into the actual steps, clone Kubespray onto your own computer, for example by using the git command-line tool. If you do not already have git installed, you can use the command below to install git on Ubuntu or other Debian-based operating systems or check the git install guide<\/a> for other OS options.<\/p>\n\n\n\n

    sudo apt install git-all<\/pre>\n\n\n\n
    Then download the Kubespray package and change to the new directory.<\/p>\n\n\n\n
    git clone https:\/\/github.com\/kubernetes-sigs\/kubespray.git<\/a>\ncd kubespray<\/pre>\n\n\n\n
    You\u2019ll also need to install Ansible and other dependencies. Luckily, Kubespray provides a handy list of the requirements which can be used to install all prerequisites with a single command. However, for this to work, you\u2019ll first need to have Python\u2019s package installer, pip, available.<\/p>\n\n\n\n
    sudo apt install python3-pip\nsudo pip3 install -r requirements.txt<\/pre>\n\n\n\n
    If you face any issue while installing the prerequisites, please check the official Kubespray repository<\/a> for troubleshooting steps.<\/p>\n\n\n\n
    Installing Terraform<\/h2>\n\n\n\n
    Terraform<\/a> is an infrastructure provisioning tool. It is used for building, changing, and versioning infrastructure safely and efficiently. Installing Terraform CLI on your computer provides you with all the tools you need to manage your infrastructure in the cloud.<\/p>\n\n\n\n
    To install Terraform, find the appropriate package<\/a> for your system, download and install it.<\/p>\n\n\n\n
    For example, to install Terraform on most Linux systems, first, download the latest version.<\/p>\n\n\n\n
    wget https:\/\/releases.hashicorp.com\/terraform\/0.14.7\/terraform_0.14.7_linux_amd64.zip<\/pre>\n\n\n\n
    Then extract the binaries to a suitable location, such as \/usr\/local\/bin<\/tt> and make sure it is included in your PATH<\/tt> environment variable. For example with the command below.<\/p>\n\n\n\n
    sudo unzip terraform_0.14.7_linux_amd64.zip -d \/usr\/local\/bin<\/pre>\n\n\n\n
    You can verify that the installation worked by listing Terraform\u2019s available subcommands in a terminal.<\/p>\n\n\n\n
    terraform -help<\/pre>\n\n\n\n
    Usage: terraform [-version] [-help]  [args]\nThe available commands for execution are listed below.\nThe primary workflow commands are given first, followed by\nless common or more advanced commands.\n...<\/pre>\n\n\n\n
    Setting up API access<\/h2>\n\n\n\n
    For Terraform to be able to deploy cloud resources on your UpCloud account, you first need to grant it access. To do so, follow the steps below.<\/p>\n\n\n\n
    Create a separate API account in your UpCloud Control Panel<\/h3>\n\n\n\n
    It is recommended to create a separate API user for Terraform to interact with UpCloud API during infrastructure deployment instead of using your main account. You can do this at the UpCloud Control Panel<\/a> using the workspace member accounts. Your API account name and password are very much comparable to a traditional API ID and key pair with the added benefit of being able to set them freely yourself.<\/p>\n\n\n\n
    To create a new account, select People<\/i> on the left side of the UpCloud Control Panel and follow the instructions. For more information, see this tutorial on how to get started with the UpCloud API<\/a>.<\/p>\n\n\n\n
    Allow API Access to your UpCloud Account<\/h3>\n\n\n\n
    Once you\u2019ve created your API account, you will need to allow it to access the UpCloud API so that Terraform can create your infrastructure on UpCloud. For this purpose, make sure you select the Allow API connections<\/strong> on the new account and set it to All addresses<\/strong> to easily ensure later steps in this guide will work.<\/p>\n\n\n
    \n
    \"Setting<\/figure>\n<\/div>\n\n\n
    You can and for security reasons perhaps should<\/i> restrict this later to your own IP.<\/p>\n\n\n\n
    Set up UpCloud user credentials<\/h3>\n\n\n\n
    Lastly, you\u2019ll need to pass the new API account credentials to Terraform. Use the commands below to export your new API username and password as environment variables in your current shell session. The username and password will then be accessible to Terraform CLI when creating your cluster.<\/p>\n\n\n\n
    export TF_VAR_UPCLOUD_USERNAME=\nexport TF_VAR_UPCLOUD_PASSWORD=<\/pre>\n\n\n\n
    Note: The credentials above are in plaintext. It is advisable to store the username and password Base64 encoded for more permanent use.<\/p>\n\n\n\n
    Overview of the infrastructure<\/h2>\n\n\n\n
    A cluster in Kubernetes is composed of multiple control plane and worker nodes.  Control plane nodes are nodes that control and manage a set of worker nodes (workloads runtime) and worker nodes are nodes that run containerized applications.<\/p>\n\n\n\n
    An example of a Kubernetes cluster setup could look like the following.<\/p>\n\n\n
    \n
    \"Kubernetes<\/figure>\n<\/div>\n\n\n
    You need to decide the number of both control plane and worker nodes for your cluster. In this post, we will use one control plane node and three worker nodes.<\/p>\n\n\n\n
    To create the Kubernetes cluster, you need to make sure you have Terraform CLI installed on your system as well as the proper configuration for your cluster. Terraform helps us to define infrastructure as a code. Defining infrastructure as code brings many advantages such as simple editing, reviewing, and versioning, as well as easy sharing amongst team members.<\/p>\n\n\n\n
    Configuring the cluster<\/h2>\n\n\n\n
    Next, we\u2019ll set up the configuration for our cluster. To avoid modifying the template files, let us copy the required files into a new directory and do the changes there.<\/p>\n\n\n\n
    Create a directory called my-upcloud-cluster as follows. The CLUSTER variable here is a shorthand for our directory name. If you want to name your directory differently, just change the next line and the rest of the configuration works the same.<\/p>\n\n\n\n
    CLUSTER=my-upcloud-cluster<\/pre>\n\n\n\n
    mkdir inventory\/$CLUSTER<\/pre>\n\n\n\n
    Copy the sample inventory and the default cluster configuration to the new directory.<\/p>\n\n\n\n
    cp -r inventory\/sample inventory\/$CLUSTER\ncp -r contrib\/terraform\/upcloud\/* inventory\/$CLUSTER\/<\/pre>\n\n\n\n
    Change your working directory to the new configuration directory and edit the cluster-settings.tfvars<\/tt> file to match your requirements.<\/p>\n\n\n\n
    cd inventory\/$CLUSTER<\/pre>\n\n\n\n
    vim cluster-settings.tfvars<\/pre>\n\n\n\n
    The following are the main Terraform variables that you can change in cluster-settings.tfvars<\/i>  file.<\/p>\n\n\n\n