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/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 - -
-Example of ready-to-deploy MKE 4 config file - -```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 -``` - -
- -### 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 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/Using-the-cluster.md b/content/docs/setup/getting-started/Using-the-cluster.md new file mode 100644 index 00000000..673dfb9f --- /dev/null +++ b/content/docs/setup/getting-started/Using-the-cluster.md @@ -0,0 +1,41 @@ +# 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 +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` + + ```shell + export KUBECONFIG=~/.mke/.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 +NAME STATUS ROLES AGE VERSION +node1 Ready 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/create-a-cluster.md b/content/docs/setup/getting-started/create-a-cluster.md new file mode 100644 index 00000000..8454fb4d --- /dev/null +++ b/content/docs/setup/getting-started/create-a-cluster.md @@ -0,0 +1,125 @@ +# Create a cluster + +## 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.md) for detailed information. + +## 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 +the `mkectl init` command: + +```shell +mkectl init > mke.yaml +``` + +In the configuration file, edit the `hosts` section to match your roster +of nodes. + +--- +***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). + +--- + +You must provide SSH information for each cluster node, as well as the role of +the node: + +
+
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 use when the cluster consists of a single node.
+
+ +
+Example: A ready-to-deploy MKE 4 config file + +```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 +``` + +
+ +## Installation + +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 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.md). 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..1a78acf2 --- /dev/null +++ b/content/docs/setup/getting-started/install-mke4-cli.md @@ -0,0 +1,116 @@ +# Install the MKE 4 CLI + +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) +- [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) + +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 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`. + +--- +***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: + + ```shell + mkectl version + ``` + + Expected output: + + ```shell + Version: v4.0.0-alpha.1.0 + ``` + + 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 +``` \ No newline at end of file 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: /aws_private.pem - port: 22 - user: ubuntu - - role: worker - ssh: - address: 18.206.202.16 - keyPath: /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..6295a75b --- /dev/null +++ b/content/docs/setup/getting-started/k0s-in-aws/terraform-scenario.md @@ -0,0 +1,97 @@ +# Scenario: Create a k0s cluster in AWS using Terraform and install MKE 4 on that cluster + +## Prerequisites + +In addition to the MKE 4 [dependencies](../create-a-cluster.md#dependencies), +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: + + - `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: + +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 + 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`. + +--- +***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` + +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: /aws_private.pem + port: 22 + user: ubuntu + - role: worker + ssh: + address: 18.206.202.16 + keyPath: /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 +``` \ No newline at end of file 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/getting-started/prerequisites.md b/content/docs/setup/getting-started/prerequisites.md new file mode 100644 index 00000000..cbf8c21a --- /dev/null +++ b/content/docs/setup/getting-started/prerequisites.md @@ -0,0 +1,42 @@ +# Prerequisites + +--- + +***Note*** + +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 + +Before installing MKE 4 Alpha 1.0, you should be aware of the current known +limitations of the software. + +### Operating systems + +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**. + +### Architecture + +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.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 new file mode 100644 index 00000000..80d2cc31 --- /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/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 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: - port: - user: - keyPath: - - address: - port: - user: - keyPath: -``` - - -## 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 --admin-username --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`. -
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 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..6b02fdaa --- /dev/null +++ b/content/docs/setup/upgrade-from-mke-3/perform-upgrade.md @@ -0,0 +1,57 @@ +# 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 --admin-username --admin-password +``` + +--- +***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: + +```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 29m v1.29.3+k0s +ip-172-31-199-207.us-west-2.compute.internal Ready master 30m v1.29.3+k0s +``` + +--- + +***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 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..b6b7e8ce --- /dev/null +++ b/content/docs/setup/upgrade-from-mke-3/upgrade-prerequisites.md @@ -0,0 +1,63 @@ +# Upgrade prerequisites + +Verify that you have the following components in place before you begin upgrading MKE3 to MKE 4: + +- 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 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 + ``` + + Example output: + + ```shell + Version: v4.0.0-alpha.1.0 + ``` + +- `k0sctl` version `0.17.4`, installed on your local enviroment: + + ```shell + 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 with SSH. + + Example `hosts.yaml` file: + + ```shell + cat hosts.yaml + ``` + + ```shell + hosts: + - address: + port: + user: + keyPath: + - address: + port: + user: + keyPath: + ```