From 3c981e4622fe132faa216558c2fd1c263605716d Mon Sep 17 00:00:00 2001
From: KoryKessel-Mirantis <kkessel@mirantis.com>
Date: Wed, 29 May 2024 01:06:32 +0200
Subject: [PATCH 01/17] Initial edits to Setup content.

---
 content/docs/setup/README.md                  |  85 --------------
 .../getting-started/Using-the-cluster.md      |  19 +++
 .../setup/getting-started/installation.md     | 108 ++++++++++++++++++
 .../setup/getting-started/prerequisites.md    |  24 ++++
 .../setup/getting-started/uninstallation.md   |  11 ++
 content/docs/setup/install-mke4-cli.md        |  11 ++
 6 files changed, 173 insertions(+), 85 deletions(-)
 delete mode 100644 content/docs/setup/README.md
 create mode 100644 content/docs/setup/getting-started/Using-the-cluster.md
 create mode 100644 content/docs/setup/getting-started/installation.md
 create mode 100644 content/docs/setup/getting-started/prerequisites.md
 create mode 100644 content/docs/setup/getting-started/uninstallation.md
 create mode 100644 content/docs/setup/install-mke4-cli.md

diff --git a/content/docs/setup/README.md b/content/docs/setup/README.md
deleted file mode 100644
index 95986054..00000000
--- a/content/docs/setup/README.md
+++ /dev/null
@@ -1,85 +0,0 @@
-# Install MKE 4 CLI
-
-- `mkectl` - The MKE 4 CLI tool, available to download from the
-  [Releases](https://github.com/MirantisContainers/mke/releases) page of the MKE 4 repository.
-
-`mkectl` is supposed to be a single binary capable of managing MKE 4 clusters without any additional dependencies.
-However, as of commit `e19af33`, it still requires the following tools to be installed on your system:
-
-- `kubectl` of version `1.29.0` or above ([download](https://kubernetes.io/docs/tasks/tools/#kubectl))
-- `k0sctl` of version `0.17.0` or above ([download](https://github.com/k0sproject/k0sctl/releases))
-
-# Installation via script
-
-You can use the [installation script](./install.sh) to install the following dependencies.
-- mkectl (default version: v4.0.0-alpha.0.3)
-- k0sctl (default version: 0.17.8)
-- kubectl (default version: v1.30.0)
-
-To override the default versions, you can pass the variables `K0SCTL_VERSION`,`MKECTL_VERSION`and `KUBECTL_VERSION`.
-
-> P.S. The script detects if kubectl is already installed in the system. If so, it will not overwrite it.
-
-### Usage
-
-1. Install the dependencies using the following command.
-
-   ```shell
-   sudo /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Mirantis/mke-docs/main/content/docs/setup/install.sh)"
-    ```
-
-2. The script is designed to detect the os and the underlying architecture. Based on this, it shall install the appropriate binaries `k0sctl`, `kubectl` and `mkectl` in `/usr/local/bin`.
-   > Note: Make sure /usr/local/bin is in your PATH environment variable.
-
-3. Confirm successful installations by running
-
-   a. _mkectl version command_
-
-    ```shell
-      mkectl version
-    ```
-   Output:
-   ```shell
-      Version: v4.0.0-alpha.0.3
-    ```
-   b. _k0sctl version command_
-    ```shell
-      k0sctl version
-    ```
-   Output:
-   ```shell
-      version: v0.17.8
-      commit: b061291
-    ```
-   c. _kubectl version command_
-    ```shell
-      kubectl version
-    ```
-   Output:
-   ```shell
-      Client Version: v1.30.0
-      Kustomize Version: v5.0.4-0.20230601165947-6ce0bf390ce3
-      Server Version: v1.29.3+k0s
-    ```
-
-### Debug mode
-To turn the debug mode on, run
-```shell
-sudo DEBUG=true /bin/sh -c "$(curl -fsSL https://raw.githubusercontent.com/Mirantis/mke-docs/main/content/docs/setup/install.sh)"
-```
-
-### Install different version
-To install non-default versions of mkectl, kubectl and k0sctl, you can use `MKECTL_VERSION`, `KUBECTL_VERSION` and `K0SCTL_VERSION` respectively.
-
-Example usage:
-```shell
-sudo K0SCTL_VERSION=0.17.4 /bin/sh -c "$(curl -fsSL https://raw.githubusercontent.com/Mirantis/mke-docs/main/content/docs/setup/install.sh)"
-```
-
-This shall install k0sctl version 0.17.4.
-```shell
-k0sctl version
-
-version: v0.17.4
-commit: 372a589
-```
diff --git a/content/docs/setup/getting-started/Using-the-cluster.md b/content/docs/setup/getting-started/Using-the-cluster.md
new file mode 100644
index 00000000..ac51c105
--- /dev/null
+++ b/content/docs/setup/getting-started/Using-the-cluster.md
@@ -0,0 +1,19 @@
+
+
+## Using the cluster
+
+You can use `kubectl` with the `mke` context to interact with the cluster.
+
+```text
+$ kubectl --context mke get nodes
+NAME    STATUS   ROLES           AGE   VERSION
+node1   Ready    <none>          2d    v1.29.3+k0s
+node2   Ready    control-plane   2d    v1.29.3+k0s
+```
+
+To modify the cluster configuration, edit the YAML configuration file and
+rerun the `apply` command.
+
+```shell
+mkectl apply -f mke.yaml
+```
diff --git a/content/docs/setup/getting-started/installation.md b/content/docs/setup/getting-started/installation.md
new file mode 100644
index 00000000..22c4e13e
--- /dev/null
+++ b/content/docs/setup/getting-started/installation.md
@@ -0,0 +1,108 @@
+## Installation
+
+### Init
+
+MKE 4 installation is performed through the use of a single YAML file,
+detailing the desired cluster configuration. To generate this YAML file, run
+the `mkectl init` command:
+
+```shell
+mkectl init > mke.yaml
+```
+
+In the configuration file, edit the `hosts` section to match your roster
+of nodes.
+
+> Configure the cluster nodes in advance, in accordance with
+  the [system requirements](#cluster-nodes-system-requirements).
+
+> Node provisioning is managed by the cluster administrators. You can, for
+instance, use [Terraform](https://www.terraform.io/) to create the nodes in a
+cloud provider. [Example Terraform configuration](k0s-in-aws/README.md).
+
+You must provide SSH information for each cluster node, as well as the role of
+the node:
+
+<dl>
+  <dt><strong>controller+worker</strong></dt>
+  <dd>A manager node that runs both control plane and data plane components.</dd>
+  <dt><strong>worker</strong></dt>
+  <dd>A worker node that runs the data plane components.</dd>
+  <dt><strong>single</strong></dt>
+  <dd>A special role, for use when the cluster consists of a single node.</dd>
+</dl>
+
+<details>
+<summary>Example: A ready-to-deploy MKE 4 config file</summary>
+
+```yaml
+hosts:
+  - ssh:
+      address: 1.1.1.1  # external IP of the first node
+      keyPath: /path/to/ssh/key.pem
+      port: 22
+      user: username
+    role: controller+worker
+  - ssh:
+      address: 2.2.2.2  # external IP of the second node
+      keyPath: /path/to/ssh/key.pem
+      port: 22
+      user: username
+    role: worker
+hardening:
+  enabled: true
+authentication:
+  enabled: true
+  saml:
+    enabled: false
+  oidc:
+    enabled: false
+  ldap:
+    enabled: false
+backup:
+  enabled: true
+  storage_provider:
+    type: InCluster
+    in_cluster_options:
+      exposed: true
+tracking:
+  enabled: true
+trust:
+  enabled: true
+logging:
+  enabled: true
+audit:
+  enabled: true
+license:
+  refresh: true
+apiServer:
+  sans: ["mydomain.com"]
+ingressController:
+  enabled: false
+monitoring:
+  enableGrafana: true
+  enableOpscare: false
+```
+
+</details>
+
+### Install
+
+To perform the installation, run the `apply` command with the generated YAML
+configuration file:
+
+```shell
+mkectl apply -f mke.yaml
+```
+
+### Known limitations
+
+- `mkectl apply` configures `mke` context in the default kubeconfig file that
+is normally located at `~/.kube/config`. If the default kubeconfig is changed,
+and the `mke` context becomes invalid or unavailable, `mkectl` will be unable
+to manage the cluster until the kubeconfig is restored.
+- You must not attempt to create a new cluster until you have first deleted the
+existing cluster. If you do make such an attempt, even through the use of a
+different config file, you will permanently lose access to the first cluster
+through `mkectl`. For information on how to delete a cluster, refer to
+[Uninstallation](#uninstallation).
diff --git a/content/docs/setup/getting-started/prerequisites.md b/content/docs/setup/getting-started/prerequisites.md
new file mode 100644
index 00000000..9f0f83e9
--- /dev/null
+++ b/content/docs/setup/getting-started/prerequisites.md
@@ -0,0 +1,24 @@
+## Prerequisites
+
+### System requirements for cluster nodes
+
+MKE 4 uses [k0s](https://k0sproject.io/) as the underlying Kubernetes
+distribution. To learn the k0s hardware requirements, refer to the [k0s
+documentation](https://docs.k0sproject.io/v1.29.4+k0s.0/system-requirements/).
+
+### Known limitations
+
+#### Operating systems
+
+Currently, MKE 4 is only certified for use on the Ubuntu 20.04 Linux
+distribution.
+
+Windows nodes are **not supported**.
+
+#### Architecture
+
+MKE 4 only supports `amd64` architecture.
+
+#### CNI
+
+`calico` is the only CNI plugin that MKE 4 supports.
diff --git a/content/docs/setup/getting-started/uninstallation.md b/content/docs/setup/getting-started/uninstallation.md
new file mode 100644
index 00000000..4c6d4f15
--- /dev/null
+++ b/content/docs/setup/getting-started/uninstallation.md
@@ -0,0 +1,11 @@
+## Uninstallation
+
+Run the `reset` command to destroy the cluster that was previously created with
+the `apply` command.
+
+```shell
+mkectl reset -f mke.yaml
+```
+
+You will be prompted to confirm the deletion of the cluster. To
+skip this step, use the `--force` flag with the `reset` command.
diff --git a/content/docs/setup/install-mke4-cli.md b/content/docs/setup/install-mke4-cli.md
new file mode 100644
index 00000000..beb5f7d0
--- /dev/null
+++ b/content/docs/setup/install-mke4-cli.md
@@ -0,0 +1,11 @@
+# Install MKE 4 CLI
+
+You can download `mkectl`, the MKE CLI tool, from the MKE 4 repository
+[Releases](https://github.com/MirantisContainers/mke/releases) page. Envisioned
+as a single binary, capable of managing MKE 4 clusters without any
+additional dependencies, as of commit `e19af33` the MKE CLI still requires that
+you have the following tools installed on your system:
+
+- `kubectl`, version `1.29.0` or later ([download](https://kubernetes.io/docs/tasks/tools/#kubectl))
+- `k0sctl`, version `0.17.0` or later ([download](https://github.com/k0sproject/k0sctl/releases))
+

From c9b2db0df3b72ded2a861470bc112fef7d1333c4 Mon Sep 17 00:00:00 2001
From: KoryKessel-Mirantis <kkessel@mirantis.com>
Date: Wed, 29 May 2024 15:52:09 +0200
Subject: [PATCH 02/17] Addition of k0s example and upgrade content edits.

---
 content/docs/setup/getting-started/README.md  | 148 ------------------
 .../setup/getting-started/installation.md     |   6 +-
 .../getting-started/k0s-in-aws/README.md      |  75 ---------
 .../k0s-in-aws/terraform-scenario.md          |  84 ++++++++++
 .../k0s-in-aws/terraform/variables.tf         |   2 +-
 .../docs/setup/upgrade-from-mke-3/README.md   | 106 -------------
 .../upgrade-from-mke-3/perform-upgrade.md     |  45 ++++++
 .../upgrade-prerequisites.md                  |  57 +++++++
 8 files changed, 190 insertions(+), 333 deletions(-)
 delete mode 100644 content/docs/setup/getting-started/README.md
 delete mode 100644 content/docs/setup/getting-started/k0s-in-aws/README.md
 create mode 100644 content/docs/setup/getting-started/k0s-in-aws/terraform-scenario.md
 delete mode 100644 content/docs/setup/upgrade-from-mke-3/README.md
 create mode 100644 content/docs/setup/upgrade-from-mke-3/perform-upgrade.md
 create mode 100644 content/docs/setup/upgrade-from-mke-3/upgrade-prerequisites.md

diff --git a/content/docs/setup/getting-started/README.md b/content/docs/setup/getting-started/README.md
deleted file mode 100644
index 11a35d2a..00000000
--- a/content/docs/setup/getting-started/README.md
+++ /dev/null
@@ -1,148 +0,0 @@
-# Getting started
-
-## Pre-requisites
-
-### Cluster nodes system requirements
-
-MKE 4 uses [k0s](https://k0sproject.io/) as the underlying Kubernetes distribution. 
-Please refer to the [k0s documentation](https://docs.k0sproject.io/v1.29.4+k0s.0/system-requirements/) for the hardware requirements.
-
-### Known limitations
-
-#### Operating systems
-
-Currently, MKE 4 is only tested on Ubuntu 20.04. Stable work on other Linux distributions is not guaranteed.
-
-Windows nodes are currently **not supported**.
-
-#### Architecture
-
-MKE 4 only supports `amd64` architecture.
-
-#### CNI
-
-MKE 4 only supports `calico` as the CNI plugin.
-
-## Installation
-
-### Init
-
-To install MKE 4, all is needed is a single YAML file that describes the desired cluster configuration. 
-This file can be generated using the `mkectl init` command:
-
-```shell
-mkectl init > mke.yaml
-```
-
-In the generated config file, the `hosts` section needs to be edited to match the list of nodes 
-that will be used in the cluster.
-
-> The nodes are expected to be created in advance and configured with accordance to the
-[system requirements](#cluster-nodes-system-requirements). It's up to the cluster administrators to decide how
-to provision the nodes. For instance, [Terraform](https://www.terraform.io/) can be used to create the nodes 
-in a cloud provider. Refer to [the example of a possible terraform configuration](k0s-in-aws/README.md).
-
-For each cluster node, SSH information and the role of the node need to be provided.
-The roles can be:
-- `controller+worker` - a manager node that runs both control plane and data plane components
-- `worker` - a worker node that runs the data plane components
-- `single` - a special role for the case when the cluster consists of a single node
-
-<details>
-<summary>Example of ready-to-deploy MKE 4 config file</summary>
-
-```yaml
-hosts:
-  - ssh:
-      address: 1.1.1.1  # external IP of the first node
-      keyPath: /path/to/ssh/key.pem
-      port: 22
-      user: username
-    role: controller+worker
-  - ssh:
-      address: 2.2.2.2  # external IP of the second node
-      keyPath: /path/to/ssh/key.pem
-      port: 22
-      user: username
-    role: worker
-hardening:
-  enabled: true
-authentication:
-  enabled: true
-  saml:
-    enabled: false
-  oidc:
-    enabled: false
-  ldap:
-    enabled: false
-backup:
-  enabled: true
-  storage_provider:
-    type: InCluster
-    in_cluster_options:
-      exposed: true
-tracking:
-  enabled: true
-trust:
-  enabled: true
-logging:
-  enabled: true
-audit:
-  enabled: true
-license:
-  refresh: true
-apiServer:
-  sans: ["mydomain.com"]
-ingressController:
-  enabled: false
-monitoring:
-  enableGrafana: true
-  enableOpscare: false
-```
-
-</details>
-
-### Install
-
-To perform the installation, simply run the `apply` command with the generated config file:
-
-```shell
-mkectl apply -f mke.yaml
-```
-
-### Known limitations
-
-- `mkectl apply` configures `mke` context in the default kubeconfig file normally located at `~/.kube/config`.
-If the default kubeconfig is changed, and the `mke` context becomes invalid or unavailable 
-`mkectl` will not be able to manage the cluster until the kubeconfig is restored.
-- After the cluster is created, you must not attempt creating another cluster until you delete the existing one. 
-For deleting the cluster, refer to the [Uninstallation](#uninstallation) section. If you try to create a new cluster,
-even with a different config file, `mkectl` will permanently lose the access to the first cluster.
-
-## Using the cluster
-
-You can use `kubectl` with the `mke` context to interact with the cluster.
-
-```text
-$ kubectl --context mke get nodes
-NAME    STATUS   ROLES           AGE   VERSION
-node1   Ready    <none>          2d    v1.29.3+k0s
-node2   Ready    control-plane   2d    v1.29.3+k0s
-```
-
-To modify the cluster configuration, edit the `mke.yaml` file and run the `apply` command again.
-
-```shell
-mkectl apply -f mke.yaml
-```
-
-## Uninstallation
-
-The reset command will destroy the cluster that was previously created by the `apply` command.
-
-```shell
-mkectl reset -f mke.yaml
-```
-
-It will ask for confirmation before proceeding with the deletion. 
-Alternatively, you can use the `--force` flag to skip the confirmation.
diff --git a/content/docs/setup/getting-started/installation.md b/content/docs/setup/getting-started/installation.md
index 22c4e13e..29c6fc97 100644
--- a/content/docs/setup/getting-started/installation.md
+++ b/content/docs/setup/getting-started/installation.md
@@ -24,11 +24,11 @@ You must provide SSH information for each cluster node, as well as the role of
 the node:
 
 <dl>
-  <dt><strong>controller+worker</strong></dt>
+  <dt>controller+worker</dt>
   <dd>A manager node that runs both control plane and data plane components.</dd>
-  <dt><strong>worker</strong></dt>
+  <dt>worker</dt>
   <dd>A worker node that runs the data plane components.</dd>
-  <dt><strong>single</strong></dt>
+  <dt>single</dt>
   <dd>A special role, for use when the cluster consists of a single node.</dd>
 </dl>
 
diff --git a/content/docs/setup/getting-started/k0s-in-aws/README.md b/content/docs/setup/getting-started/k0s-in-aws/README.md
deleted file mode 100644
index 7c1b8118..00000000
--- a/content/docs/setup/getting-started/k0s-in-aws/README.md
+++ /dev/null
@@ -1,75 +0,0 @@
-This example shows how to create a k0s cluster in AWS using Terraform and then install MKE-4 on it.
-
-#### Prerequisites
-
-Along with `mkectl`, you will also need the following tools installed:
-
-* [k0sctl](https://github.com/k0sproject/k0sctl#installation) - required for installing a k0s distribution
-* [terraform](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli) - for creating VMs in AWS
-
-You will also need an AWS account and the `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN` env variables set for the AWS CLI.
-
-#### Create virtual machines on AWS
-
-Creating virtual machines on AWS can be easily done using the [example Terraform scripts](./terraform/).
-
-After copying the example Terraform folder to your local machine, you can create the VMs with the following steps:
-
-1. Create a `terraform.tfvars` file with content similar to:
-```
-cluster_name = "k0s-cluster"
-controller_count = 1
-worker_count = 1
-cluster_flavor = "m5.large"
-region = "us-east-1"
-```
-2. `terraform init`
-3. `terraform apply -auto-approve`
-4. `terraform output --raw k0s_cluster > VMs.yaml`
-
-> To get detailed information about the created VMs, use the AWS CLI:
-> ```
-> aws ec2 describe-instances --region $(grep "region" terraform.tfvars | awk -F' *= *' '{print $2}' | tr -d '"')
-> ```
-> Alternatively, for a visual overview:
-> Go to the AWS EC2 page. Select the desired region from the dropdown menu at the top-right corner.
-
-#### Install MKE4 on `k0s`
-
-1. Generate a sample mke.yaml file using the following command:
-```shell   
-mkectl init > mke.yaml
-```
-
-2. Edit the `hosts` section in `mke.yaml` using the values from the `VMs.yaml` file.
-
-The `hosts` section should look similar to:
-```yaml
-hosts:
-  - role: controller+worker
-    ssh:
-      address: 54.91.231.190
-      keyPath: <path_to_terraform_folder>/aws_private.pem
-      port: 22
-      user: ubuntu
-  - role: worker
-    ssh:
-      address: 18.206.202.16
-      keyPath: <path_to_terraform_folder>/aws_private.pem
-      port: 22
-      user: ubuntu
-```
-
-3. Create the MKE-4 cluster
-```shell
-mkectl apply -f mke.yaml
-```
-
-This shall install MKE-4 in the aws cluster.
-
-#### Cleanup
-
-Delete virtual machines by changing to the example Terraform folder and running:
-``` bash
-terraform destroy --auto-approve
-```
diff --git a/content/docs/setup/getting-started/k0s-in-aws/terraform-scenario.md b/content/docs/setup/getting-started/k0s-in-aws/terraform-scenario.md
new file mode 100644
index 00000000..8a0d295c
--- /dev/null
+++ b/content/docs/setup/getting-started/k0s-in-aws/terraform-scenario.md
@@ -0,0 +1,84 @@
+**Scenario**: Create a k0s cluster in AWS using Terraform and install MKE 4 on that cluster.
+
+### Prerequisites
+
+You must have the following componenets installed:
+
+* [mkectl](https://github.com/MirantisContainers/mke/releases)
+* [k0sctl](https://github.com/k0sproject/k0sctl#installation) (required for installing a k0s distribution)
+* [Terraform](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli)
+  (required for creating VMs in AWS)
+* AWS account
+* env variables, set for AWS CLI:
+  - `AWS_ACCESS_KEY_ID`
+  - `AWS_SECRET_ACCESS_KEY`
+  - `AWS_SESSION_TOKEN`
+
+### Create virtual machines on AWS
+
+To create virtual machines on AWS using the [example Terraform scripts](./terraform/):
+
+1. Copy the example Terraform folder to your local machine,
+
+2. Create a `terraform.tfvars` file with content similar to:
+   ```
+   cluster_name = "k0s-cluster"
+   controller_count = 1
+   worker_count = 1
+   cluster_flavor = "m5.large"
+   region = "us-east-1"
+   ```
+3. Run `terraform init`.
+4. Run `terraform apply -auto-approve`.
+5. Run `terraform output --raw k0s_cluster > VMs.yaml`.
+
+> To get detailed information on the VMs using the AWS CLI, run:
+> ```
+> aws ec2 describe-instances --region $(grep "region" terraform.tfvars | awk -F' *= *' '{print $2}' | tr -d '"')
+> ```
+> Alternatively, you can get a visual overview of the VMs at the AWS EC2 page
+> by selecting the desired region from the dropdown menu in the top-right
+> corner.
+
+### Install MKE4 on `k0s`
+
+1. Generate a sample `mke.yaml` file:
+
+   ```shell
+   mkectl init > mke.yaml
+   ```
+
+2. Edit the `hosts` section in `mke.yaml`, using the values from the `VMs.yaml`
+   file.
+
+   The `hosts` section should resemble the following:
+
+   ```yaml
+   hosts:
+     - role: controller+worker
+       ssh:
+         address: 54.91.231.190
+         keyPath: <path_to_terraform_folder>/aws_private.pem
+         port: 22
+         user: ubuntu
+     - role: worker
+       ssh:
+         address: 18.206.202.16
+         keyPath: <path_to_terraform_folder>/aws_private.pem
+         port: 22
+         user: ubuntu
+   ```
+
+3. Create the MKE 4 cluster:
+
+   ```shell
+   mkectl apply -f mke.yaml
+   ```
+
+### Cleanup
+
+To delete virtual machines, navigate to the Terraform folder and run:
+
+``` bash
+terraform destroy --auto-approve
+```
diff --git a/content/docs/setup/getting-started/k0s-in-aws/terraform/variables.tf b/content/docs/setup/getting-started/k0s-in-aws/terraform/variables.tf
index 182a5052..79df8294 100644
--- a/content/docs/setup/getting-started/k0s-in-aws/terraform/variables.tf
+++ b/content/docs/setup/getting-started/k0s-in-aws/terraform/variables.tf
@@ -20,5 +20,5 @@ variable "cluster_flavor" {
 
 variable "region" {
   type    = string
-  default = "us-east-1"  
+  default = "us-east-1"
 }
\ No newline at end of file
diff --git a/content/docs/setup/upgrade-from-mke-3/README.md b/content/docs/setup/upgrade-from-mke-3/README.md
deleted file mode 100644
index 9ce9b8b5..00000000
--- a/content/docs/setup/upgrade-from-mke-3/README.md
+++ /dev/null
@@ -1,106 +0,0 @@
-# Upgrade from MKE 3 to MKE 4
-
-This document describes how to upgrade from MKE 3 to MKE 4.
-
-## Prerequisites
-
-Before you begin the upgrade process, ensure that you have the following:
-
-- A running MKE 3.7.x cluster.
-```shell
-kubectl get nodes
-```
-```shell
-NAME                                           STATUS   ROLES    AGE     VERSION
-ip-172-31-103-202.us-west-2.compute.internal   Ready    master   7m3s    v1.27.7-mirantis-1
-ip-172-31-104-233.us-west-2.compute.internal   Ready    master   7m3s    v1.27.7-mirantis-1
-ip-172-31-191-216.us-west-2.compute.internal   Ready    <none>   6m59s   v1.27.7-mirantis-1
-ip-172-31-199-207.us-west-2.compute.internal   Ready    master   8m4s    v1.27.7-mirantis-1
-```
-- The latest `mkectl` binary installed on your local enviroment.
-```shell
-mkectl version
-```
-```shell
-Version: v0.0.5
-```
-- `k0sctl` version `0.17.4` installed on your local enviroment.
-```shell
-k0sctl version
-```
-
-```shell
-version: v0.17.4
-commit: 372a589
-```
-- Create a `hosts.yaml` file that describes information needed by `mkectl` to connect to each node via ssh. This is needed to perform an upgrade. An example file is shown below:
-
-```shell
-cat hosts.yaml
-```
-
-```shell
-hosts:
-  - address: <host1-external-ip>
-    port: <ssh-port>
-    user: <ssh-user>
-    keyPath: <path-to-ssh-key>
-  - address: <host2-external-ip>
-    port: <ssh-port>
-    user: <ssh-user>
-    keyPath: <path-to-ssh-key>
-```
-
-
-## Perform the Upgrade
-
-Users can upgrade from MKE 3 to MKE 4 using the `mkectl` tool. The `mkectl` tool automates the upgrade process by performing the following steps:
-- Perform pre upgrade checks to verify that the cluster can be upgraded.
-- Perfom pre upgrade migrations to prepare the cluster for a migration from hyperkube based MKE 3 cluster to k0s based MKE 4 cluster.
-- Migrate manager nodes to k0s.
-- Migrate worker nodes to k0s.
-- Perform post upgrade cleanup to remove MKE 3 components.
-- Output the new MKE 4 config file.
-
-To upgrade an MKE 3 cluster, run the following command:
-
-```shell
-mkectl upgrade --hosts-path <path-to-hosts-yaml> --admin-username <admin-username> --admin-password <admin-password>
-```
-
-> If you don't specify `--config-out` flag, the MKE 4 config file will be printed to the console 
-after the migration is complete. You can save this output to a file for future use with `mkectl apply`.
-<br>Alternatively, you can set `--config-out` to the path where you want to save the MKE 4 config file.
-
-- The upgrade process will take some time to complete. After the upgrade is complete, verify that the MKE 4 cluster is running:
-
-```shell
-sudo k0s kc get nodes
-```
-```shell
-NAME                                           STATUS   ROLES    AGE   VERSION
-ip-172-31-103-202.us-west-2.compute.internal   Ready    master   29m   v1.29.3+k0s
-ip-172-31-104-233.us-west-2.compute.internal   Ready    master   29m   v1.29.3+k0s
-ip-172-31-191-216.us-west-2.compute.internal   Ready    <none>   29m   v1.29.3+k0s
-ip-172-31-199-207.us-west-2.compute.internal   Ready    master   30m   v1.29.3+k0s
-```
-
-- The MKE 3 cluster will no longer be accessible via the previously created client bundle:
-```shell
-kubectl get nodes
-```
-```shell
-Error from server (Forbidden): nodes is forbidden: User "admin" cannot list resource "nodes" in API group "" at the cluster scope
-```
-
-- The docker swarm cluster will no longer be accessible:
-```shell
-docker service ls
-```
-```shell
-Error response from daemon: This node is not a swarm manager. Use "docker swarm init" or "docker swarm join" to connect this node to swarm and try again.
-```
-
-## Upgrade failures
-
-In case an upgrade fails for any reason, the `mkectl` tool automatically rolls back the upgrade process. The rollback process will restore the MKE 3 cluster to its original state.
\ No newline at end of file
diff --git a/content/docs/setup/upgrade-from-mke-3/perform-upgrade.md b/content/docs/setup/upgrade-from-mke-3/perform-upgrade.md
new file mode 100644
index 00000000..1c999fed
--- /dev/null
+++ b/content/docs/setup/upgrade-from-mke-3/perform-upgrade.md
@@ -0,0 +1,45 @@
+## Perform the Upgrade
+
+An upgrade from MKE 3 to MKE 4 consists of the following steps, all of which
+are performed through the use of the `mkectl` tool:
+- Run pre-upgrade checks, to verify the upgradability of the cluster.
+- Carry out pre-upgrade migrations, to prepare the cluster for a migration from
+  a hyperkube-based MKE 3 cluster to a k0s-based MKE 4 cluster.
+- Migrate manager nodes to k0s.
+- Migrate worker nodes to k0s.
+- Carry out post-upgrade cleanup, to remove MKE 3 components.
+- Output the new MKE 4 config file.
+
+To upgrade an MKE 3 cluster, run the following command:
+
+```shell
+mkectl upgrade --hosts-path <path-to-hosts-yaml> --admin-username <admin-username> --admin-password <admin-password>
+```
+
+> The MKE 4 config file prints to your console when the migration is
+> complete. To output the config file to a file for future use, run
+  `mkectl apply`. Alternatively, you can set the `--config-out` flag to the
+  path where you want to save the MKE 4 config file.
+
+The upgrade process requires time to complete. Once the process is complete,
+run the following command to verify that the MKE 4 cluster is operating:
+
+```shell
+sudo k0s kc get nodes
+```
+Example output:
+
+```shell
+NAME                                           STATUS   ROLES    AGE   VERSION
+ip-172-31-103-202.us-west-2.compute.internal   Ready    master   29m   v1.29.3+k0s
+ip-172-31-104-233.us-west-2.compute.internal   Ready    master   29m   v1.29.3+k0s
+ip-172-31-191-216.us-west-2.compute.internal   Ready    <none>   29m   v1.29.3+k0s
+ip-172-31-199-207.us-west-2.compute.internal   Ready    master   30m   v1.29.3+k0s
+```
+
+>The MKE 3 cluster will no longer be accessible by way of the previously
+>created client bundle. The docker swarm cluster will no longer be
+>accessible as well.
+
+In the event of an upgrade failure, the upgrade process rolls back,
+restoring the MKE 3 cluster to its original state.
\ No newline at end of file
diff --git a/content/docs/setup/upgrade-from-mke-3/upgrade-prerequisites.md b/content/docs/setup/upgrade-from-mke-3/upgrade-prerequisites.md
new file mode 100644
index 00000000..41c12c68
--- /dev/null
+++ b/content/docs/setup/upgrade-from-mke-3/upgrade-prerequisites.md
@@ -0,0 +1,57 @@
+# Upgrade from MKE 3 to MKE 4
+
+## Prerequisites
+
+Verify that you have the following components in place before you begin the upgrade process:
+
+- A running MKE 3.7.x cluster:
+
+  ```shell
+  kubectl get nodes
+  ```
+  ```shell
+  NAME                                           STATUS   ROLES    AGE     VERSION
+  ip-172-31-103-202.us-west-2.compute.internal   Ready    master   7m3s    v1.27.7-mirantis-1
+  ip-172-31-104-233.us-west-2.compute.internal   Ready    master   7m3s    v1.27.7-mirantis-1
+  ip-172-31-191-216.us-west-2.compute.internal   Ready    <none>   6m59s   v1.27.7-mirantis-1
+  ip-172-31-199-207.us-west-2.compute.internal   Ready    master   8m4s    v1.27.7-mirantis-1
+  ```
+- The latest `mkectl` binary, installed on your local enviroment:
+
+  ```shell
+  mkectl version
+  ```
+  ```shell
+  Version: v0.0.5
+  ```
+
+- `k0sctl` version `0.17.4`, installed on your local enviroment:
+
+  ```shell
+  k0sctl version
+  ```
+
+  ```shell
+  version: v0.17.4
+  commit: 372a589
+  ```
+- A `hosts.yaml` file, to provide the information required by `mkectl` to
+  connect to each node by way of SSH.
+
+  Example `hosts.yaml` file:
+
+  ```shell
+  cat hosts.yaml
+  ```
+
+  ```shell
+  hosts:
+    - address: <host1-external-ip>
+      port: <ssh-port>
+      user: <ssh-user>
+      keyPath: <path-to-ssh-key>
+    - address: <host2-external-ip>
+      port: <ssh-port>
+      user: <ssh-user>
+      keyPath: <path-to-ssh-key>
+  ```

From f5e1bcc4bb4820da60dd4458c688c4eaa8ab7168 Mon Sep 17 00:00:00 2001
From: KoryKessel-Mirantis <kkessel@mirantis.com>
Date: Wed, 29 May 2024 17:54:14 +0200
Subject: [PATCH 03/17] Fix bad links in Installation and Terraform scenario.

---
 content/docs/setup/getting-started/installation.md         | 7 ++++---
 .../setup/getting-started/k0s-in-aws/terraform-scenario.md | 3 ++-
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/content/docs/setup/getting-started/installation.md b/content/docs/setup/getting-started/installation.md
index 29c6fc97..2adc5cb3 100644
--- a/content/docs/setup/getting-started/installation.md
+++ b/content/docs/setup/getting-started/installation.md
@@ -14,11 +14,12 @@ In the configuration file, edit the `hosts` section to match your roster
 of nodes.
 
 > Configure the cluster nodes in advance, in accordance with
-  the [system requirements](#cluster-nodes-system-requirements).
+  the [system requirements](#System-requirements-for-cluster-nodes).
 
 > Node provisioning is managed by the cluster administrators. You can, for
 instance, use [Terraform](https://www.terraform.io/) to create the nodes in a
-cloud provider. [Example Terraform configuration](k0s-in-aws/README.md).
+cloud provider. [Example Terraform
+configuration](k0s-in-aws/terraform-scenario.md).
 
 You must provide SSH information for each cluster node, as well as the role of
 the node:
@@ -105,4 +106,4 @@ to manage the cluster until the kubeconfig is restored.
 existing cluster. If you do make such an attempt, even through the use of a
 different config file, you will permanently lose access to the first cluster
 through `mkectl`. For information on how to delete a cluster, refer to
-[Uninstallation](#uninstallation).
+[Uninstallation](uninstallation.md).
diff --git a/content/docs/setup/getting-started/k0s-in-aws/terraform-scenario.md b/content/docs/setup/getting-started/k0s-in-aws/terraform-scenario.md
index 8a0d295c..2c9b2935 100644
--- a/content/docs/setup/getting-started/k0s-in-aws/terraform-scenario.md
+++ b/content/docs/setup/getting-started/k0s-in-aws/terraform-scenario.md
@@ -16,7 +16,8 @@ You must have the following componenets installed:
 
 ### Create virtual machines on AWS
 
-To create virtual machines on AWS using the [example Terraform scripts](./terraform/):
+To create virtual machines on AWS using the
+[example Terraform scripts](./terraform/):
 
 1. Copy the example Terraform folder to your local machine,
 

From 8012fb3b7e74a21ddabdee79fb3d3ae0237c6ef9 Mon Sep 17 00:00:00 2001
From: KoryKessel-Mirantis <kkessel@mirantis.com>
Date: Wed, 29 May 2024 18:08:40 +0200
Subject: [PATCH 04/17] Fix url for "System requirements for cluster nodes"
 heading by changing the case of a single character.

---
 content/docs/setup/getting-started/installation.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/content/docs/setup/getting-started/installation.md b/content/docs/setup/getting-started/installation.md
index 2adc5cb3..9a1b2f8e 100644
--- a/content/docs/setup/getting-started/installation.md
+++ b/content/docs/setup/getting-started/installation.md
@@ -14,7 +14,7 @@ In the configuration file, edit the `hosts` section to match your roster
 of nodes.
 
 > Configure the cluster nodes in advance, in accordance with
-  the [system requirements](#System-requirements-for-cluster-nodes).
+  the [system requirements](#system-requirements-for-cluster-nodes).
 
 > Node provisioning is managed by the cluster administrators. You can, for
 instance, use [Terraform](https://www.terraform.io/) to create the nodes in a

From 22f09bd98dd613b8e2fabbc36248c618d7a16927 Mon Sep 17 00:00:00 2001
From: KoryKessel-Mirantis <kkessel@mirantis.com>
Date: Wed, 29 May 2024 18:15:21 +0200
Subject: [PATCH 05/17] Add md filename to the "System requirements for cluster
 nodes" link in Installation.

---
 content/docs/setup/getting-started/installation.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/content/docs/setup/getting-started/installation.md b/content/docs/setup/getting-started/installation.md
index 9a1b2f8e..6f5b5da3 100644
--- a/content/docs/setup/getting-started/installation.md
+++ b/content/docs/setup/getting-started/installation.md
@@ -13,8 +13,8 @@ mkectl init > mke.yaml
 In the configuration file, edit the `hosts` section to match your roster
 of nodes.
 
-> Configure the cluster nodes in advance, in accordance with
-  the [system requirements](#system-requirements-for-cluster-nodes).
+> Configure the cluster nodes in advance, in accordance with the
+  [system requirements](prerequisites.md#system-requirements-for-cluster-nodes).
 
 > Node provisioning is managed by the cluster administrators. You can, for
 instance, use [Terraform](https://www.terraform.io/) to create the nodes in a

From c6c2e3ae929bf91d035a1e355499083579df074c Mon Sep 17 00:00:00 2001
From: KoryKessel-Mirantis <kkessel@mirantis.com>
Date: Thu, 30 May 2024 18:16:53 +0200
Subject: [PATCH 06/17] Edit in response to suggested edit to "Using the
 cluster" content.

---
 .../getting-started/Using-the-cluster.md      | 27 ++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

diff --git a/content/docs/setup/getting-started/Using-the-cluster.md b/content/docs/setup/getting-started/Using-the-cluster.md
index ac51c105..558ee987 100644
--- a/content/docs/setup/getting-started/Using-the-cluster.md
+++ b/content/docs/setup/getting-started/Using-the-cluster.md
@@ -2,7 +2,32 @@
 
 ## Using the cluster
 
-You can use `kubectl` with the `mke` context to interact with the cluster.
+You can use `kubectl` with the `mke` context to interact with the cluster,
+though it is necessary to specify the configuration. `mkectl` outputs the
+kubeconfig of the cluster to `~/.mke/<cluster name>.kubeconfig`, from where you
+can use it to:
+
+- Set the KUBECONFIG env var to point to `~/.mke/mke.kubeconfig`
+
+  Example:
+
+  ```shell
+     `export KUBECONFIG=~/.mke/<cluster name>.kubeconfig`
+  ```
+
+- Append the contents to the default kubeconfig:
+
+  ```shell
+  `cat ~/.mke/mke.kubeconfig >> ~/.kube/config`
+  ```
+
+- Specify the config as a command argument:
+
+  ```shell
+ `kubectl --kubeconfig ~/.mke/mke.kubeconfig`
+  ```
+
+Example output:
 
 ```text
 $ kubectl --context mke get nodes

From 19db78f27c0b809cfc2c354288a420f4dea7b4ad Mon Sep 17 00:00:00 2001
From: KoryKessel-Mirantis <kkessel@mirantis.com>
Date: Thu, 6 Jun 2024 19:42:17 +0200
Subject: [PATCH 07/17] Edits based on SME reviewer comments.

---
 content/docs/reference/known-issuees.md       | 38 ++++++++
 .../getting-started/Using-the-cluster.md      |  5 +-
 .../setup/getting-started/install-mke4-cli.md | 88 +++++++++++++++++++
 .../setup/getting-started/installation.md     | 15 +++-
 .../setup/getting-started/prerequisites.md    | 13 ++-
 content/docs/setup/install-mke4-cli.md        | 11 ---
 .../upgrade-prerequisites.md                  |  2 +-
 7 files changed, 154 insertions(+), 18 deletions(-)
 create mode 100644 content/docs/reference/known-issuees.md
 create mode 100644 content/docs/setup/getting-started/install-mke4-cli.md
 delete mode 100644 content/docs/setup/install-mke4-cli.md

diff --git a/content/docs/reference/known-issuees.md b/content/docs/reference/known-issuees.md
new file mode 100644
index 00000000..1d3ae4ec
--- /dev/null
+++ b/content/docs/reference/known-issuees.md
@@ -0,0 +1,38 @@
+# Known issues
+
+MKE 4 Alpha.1 known issues with available workarounds include:
+
+## [BOP-694] MKE 3 upgrade rollback destabilizes the cluster
+
+When a rollback to MKE 3 occurs as the result of an upgrade issue, the MKE
+cluster is inaccessible through the MKE web UI address and ``ucp-auth``
+containers continually restart.
+
+**Workaround:** Uninstall MKE 3 and restore it from a backup.
+
+## [BOP-708] RBAC resource creation fails during mkectl upgrade when OIDC enabled
+
+During a mkectl upgrade from MKE 3, RBAC resource creation fails when OIDC is
+enabled.
+
+**Workaround:**
+
+1. Copy the MKE 4 config that prints at the end of migration.
+
+   Example:
+
+   ```
+   INF Below is your new MKE 4 config. Save it to a file and use it to configure the MKE 4 cluster with mkectl apply:
+   ```
+
+2. Update the ``authentication.oidc.clientSecret`` field to the secret field
+   from your identity provider.
+
+3. Apply the updated MKE 4 config.
+
+## [BOP-686] In MKE 3 upgrade, kubectl commands return "No agent available"
+
+Following an upgrade from MKE3, kubectl commands such as `exec` and `logs`
+return ``No agent available``.
+
+**Workaround:**
diff --git a/content/docs/setup/getting-started/Using-the-cluster.md b/content/docs/setup/getting-started/Using-the-cluster.md
index 558ee987..62a500e3 100644
--- a/content/docs/setup/getting-started/Using-the-cluster.md
+++ b/content/docs/setup/getting-started/Using-the-cluster.md
@@ -4,8 +4,9 @@
 
 You can use `kubectl` with the `mke` context to interact with the cluster,
 though it is necessary to specify the configuration. `mkectl` outputs the
-kubeconfig of the cluster to `~/.mke/<cluster name>.kubeconfig`, from where you
-can use it to:
+kubeconfig of the cluster to `~/mke/.mke.kubeconfig`.
+
+You can apply ``.mke.kubeconfig`` using any one of the following methods:
 
 - Set the KUBECONFIG env var to point to `~/.mke/mke.kubeconfig`
 
diff --git a/content/docs/setup/getting-started/install-mke4-cli.md b/content/docs/setup/getting-started/install-mke4-cli.md
new file mode 100644
index 00000000..d3e8c2cf
--- /dev/null
+++ b/content/docs/setup/getting-started/install-mke4-cli.md
@@ -0,0 +1,88 @@
+# Install the MKE 4 CLI
+
+You can download `mkectl`, the MKE CLI tool, from the MKE 4 repository
+[Releases](https://github.com/MirantisContainers/mke/releases) page. Envisioned
+as a single binary, capable of managing MKE 4 clusters without any
+additional dependencies, as of `MKE 4.0.0-alpha.1.0` the MKE CLI still requires
+that you have the following tools installed on your system:
+
+- `kubectl`, version `1.29.0` or later ([download](https://kubernetes.io/docs/tasks/tools/#kubectl))
+- `k0sctl`, version `0.17.0` or later
+  ([download](https://github.com/k0sproject/k0sctl/releases))
+
+## Install using a script
+
+You can use the [install.sh](./install.sh) script to install the following
+dependencies:
+
+- `mkectl` (default version: v4.0.0-alpha.0.3)
+- `k0sctl` (default version: 0.17.8)
+- `kubectl` (default version: v1.30.0)
+
+To override the default versions, pass the variables `K0SCTL_VERSION`,`MKECTL_VERSION`and `KUBECTL_VERSION`.
+
+>The `install.sh` script detects whether kubectl is already installed on your
+>system and will not overwrite it. It also detects the operating system and the
+>underlying architecture, based on which it will install the `k0sctl`, `kubectl`
+ and `mkectl` binaries in `/usr/local/bin`. Thus, you must ensure that
+` /usr/local/bin` is in your PATH environment variable.
+
+1. Install the dependencies:
+
+   ```shell
+   sudo /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Mirantis/mke-docs/main/content/docs/setup/install.sh)"
+    ```
+3. Confirm the installations:
+
+   1. To confirm `mkectl`, run:
+
+      ```shell
+        mkectl version
+      ```
+      Expected output:
+      ```shell
+         Version: v4.0.0-alpha.0.3
+       ```
+   2. To confirm `k0sctl`, run:
+       ```shell
+         k0sctl version
+       ```
+      Expected output:
+      ```shell
+         version: v0.17.8
+         commit: b061291
+       ```
+   3. To confirm kubectl, run:
+       ```shell
+         kubectl version
+       ```
+      Expected output:
+      ```shell
+         Client Version: v1.30.0
+         Kustomize Version: v5.0.4-0.20230601165947-6ce0bf390ce3
+         Server Version: v1.29.3+k0s
+       ```
+
+### Start Debug mode
+To turn the debug mode on, run:
+```shell
+sudo DEBUG=true /bin/sh -c "$(curl -fsSL https://raw.githubusercontent.com/Mirantis/mke-docs/main/content/docs/setup/install.sh)"
+```
+
+### Install different dependency versions
+
+You can use the `MKECTL_VERSION`, `KUBECTL_VERSION` and `K0SCTL_VERSION`
+variables to install non-default versions of `mkectl`, `kubectl` and `k0sctl`.
+
+Example:
+```shell
+sudo K0SCTL_VERSION=0.17.4 /bin/sh -c "$(curl -fsSL https://raw.githubusercontent.com/Mirantis/mke-docs/main/content/docs/setup/install.sh)"
+```
+
+Example output:
+```shell
+k0sctl version
+
+version: v0.17.4
+commit: 372a589
+```
diff --git a/content/docs/setup/getting-started/installation.md b/content/docs/setup/getting-started/installation.md
index 6f5b5da3..c59b4472 100644
--- a/content/docs/setup/getting-started/installation.md
+++ b/content/docs/setup/getting-started/installation.md
@@ -1,5 +1,15 @@
 ## Installation
 
+### Dependencies
+
+A number of tools must be installed on your system before you can install MKE
+4:
+* mkectl
+* k0sctl
+* kubectl
+
+Refer to [Install the MKE 4 CLI](install-mke4-cli) for detailed information.
+
 ### Init
 
 MKE 4 installation is performed through the use of a single YAML file,
@@ -14,8 +24,9 @@ In the configuration file, edit the `hosts` section to match your roster
 of nodes.
 
 > Configure the cluster nodes in advance, in accordance with the
-  [system requirements](prerequisites.md#system-requirements-for-cluster-nodes).
-
+  [system
+  requirements](prerequisites.md#system-requirements-for-cluster-nodes).
+>
 > Node provisioning is managed by the cluster administrators. You can, for
 instance, use [Terraform](https://www.terraform.io/) to create the nodes in a
 cloud provider. [Example Terraform
diff --git a/content/docs/setup/getting-started/prerequisites.md b/content/docs/setup/getting-started/prerequisites.md
index 9f0f83e9..8cecda23 100644
--- a/content/docs/setup/getting-started/prerequisites.md
+++ b/content/docs/setup/getting-started/prerequisites.md
@@ -1,5 +1,8 @@
 ## Prerequisites
 
+>The prerequisites detailed herein apply only to the Alpha 1.0
+>pre-release version of MKE 4.
+
 ### System requirements for cluster nodes
 
 MKE 4 uses [k0s](https://k0sproject.io/) as the underlying Kubernetes
@@ -10,8 +13,10 @@ documentation](https://docs.k0sproject.io/v1.29.4+k0s.0/system-requirements/).
 
 #### Operating systems
 
-Currently, MKE 4 is only certified for use on the Ubuntu 20.04 Linux
-distribution.
+Currently, MKE 4 is only certified for use on the following distributions:
+
+* Ubuntu 22.04 Linux
+* Ubuntu 20.04 Linux
 
 Windows nodes are **not supported**.
 
@@ -22,3 +27,7 @@ MKE 4 only supports `amd64` architecture.
 #### CNI
 
 `calico` is the only CNI plugin that MKE 4 supports.
+
+#### mkectl
+
+`mkectl`, the [MKE CLI tool](install-mke4-cli), must be installed prior to MKE 4 installation.
diff --git a/content/docs/setup/install-mke4-cli.md b/content/docs/setup/install-mke4-cli.md
deleted file mode 100644
index beb5f7d0..00000000
--- a/content/docs/setup/install-mke4-cli.md
+++ /dev/null
@@ -1,11 +0,0 @@
-# Install MKE 4 CLI
-
-You can download `mkectl`, the MKE CLI tool, from the MKE 4 repository
-[Releases](https://github.com/MirantisContainers/mke/releases) page. Envisioned
-as a single binary, capable of managing MKE 4 clusters without any
-additional dependencies, as of commit `e19af33` the MKE CLI still requires that
-you have the following tools installed on your system:
-
-- `kubectl`, version `1.29.0` or later ([download](https://kubernetes.io/docs/tasks/tools/#kubectl))
-- `k0sctl`, version `0.17.0` or later ([download](https://github.com/k0sproject/k0sctl/releases))
-
diff --git a/content/docs/setup/upgrade-from-mke-3/upgrade-prerequisites.md b/content/docs/setup/upgrade-from-mke-3/upgrade-prerequisites.md
index 41c12c68..6f9a99a8 100644
--- a/content/docs/setup/upgrade-from-mke-3/upgrade-prerequisites.md
+++ b/content/docs/setup/upgrade-from-mke-3/upgrade-prerequisites.md
@@ -22,7 +22,7 @@ Verify that you have the following components in place before you begin the upgr
   mkectl version
   ```
   ```shell
-  Version: v0.0.5
+  Version: v4.0.0-alpha.1.0
   ```
 
 - `k0sctl` version `0.17.4`, installed on your local enviroment:

From ccba35cc2a181666adb44cb5dbd6ab75c3cda1a7 Mon Sep 17 00:00:00 2001
From: KoryKessel-Mirantis <kkessel@mirantis.com>
Date: Sat, 8 Jun 2024 00:27:05 +0200
Subject: [PATCH 08/17] Remove Known issues topic from PR.

---
 content/docs/reference/known-issuees.md | 38 -------------------------
 1 file changed, 38 deletions(-)
 delete mode 100644 content/docs/reference/known-issuees.md

diff --git a/content/docs/reference/known-issuees.md b/content/docs/reference/known-issuees.md
deleted file mode 100644
index 1d3ae4ec..00000000
--- a/content/docs/reference/known-issuees.md
+++ /dev/null
@@ -1,38 +0,0 @@
-# Known issues
-
-MKE 4 Alpha.1 known issues with available workarounds include:
-
-## [BOP-694] MKE 3 upgrade rollback destabilizes the cluster
-
-When a rollback to MKE 3 occurs as the result of an upgrade issue, the MKE
-cluster is inaccessible through the MKE web UI address and ``ucp-auth``
-containers continually restart.
-
-**Workaround:** Uninstall MKE 3 and restore it from a backup.
-
-## [BOP-708] RBAC resource creation fails during mkectl upgrade when OIDC enabled
-
-During a mkectl upgrade from MKE 3, RBAC resource creation fails when OIDC is
-enabled.
-
-**Workaround:**
-
-1. Copy the MKE 4 config that prints at the end of migration.
-
-   Example:
-
-   ```
-   INF Below is your new MKE 4 config. Save it to a file and use it to configure the MKE 4 cluster with mkectl apply:
-   ```
-
-2. Update the ``authentication.oidc.clientSecret`` field to the secret field
-   from your identity provider.
-
-3. Apply the updated MKE 4 config.
-
-## [BOP-686] In MKE 3 upgrade, kubectl commands return "No agent available"
-
-Following an upgrade from MKE3, kubectl commands such as `exec` and `logs`
-return ``No agent available``.
-
-**Workaround:**

From 77cfadfc25c327a99590195cccbcf4ce884e9317 Mon Sep 17 00:00:00 2001
From: KoryKessel-Mirantis <kkessel@mirantis.com>
Date: Sat, 8 Jun 2024 00:50:36 +0200
Subject: [PATCH 09/17] Edits made in reference to comments form RyanZ and
 SakshiS.

---
 content/docs/setup/getting-started/install-mke4-cli.md    | 8 ++++----
 .../getting-started/k0s-in-aws/terraform-scenario.md      | 4 +---
 2 files changed, 5 insertions(+), 7 deletions(-)

diff --git a/content/docs/setup/getting-started/install-mke4-cli.md b/content/docs/setup/getting-started/install-mke4-cli.md
index d3e8c2cf..882a0c38 100644
--- a/content/docs/setup/getting-started/install-mke4-cli.md
+++ b/content/docs/setup/getting-started/install-mke4-cli.md
@@ -1,8 +1,8 @@
 # Install the MKE 4 CLI
 
-You can download `mkectl`, the MKE CLI tool, from the MKE 4 repository
-[Releases](https://github.com/MirantisContainers/mke/releases) page. Envisioned
-as a single binary, capable of managing MKE 4 clusters without any
+You can download `mkectl`, the MKE CLI tool, from the [S3
+bucket](https://s3.us-east-2.amazonaws.com/packages-stage-mirantis.com/v4.0.0-alpha1.0).
+Envisioned as a single binary, capable of managing MKE 4 clusters without any
 additional dependencies, as of `MKE 4.0.0-alpha.1.0` the MKE CLI still requires
 that you have the following tools installed on your system:
 
@@ -41,7 +41,7 @@ To override the default versions, pass the variables `K0SCTL_VERSION`,`MKECTL_VE
       ```
       Expected output:
       ```shell
-         Version: v4.0.0-alpha.0.3
+         Version: v4.0.0-alpha.1.0
        ```
    2. To confirm `k0sctl`, run:
        ```shell
diff --git a/content/docs/setup/getting-started/k0s-in-aws/terraform-scenario.md b/content/docs/setup/getting-started/k0s-in-aws/terraform-scenario.md
index 2c9b2935..503f91b6 100644
--- a/content/docs/setup/getting-started/k0s-in-aws/terraform-scenario.md
+++ b/content/docs/setup/getting-started/k0s-in-aws/terraform-scenario.md
@@ -2,10 +2,8 @@
 
 ### Prerequisites
 
-You must have the following componenets installed:
+In addition to the MKE 4 [dependencies](../installation.md#dependencies), you must have the following componenets installed:
 
-* [mkectl](https://github.com/MirantisContainers/mke/releases)
-* [k0sctl](https://github.com/k0sproject/k0sctl#installation) (required for installing a k0s distribution)
 * [Terraform](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli)
   (required for creating VMs in AWS)
 * AWS account

From 5c3583527264a7310f28f12a7f3861b94fb3440e Mon Sep 17 00:00:00 2001
From: KoryKessel-Mirantis <kkessel@mirantis.com>
Date: Mon, 10 Jun 2024 19:34:43 +0200
Subject: [PATCH 10/17] Edits in response to comments from SSharma and NNiesen,
 link fixes.

---
 .../getting-started/{installation.md => create-a-cluster.md}  | 4 ++--
 content/docs/setup/getting-started/install-mke4-cli.md        | 2 +-
 content/docs/setup/getting-started/prerequisites.md           | 3 ++-
 3 files changed, 5 insertions(+), 4 deletions(-)
 rename content/docs/setup/getting-started/{installation.md => create-a-cluster.md} (96%)

diff --git a/content/docs/setup/getting-started/installation.md b/content/docs/setup/getting-started/create-a-cluster.md
similarity index 96%
rename from content/docs/setup/getting-started/installation.md
rename to content/docs/setup/getting-started/create-a-cluster.md
index c59b4472..ef1ef41d 100644
--- a/content/docs/setup/getting-started/installation.md
+++ b/content/docs/setup/getting-started/create-a-cluster.md
@@ -1,4 +1,4 @@
-## Installation
+## Create a cluster
 
 ### Dependencies
 
@@ -8,7 +8,7 @@ A number of tools must be installed on your system before you can install MKE
 * k0sctl
 * kubectl
 
-Refer to [Install the MKE 4 CLI](install-mke4-cli) for detailed information.
+Refer to [Install the MKE 4 CLI](install-mke4-cli.md) for detailed information.
 
 ### Init
 
diff --git a/content/docs/setup/getting-started/install-mke4-cli.md b/content/docs/setup/getting-started/install-mke4-cli.md
index 882a0c38..35497147 100644
--- a/content/docs/setup/getting-started/install-mke4-cli.md
+++ b/content/docs/setup/getting-started/install-mke4-cli.md
@@ -12,7 +12,7 @@ that you have the following tools installed on your system:
 
 ## Install using a script
 
-You can use the [install.sh](./install.sh) script to install the following
+You can use the [install.sh](../install.sh) script to install the following
 dependencies:
 
 - `mkectl` (default version: v4.0.0-alpha.0.3)
diff --git a/content/docs/setup/getting-started/prerequisites.md b/content/docs/setup/getting-started/prerequisites.md
index 8cecda23..32043ed5 100644
--- a/content/docs/setup/getting-started/prerequisites.md
+++ b/content/docs/setup/getting-started/prerequisites.md
@@ -30,4 +30,5 @@ MKE 4 only supports `amd64` architecture.
 
 #### mkectl
 
-`mkectl`, the [MKE CLI tool](install-mke4-cli), must be installed prior to MKE 4 installation.
+`mkectl`, the [MKE CLI tool](install-mke4-cli.md), must be installed prior to
+MKE 4 installation.

From a94a19db8b87e322f176a9f5e5b26ec33f337258 Mon Sep 17 00:00:00 2001
From: KoryKessel-Mirantis <kkessel@mirantis.com>
Date: Mon, 10 Jun 2024 19:38:41 +0200
Subject: [PATCH 11/17] Fix to link in terraform-scenario, caused by filename
 change in previous commit.

---
 .../setup/getting-started/k0s-in-aws/terraform-scenario.md     | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/content/docs/setup/getting-started/k0s-in-aws/terraform-scenario.md b/content/docs/setup/getting-started/k0s-in-aws/terraform-scenario.md
index 503f91b6..72898eba 100644
--- a/content/docs/setup/getting-started/k0s-in-aws/terraform-scenario.md
+++ b/content/docs/setup/getting-started/k0s-in-aws/terraform-scenario.md
@@ -2,7 +2,8 @@
 
 ### Prerequisites
 
-In addition to the MKE 4 [dependencies](../installation.md#dependencies), you must have the following componenets installed:
+In addition to the MKE 4 [dependencies](../create-a-cluster.md#dependencies),
+you must have the following componenets installed:
 
 * [Terraform](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli)
   (required for creating VMs in AWS)

From 88bc9a9635bae89c6e6660c387ab3193860018ec Mon Sep 17 00:00:00 2001
From: KoryKessel-Mirantis <kkessel@mirantis.com>
Date: Mon, 10 Jun 2024 20:02:07 +0200
Subject: [PATCH 12/17] Insertion of mkectl download links

---
 .../docs/setup/getting-started/install-mke4-cli.md    | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/content/docs/setup/getting-started/install-mke4-cli.md b/content/docs/setup/getting-started/install-mke4-cli.md
index 35497147..481d9a6a 100644
--- a/content/docs/setup/getting-started/install-mke4-cli.md
+++ b/content/docs/setup/getting-started/install-mke4-cli.md
@@ -1,7 +1,14 @@
 # Install the MKE 4 CLI
 
-You can download `mkectl`, the MKE CLI tool, from the [S3
-bucket](https://s3.us-east-2.amazonaws.com/packages-stage-mirantis.com/v4.0.0-alpha1.0).
+You can download `mkectl`, the MKE CLI tool, from the S3 bucket:
+
+- [Linux arm64](https://s3.us-east-2.amazonaws.com/packages-stage-mirantis.com/v4.0.0-alpha1.0/mkectl_linux_arm64.tar.gz)
+- [Linux x86 64](https://s3.us-east-2.amazonaws.com/packages-stage-mirantis.com/v4.0.0-alpha1.0/mkectl_linux_x86_64.tar.gz)
+- [Darwin arm64](https://s3.us-east-2.amazonaws.com/packages-stage-mirantis.com/v4.0.0-alpha1.0/mkectl_darwin_arm64.tar.gz)
+- [Darwin x86 64](https://s3.us-east-2.amazonaws.com/packages-stage-mirantis.com/v4.0.0-alpha1.0/mkectl_darwin_x86_64.tar.gz)
+- [Windows arm64](https://s3.us-east-2.amazonaws.com/packages-stage-mirantis.com/v4.0.0-alpha1.0/mkectl_windows_arm64.zip)
+- [Windows x86 64](https://s3.us-east-2.amazonaws.com/packages-stage-mirantis.com/v4.0.0-alpha1.0/mkectl_windows_x86_64.zip)
+
 Envisioned as a single binary, capable of managing MKE 4 clusters without any
 additional dependencies, as of `MKE 4.0.0-alpha.1.0` the MKE CLI still requires
 that you have the following tools installed on your system:

From 8e7e2a51eb7a9f50e49ea07712ed08f8ec6c0f6d Mon Sep 17 00:00:00 2001
From: KoryKessel-Mirantis <kkessel@mirantis.com>
Date: Mon, 10 Jun 2024 20:04:07 +0200
Subject: [PATCH 13/17] Added word 'image' to the mkectl download link text.

---
 .../docs/setup/getting-started/install-mke4-cli.md   | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/content/docs/setup/getting-started/install-mke4-cli.md b/content/docs/setup/getting-started/install-mke4-cli.md
index 481d9a6a..5ab15707 100644
--- a/content/docs/setup/getting-started/install-mke4-cli.md
+++ b/content/docs/setup/getting-started/install-mke4-cli.md
@@ -2,12 +2,12 @@
 
 You can download `mkectl`, the MKE CLI tool, from the S3 bucket:
 
-- [Linux arm64](https://s3.us-east-2.amazonaws.com/packages-stage-mirantis.com/v4.0.0-alpha1.0/mkectl_linux_arm64.tar.gz)
-- [Linux x86 64](https://s3.us-east-2.amazonaws.com/packages-stage-mirantis.com/v4.0.0-alpha1.0/mkectl_linux_x86_64.tar.gz)
-- [Darwin arm64](https://s3.us-east-2.amazonaws.com/packages-stage-mirantis.com/v4.0.0-alpha1.0/mkectl_darwin_arm64.tar.gz)
-- [Darwin x86 64](https://s3.us-east-2.amazonaws.com/packages-stage-mirantis.com/v4.0.0-alpha1.0/mkectl_darwin_x86_64.tar.gz)
-- [Windows arm64](https://s3.us-east-2.amazonaws.com/packages-stage-mirantis.com/v4.0.0-alpha1.0/mkectl_windows_arm64.zip)
-- [Windows x86 64](https://s3.us-east-2.amazonaws.com/packages-stage-mirantis.com/v4.0.0-alpha1.0/mkectl_windows_x86_64.zip)
+- [Linux arm64 image](https://s3.us-east-2.amazonaws.com/packages-stage-mirantis.com/v4.0.0-alpha1.0/mkectl_linux_arm64.tar.gz)
+- [Linux x86 64 image](https://s3.us-east-2.amazonaws.com/packages-stage-mirantis.com/v4.0.0-alpha1.0/mkectl_linux_x86_64.tar.gz)
+- [Darwin arm64 image](https://s3.us-east-2.amazonaws.com/packages-stage-mirantis.com/v4.0.0-alpha1.0/mkectl_darwin_arm64.tar.gz)
+- [Darwin x86 64 image](https://s3.us-east-2.amazonaws.com/packages-stage-mirantis.com/v4.0.0-alpha1.0/mkectl_darwin_x86_64.tar.gz)
+- [Windows arm64 image](https://s3.us-east-2.amazonaws.com/packages-stage-mirantis.com/v4.0.0-alpha1.0/mkectl_windows_arm64.zip)
+- [Windows x86 64 image](https://s3.us-east-2.amazonaws.com/packages-stage-mirantis.com/v4.0.0-alpha1.0/mkectl_windows_x86_64.zip)
 
 Envisioned as a single binary, capable of managing MKE 4 clusters without any
 additional dependencies, as of `MKE 4.0.0-alpha.1.0` the MKE CLI still requires

From 30f5b7ab3f1ea49e29db19ffad67c1d0f1acfdf3 Mon Sep 17 00:00:00 2001
From: Ryan Zhang <ryan.us@icloud.com>
Date: Mon, 10 Jun 2024 11:09:22 -0700
Subject: [PATCH 14/17] Apply suggestions from code review

---
 content/docs/setup/getting-started/install-mke4-cli.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/content/docs/setup/getting-started/install-mke4-cli.md b/content/docs/setup/getting-started/install-mke4-cli.md
index 5ab15707..c4185abd 100644
--- a/content/docs/setup/getting-started/install-mke4-cli.md
+++ b/content/docs/setup/getting-started/install-mke4-cli.md
@@ -3,11 +3,11 @@
 You can download `mkectl`, the MKE CLI tool, from the S3 bucket:
 
 - [Linux arm64 image](https://s3.us-east-2.amazonaws.com/packages-stage-mirantis.com/v4.0.0-alpha1.0/mkectl_linux_arm64.tar.gz)
-- [Linux x86 64 image](https://s3.us-east-2.amazonaws.com/packages-stage-mirantis.com/v4.0.0-alpha1.0/mkectl_linux_x86_64.tar.gz)
-- [Darwin arm64 image](https://s3.us-east-2.amazonaws.com/packages-stage-mirantis.com/v4.0.0-alpha1.0/mkectl_darwin_arm64.tar.gz)
-- [Darwin x86 64 image](https://s3.us-east-2.amazonaws.com/packages-stage-mirantis.com/v4.0.0-alpha1.0/mkectl_darwin_x86_64.tar.gz)
+- [Linux x86_64 image](https://s3.us-east-2.amazonaws.com/packages-stage-mirantis.com/v4.0.0-alpha1.0/mkectl_linux_x86_64.tar.gz)
+- [MacOS arm64 image](https://s3.us-east-2.amazonaws.com/packages-stage-mirantis.com/v4.0.0-alpha1.0/mkectl_darwin_arm64.tar.gz)
+- [MacOS x86_64 image](https://s3.us-east-2.amazonaws.com/packages-stage-mirantis.com/v4.0.0-alpha1.0/mkectl_darwin_x86_64.tar.gz)
 - [Windows arm64 image](https://s3.us-east-2.amazonaws.com/packages-stage-mirantis.com/v4.0.0-alpha1.0/mkectl_windows_arm64.zip)
-- [Windows x86 64 image](https://s3.us-east-2.amazonaws.com/packages-stage-mirantis.com/v4.0.0-alpha1.0/mkectl_windows_x86_64.zip)
+- [Windows x86_64 image](https://s3.us-east-2.amazonaws.com/packages-stage-mirantis.com/v4.0.0-alpha1.0/mkectl_windows_x86_64.zip)
 
 Envisioned as a single binary, capable of managing MKE 4 clusters without any
 additional dependencies, as of `MKE 4.0.0-alpha.1.0` the MKE CLI still requires

From 4e0849d1a1d41d6e3a2dacd5d0b34c946eb320ac Mon Sep 17 00:00:00 2001
From: KoryKessel-Mirantis <kkessel@mirantis.com>
Date: Tue, 11 Jun 2024 12:50:29 +0200
Subject: [PATCH 15/17] Edits in response to review by Magda Dziadosz.

---
 .../getting-started/Using-the-cluster.md      | 12 ++---
 .../setup/getting-started/create-a-cluster.md | 21 ++++----
 .../setup/getting-started/install-mke4-cli.md | 50 +++++++++++--------
 .../upgrade-prerequisites.md                  | 14 ++++--
 4 files changed, 54 insertions(+), 43 deletions(-)

diff --git a/content/docs/setup/getting-started/Using-the-cluster.md b/content/docs/setup/getting-started/Using-the-cluster.md
index 62a500e3..673dfb9f 100644
--- a/content/docs/setup/getting-started/Using-the-cluster.md
+++ b/content/docs/setup/getting-started/Using-the-cluster.md
@@ -1,6 +1,4 @@
-
-
-## Using the cluster
+# Using the cluster
 
 You can use `kubectl` with the `mke` context to interact with the cluster,
 though it is necessary to specify the configuration. `mkectl` outputs the
@@ -10,22 +8,20 @@ You can apply ``.mke.kubeconfig`` using any one of the following methods:
 
 - Set the KUBECONFIG env var to point to `~/.mke/mke.kubeconfig`
 
-  Example:
-
   ```shell
-     `export KUBECONFIG=~/.mke/<cluster name>.kubeconfig`
+  export KUBECONFIG=~/.mke/<cluster name>.kubeconfig
   ```
 
 - Append the contents to the default kubeconfig:
 
   ```shell
-  `cat ~/.mke/mke.kubeconfig >> ~/.kube/config`
+  cat ~/.mke/mke.kubeconfig >> ~/.kube/config
   ```
 
 - Specify the config as a command argument:
 
   ```shell
- `kubectl --kubeconfig ~/.mke/mke.kubeconfig`
+  kubectl --kubeconfig ~/.mke/mke.kubeconfig
   ```
 
 Example output:
diff --git a/content/docs/setup/getting-started/create-a-cluster.md b/content/docs/setup/getting-started/create-a-cluster.md
index ef1ef41d..7fea6f6e 100644
--- a/content/docs/setup/getting-started/create-a-cluster.md
+++ b/content/docs/setup/getting-started/create-a-cluster.md
@@ -1,16 +1,17 @@
-## Create a cluster
+# Create a cluster
 
-### Dependencies
+## Dependencies
 
 A number of tools must be installed on your system before you can install MKE
 4:
-* mkectl
-* k0sctl
-* kubectl
+
+- mkectl
+- k0sctl
+- kubectl
 
 Refer to [Install the MKE 4 CLI](install-mke4-cli.md) for detailed information.
 
-### Init
+## Initialization
 
 MKE 4 installation is performed through the use of a single YAML file,
 detailing the desired cluster configuration. To generate this YAML file, run
@@ -28,7 +29,7 @@ of nodes.
   requirements](prerequisites.md#system-requirements-for-cluster-nodes).
 >
 > Node provisioning is managed by the cluster administrators. You can, for
-instance, use [Terraform](https://www.terraform.io/) to create the nodes in a
+instance, use Terraform to create the nodes in a
 cloud provider. [Example Terraform
 configuration](k0s-in-aws/terraform-scenario.md).
 
@@ -98,7 +99,7 @@ monitoring:
 
 </details>
 
-### Install
+## Installation
 
 To perform the installation, run the `apply` command with the generated YAML
 configuration file:
@@ -107,10 +108,10 @@ configuration file:
 mkectl apply -f mke.yaml
 ```
 
-### Known limitations
+## Known limitations
 
 - `mkectl apply` configures `mke` context in the default kubeconfig file that
-is normally located at `~/.kube/config`. If the default kubeconfig is changed,
+is located at `~/.kube/config`. If the default kubeconfig is changed,
 and the `mke` context becomes invalid or unavailable, `mkectl` will be unable
 to manage the cluster until the kubeconfig is restored.
 - You must not attempt to create a new cluster until you have first deleted the
diff --git a/content/docs/setup/getting-started/install-mke4-cli.md b/content/docs/setup/getting-started/install-mke4-cli.md
index c4185abd..0578ff70 100644
--- a/content/docs/setup/getting-started/install-mke4-cli.md
+++ b/content/docs/setup/getting-started/install-mke4-cli.md
@@ -10,7 +10,7 @@ You can download `mkectl`, the MKE CLI tool, from the S3 bucket:
 - [Windows x86_64 image](https://s3.us-east-2.amazonaws.com/packages-stage-mirantis.com/v4.0.0-alpha1.0/mkectl_windows_x86_64.zip)
 
 Envisioned as a single binary, capable of managing MKE 4 clusters without any
-additional dependencies, as of `MKE 4.0.0-alpha.1.0` the MKE CLI still requires
+additional dependencies, as of `MKE 4.0.0-alpha.1.0` the MKE CLI requires
 that you have the following tools installed on your system:
 
 - `kubectl`, version `1.29.0` or later ([download](https://kubernetes.io/docs/tasks/tools/#kubectl))
@@ -28,7 +28,7 @@ dependencies:
 
 To override the default versions, pass the variables `K0SCTL_VERSION`,`MKECTL_VERSION`and `KUBECTL_VERSION`.
 
->The `install.sh` script detects whether kubectl is already installed on your
+>The `install.sh` script detects whether `kubectl` is already installed on your
 >system and will not overwrite it. It also detects the operating system and the
 >underlying architecture, based on which it will install the `k0sctl`, `kubectl`
  and `mkectl` binaries in `/usr/local/bin`. Thus, you must ensure that
@@ -39,36 +39,46 @@ To override the default versions, pass the variables `K0SCTL_VERSION`,`MKECTL_VE
    ```shell
    sudo /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Mirantis/mke-docs/main/content/docs/setup/install.sh)"
     ```
-3. Confirm the installations:
+2. Confirm dependency installations:
 
    1. To confirm `mkectl`, run:
 
       ```shell
-        mkectl version
+      mkectl version
       ```
+
       Expected output:
+
       ```shell
-         Version: v4.0.0-alpha.1.0
-       ```
+      Version: v4.0.0-alpha.1.0
+      ```
+
    2. To confirm `k0sctl`, run:
-       ```shell
-         k0sctl version
-       ```
+
+      ```shell
+      k0sctl version
+      ```
+
       Expected output:
+
       ```shell
-         version: v0.17.8
-         commit: b061291
-       ```
-   3. To confirm kubectl, run:
-       ```shell
-         kubectl version
-       ```
+      version: v0.17.8
+      commit: b061291
+      ```
+
+   3. To confirm `kubectl`, run:
+
+      ```shell
+      kubectl version
+      ```
+
       Expected output:
+
       ```shell
-         Client Version: v1.30.0
-         Kustomize Version: v5.0.4-0.20230601165947-6ce0bf390ce3
-         Server Version: v1.29.3+k0s
-       ```
+      Client Version: v1.30.0
+      Kustomize Version: v5.0.4-0.20230601165947-6ce0bf390ce3
+      Server Version: v1.29.3+k0s
+      ```
 
 ### Start Debug mode
 To turn the debug mode on, run:
diff --git a/content/docs/setup/upgrade-from-mke-3/upgrade-prerequisites.md b/content/docs/setup/upgrade-from-mke-3/upgrade-prerequisites.md
index 6f9a99a8..dbd29cdd 100644
--- a/content/docs/setup/upgrade-from-mke-3/upgrade-prerequisites.md
+++ b/content/docs/setup/upgrade-from-mke-3/upgrade-prerequisites.md
@@ -1,8 +1,6 @@
-# Upgrade from MKE 3 to MKE 4
+# Upgrade prerequisites
 
-## Prerequisites
-
-Verify that you have the following components in place before you begin the upgrade process:
+Verify that you have the following components in place before you begin upgrading MKE3 to MKE 4:
 
 - A running MKE 3.7.x cluster:
 
@@ -21,6 +19,9 @@ Verify that you have the following components in place before you begin the upgr
   ```shell
   mkectl version
   ```
+
+  Example output:
+
   ```shell
   Version: v4.0.0-alpha.1.0
   ```
@@ -31,12 +32,15 @@ Verify that you have the following components in place before you begin the upgr
   k0sctl version
   ```
 
+  Example output:
+
   ```shell
   version: v0.17.4
   commit: 372a589
   ```
+
 - A `hosts.yaml` file, to provide the information required by `mkectl` to
-  connect to each node by way of SSH.
+  connect to each node with SSH.
 
   Example `hosts.yaml` file:
 

From 5c37935a45d395c9e5aa667fe294e5c5ae8ed7f5 Mon Sep 17 00:00:00 2001
From: KoryKessel-Mirantis <kkessel@mirantis.com>
Date: Tue, 11 Jun 2024 14:26:49 +0200
Subject: [PATCH 16/17] Part 2: Edits in response to review by Magda Dziadosz.

---
 .../setup/getting-started/install-mke4-cli.md |  6 ++-
 .../k0s-in-aws/terraform-scenario.md          | 52 ++++++++++++-------
 .../setup/getting-started/prerequisites.md    | 29 +++++++----
 .../setup/getting-started/uninstallation.md   |  2 +-
 .../upgrade-from-mke-3/perform-upgrade.md     | 30 +++++++----
 5 files changed, 76 insertions(+), 43 deletions(-)

diff --git a/content/docs/setup/getting-started/install-mke4-cli.md b/content/docs/setup/getting-started/install-mke4-cli.md
index 0578ff70..299e5256 100644
--- a/content/docs/setup/getting-started/install-mke4-cli.md
+++ b/content/docs/setup/getting-started/install-mke4-cli.md
@@ -81,7 +81,9 @@ To override the default versions, pass the variables `K0SCTL_VERSION`,`MKECTL_VE
       ```
 
 ### Start Debug mode
+
 To turn the debug mode on, run:
+
 ```shell
 sudo DEBUG=true /bin/sh -c "$(curl -fsSL https://raw.githubusercontent.com/Mirantis/mke-docs/main/content/docs/setup/install.sh)"
 ```
@@ -92,14 +94,16 @@ You can use the `MKECTL_VERSION`, `KUBECTL_VERSION` and `K0SCTL_VERSION`
 variables to install non-default versions of `mkectl`, `kubectl` and `k0sctl`.
 
 Example:
+
 ```shell
 sudo K0SCTL_VERSION=0.17.4 /bin/sh -c "$(curl -fsSL https://raw.githubusercontent.com/Mirantis/mke-docs/main/content/docs/setup/install.sh)"
 ```
 
 Example output:
+
 ```shell
 k0sctl version
 
 version: v0.17.4
 commit: 372a589
-```
+```
\ No newline at end of file
diff --git a/content/docs/setup/getting-started/k0s-in-aws/terraform-scenario.md b/content/docs/setup/getting-started/k0s-in-aws/terraform-scenario.md
index 72898eba..3844b051 100644
--- a/content/docs/setup/getting-started/k0s-in-aws/terraform-scenario.md
+++ b/content/docs/setup/getting-started/k0s-in-aws/terraform-scenario.md
@@ -1,26 +1,29 @@
-**Scenario**: Create a k0s cluster in AWS using Terraform and install MKE 4 on that cluster.
+# Scenario: Create a k0s cluster in AWS using Terraform and install MKE 4 on that cluster
 
-### Prerequisites
+## Prerequisites
 
 In addition to the MKE 4 [dependencies](../create-a-cluster.md#dependencies),
-you must have the following componenets installed:
+you must have the following components installed:
+
+- [Terraform](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli)
+(required for creating VMs in AWS)
+
+- AWS account
+
+- env variables, set for AWS CLI:
 
-* [Terraform](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli)
-  (required for creating VMs in AWS)
-* AWS account
-* env variables, set for AWS CLI:
   - `AWS_ACCESS_KEY_ID`
   - `AWS_SECRET_ACCESS_KEY`
   - `AWS_SESSION_TOKEN`
 
-### Create virtual machines on AWS
+## Create virtual machines on AWS
 
-To create virtual machines on AWS using the
-[example Terraform scripts](./terraform/):
+To create virtual machines on AWS using the example Terraform scripts:
 
-1. Copy the example Terraform folder to your local machine,
+1. Copy the [example Terraform folder](./terraform) to your local machine.
 
 2. Create a `terraform.tfvars` file with content similar to:
+
    ```
    cluster_name = "k0s-cluster"
    controller_count = 1
@@ -28,19 +31,28 @@ To create virtual machines on AWS using the
    cluster_flavor = "m5.large"
    region = "us-east-1"
    ```
+
 3. Run `terraform init`.
+
 4. Run `terraform apply -auto-approve`.
+
 5. Run `terraform output --raw k0s_cluster > VMs.yaml`.
 
-> To get detailed information on the VMs using the AWS CLI, run:
-> ```
-> aws ec2 describe-instances --region $(grep "region" terraform.tfvars | awk -F' *= *' '{print $2}' | tr -d '"')
-> ```
-> Alternatively, you can get a visual overview of the VMs at the AWS EC2 page
-> by selecting the desired region from the dropdown menu in the top-right
-> corner.
+---
+***Note***
+
+To get detailed information on the VMs using the AWS CLI, run:
+
+```
+aws ec2 describe-instances --region $(grep "region" terraform.tfvars | awk -F' *= *' '{print $2}' | tr -d '"')
+```
+Alternatively, you can get a visual overview of the VMs at the AWS EC2 page
+by selecting the desired region from the dropdown menu in the top-right
+corner.
+
+---
 
-### Install MKE4 on `k0s`
+## Install MKE4 on `k0s`
 
 1. Generate a sample `mke.yaml` file:
 
@@ -75,7 +87,7 @@ To create virtual machines on AWS using the
    mkectl apply -f mke.yaml
    ```
 
-### Cleanup
+## Cleanup
 
 To delete virtual machines, navigate to the Terraform folder and run:
 
diff --git a/content/docs/setup/getting-started/prerequisites.md b/content/docs/setup/getting-started/prerequisites.md
index 32043ed5..10efa223 100644
--- a/content/docs/setup/getting-started/prerequisites.md
+++ b/content/docs/setup/getting-started/prerequisites.md
@@ -1,34 +1,41 @@
-## Prerequisites
+# Prerequisites
 
->The prerequisites detailed herein apply only to the Alpha 1.0
->pre-release version of MKE 4.
+---
+***Note***
 
-### System requirements for cluster nodes
+The prerequisites detailed herein apply only to the Alpha 1.0 pre-release version of MKE 4.
+
+---
+
+## System requirements for cluster nodes
 
 MKE 4 uses [k0s](https://k0sproject.io/) as the underlying Kubernetes
 distribution. To learn the k0s hardware requirements, refer to the [k0s
 documentation](https://docs.k0sproject.io/v1.29.4+k0s.0/system-requirements/).
 
-### Known limitations
+## Known limitations
+
+Before installing MKE 4 Alpha 1.0, you should be aware of the current known
+limitations of the software.
 
-#### Operating systems
+### Operating systems
 
 Currently, MKE 4 is only certified for use on the following distributions:
 
-* Ubuntu 22.04 Linux
-* Ubuntu 20.04 Linux
+- Ubuntu 22.04 Linux
+- Ubuntu 20.04 Linux
 
 Windows nodes are **not supported**.
 
-#### Architecture
+### Architecture
 
 MKE 4 only supports `amd64` architecture.
 
-#### CNI
+### CNI
 
 `calico` is the only CNI plugin that MKE 4 supports.
 
-#### mkectl
+### mkectl
 
 `mkectl`, the [MKE CLI tool](install-mke4-cli.md), must be installed prior to
 MKE 4 installation.
diff --git a/content/docs/setup/getting-started/uninstallation.md b/content/docs/setup/getting-started/uninstallation.md
index 4c6d4f15..80d2cc31 100644
--- a/content/docs/setup/getting-started/uninstallation.md
+++ b/content/docs/setup/getting-started/uninstallation.md
@@ -1,4 +1,4 @@
-## Uninstallation
+# Uninstallation
 
 Run the `reset` command to destroy the cluster that was previously created with
 the `apply` command.
diff --git a/content/docs/setup/upgrade-from-mke-3/perform-upgrade.md b/content/docs/setup/upgrade-from-mke-3/perform-upgrade.md
index 1c999fed..9faff102 100644
--- a/content/docs/setup/upgrade-from-mke-3/perform-upgrade.md
+++ b/content/docs/setup/upgrade-from-mke-3/perform-upgrade.md
@@ -1,9 +1,10 @@
-## Perform the Upgrade
+# Perform the Upgrade
 
 An upgrade from MKE 3 to MKE 4 consists of the following steps, all of which
 are performed through the use of the `mkectl` tool:
-- Run pre-upgrade checks, to verify the upgradability of the cluster.
-- Carry out pre-upgrade migrations, to prepare the cluster for a migration from
+
+- Run pre-upgrade checks to verify the upgradability of the cluster.
+- Carry out pre-upgrade migrations to prepare the cluster for a migration from
   a hyperkube-based MKE 3 cluster to a k0s-based MKE 4 cluster.
 - Migrate manager nodes to k0s.
 - Migrate worker nodes to k0s.
@@ -16,10 +17,15 @@ To upgrade an MKE 3 cluster, run the following command:
 mkectl upgrade --hosts-path <path-to-hosts-yaml> --admin-username <admin-username> --admin-password <admin-password>
 ```
 
-> The MKE 4 config file prints to your console when the migration is
-> complete. To output the config file to a file for future use, run
-  `mkectl apply`. Alternatively, you can set the `--config-out` flag to the
-  path where you want to save the MKE 4 config file.
+---
+***Note***
+
+The MKE 4 config file prints to your console when the migration is complete. To
+output the config file to a file for future use, run `mkectl apply`.
+Alternatively, you can set the `--config-out` flag to the path where you want
+to save the MKE 4 config file.
+
+---
 
 The upgrade process requires time to complete. Once the process is complete,
 run the following command to verify that the MKE 4 cluster is operating:
@@ -37,9 +43,13 @@ ip-172-31-191-216.us-west-2.compute.internal   Ready    <none>   29m   v1.29.3+k
 ip-172-31-199-207.us-west-2.compute.internal   Ready    master   30m   v1.29.3+k0s
 ```
 
->The MKE 3 cluster will no longer be accessible by way of the previously
->created client bundle. The docker swarm cluster will no longer be
->accessible as well.
+---
+***Note***
+
+The MKE 3 cluster will no longer be accessible through the previously created
+client bundle. The docker swarm cluster will no longer be accessible as well.
+
+---
 
 In the event of an upgrade failure, the upgrade process rolls back,
 restoring the MKE 3 cluster to its original state.
\ No newline at end of file

From 7e89154a94af34cfda0af7554ec61efddec52e7d Mon Sep 17 00:00:00 2001
From: KoryKessel-Mirantis <kkessel@mirantis.com>
Date: Tue, 11 Jun 2024 15:40:39 +0200
Subject: [PATCH 17/17] Final cleanup of markdown elements before merge.

---
 .../setup/getting-started/create-a-cluster.md  | 18 +++++++++++-------
 .../setup/getting-started/install-mke4-cli.md  | 17 ++++++++++++-----
 .../k0s-in-aws/terraform-scenario.md           |  3 ++-
 .../setup/getting-started/prerequisites.md     |  1 +
 .../upgrade-from-mke-3/perform-upgrade.md      |  2 ++
 .../upgrade-prerequisites.md                   |  2 ++
 6 files changed, 30 insertions(+), 13 deletions(-)

diff --git a/content/docs/setup/getting-started/create-a-cluster.md b/content/docs/setup/getting-started/create-a-cluster.md
index 7fea6f6e..8454fb4d 100644
--- a/content/docs/setup/getting-started/create-a-cluster.md
+++ b/content/docs/setup/getting-started/create-a-cluster.md
@@ -24,14 +24,18 @@ mkectl init > mke.yaml
 In the configuration file, edit the `hosts` section to match your roster
 of nodes.
 
-> Configure the cluster nodes in advance, in accordance with the
-  [system
+---
+***Note***
+
+Configure the cluster nodes in advance, in accordance with the [system
   requirements](prerequisites.md#system-requirements-for-cluster-nodes).
->
-> Node provisioning is managed by the cluster administrators. You can, for
-instance, use Terraform to create the nodes in a
-cloud provider. [Example Terraform
-configuration](k0s-in-aws/terraform-scenario.md).
+
+Node provisioning is managed by the cluster administrators. You can, for
+instance, use Terraform to create the nodes in a cloud provider.
+[Example
+Terraform configuration](k0s-in-aws/terraform-scenario.md).
+
+---
 
 You must provide SSH information for each cluster node, as well as the role of
 the node:
diff --git a/content/docs/setup/getting-started/install-mke4-cli.md b/content/docs/setup/getting-started/install-mke4-cli.md
index 299e5256..1a78acf2 100644
--- a/content/docs/setup/getting-started/install-mke4-cli.md
+++ b/content/docs/setup/getting-started/install-mke4-cli.md
@@ -26,19 +26,26 @@ dependencies:
 - `k0sctl` (default version: 0.17.8)
 - `kubectl` (default version: v1.30.0)
 
-To override the default versions, pass the variables `K0SCTL_VERSION`,`MKECTL_VERSION`and `KUBECTL_VERSION`.
+To override the default versions, pass the variables
+`K0SCTL_VERSION`,`MKECTL_VERSION`and `KUBECTL_VERSION`.
 
->The `install.sh` script detects whether `kubectl` is already installed on your
->system and will not overwrite it. It also detects the operating system and the
->underlying architecture, based on which it will install the `k0sctl`, `kubectl`
- and `mkectl` binaries in `/usr/local/bin`. Thus, you must ensure that
+---
+***Note***
+
+The `install.sh` script detects whether `kubectl` is already installed on your
+system and will not overwrite it. It also detects the operating system and the
+underlying architecture, based on which it will install the `k0sctl`, `kubectl`
+and `mkectl` binaries in `/usr/local/bin`. Thus, you must ensure that
 ` /usr/local/bin` is in your PATH environment variable.
 
+---
+
 1. Install the dependencies:
 
    ```shell
    sudo /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Mirantis/mke-docs/main/content/docs/setup/install.sh)"
     ```
+
 2. Confirm dependency installations:
 
    1. To confirm `mkectl`, run:
diff --git a/content/docs/setup/getting-started/k0s-in-aws/terraform-scenario.md b/content/docs/setup/getting-started/k0s-in-aws/terraform-scenario.md
index 3844b051..6295a75b 100644
--- a/content/docs/setup/getting-started/k0s-in-aws/terraform-scenario.md
+++ b/content/docs/setup/getting-started/k0s-in-aws/terraform-scenario.md
@@ -46,6 +46,7 @@ To get detailed information on the VMs using the AWS CLI, run:
 ```
 aws ec2 describe-instances --region $(grep "region" terraform.tfvars | awk -F' *= *' '{print $2}' | tr -d '"')
 ```
+
 Alternatively, you can get a visual overview of the VMs at the AWS EC2 page
 by selecting the desired region from the dropdown menu in the top-right
 corner.
@@ -93,4 +94,4 @@ To delete virtual machines, navigate to the Terraform folder and run:
 
 ``` bash
 terraform destroy --auto-approve
-```
+```
\ No newline at end of file
diff --git a/content/docs/setup/getting-started/prerequisites.md b/content/docs/setup/getting-started/prerequisites.md
index 10efa223..cbf8c21a 100644
--- a/content/docs/setup/getting-started/prerequisites.md
+++ b/content/docs/setup/getting-started/prerequisites.md
@@ -1,6 +1,7 @@
 # Prerequisites
 
 ---
+
 ***Note***
 
 The prerequisites detailed herein apply only to the Alpha 1.0 pre-release version of MKE 4.
diff --git a/content/docs/setup/upgrade-from-mke-3/perform-upgrade.md b/content/docs/setup/upgrade-from-mke-3/perform-upgrade.md
index 9faff102..6b02fdaa 100644
--- a/content/docs/setup/upgrade-from-mke-3/perform-upgrade.md
+++ b/content/docs/setup/upgrade-from-mke-3/perform-upgrade.md
@@ -33,6 +33,7 @@ run the following command to verify that the MKE 4 cluster is operating:
 ```shell
 sudo k0s kc get nodes
 ```
+
 Example output:
 
 ```shell
@@ -44,6 +45,7 @@ ip-172-31-199-207.us-west-2.compute.internal   Ready    master   30m   v1.29.3+k
 ```
 
 ---
+
 ***Note***
 
 The MKE 3 cluster will no longer be accessible through the previously created
diff --git a/content/docs/setup/upgrade-from-mke-3/upgrade-prerequisites.md b/content/docs/setup/upgrade-from-mke-3/upgrade-prerequisites.md
index dbd29cdd..b6b7e8ce 100644
--- a/content/docs/setup/upgrade-from-mke-3/upgrade-prerequisites.md
+++ b/content/docs/setup/upgrade-from-mke-3/upgrade-prerequisites.md
@@ -7,6 +7,7 @@ Verify that you have the following components in place before you begin upgradin
   ```shell
   kubectl get nodes
   ```
+
   ```shell
   NAME                                           STATUS   ROLES    AGE     VERSION
   ip-172-31-103-202.us-west-2.compute.internal   Ready    master   7m3s    v1.27.7-mirantis-1
@@ -14,6 +15,7 @@ Verify that you have the following components in place before you begin upgradin
   ip-172-31-191-216.us-west-2.compute.internal   Ready    <none>   6m59s   v1.27.7-mirantis-1
   ip-172-31-199-207.us-west-2.compute.internal   Ready    master   8m4s    v1.27.7-mirantis-1
   ```
+
 - The latest `mkectl` binary, installed on your local enviroment:
 
   ```shell