Upgrade Scenarios#
Upgrading to MKE 4.1.4 introduces changes in how ingress and external access are managed, particularly around the use of load balancers and Gateway ports. Because ingress configurations can vary between environments, the upgrade process is not one-size-fits-all. Instead, it depends on whether ingress is enabled in the source cluster and whether it should be retained after the upgrade.
The information herein outlines the supported upgrade paths and required actions for each scenario. It highlights when upgrades are possible, what infrastructure adjustments (such as load balancer provisioning) are needed, and how to correctly invoke the mkectl upgrade command with the appropriate parameters.
Carefully review the scenario that matches your current setup to ensure a smooth and successful upgrade and to avoid unsupported configurations.
From MKE 3.7 and MKE 3.8#
| Ingress enabled in source | Ingress retained | Action | To invokemkectl upgrade |
|---|---|---|---|
| No | No | Provision a load balancer that maps from gateway-listener-port to gateway-https-node-port. |
mkectl upgrade --external-address <load-balancer-DNS>:<gateway-listener-port-number> --gateway-https-node-port <value> --gateway-http-node-port <value>. The three parameters are all required. The --gateway-listener-port parameter, however, is not allowed. If the Gateway listener port number is omitted from the --external-address parameter, port 443 is assumed. |
| No | Yes | Scenario not supported. If ingress-nginx was not initially enabled in the source MKE 3 cluster, it implies the --remove-ingress-nginx parameter even when it is not explicitly specified. |
NA |
| Yes | No | Provision a load balancer that maps from gateway-listener-port to either gateway-https-node-port, which takes precedence if specified, or to the configured HTTPS NodePort for ingress-controller. |
mkectl upgrade --external-address <load-balancer-DNS>:<gateway-listener-port-number> --gateway-https-node-port <value> --gateway-http-node-port <value>. The --external-address --gateway-https-node-port <value> and --gateway-http-node-port <value>, are optional; when they are not included, the values originally configured for ingress controller are carry forward. The --gateway-listener-port parameter is not allowed. If the Gateway listener port number is omitted from the --external-address parameter, port 443 is assumed. |
| Yes | Yes | Provisions a load balancer that maps from gateway-listener-port to gateway-https-node-port. |
mkectl upgrade --external-address <load-balancer-DNS>:<gateway-listener-port-number> --gateway-https-node-port <value> --gateway-http-node-port <value>. The three parameters are all required. The --gateway-listener-port parameter, however, is not allowed. If the Gateway listener port number is omitted from the --external-address parameter, port 443 is assumed. |
From MKE 4k 4.1.2#
| Ingress enabled in source | Ingress retained | Action | To invokemkectl upgrade |
|---|---|---|---|
| No | No | Scenario not supported. Ingress-nginx must be enabled in MKE 4k clusters prior to version 4.1.2. | NA |
| No | Yes | Upgrade not supported. Ingress-nginx must be enabled in MKE 4k clusters prior to version 4.1.2. | NA |
| Yes | No | After the upgrade, only the Gateway controller remains active, and the existing ingress NodePorts are preserved and guaranteed to remain valid. As a result, these NodePorts can be reused with no changes required. In addition, no additional load balancer configuration is needed. The existing load balancer, which currently routes traffic to the ingress HTTPS NodePort, will continue to function correctly, as that port is repurposed for the gateway HTTPS NodePort during the upgrade process. | The use of --keep-ingress-nginx, --gateway-https-node-port, --gateway-http-node-port, or --gateway-listener-port will cause the upgrade to fail. |
| Yes | Yes | Provision a load balancer with a mapping from the gateway-listener-port to the gateway-https-node-port. |
All four of the mkectl upgrade command parameters are required: --keep-ingress-nginx, --gateway-https-node-port <value>, --gateway-http-node-port <value>, and --gateway-listener-port <value>. |
From MKE 4k 4.1.3#
| Ingress enabled in source | Ingress retained | Action | To invokemkectl upgrade |
|---|---|---|---|
| No | No | No action is necessary as MKE 4k 4.1.4 will use the existing load balancer and Gateway NodePort configuration. | Do not use any of the gateway paramters with the mkectl upgrade command. |
| Yes | No | Scenario not supported. MKE 4k 4.1.3 is limited to fresh installations, and beginning with that product version, ingress-nginx cannot be enabled on fresh MKE 4k installations. | NA |