DKP Essential Upgrade
Upgrade your Konvoy environment within the DKP Essential License.
Prerequisites
Create an on-demand backup of your current configuration with Velero.
Follow the steps listed in the DKP upgrade overview.
Check what version of DKP you have downloaded currently using cli command dkp version.
Ensure that all platform applications in the management cluster are upgraded to avoid compatibility issues with the Kubernetes version included in this release. This is done automatically when upgrading Kommander, so ensure that you upgrade Kommander prior to upgrading Konvoy.
Set the appropriate environment variables:
For air-gapped: Download the required bundles either at our support site or by using the CLI.
For Azure, set the required environment variables.
For AWS, set the required environment variables.
For vSphere, set the required environment variables.
For GCP, set the required environment variables.
vSphere only: If you want to resize your disk, ensure you have reviewed Create a vSphere Base OS Image.
Overview
To upgrade Konvoy for DKP Essential:
Upgrade the Cluster API (CAPI) components.
Upgrade the core addons.
Upgrade the Kubernetes version.
If you have more than one Essential cluster, repeat all of these steps for each Essential cluster. For a full list of DKP Essential features, see DKP Essential.
For air-gapped environments, you must run
konvoy-image upload artifacts
to copy the artifacts onto the cluster hosts before you begin the Upgrade the CAPI Components section below.- CODE
konvoy-image upload artifacts \ --container-images-dir=./artifacts/images/ \ --os-packages-bundle=./artifacts/$OS_PACKAGES_BUNDLE \ --containerd-bundle=artifacts/$CONTAINERD_BUNDLE \ --pip-packages-bundle=./artifacts/pip-packages.tar.gz
For air-gapped environments, seed the docker registry as explained here: Air-gapped Seed the Registry
Upgrade the CAPI components
New versions of DKP come pre-bundled with newer versions of CAPI, newer versions of infrastructure providers, or new infrastructure providers. When using a new version of the DKP CLI, upgrade all of these components first.
Ensure your dkp
configuration references the management cluster where you want to run the upgrade by setting the KUBECONFIG
environment variable, or using the --kubeconfig
flag, in accordance with Kubernetes conventions.
Run the following upgrade command for the CAPI components:
If you created CAPI components using flags to specify values, use those same flags during Upgrade to preserve existing values while setting additional values.
Refer to dkp create cluster for flag descriptions for
--with-aws-bootstrap-credentials
and--aws-service-endpoints
Refer to the HTTP section for details: Universal Configurations for all Infrastructures
dkp upgrade capi-components
The command should output something similar to the following:
✓ Upgrading CAPI components
✓ Waiting for CAPI components to be upgraded
✓ Initializing new CAPI components
✓ Deleting Outdated Global ClusterResourceSets
If the upgrade fails, review the prerequisites section and ensure that you’ve followed the steps in the DKP upgrade overview.
Upgrade the Core Addons
To install the core addons, DKP relies on the ClusterResourceSet
Cluster API feature. In the CAPI component upgrade, we deleted the previous set of outdated global ClusterResourceSets
because in past releases, some addons were installed using a global configuration. In order to support individual cluster upgrades, DKP now installs all addons with a unique set of ClusterResourceSets
and corresponding referenced resources, all named using the cluster’s name as a suffix. For example: calico-cni-installation-my-aws-cluster
.
If you modify any of the ClusterResourceSet
definitions, these changes are not be preserved when running the command dkp upgrade addons
. You must use the --dry-run -o yaml
options to save the new configuration to a file and continue the same changes upon each upgrade.
Your cluster comes preconfigured with a few different core addons that provide functionality to your cluster upon creation. These include: CSI, CNI, Cluster Autoscaler, and Node Feature Discovery. New versions of DKP may come pre-bundled with newer versions of these addons.
If you have more than one essential cluster, ensure your dkp
configuration references the cluster where you want to run the upgrade by setting the KUBECONFIG
environment variable, or using the --kubeconfig
flag, in accordance with Kubernetes conventions.
Perform the following steps to update your addons.
Ensure your
dkp
configuration references the cluster where you want to run the upgrade by setting theKUBECONFIG
environment variable, or using the--kubeconfig
flag, in accordance with Kubernetes conventions.Upgrade the core addons in a cluster using the
dkp upgrade addons
command specifying the cluster infrastructure (chooseaws
,azure
,vsphere
,eks
,gcp
,preprovisioned
) and the name of the cluster.
Examples for upgrade core addons commands:
export CLUSTER_NAME=my-azure-cluster
dkp upgrade addons azure --cluster-name=${CLUSTER_NAME}
OR
export CLUSTER_NAME=my-aws-cluster
dkp upgrade addons aws --cluster-name=${CLUSTER_NAME}
The output for the AWS example should be similar to:
Generating addon resources
clusterresourceset.addons.cluster.x-k8s.io/calico-cni-installation-my-aws-cluster upgraded
configmap/calico-cni-installation-my-aws-cluster upgraded
clusterresourceset.addons.cluster.x-k8s.io/tigera-operator-my-aws-cluster upgraded
configmap/tigera-operator-my-aws-cluster upgraded
clusterresourceset.addons.cluster.x-k8s.io/aws-ebs-csi-my-aws-cluster upgraded
configmap/aws-ebs-csi-my-aws-cluster upgraded
clusterresourceset.addons.cluster.x-k8s.io/cluster-autoscaler-my-aws-cluster upgraded
configmap/cluster-autoscaler-my-aws-cluster upgraded
clusterresourceset.addons.cluster.x-k8s.io/node-feature-discovery-my-aws-cluster upgraded
configmap/node-feature-discovery-my-aws-cluster upgraded
clusterresourceset.addons.cluster.x-k8s.io/nvidia-feature-discovery-my-aws-cluster upgraded
configmap/nvidia-feature-discovery-my-aws-cluster upgraded
See Also
DKP upgrade addons for more CLI command help.
Upgrade the Kubernetes version
When upgrading the Kubernetes version of a cluster, first upgrade the control plane and then the node pools.
Build a new image if applicable.
If an AMI was specified when initially creating a cluster for AWS, you must build a new one with Konvoy Image Builder.
If an Azure Machine Image was specified for Azure, you must build a new one with Konvoy Image Builder.
If a vSphere template Image was specified for vSphere, you must build a new one with Konvoy Image Builder.
You must build a new GCP image with Konvoy Image Builder.
Upgrade the Kubernetes version of the control plane. Each cloud provider has distinctive commands. Below is the AWS command example. Select the drop-down menu next to your provider for compliant CLI.
NOTE: The first example below is for AWS. If you created your initial cluster with a custom AMI using the--ami
flag, it is required to set the--ami
flag during the Kubernetes upgrade.CODEdkp update controlplane aws --cluster-name=${CLUSTER_NAME} --kubernetes-version=v1.25.4
If you need to verify or discover your cluster name to use with this example, first run the kubectl get clusters
command.
The output should be similar to the below example, with the provider name corresponding to the CLI you executed from the choices above:
Some advanced options are available for various providers. An example would be regarding AMI instance type: aws: --ami, --instance-type
. To see all the options for your particular provider, run this command dkp update controlplane aws|vsphere|preprovisioned|gcp|azure --help
for more advance options.
NOTE: The commanddkp update controlplane {provider}
has a 30 minute default timeout for the update process to finish. If you see the error "timed out waiting for the condition
“, you can check the control plane nodes version using the command kubectl get machines -o wide $KUBECONFIG
before trying again.
The output should be similar to:
Updating control plane resource controlplane.cluster.x-k8s.io/v1beta1, Kind=KubeadmControlPlane default/my-aws-cluster-control-plane
Waiting for control plane update to finish.
✓ Updating the control plane
kubectl set image -n kube-system daemonset.v1.apps/kube-proxy kube-proxy=docker.io/mesosphere/kube-proxy:v1.25.4_fips.0
3. Upgrade the Kubernetes version of your node pools. Upgrading a node pool involves draining the existing nodes in the node pool and replacing them with new nodes. In order to ensure minimum downtime and maintain high availability of the critical application workloads during the upgrade process, we recommend deploying Pod Disruption Budget (Disruptions) for your critical applications. For more information, refer to Update Cluster Nodepools documentation.
a. First, get a list of all node pools available in your cluster by running the following command:
dkp get nodepool --cluster-name ${CLUSTER_NAME}
b. Select the nodepool you want to upgrade with the command below:
export NODEPOOL_NAME=my-nodepool
c. Then update the selected nodepool using the command below. The first example command shows AWS language, so select the drop-down menu for your provider for the correct command. Execute the update
command for each of the node pools listed in the previous command.
NOTE: The first example below is for AWS. If you created your initial cluster with a custom AMI using the --ami
flag, it is required to set the --ami
flag during the Kubernetes upgrade.
dkp update nodepool aws ${NODEPOOL_NAME} --cluster-name=${CLUSTER_NAME} --kubernetes-version=v1.25.4
The output should be similar to the following, with the name of the infrastructure provider shown accordingly:
Updating node pool resource cluster.x-k8s.io/v1beta1, Kind=MachineDeployment default/my-aws-cluster-my-nodepool
Waiting for node pool update to finish.
✓ Updating the my-aws-cluster-my-nodepool node pool
4. Repeat this step for each additional node pool.
When all nodepools have been updated, your upgrade is complete. For the overall process for upgrading to the latest version of DKP, refer back to DKP Upgrade for more details.
For the overall process for upgrading to the latest version of DKP, refer back to DKP Upgrade.