From d374940be876724e6decf15911e8039452ddead5 Mon Sep 17 00:00:00 2001 From: KoryKessel-Mirantis Date: Wed, 23 Apr 2025 18:06:52 +0200 Subject: [PATCH 01/17] Creation of Offline Installation topic. --- content/docs/getting-started/_index.md | 2 +- .../docs/getting-started/create-cluster.md | 7 ++ .../getting-started/offline-installation.md | 111 ++++++++++++++++++ 3 files changed, 119 insertions(+), 1 deletion(-) create mode 100644 content/docs/getting-started/offline-installation.md diff --git a/content/docs/getting-started/_index.md b/content/docs/getting-started/_index.md index 2fde721e..dfb0038b 100644 --- a/content/docs/getting-started/_index.md +++ b/content/docs/getting-started/_index.md @@ -45,7 +45,7 @@ container orchestration and management. {{% /steps %}} In addition, this **Getting started** section offers such other key MKE 4 -information as [how to use kubectl to access and manage +information as [how to perform an offline installation](offline-installation), [how to use kubectl to access and manage your cluster](access-manage-cluster-kubectl), [how to add and remove cluster nodes](add-and-remove-cluster-nodes), [how to obtain the current MKE 4 configuration file](get-current-mke-config), and [how to uninstall a diff --git a/content/docs/getting-started/create-cluster.md b/content/docs/getting-started/create-cluster.md index b73b399a..adbce72e 100644 --- a/content/docs/getting-started/create-cluster.md +++ b/content/docs/getting-started/create-cluster.md @@ -3,6 +3,13 @@ title: Create a cluster weight: 3 --- +{{< callout type="info" >}} + +For information on how to create a cluster in an airgapped environment, refer +to airgap MKE 4 installation, refer to [Offline installation](../offline-installation). + +{{< /callout >}} + ## Install dependecies Verify that you have installed `mkectl` and other dependencies on your system diff --git a/content/docs/getting-started/offline-installation.md b/content/docs/getting-started/offline-installation.md new file mode 100644 index 00000000..57af7867 --- /dev/null +++ b/content/docs/getting-started/offline-installation.md @@ -0,0 +1,111 @@ +--- +title: Offline installation +weight: 3 +--- + +The installation and upgrade procedures for MKE 4k reflect those of the online +scenario. While the online installation, though, typically uses +`registry.mirantis.com` as the primary OCI registry as the repository for MKE + 4k materials, with the offline scenario you instead specify a private +registry from which to pull the MKE 4k artifacts, images, and charts. + +{{< callout type="info" >}} + +You can download the MKE 4 artifacts from the releases page. + +{{< /callout >}} + +## Dependencies ## + +- skopeo 1.6.1 or later +- An OCI-based private registry that is accessible from all cluster nodes. +- All MKE 4 artifacts and images must be publicly accessible, with no required authentication. +- The registry must use HTTPS, and the TLS certificates of the registry server +must be signed by a publicly trusted Certificate Authority. +- The registry must support multi-level nesting, for image names + +## Preparation ## + +1. Download the offline bundle from the releases page: + + ```bash + wget https://packages.mirantis.com/caas/mke_bundle_v4.1.0.tar.gz -O mke_bundle_v4.1.0.tar.gz + ``` + +2. Transfer the bundle file to a machine that can access your private registry. + +3. On the machine with registry access, set the environment variables: + + ```bash + export REGISTRY_ADDRESS="" # Registry hostname and optionally port, e.g. "private-registry.example.com:8080". Must NOT end with a slash '/' + export REGISTRY_PROJECT_PATH="" # Path to the registry project that will store all MKE 4 artifacts. Must NOT end with a slash '/'. E.g. "mke". Registry address and path should make the full registry path. With the examples above, the full path will be REGISTRY_ADDRESS + "/" + REGISTRY_PROJECT_PATH == "private-registry.example.com:8080/mke" + export REGISTRY_USERNAME="" # Username of the account allowed to push + export REGISTRY_PASSWORD="" # Password for the same account + export BUNDLE_NAME="mke_bundle_v4.1.0-rc.1.tar.gz" # The name of previously downloaded bundle file. The file must be located in the same directory where you run the preparation steps + ``` + +4. Upload the MKE 4k images and helm charts to your private registry: + + ``` + # Login to the registry + skopeo login "$REGISTRY_ADDRESS" -u "$REGISTRY_USERNAME" -p "$REGISTRY_PASSWORD" + + # Extract the bundle + tar -xzf "$BUNDLE_NAME" -C ./ + + # Iterate over bundle artifacts and upload each one using skopeo + for archive in $(find ./bundle -print | grep ".tar"); do + # Form the image name from the archive name + img=$(basename "$archive" | sed 's~\.tar~~' | tr '&' '/' | tr '@' ':'); + + echo "Uploading $img"; + # Copy artifact from local oci archive to the registry + skopeo copy -q --retry-times 3 --multi-arch all "oci-archive:$archive" "docker://$REGISTRY_ADDRESS/$REGISTRY_PROJECT_PATH/$img"; + done; + ``` + +## New Installation ## + +1. Refer to the [Create a Cluster](../create-cluster/#initialize-deployment) procedure for detail on +how to create a `mke4.yaml` configuration file. + +2. Add the following additional settings to the `mke4.yaml` configuration file: + + | Setting | Description | + |------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + | `.spec.registries.imageRegistry.URL` | Sets your registry address with a project path that contains your MKE 4 images. For example, `private-registry.example.com:8080/mke`.

The setting must not end with a slash `/`.

The port is optional. | + | `.spec.registries.chartRegistry.URL` | Sets your registry address with a project path that contains your MKE 4 helm charts in OCI format. For example, `oci://private-registry.example.com:8080/mke`.

The setting must always start with `oci://`, and it must not end with a slash `/` .

If you uploaded the bundle as previously described, the registry address and path will be the same for chart and image registry, with the only difference being the `oci://` prefix in the chart registry URL. | + | `.spec.airgap.enabled = true` | Indicates that your environment is airgapped. With this setting in place, run proceed with the installation normally by running | + + +3. Run the `mkectl apply` command. + +## Upgrade ## + +To perform an offline upgrade from MKE 3 to MKE 4k, you adhere to the +procedure as described in [Migrate from MKE 3.x](../../migrate-from-mke-3), +adding the following flags to the `mkectl upgrade` command: + +* `--image-registry=` +* `--chart-registry=oci://` +* `--mke3-airgapped=true` + +{{< callout type="info" >}} + +For detail on the `mkectl upgrade` command flags, refer to the mke4.yml +configuation file settings descriptions offered above for new installations. + +{{< /callout >}} + +## MKE 4 versus MKE 3 ## + +MKE 3 requires the use of the `docker load` command to load offline bundles +directly into Docker on every cluster node. While this approach does not +require you to have a private registry, it also means that the cluster cannot +repull the image should any of the loaded images go missing. As such, MKE 3 +users must disable Kubernetes garbage collection, which can sometimes prune +images of optional components that are not always enabled. This is not an issue +with MKE 4, as images are pulled from a private registry that the customer +provides, and thus there is no need to disable Kubernetes garbage collection. +That said, though, users must ensure that the registry is available at all +times and that it is accessible from every cluster node. \ No newline at end of file From 44f7dd916f1e95330368cbdf878bdb05a63f6853 Mon Sep 17 00:00:00 2001 From: Kory <57411706+KoryKessel-Mirantis@users.noreply.github.com> Date: Thu, 24 Apr 2025 16:37:17 +0200 Subject: [PATCH 02/17] Update content/docs/getting-started/offline-installation.md Replace 'repository' with 'registry'. Co-authored-by: Dmitry Shishlyannikov <9266670+byDimasik@users.noreply.github.com> --- content/docs/getting-started/offline-installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/getting-started/offline-installation.md b/content/docs/getting-started/offline-installation.md index 57af7867..fa8c5dee 100644 --- a/content/docs/getting-started/offline-installation.md +++ b/content/docs/getting-started/offline-installation.md @@ -5,7 +5,7 @@ weight: 3 The installation and upgrade procedures for MKE 4k reflect those of the online scenario. While the online installation, though, typically uses -`registry.mirantis.com` as the primary OCI registry as the repository for MKE +`registry.mirantis.com` as the primary OCI registry for MKE 4k materials, with the offline scenario you instead specify a private registry from which to pull the MKE 4k artifacts, images, and charts. From cb2fdc1c9317ecbe9482f38fd612c19516aedd23 Mon Sep 17 00:00:00 2001 From: Kory <57411706+KoryKessel-Mirantis@users.noreply.github.com> Date: Thu, 24 Apr 2025 16:37:46 +0200 Subject: [PATCH 03/17] Update content/docs/getting-started/create-cluster.md Spacing fix. Co-authored-by: Dmitry Shishlyannikov <9266670+byDimasik@users.noreply.github.com> --- content/docs/getting-started/create-cluster.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/getting-started/create-cluster.md b/content/docs/getting-started/create-cluster.md index adbce72e..c17e9a94 100644 --- a/content/docs/getting-started/create-cluster.md +++ b/content/docs/getting-started/create-cluster.md @@ -6,7 +6,7 @@ weight: 3 {{< callout type="info" >}} For information on how to create a cluster in an airgapped environment, refer -to airgap MKE 4 installation, refer to [Offline installation](../offline-installation). +to airgap MKE 4 installation, refer to [Offline installation](../offline-installation). {{< /callout >}} From 86ae65d048c7ca43f9c755d49037ce5b8b520570 Mon Sep 17 00:00:00 2001 From: Kory <57411706+KoryKessel-Mirantis@users.noreply.github.com> Date: Thu, 24 Apr 2025 16:38:18 +0200 Subject: [PATCH 04/17] Update content/docs/getting-started/offline-installation.md Add a link to skopeo reference. Co-authored-by: Dmitry Shishlyannikov <9266670+byDimasik@users.noreply.github.com> --- content/docs/getting-started/offline-installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/getting-started/offline-installation.md b/content/docs/getting-started/offline-installation.md index fa8c5dee..b9cd1e91 100644 --- a/content/docs/getting-started/offline-installation.md +++ b/content/docs/getting-started/offline-installation.md @@ -17,7 +17,7 @@ You can download the MKE 4 artifacts from the releases page. ## Dependencies ## -- skopeo 1.6.1 or later +- [skopeo](https://github.com/containers/skopeo) 1.6.1 or later - An OCI-based private registry that is accessible from all cluster nodes. - All MKE 4 artifacts and images must be publicly accessible, with no required authentication. - The registry must use HTTPS, and the TLS certificates of the registry server From 69606425db1a307d89d7e74fe2a9e04482e4bbd5 Mon Sep 17 00:00:00 2001 From: Kory <57411706+KoryKessel-Mirantis@users.noreply.github.com> Date: Thu, 24 Apr 2025 16:39:07 +0200 Subject: [PATCH 05/17] Update content/docs/getting-started/offline-installation.md Change wget command to curl command. Co-authored-by: Dmitry Shishlyannikov <9266670+byDimasik@users.noreply.github.com> --- content/docs/getting-started/offline-installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/getting-started/offline-installation.md b/content/docs/getting-started/offline-installation.md index b9cd1e91..a0dee252 100644 --- a/content/docs/getting-started/offline-installation.md +++ b/content/docs/getting-started/offline-installation.md @@ -29,7 +29,7 @@ must be signed by a publicly trusted Certificate Authority. 1. Download the offline bundle from the releases page: ```bash - wget https://packages.mirantis.com/caas/mke_bundle_v4.1.0.tar.gz -O mke_bundle_v4.1.0.tar.gz + curl -L https://packages.mirantis.com/caas/mke_bundle_v4.1.0.tar.gz -o mke_bundle_v4.1.0.tar.gz ``` 2. Transfer the bundle file to a machine that can access your private registry. From 19582e5e8585fa615d84923a8bed7195829dadbd Mon Sep 17 00:00:00 2001 From: Kory <57411706+KoryKessel-Mirantis@users.noreply.github.com> Date: Thu, 24 Apr 2025 16:40:24 +0200 Subject: [PATCH 06/17] Update content/docs/getting-started/offline-installation.md Spacing fix. Co-authored-by: Dmitry Shishlyannikov <9266670+byDimasik@users.noreply.github.com> --- content/docs/getting-started/offline-installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/getting-started/offline-installation.md b/content/docs/getting-started/offline-installation.md index a0dee252..440c9f5f 100644 --- a/content/docs/getting-started/offline-installation.md +++ b/content/docs/getting-started/offline-installation.md @@ -74,7 +74,7 @@ how to create a `mke4.yaml` configuration file. | Setting | Description | |------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `.spec.registries.imageRegistry.URL` | Sets your registry address with a project path that contains your MKE 4 images. For example, `private-registry.example.com:8080/mke`.

The setting must not end with a slash `/`.

The port is optional. | - | `.spec.registries.chartRegistry.URL` | Sets your registry address with a project path that contains your MKE 4 helm charts in OCI format. For example, `oci://private-registry.example.com:8080/mke`.

The setting must always start with `oci://`, and it must not end with a slash `/` .

If you uploaded the bundle as previously described, the registry address and path will be the same for chart and image registry, with the only difference being the `oci://` prefix in the chart registry URL. | + | `.spec.registries.chartRegistry.URL` | Sets your registry address with a project path that contains your MKE 4 helm charts in OCI format. For example, `oci://private-registry.example.com:8080/mke`.

The setting must always start with `oci://`, and it must not end with a slash `/` .

If you uploaded the bundle as previously described, the registry address and path will be the same for chart and image registry, with the only difference being the `oci://` prefix in the chart registry URL. | | `.spec.airgap.enabled = true` | Indicates that your environment is airgapped. With this setting in place, run proceed with the installation normally by running | From 48c6740be8b7e2403b58ab6d33677ba936962821 Mon Sep 17 00:00:00 2001 From: Kory <57411706+KoryKessel-Mirantis@users.noreply.github.com> Date: Thu, 24 Apr 2025 16:41:14 +0200 Subject: [PATCH 07/17] Update content/docs/getting-started/offline-installation.md Remove line inadvertently left in following edit. Co-authored-by: Dmitry Shishlyannikov <9266670+byDimasik@users.noreply.github.com> --- content/docs/getting-started/offline-installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/getting-started/offline-installation.md b/content/docs/getting-started/offline-installation.md index 440c9f5f..c6c733ff 100644 --- a/content/docs/getting-started/offline-installation.md +++ b/content/docs/getting-started/offline-installation.md @@ -75,7 +75,7 @@ how to create a `mke4.yaml` configuration file. |------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `.spec.registries.imageRegistry.URL` | Sets your registry address with a project path that contains your MKE 4 images. For example, `private-registry.example.com:8080/mke`.

The setting must not end with a slash `/`.

The port is optional. | | `.spec.registries.chartRegistry.URL` | Sets your registry address with a project path that contains your MKE 4 helm charts in OCI format. For example, `oci://private-registry.example.com:8080/mke`.

The setting must always start with `oci://`, and it must not end with a slash `/` .

If you uploaded the bundle as previously described, the registry address and path will be the same for chart and image registry, with the only difference being the `oci://` prefix in the chart registry URL. | - | `.spec.airgap.enabled = true` | Indicates that your environment is airgapped. With this setting in place, run proceed with the installation normally by running | + | `.spec.airgap.enabled = true` | Indicates that your environment is airgapped. | 3. Run the `mkectl apply` command. From a7cdd818bf7d1a0a193d3856e45ac4d455977016 Mon Sep 17 00:00:00 2001 From: Kory <57411706+KoryKessel-Mirantis@users.noreply.github.com> Date: Thu, 24 Apr 2025 17:13:10 +0200 Subject: [PATCH 08/17] Update content/docs/getting-started/offline-installation.md Add 'a' to mke.yaml reference. Co-authored-by: Dmitry Shishlyannikov --- content/docs/getting-started/offline-installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/getting-started/offline-installation.md b/content/docs/getting-started/offline-installation.md index c6c733ff..d4a3d6e1 100644 --- a/content/docs/getting-started/offline-installation.md +++ b/content/docs/getting-started/offline-installation.md @@ -92,7 +92,7 @@ adding the following flags to the `mkectl upgrade` command: {{< callout type="info" >}} -For detail on the `mkectl upgrade` command flags, refer to the mke4.yml +For detail on the `mkectl upgrade` command flags, refer to the `mke4.yaml` configuation file settings descriptions offered above for new installations. {{< /callout >}} From 4c135fe1260ccda59047b6b965820d48a4af8a88 Mon Sep 17 00:00:00 2001 From: KoryKessel-Mirantis Date: Thu, 24 Apr 2025 18:04:52 +0200 Subject: [PATCH 09/17] Edits in responsse to DShishliannikov comments. --- .../docs/getting-started/create-cluster.md | 4 +- .../getting-started/offline-installation.md | 42 ++++++++++++------- 2 files changed, 30 insertions(+), 16 deletions(-) diff --git a/content/docs/getting-started/create-cluster.md b/content/docs/getting-started/create-cluster.md index c17e9a94..a97e1a3b 100644 --- a/content/docs/getting-started/create-cluster.md +++ b/content/docs/getting-started/create-cluster.md @@ -6,7 +6,7 @@ weight: 3 {{< callout type="info" >}} For information on how to create a cluster in an airgapped environment, refer -to airgap MKE 4 installation, refer to [Offline installation](../offline-installation). +to airgap MKE 4 installation, refer to [Offline installation](../offline-installation). {{< /callout >}} @@ -85,4 +85,4 @@ not be able to manage the cluster until the kubeconfig is restored. {{< /callout >}} Once the new cluster is viable, you can start interacting with it using -`kubectl` with the `mke` context. +`kubectl` with the `mke` context. \ No newline at end of file diff --git a/content/docs/getting-started/offline-installation.md b/content/docs/getting-started/offline-installation.md index d4a3d6e1..1dc1dd2c 100644 --- a/content/docs/getting-started/offline-installation.md +++ b/content/docs/getting-started/offline-installation.md @@ -11,7 +11,7 @@ registry from which to pull the MKE 4k artifacts, images, and charts. {{< callout type="info" >}} -You can download the MKE 4 artifacts from the releases page. +You can download the MKE 4 artifacts from the [mke-release GitHub repo](https://github.com/MirantisContainers/mke-release/releases). {{< /callout >}} @@ -19,31 +19,45 @@ You can download the MKE 4 artifacts from the releases page. - [skopeo](https://github.com/containers/skopeo) 1.6.1 or later - An OCI-based private registry that is accessible from all cluster nodes. -- All MKE 4 artifacts and images must be publicly accessible, with no required authentication. -- The registry must use HTTPS, and the TLS certificates of the registry server -must be signed by a publicly trusted Certificate Authority. -- The registry must support multi-level nesting, for image names + - All MKE 4 artifacts and images must be publicly accessible, with no required authentication. + - The registry must use HTTPS, and the TLS certificates of the registry server + must be signed by a publicly trusted Certificate Authority. Private certificate authorities or self-signed certificates are not currently supported. + - The registry must support multi-level nesting. For example, + `registry.com/level-one/level-two/level-three/image-name:latest`. Some + registries only allow one level of nesting, such as + `registry.com/level-one/image:latest`, so verify that your registry + supports deeper nesting for image names. ## Preparation ## -1. Download the offline bundle from the releases page: +1. Download the offline bundle, either from the [mke-release GitHub + repo](https://github.com/MirantisContainers/mke-release/releases), or + from the command line as follows: - ```bash - curl -L https://packages.mirantis.com/caas/mke_bundle_v4.1.0.tar.gz -o mke_bundle_v4.1.0.tar.gz - ``` + ```bash + curl -L https://packages.mirantis.com/caas/mke_bundle_v4.1.0.tar.gz -o mke_bundle_v4.1.0.tar.gz + ``` 2. Transfer the bundle file to a machine that can access your private registry. 3. On the machine with registry access, set the environment variables: ```bash - export REGISTRY_ADDRESS="" # Registry hostname and optionally port, e.g. "private-registry.example.com:8080". Must NOT end with a slash '/' - export REGISTRY_PROJECT_PATH="" # Path to the registry project that will store all MKE 4 artifacts. Must NOT end with a slash '/'. E.g. "mke". Registry address and path should make the full registry path. With the examples above, the full path will be REGISTRY_ADDRESS + "/" + REGISTRY_PROJECT_PATH == "private-registry.example.com:8080/mke" - export REGISTRY_USERNAME="" # Username of the account allowed to push - export REGISTRY_PASSWORD="" # Password for the same account - export BUNDLE_NAME="mke_bundle_v4.1.0-rc.1.tar.gz" # The name of previously downloaded bundle file. The file must be located in the same directory where you run the preparation steps + export REGISTRY_ADDRESS='' + export REGISTRY_PROJECT_PATH='' + export REGISTRY_USERNAME='' + export REGISTRY_PASSWORD='' + export BUNDLE_NAME='mke_bundle_v.tar.gz' ``` +| Environment variable | Description | +|--------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| REGISTRY_ADDRESS=' ' | Registry hostname (required) and port (optional). The value must not end with a slash '/'.

Example: `private-registry.example.com:8080` | +| REGISTRY_PROJECT_PATH= '' | Path to the registry project that will store all MKE 4 artifacts. The registry address and path should comprise the full registry path. The value must not end with a slash '/'.

Example: `REGISTRY_ADDRESS + '/' + REGISTRY_PROJECT_PATH == 'private-registry.example.com:8080/mke` | +| REGISTRY_USERNAME= '' | Username for the account that is allowed to push. | +| REGISTRY_PASSWORD= '' | Password for the account that is allowed to push. | +| BUNDLE_NAME= 'mke_bundle_v.tar.gz' | The name of previously downloaded bundle file, which must be located in the same directory in which you run the preparation steps. | + 4. Upload the MKE 4k images and helm charts to your private registry: ``` From 2aa33550d770a5fb24903721ffc59bb8733c356c Mon Sep 17 00:00:00 2001 From: KoryKessel-Mirantis Date: Thu, 24 Apr 2025 18:26:53 +0200 Subject: [PATCH 10/17] Fix clause doubling in info directive on Create a cluster topic. --- content/docs/getting-started/create-cluster.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/docs/getting-started/create-cluster.md b/content/docs/getting-started/create-cluster.md index a97e1a3b..7b90158a 100644 --- a/content/docs/getting-started/create-cluster.md +++ b/content/docs/getting-started/create-cluster.md @@ -5,8 +5,7 @@ weight: 3 {{< callout type="info" >}} -For information on how to create a cluster in an airgapped environment, refer -to airgap MKE 4 installation, refer to [Offline installation](../offline-installation). +For information on how to create a cluster in an airgapped environment, refer to [Offline installation](../offline-installation). {{< /callout >}} From 56e35b448b9b906cc7b20fe817b6950d0a8fde39 Mon Sep 17 00:00:00 2001 From: KoryKessel-Mirantis Date: Thu, 24 Apr 2025 21:18:58 +0200 Subject: [PATCH 11/17] Restructuring to handle offline upgrade content. --- .../getting-started/offline-installation.md | 28 ++++++------------- content/docs/migrate-from-MKE-3.md | 17 ++++++++++- 2 files changed, 25 insertions(+), 20 deletions(-) diff --git a/content/docs/getting-started/offline-installation.md b/content/docs/getting-started/offline-installation.md index 1dc1dd2c..1e095d97 100644 --- a/content/docs/getting-started/offline-installation.md +++ b/content/docs/getting-started/offline-installation.md @@ -78,7 +78,15 @@ You can download the MKE 4 artifacts from the [mke-release GitHub repo](https:// done; ``` -## New Installation ## +## Installation ## + +{{< callout type="info" >}} + +For information on performing an upgrade to an existing installation in an +airgap environment, refer to [Offline +upgrade](../../migrate-from-mke-3/#offline-upgrade). + +{{< /callout >}} 1. Refer to the [Create a Cluster](../create-cluster/#initialize-deployment) procedure for detail on how to create a `mke4.yaml` configuration file. @@ -91,26 +99,8 @@ how to create a `mke4.yaml` configuration file. | `.spec.registries.chartRegistry.URL` | Sets your registry address with a project path that contains your MKE 4 helm charts in OCI format. For example, `oci://private-registry.example.com:8080/mke`.

The setting must always start with `oci://`, and it must not end with a slash `/` .

If you uploaded the bundle as previously described, the registry address and path will be the same for chart and image registry, with the only difference being the `oci://` prefix in the chart registry URL. | | `.spec.airgap.enabled = true` | Indicates that your environment is airgapped. | - 3. Run the `mkectl apply` command. -## Upgrade ## - -To perform an offline upgrade from MKE 3 to MKE 4k, you adhere to the -procedure as described in [Migrate from MKE 3.x](../../migrate-from-mke-3), -adding the following flags to the `mkectl upgrade` command: - -* `--image-registry=` -* `--chart-registry=oci://` -* `--mke3-airgapped=true` - -{{< callout type="info" >}} - -For detail on the `mkectl upgrade` command flags, refer to the `mke4.yaml` -configuation file settings descriptions offered above for new installations. - -{{< /callout >}} - ## MKE 4 versus MKE 3 ## MKE 3 requires the use of the `docker load` command to load offline bundles diff --git a/content/docs/migrate-from-MKE-3.md b/content/docs/migrate-from-MKE-3.md index 832edb0b..44828098 100644 --- a/content/docs/migrate-from-MKE-3.md +++ b/content/docs/migrate-from-MKE-3.md @@ -254,7 +254,8 @@ mkectl upgrade --hosts-path \ ``` The external address is the domain name of the load balancer. For details, -see [System requirements: Load balancer requirements](../getting-started/system-requirements#load-balancer-requirements). +see [System requirements: Load balancer +requirements](../getting-started/system-requirements#load-balancer-requirements). The `--config-out` flag allows you to specify a path where the MKE 4 configuration file will be automatically created and saved during migration. If not specified, @@ -283,6 +284,20 @@ client bundle. The docker swarm cluster will no longer be accessible as well. {{< /callout >}} +### Offline upgrade + +To perform an offline upgrade from MKE 3 to MKE 4k, add the following flags to the `mkectl upgrade` command: + +* `--image-registry=` +* `--chart-registry=oci://` +* `--mke3-airgapped=true` + +| Setting | Description | +|------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `.spec.registries.imageRegistry.URL` | Sets your registry address with a project path that contains your MKE 4 images. For example, `private-registry.example.com:8080/mke`.

The setting must not end with a slash `/`.

The port is optional. | +| `.spec.registries.chartRegistry.URL` | Sets your registry address with a project path that contains your MKE 4 helm charts in OCI format. For example, `oci://private-registry.example.com:8080/mke`.

The setting must always start with `oci://`, and it must not end with a slash `/` .

If you uploaded the bundle as previously described, the registry address and path will be the same for chart and image registry, with the only difference being the `oci://` prefix in the chart registry URL. | +| `.spec.airgap.enabled = true` | Indicates that your environment is airgapped. | + ### Migration failure In the event of an upgrade failure, the upgrade process rolls back, From fe38421a845ef5759c0ed5c8a791104e2e8b3bc9 Mon Sep 17 00:00:00 2001 From: KoryKessel-Mirantis Date: Fri, 25 Apr 2025 00:26:11 +0200 Subject: [PATCH 12/17] Edits in response to DShishliannikov's second round of comments. --- content/docs/getting-started/offline-installation.md | 8 ++++---- content/docs/migrate-from-MKE-3.md | 5 ++++- 2 files changed, 8 insertions(+), 5 deletions(-) diff --git a/content/docs/getting-started/offline-installation.md b/content/docs/getting-started/offline-installation.md index 1e095d97..734a473b 100644 --- a/content/docs/getting-started/offline-installation.md +++ b/content/docs/getting-started/offline-installation.md @@ -7,7 +7,7 @@ The installation and upgrade procedures for MKE 4k reflect those of the online scenario. While the online installation, though, typically uses `registry.mirantis.com` as the primary OCI registry for MKE 4k materials, with the offline scenario you instead specify a private -registry from which to pull the MKE 4k artifacts, images, and charts. +registry from which to pull the MKE 4k images and charts. {{< callout type="info" >}} @@ -35,7 +35,7 @@ You can download the MKE 4 artifacts from the [mke-release GitHub repo](https:// from the command line as follows: ```bash - curl -L https://packages.mirantis.com/caas/mke_bundle_v4.1.0.tar.gz -o mke_bundle_v4.1.0.tar.gz + curl -L https://packages.mirantis.com/caas/mke_bundle_v.tar.gz -o mke_bundle_v.tar.gz ``` 2. Transfer the bundle file to a machine that can access your private registry. @@ -60,7 +60,7 @@ You can download the MKE 4 artifacts from the [mke-release GitHub repo](https:// 4. Upload the MKE 4k images and helm charts to your private registry: - ``` + ```bash # Login to the registry skopeo login "$REGISTRY_ADDRESS" -u "$REGISTRY_USERNAME" -p "$REGISTRY_PASSWORD" @@ -82,7 +82,7 @@ You can download the MKE 4 artifacts from the [mke-release GitHub repo](https:// {{< callout type="info" >}} -For information on performing an upgrade to an existing installation in an +For information on performing an upgrade to an existing MKE 3 installation in an airgap environment, refer to [Offline upgrade](../../migrate-from-mke-3/#offline-upgrade). diff --git a/content/docs/migrate-from-MKE-3.md b/content/docs/migrate-from-MKE-3.md index 44828098..e6749ca9 100644 --- a/content/docs/migrate-from-MKE-3.md +++ b/content/docs/migrate-from-MKE-3.md @@ -286,7 +286,10 @@ client bundle. The docker swarm cluster will no longer be accessible as well. ### Offline upgrade -To perform an offline upgrade from MKE 3 to MKE 4k, add the following flags to the `mkectl upgrade` command: +To perform an offline upgrade from MKE 3 to MKE 4k, [prepare your environment +as described in Offline +installation](../getting-started/offline-installation/#preparation), and add +the following flags to the `mkectl upgrade` command: * `--image-registry=` * `--chart-registry=oci://` From 3d2f8a04e5d123a0c4d9f0a148f2b43b62d7fb37 Mon Sep 17 00:00:00 2001 From: Kory <57411706+KoryKessel-Mirantis@users.noreply.github.com> Date: Fri, 25 Apr 2025 00:42:01 +0200 Subject: [PATCH 13/17] Update content/docs/migrate-from-MKE-3.md Transition to provided flag names. Co-authored-by: Dmitry Shishlyannikov --- content/docs/migrate-from-MKE-3.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/docs/migrate-from-MKE-3.md b/content/docs/migrate-from-MKE-3.md index e6749ca9..6b45361c 100644 --- a/content/docs/migrate-from-MKE-3.md +++ b/content/docs/migrate-from-MKE-3.md @@ -297,9 +297,9 @@ the following flags to the `mkectl upgrade` command: | Setting | Description | |------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `.spec.registries.imageRegistry.URL` | Sets your registry address with a project path that contains your MKE 4 images. For example, `private-registry.example.com:8080/mke`.

The setting must not end with a slash `/`.

The port is optional. | -| `.spec.registries.chartRegistry.URL` | Sets your registry address with a project path that contains your MKE 4 helm charts in OCI format. For example, `oci://private-registry.example.com:8080/mke`.

The setting must always start with `oci://`, and it must not end with a slash `/` .

If you uploaded the bundle as previously described, the registry address and path will be the same for chart and image registry, with the only difference being the `oci://` prefix in the chart registry URL. | -| `.spec.airgap.enabled = true` | Indicates that your environment is airgapped. | +| `--image-registry` | Sets your registry address with a project path that contains your MKE 4 images. For example, `private-registry.example.com:8080/mke`.

The setting must not end with a slash `/`.

The port is optional. | +| `--chart-registry` | Sets your registry address with a project path that contains your MKE 4 helm charts in OCI format. For example, `oci://private-registry.example.com:8080/mke`.

The setting must always start with `oci://`, and it must not end with a slash `/` .

If you uploaded the bundle as previously described, the registry address and path will be the same for chart and image registry, with the only difference being the `oci://` prefix in the chart registry URL. | +| `--mke3-airgapped=true` | Indicates that your environment is airgapped. | ### Migration failure From f0b01767c8132e382a63647b5fbb94ab0dca653b Mon Sep 17 00:00:00 2001 From: Kory <57411706+KoryKessel-Mirantis@users.noreply.github.com> Date: Fri, 25 Apr 2025 00:42:32 +0200 Subject: [PATCH 14/17] Update content/docs/getting-started/offline-installation.md Strip out vagueish 'artifacts' in favor of 'images and charts'. Co-authored-by: Dmitry Shishlyannikov --- content/docs/getting-started/offline-installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/getting-started/offline-installation.md b/content/docs/getting-started/offline-installation.md index 734a473b..c74656e7 100644 --- a/content/docs/getting-started/offline-installation.md +++ b/content/docs/getting-started/offline-installation.md @@ -19,7 +19,7 @@ You can download the MKE 4 artifacts from the [mke-release GitHub repo](https:// - [skopeo](https://github.com/containers/skopeo) 1.6.1 or later - An OCI-based private registry that is accessible from all cluster nodes. - - All MKE 4 artifacts and images must be publicly accessible, with no required authentication. + - All MKE 4 images and charts must be publicly accessible, with no required authentication. - The registry must use HTTPS, and the TLS certificates of the registry server must be signed by a publicly trusted Certificate Authority. Private certificate authorities or self-signed certificates are not currently supported. - The registry must support multi-level nesting. For example, From d3bb4f0a7f03f463b43efbffd423649f3e8b864f Mon Sep 17 00:00:00 2001 From: Kory <57411706+KoryKessel-Mirantis@users.noreply.github.com> Date: Tue, 29 Apr 2025 10:43:50 +0200 Subject: [PATCH 15/17] Update content/docs/getting-started/offline-installation.md Hyphenate 'repull'. Co-authored-by: Magdalena Dziadosz <160592158+MagdaDziadosz@users.noreply.github.com> --- content/docs/getting-started/offline-installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/getting-started/offline-installation.md b/content/docs/getting-started/offline-installation.md index c74656e7..485c086e 100644 --- a/content/docs/getting-started/offline-installation.md +++ b/content/docs/getting-started/offline-installation.md @@ -106,7 +106,7 @@ how to create a `mke4.yaml` configuration file. MKE 3 requires the use of the `docker load` command to load offline bundles directly into Docker on every cluster node. While this approach does not require you to have a private registry, it also means that the cluster cannot -repull the image should any of the loaded images go missing. As such, MKE 3 +re-pull the image should any of the loaded images go missing. As such, MKE 3 users must disable Kubernetes garbage collection, which can sometimes prune images of optional components that are not always enabled. This is not an issue with MKE 4, as images are pulled from a private registry that the customer From a41554dd3f5ca3d3a31727e4ddd8db9a5851ef06 Mon Sep 17 00:00:00 2001 From: Kory <57411706+KoryKessel-Mirantis@users.noreply.github.com> Date: Tue, 29 Apr 2025 10:44:22 +0200 Subject: [PATCH 16/17] Update content/docs/getting-started/offline-installation.md Remove extraneous ', though,'. Co-authored-by: Magdalena Dziadosz <160592158+MagdaDziadosz@users.noreply.github.com> --- content/docs/getting-started/offline-installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/getting-started/offline-installation.md b/content/docs/getting-started/offline-installation.md index 485c086e..1a4f89c9 100644 --- a/content/docs/getting-started/offline-installation.md +++ b/content/docs/getting-started/offline-installation.md @@ -4,7 +4,7 @@ weight: 3 --- The installation and upgrade procedures for MKE 4k reflect those of the online -scenario. While the online installation, though, typically uses +scenario. While the online installation typically uses `registry.mirantis.com` as the primary OCI registry for MKE 4k materials, with the offline scenario you instead specify a private registry from which to pull the MKE 4k images and charts. From 5a390aedbfd234fe04e2725141ddfca992ea59b3 Mon Sep 17 00:00:00 2001 From: Kory <57411706+KoryKessel-Mirantis@users.noreply.github.com> Date: Tue, 29 Apr 2025 10:44:50 +0200 Subject: [PATCH 17/17] Bought an 'n'. Co-authored-by: Magdalena Dziadosz <160592158+MagdaDziadosz@users.noreply.github.com> --- content/docs/getting-started/offline-installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/getting-started/offline-installation.md b/content/docs/getting-started/offline-installation.md index 1a4f89c9..0ae09400 100644 --- a/content/docs/getting-started/offline-installation.md +++ b/content/docs/getting-started/offline-installation.md @@ -89,7 +89,7 @@ upgrade](../../migrate-from-mke-3/#offline-upgrade). {{< /callout >}} 1. Refer to the [Create a Cluster](../create-cluster/#initialize-deployment) procedure for detail on -how to create a `mke4.yaml` configuration file. +how to create an `mke4.yaml` configuration file. 2. Add the following additional settings to the `mke4.yaml` configuration file: