diff --git a/docs/labs/kubernetes-the-hard-way/00-README.md b/docs/labs/kubernetes-the-hard-way/00-README.md index dd1108f2b..772f2c1f2 100644 --- a/docs/labs/kubernetes-the-hard-way/00-README.md +++ b/docs/labs/kubernetes-the-hard-way/00-README.md @@ -1,18 +1,24 @@ +--- +title: Introduction +author: Wale Soyinka +contributors: Steven Spencer +--- -This is a fork of the original ["Kubernetes the hard way"](https://github.com/kelseyhightower/kubernetes-the-hard-way) originally written by kelseyhightower -. Unlike the original that is based on Debian like distros for the ARM64 architecture, this fork is targetted at Enterprise Linux distributions such as Rocky Linux running on x86_64 architecture. +This is a fork of the original ["Kubernetes the hard way"](https://github.com/kelseyhightower/kubernetes-the-hard-way) originally written by Kelsey Hightower (GitHub: kelseyhightower). +Unlike the original that bases itself on Debian like distributions for the ARM64 architecture, this fork targets Enterprise Linux distributions such as Rocky Linux running on x86_64 architecture. # Kubernetes The Hard Way -This tutorial walks you through setting up Kubernetes the hard way. This guide is not for someone looking for a fully automated tool to bring up a Kubernetes cluster. Kubernetes The Hard Way is optimized for learning, which means taking the long route to ensure you understand each task required to bootstrap a Kubernetes cluster. +This tutorial walks you through setting up Kubernetes the hard way. This guide is not for someone looking for a fully automated tool to bring up a Kubernetes cluster. Kubernetes The Hard Way, designed for learning, means taking the long route to ensure you understand each task required to bootstrap a Kubernetes cluster. -> The results of this tutorial should not be viewed as production ready, and may receive limited support from the community, but don't let that stop you from learning! +Do not view the results of this tutorial as production ready, and it might not receive support from the community, but do not let that stop you from learning! ## Copyright -Creative Commons License
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. +![Creative Commons License](images/cc_by_sa.png) +Licensing of this work is under a [Creative Commons Attribution-NonCommercial-=ShareAlike 4.0 International License](http://creativecommons.org/licenses/by-nc-sa/4.0/). ## Target Audience @@ -31,18 +37,18 @@ Component versions: ## Labs -This tutorial requires four (4) x86_64 based virtual or physical machines connected to the same network. While x86_64 based machines are used for the tutorial, the lessons learned can be applied to other platforms. - -* [Prerequisites](docs/01-prerequisites.md) -* [Setting up the Jumpbox](docs/02-jumpbox.md) -* [Provisioning Compute Resources](docs/03-compute-resources.md) -* [Provisioning the CA and Generating TLS Certificates](docs/04-certificate-authority.md) -* [Generating Kubernetes Configuration Files for Authentication](docs/05-kubernetes-configuration-files.md) -* [Generating the Data Encryption Config and Key](docs/06-data-encryption-keys.md) -* [Bootstrapping the etcd Cluster](docs/07-bootstrapping-etcd.md) -* [Bootstrapping the Kubernetes Control Plane](docs/08-bootstrapping-kubernetes-controllers.md) -* [Bootstrapping the Kubernetes Worker Nodes](docs/09-bootstrapping-kubernetes-workers.md) -* [Configuring kubectl for Remote Access](docs/10-configuring-kubectl.md) -* [Provisioning Pod Network Routes](docs/11-pod-network-routes.md) -* [Smoke Test](docs/12-smoke-test.md) -* [Cleaning Up](docs/13-cleanup.md) +This tutorial requires four (4) x86_64 based virtual or physical machines connected to the same network. While the tutorial uses x86_64 based machines, you can apply the lessons learned to other platforms. + +* [Prerequisites](01-prerequisites.md) +* [Setting up the Jumpbox](02-jumpbox.md) +* [Provisioning Compute Resources](03-compute-resources.md) +* [Provisioning the CA and Generating TLS Certificates](04-certificate-authority.md) +* [Generating Kubernetes Configuration Files for Authentication](05-kubernetes-configuration-files.md) +* [Generating the Data Encryption Config and Key](06-data-encryption-keys.md) +* [Bootstrapping the etcd Cluster](07-bootstrapping-etcd.md) +* [Bootstrapping the Kubernetes Control Plane](08-bootstrapping-kubernetes-controllers.md) +* [Bootstrapping the Kubernetes Worker Nodes](09-bootstrapping-kubernetes-workers.md) +* [Configuring kubectl for Remote Access](10-configuring-kubectl.md) +* [Provisioning Pod Network Routes](11-pod-network-routes.md) +* [Smoke Test](12-smoke-test.md) +* [Cleaning Up](13-cleanup.md) diff --git a/docs/labs/kubernetes-the-hard-way/01-prerequisites.md b/docs/labs/kubernetes-the-hard-way/01-prerequisites.md index c587e42fb..f09d89a35 100644 --- a/docs/labs/kubernetes-the-hard-way/01-prerequisites.md +++ b/docs/labs/kubernetes-the-hard-way/01-prerequisites.md @@ -13,9 +13,9 @@ This tutorial requires four (4) virtual or physical x86_64 machines running Debi | node-0 | Kubernetes worker node | 1 | 2GB | 20GB | | node-1 | Kubernetes worker node | 1 | 2GB | 20GB | -How you provision the machines is up to you, the only requirement is that each machine meet the above system requirements including the machine specs and OS version. Once you have all four machine provisioned, verify the system requirements by running the `uname` command on each machine: +How you provision the machines is up to you, the only requirement is that each machine meet the above system requirements including the machine specs and operating system version. Once you have all four machine provisioned, verify the system requirements by running the `uname` command on each machine: -```bash +```bash uname -mov ``` diff --git a/docs/labs/kubernetes-the-hard-way/02-jumpbox.md b/docs/labs/kubernetes-the-hard-way/02-jumpbox.md index 74327a195..9270bb953 100644 --- a/docs/labs/kubernetes-the-hard-way/02-jumpbox.md +++ b/docs/labs/kubernetes-the-hard-way/02-jumpbox.md @@ -1,8 +1,8 @@ # Set Up The Jumpbox -In this lab you will set up one of the four machines to be a `jumpbox`. This machine will be used to run commands in this tutorial. While a dedicated machine is being used to ensure consistency, these commands can also be run from just about any machine including your personal workstation running macOS or Linux. +In this lab you will set up one of the four machines to be a `jumpbox`. You will use this machine to run commands in this tutorial. While the use of a dedicated machine is to ensure consistency, you can run these commands from just about any machine, including your personal workstation running macOS or Linux. -Think of the `jumpbox` as the administration machine that you will use as a home base when setting up your Kubernetes cluster from the ground up. One thing we need to do before we get started is install a few command line utilities and clone the Kubernetes The Hard Way git repository, which contains some additional configuration files that will be used to configure various Kubernetes components throughout this tutorial. +Think of the `jumpbox` as the administration machine that you will use as a home base when setting up your Kubernetes cluster from the ground up. One thing you need to do before you get started is to install a few command line utilities and clone the Kubernetes The Hard Way git repository, which contains some additional configuration files that you will use to configure various Kubernetes components throughout this tutorial. Log in to the `jumpbox`: @@ -10,19 +10,19 @@ Log in to the `jumpbox`: ssh root@jumpbox ``` -All commands will be run as the `root` user. This is being done for the sake of convenience, and will help reduce the number of commands required to set everything up. +You will run all commands as the `root` user, for the sake of convenience, and it will help reduce the number of commands required to set everything up. -### Install Command Line Utilities +## Install Command Line Utilities -Now that you are logged into the `jumpbox` machine as the `root` user, you will install the command line utilities that will be used to preform various tasks throughout the tutorial. +Once logged into the `jumpbox` machine as the `root` user, you will install the command line utilities that you will use to preform various tasks throughout the tutorial: ```bash sudo dnf -y install wget curl vim openssl git ``` -### Sync GitHub Repository +## Sync GitHub Repository -Now it's time to download a copy of this tutorial which contains the configuration files and templates that will be used build your Kubernetes cluster from the ground up. Clone the Kubernetes The Hard Way git repository using the `git` command: +Now it is time to download a copy of this tutorial which contains the configuration files and templates that you will use to build your Kubernetes cluster from the ground up. Clone the Kubernetes The Hard Way git repository using the `git` command: ```bash git clone --depth 1 \ @@ -45,17 +45,16 @@ pwd /root/kubernetes-the-hard-way ``` -### Download Binaries +## Download Binaries -In this section you will download the binaries for the various Kubernetes components. The binaries will be stored in the `Downloads` directory on the `jumpbox`, which will reduce the amount of internet bandwidth required to complete this tutorial as we avoid downloading the binaries multiple times for each machine in our Kubernetes cluster. +Here you will download the binaries for the various Kubernetes components. Store these binaries in the `Downloads` directory on the `jumpbox`. This will reduce the amount of internet bandwidth required to complete this tutorial as you avoid downloading the binaries multiple times for each machine in our Kubernetes cluster. -The binaries that will be downloaded are listed in the `downloads.txt` file, which you can review using the `cat` command: +The `download.txt` file lists the binaries you will download, which you can review using the `cat` command: ```bash cat downloads.txt ``` - Download the binaries listed in the `downloads.txt` file into a directory called `downloads` using the `wget` command: ```bash @@ -66,7 +65,7 @@ wget -q --show-progress \ -i downloads.txt ``` -Depending on your internet connection speed it may take a while to download the `584` megabytes of binaries, and once the download is complete, you can list them using the `ls` command: +Depending on your internet connection speed it might take a while to download the `584` megabytes of binaries. Once the download is complete, you can list them using the `ls` command: ```bash ls -loh downloads @@ -87,9 +86,9 @@ total 557M -rw-r--r--. 1 root 11M Feb 13 20:19 runc.amd64 ``` -### Install kubectl +## Install kubectl -In this section you will install the `kubectl`, the official Kubernetes client command line tool, on the `jumpbox` machine. `kubectl will be used to interact with the Kubernetes control plane once your cluster is provisioned later in this tutorial. +In this section you will install the `kubectl`, the official Kubernetes client command line tool, on the `jumpbox` machine. You will use `kubectl` to interact with the Kubernetes control plane after provisioning of your cluster completes later in this tutorial. Use the `chmod` command to make the `kubectl` binary executable and move it to the `/usr/local/bin/` directory: @@ -98,7 +97,7 @@ Use the `chmod` command to make the `kubectl` binary executable and move it to t cp downloads/kubectl /usr/local/bin/ ``` -At this point `kubectl` is installed and can be verified by running the `kubectl` command: +Since your installation of `kubectl` is complete, you can verify it by running the `kubectl` command: ```bash kubectl version --client @@ -109,6 +108,6 @@ Client Version: v1.32.0 Kustomize Version: v5.5.0 ``` -At this point the `jumpbox` has been set up with all the command line tools and utilities necessary to complete the labs in this tutorial. +At this point, you have set up `jumpbox` with all the command line tools and utilities necessary to complete the labs in this tutorial. Next: [Provisioning Compute Resources](03-compute-resources.md) diff --git a/docs/labs/kubernetes-the-hard-way/03-compute-resources.md b/docs/labs/kubernetes-the-hard-way/03-compute-resources.md index 1ee2b74ea..796a3412d 100644 --- a/docs/labs/kubernetes-the-hard-way/03-compute-resources.md +++ b/docs/labs/kubernetes-the-hard-way/03-compute-resources.md @@ -4,7 +4,7 @@ Kubernetes requires a set of machines to host the Kubernetes control plane and t ## Machine Database -This tutorial will leverage a text file, which will serve as a machine database, to store the various machine attributes that will be used when setting up the Kubernetes control plane and worker nodes. The following schema represents entries in the machine database, one entry per line: +This tutorial will leverage a text file, which will serve as a machine database, to store the various machine attributes that you will use when setting up the Kubernetes control plane and worker nodes. The following schema represents entries in the machine database, one entry per line: ```text IPV4_ADDRESS FQDN HOSTNAME POD_SUBNET @@ -12,7 +12,7 @@ IPV4_ADDRESS FQDN HOSTNAME POD_SUBNET Each of the columns corresponds to a machine IP address `IPV4_ADDRESS`, fully qualified domain name `FQDN`, host name `HOSTNAME`, and the IP subnet `POD_SUBNET`. Kubernetes assigns one IP address per `pod` and the `POD_SUBNET` represents the unique IP address range assigned to each machine in the cluster for doing so. -Here is an example machine database similar to the one used when creating this tutorial. Notice the IP addresses have been masked out. Your machines can be assigned any IP address as long as each machine is reachable from each other and the `jumpbox`. +Here is an example machine database similar to the one used when creating this tutorial. Notice the hidden IP addresses. You can assign any IP address to your machines provided that each machine is reachable from each other and the `jumpbox`. ```bash cat machines.txt @@ -24,17 +24,17 @@ XXX.XXX.XXX.XXX node-0.kubernetes.local node-0 10.200.0.0/24 XXX.XXX.XXX.XXX node-1.kubernetes.local node-1 10.200.1.0/24 ``` -Now it's your turn to create a `machines.txt` file with the details for the three machines you will be using to create your Kubernetes cluster. Use the example machine database from above and add the details for your machines. +Now it is your turn to create a `machines.txt` file with the details for the three machines you will be using to create your Kubernetes cluster. Use the example machine database from above and add the details for your machines. ## Configuring SSH Access -SSH will be used to configure the machines in the cluster. Verify that you have `root` SSH access to each machine listed in your machine database. You may need to enable root SSH access on each node by updating the sshd_config file and restarting the SSH server. +You will use SSH to configure the machines in the cluster. Verify that you have `root` SSH access to each machine listed in your machine database. You might need to enable root SSH access on each node by updating the `sshd_config` file and restarting the SSH server. ### Enable root SSH Access -If `root` SSH access is enabled for each of your machines you can skip this section. +If you have `root` SSH access for each of your machines you can skip this section. -By default, a new `debian` install disables SSH access for the `root` user. This is done for security reasons as the `root` user has total administrative control of unix-like systems. If a weak password is used on a machine connected to the internet, well, let's just say it's only a matter of time before your machine belongs to someone else. As mentioned earlier, we are going to enable `root` access over SSH in order to streamline the steps in this tutorial. Security is a tradeoff, and in this case, we are optimizing for convenience. Log on to each machine via SSH using your user account, then switch to the `root` user using the `su` command: +By default, a new `debian` install disables SSH access for the `root` user. This is for security reasons, as the `root` user has total administrative control of unix-like systems. If a weak password is in use on a machine connected to the internet, well, it is only a matter of time before your machine belongs to someone else. As mentioned earlier, you are going to enable `root` access over SSH to streamline the steps in this tutorial. Security is a trade-off, and in this case, you are optimizing for convenience. Log on to each machine using SSH and your user account, then switch to the `root` user with the `su` command: ```bash su - root @@ -56,7 +56,7 @@ systemctl restart sshd ### Generate and Distribute SSH Keys -In this section you will generate and distribute an SSH keypair to the `server`, `node-0`, and `node-1`, machines, which will be used to run commands on those machines throughout this tutorial. Run the following commands from the `jumpbox` machine. +Here you will generate and distribute an SSH keypair to the `server`, `node-0`, and `node-1`, machines, which you will use to run commands on those machines throughout this tutorial. Run the following commands from the `jumpbox` machine. Generate a new SSH key: @@ -64,7 +64,7 @@ Generate a new SSH key: ssh-keygen ``` -Press ENTER to accept all the default values for the prompts here: +Press ++enter++ to accept all the default values for the prompts here: ```text Generating public/private rsa key pair. @@ -83,7 +83,7 @@ while read IP FQDN HOST SUBNET; do done < machines.txt ``` -Once each key is added, verify SSH public key access is working: +Once you add each key, verify SSH public key access is working: ```bash while read IP FQDN HOST SUBNET; do @@ -99,7 +99,7 @@ x86_64 GNU/Linux ## Hostnames -In this section you will assign hostnames to the `server`, `node-0`, and `node-1` machines. The hostname will be used when executing commands from the `jumpbox` to each machine. The hostname also plays a major role within the cluster. Instead of Kubernetes clients using an IP address to issue commands to the Kubernetes API server, those clients will use the `server` hostname instead. Hostnames are also used by each worker machine, `node-0` and `node-1` when registering with a given Kubernetes cluster. +In this section you will assign hostnames to the `server`, `node-0`, and `node-1` machines. You will use the hostname when executing commands from the `jumpbox` to each machine. The hostname also plays a major role within the cluster. Instead of Kubernetes clients using an IP address to issue commands to the Kubernetes API server, those clients will use the `server` hostname instead. Hostnames are also used by each worker machine, `node-0` and `node-1` when registering with a given Kubernetes cluster. To configure the hostname for each machine, run the following commands on the `jumpbox`. @@ -114,7 +114,7 @@ while read IP FQDN HOST SUBNET; do done < machines.txt ``` -Verify the hostname is set on each machine: +Verify the hostname set up on each machine: ```bash while read IP FQDN HOST SUBNET; do @@ -130,7 +130,7 @@ node-1.kubernetes.local ## Host Lookup Table -In this section you will generate a `hosts` file which will be appended to `/etc/hosts` file on `jumpbox` and to the `/etc/hosts` files on all three cluster members used for this tutorial. This will allow each machine to be reachable using a hostname such as `server`, `node-0`, or `node-1`. +In this section you will generate a `hosts` file and append it to `/etc/hosts` file on `jumpbox` and to the `/etc/hosts` files on all three cluster members used for this tutorial. This will allow each machine to be reachable using a hostname such as `server`, `node-0`, or `node-1`. Create a new `hosts` file and add a header to identify the machines being added: @@ -172,7 +172,7 @@ Append the DNS entries from `hosts` to `/etc/hosts`: cat hosts >> /etc/hosts ``` -Verify that the `/etc/hosts` file has been updated: +Verify the updating of the `/etc/hosts` file: ```bash cat /etc/hosts @@ -188,7 +188,7 @@ XXX.XXX.XXX.XXX node-0.kubernetes.local node-0 XXX.XXX.XXX.XXX node-1.kubernetes.local node-1 ``` -At this point you should be able to SSH to each machine listed in the `machines.txt` file using a hostname. +At this point you should be able to SSH to each machine listed in the `machines.txt` file by using a hostname. ```bash for host in server node-0 node-1 @@ -216,6 +216,6 @@ while read IP FQDN HOST SUBNET; do done < machines.txt ``` -At this point hostnames can be used when connecting to machines from your `jumpbox` machine, or any of the three machines in the Kubernetes cluster. Instead of using IP addresses you can now connect to machines using a hostname such as `server`, `node-0`, or `node-1`. +At this point you can use hostnames when connecting to machines from your `jumpbox` machine, or any of the three machines in the Kubernetes cluster. Instead of using IP addresses you can now connect to machines by using a hostname such as `server`, `node-0`, or `node-1`. Next: [Provisioning a CA and Generating TLS Certificates](04-certificate-authority.md) diff --git a/docs/labs/kubernetes-the-hard-way/images/cc_by_sa.png b/docs/labs/kubernetes-the-hard-way/images/cc_by_sa.png new file mode 100644 index 000000000..80ff9f371 Binary files /dev/null and b/docs/labs/kubernetes-the-hard-way/images/cc_by_sa.png differ