Upgrade the Configuration#

To upgrade an MKE 3 cluster with GPU enabled, ensure you complete the GPU prerequisites before starting the upgrade process.

Kubernetes Custom Flags#

MKE 3 and MKE 4 both support the application of additional flags to Kubernetes components that have the following fields in the MKE configuration file, each specified as a list of strings:

custom_kube_api_server_flags
custom_kube_controller_manager_flags
custom_kubelet_flags
custom_kube_scheduler_flags
custom_kube_proxy_flags

MKE 4 supports an extraArgs field for each of these components, though, which accepts a map of key-value pairs. During upgrade from MKE 3, MKE 4 converts these custom flags to the corresponding extraArgs field. Any flags that cannot be automatically converted are listed in the upgrade summary.

Custom flags conversion example#

The following example shows a kube-apiserver custom flag before and after conversion:

MKE 3 configuration file:

[cluster_config.custom_kube_api_server_flags] = ["--enable-garbage-collector=false"]

MKE 4 configuration file:

spec:
  apiServer:
    extraArgs:
      enable-garbage-collector: false

Custom flag validation#

During conversion, mkectl upgrade checks the flag names in each of the following MKE 3 settings against the flags that the corresponding component accepts in the Kubernetes version that MKE 4 deploys. For that version, refer to Major component versions.

MKE 3 setting	Component
`custom_kube_api_server_flags`	kube-apiserver
`custom_kube_controller_manager_flags`	kube-controller-manager
`custom_kube_scheduler_flags`	kube-scheduler
`custom_kubelet_flags`	kubelet

A flag that was removed or renamed upstream is still copied to extraArgs, and the component fails to start after the upgrade. The upgrade summary lists each such flag under Configuration Warnings, along with any other conversion warnings:

Configuration Warnings
----------------------
- custom_kube_api_server_flags: "--insecure-port" is not a valid kube-apiserver flag for Kubernetes 1.35.4; it was removed or renamed and will cause kube-apiserver to fail on start. Remove or replace it before upgrading.
- custom_kube_controller_manager_flags: "--pod-eviction-timeout" is not a valid kube-controller-manager flag for Kubernetes 1.35.4; it was removed or renamed and will cause kube-controller-manager to fail on start. Remove or replace it before upgrading.

Warning

Invalid flags do not stop the upgrade. The upgrade reports them only after it completes, and does not report them at all if it fails. To review the warnings without changing the cluster, run mkectl upgrade --dry-run first.

To resolve a flag warning:

Check the Kubernetes changelog for each minor release from your MKE 3 Kubernetes version through the version that MKE 4 deploys. Look for the flag under Deprecation or API Change.
Optional. Confirm the valid flags on the reference page for the component, such as kube-apiserver.
Remove the flag from the MKE 3 configuration, or replace it with its renamed equivalent.
Run mkectl upgrade --dry-run again to confirm that the warning is gone.

The mkectl upgrade command checks flag names only, not values. Manually review the values of all custom flags, along with the names of flags in the following cases, which mkectl does not validate:

custom_kubelet_flags_profiles. MKE 4 converts these flags separately, as described in Kubelet Custom Flag Profiles.
custom_kubelet_flags, when mkectl cannot determine the set of valid kubelet flags. In that case, mkectl skips kubelet validation rather than report valid flags as invalid.

MKE 4 does not migrate custom_kube_proxy_flags, so mkectl does not validate it. Instead, mkectl logs a warning and drops the setting.

Kubelet Custom Flag Profiles#

MKE 3 supports a map of kubelet flag profiles to specific nodes using the custom_kubelet_flags_profiles setting in the toml configuration file.

MKE 4 does not support kubelet flag profiles, but you can use Kubelet custom profiles to map KubeletConfiguration values to specific nodes. MKE 4 does support the migration of MKE 3 kubelet flag profiles to kubelet custom profiles.

The conversion of flags to KubeletConfiguration values is best-effort, and any flags that cannot be converted are listed in the upgrade summary. Hosts with a custom flag profile label are marked for the corresponding kubelet custom profile.

A --tls-cipher-suites flag in an MKE 3 profile becomes the tlsCipherSuites value of the corresponding MKE 4 custom profile. Cipher names that are stored using their MKE 3 spelling are normalized to the canonical MKE 4 names as part of this conversion, which is what allows a migrated profile to pass the cipher validation that is described in TLS cipher suites.

TLS cipher suites#

MKE 3 hardens control-plane TLS ciphers through the per-component cipher_suites_for_kube_api_server, cipher_suites_for_kubelet, and cipher_suites_for_etcd_server settings.

On upgrade, MKE 4 migrates these settings as follows:

Each cipher_suites_for_* list maps to the tlsCipherSuites field of the corresponding component:
- spec.apiServer
- spec.kubelet
- spec.etcd
These lists are migrated unchanged in every case, including when the setting is left false. The MKE 3 reconcilers pass --tls-cipher-suites whenever the field is non-empty, with no hardening check, and thus the lists are live configuration on the running cluster and must survive the upgrade.

Cipher-suite names that MKE 3 stored using their legacy spelling, such as TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305, are normalized to the canonical name that MKE 4 expects, which is TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256.
When the policy is inherited, the upgrade summary reports it under a TLS Ciphers heading. This heading names the benchmark revision, lists the suites that are now enforced, and notes that a per-component list still takes precedence. In FIPS mode, the summary excludes the non-FIPS ChaCha20 suites and lists the six suites that apply. If the setting is not migrated, the summary prints nothing.

Pre-Logon Message#

MKE 3 supports a banner that displays above the login form that you set using the pre_logon_message field in the MKE 3 configuration file. This setting is converted automatically during the upgrade process, into the authentication.preLogonMessage field of the mke4.yaml configuration file.

Example: Pre-logon message conversion:

MKE 3 configuration file:

[cluster_config]
  pre_logon_message = "Authorized use only.\nActivity is monitored."

mke4.yaml configuration file:

spec:
  authentication:
    preLogonMessage: |-
      Authorized use only.
      Activity is monitored.

Refer to Set a pre-logon message for more information.