How to Migrate Standard Package PackageInstall (PKGi) in Workload Clusters to VKS Addons
search cancel

How to Migrate Standard Package PackageInstall (PKGi) in Workload Clusters to VKS Addons

book

Article ID: 415972

calendar_today

Updated On:

Products

Tanzu Kubernetes Runtime VMware vSphere Kubernetes Service

Issue/Introduction

Workload clusters using standard packages as PackageInstalls (PKGI) will need to be migrated to the new VKS addon management.

This KB article will provide steps on how to manually migrate packageInstalls installed from standard package repositories that running in workload clusters to VKS addon equivalents.

Environment

vSphere 8.X

vSphere Supervisor 8.X

VKS 3.5.0 or higher

Resolution

For vSphere 8.X environments:

  1. Upload the attached "pkgi-migrate.sh" script to a jumpbox with access to the workload cluster's context


  2. Change the permissions of the shell script:
    chmod a+x ./pkgi-migrate.sh

     

  3. Connect into the workload cluster context with the desired PKGI to be migrated


  4. List the PKGI to be migrated, it may be easiest to save this output separately as it will be used as a reference in future steps:
    kubectl get pkgi -A

    Automatically installed system PKGi that do not need to be migrated:

    • antrea
    • vsphere-pv-csi
    • vsphere-cpi
    • kapp-controller
    • guest-cluster-auth-service
    • metrics-server
    • gateway-api
    • secretgen-controller
    • pinniped
    • calico
    • csi-proxy (deprecated in KR 1.34)
    • capabilities (deprecated in KR 1.31)


  5. Run the script against the PKGI to be migrated, replacing the below values in brackets <> accordingly for each PKGI:
    ./pkgi-migrate.sh -c <workload cluster name> -s <PKGI namespace> -p <PKGI name>

     

 

For vSphere 9.X environments:

  1. Connect into the workload cluster's context using VCF CLI:
    vcf context list

vcf context use <workload cluster context>

     

  2. List the PKGI to be migrated, it may be easiest to save this output separately as it will be used as a reference in future steps:
    vcf package installed list -A

    • Automatically installed system PKGi that do not need to be migrated:

      • antrea
      • vsphere-pv-csi
      • vsphere-cpi
      • kapp-controller
      • guest-cluster-auth-service
      • metrics-server
      • gateway-api
      • secretgen-controller
      • pinniped
      • calico
      • csi-proxy (deprecated in KR 1.34)
      • capabilities (deprecated in KR 1.31)

  3. If applicable, save the data values file for the PKGI into a file:
    vcf package installed get <package name> -n <package namespace> --values-file-output <values filename>.out

    If the PKGI uses only default values, the above file will be empty.

  4. Connect into the Supervisor cluster context with the workload cluster's namespace using VCF CLI:
    vcf context use <supervisor-context>:<workload cluster namespace>

     

  5. List all available VKS addons:
    vcf addon available list

     

  6. Confirm on the VKS addon and available versions:
    vcf addon available list <addon name>

     

  7. Perform the migration to VKS addon by specifying the PKGI package name and the desired VKS addon name with version:
    If the data values file for the PKGI was empty, the -f flag can be omitted:
    vcf addon install migrate <package name> --addon-name <addon name> --cluster-name <workload cluster name> -v <addon version> -f <data values filename>.out

     

  8. Check and validate the migration to VKS addon:
    vcf addon install list --cluster-name <workload cluster name>

    An addon in Ready=True state indicates that the migration completed successfully and it is working without issue.
    For any addons in Ready=False state, check the below section for troubleshooting.

Additional Information

Troubleshooting VKS Addon Migration Issues

If the migration fails, or the VKS addon remains in Ready=False state, see the below troubleshooting steps accordingly.

  1. Connect into the Supervisor cluster context with the workload cluster's namespace: 
    vcf context use <supervisor-context>:<workload cluster namespace>

     

  2. Check the list of installed VKS addons:
    vcf addon install list --cluster-name <workload cluster name>

    If the migrated PKGI is not present in the above list, check that the "vcf addon install migrate" command was run properly and re-run it once more.

If you encounter "unable to get the Configmap" errors, the VKS addon will need to be created manually:

  • Run the VKS addon creation command (with the data values file, if applicable):

    vcf addon install create <addon name> --cluster-name <workload cluster name> -f <data values file>.out

     

If the VKS Addon is listed, but remains in Ready=False state:

  • Update the installation (with the data values file, if applicable):
    vcf addon install update <addon name> --cluster-name <workload cluster> -f <data values file>.out

     

  • Check the status and details of the VKS addon:
    vcf addon install get <addon name> --cluster-name <workload cluster name>

     

(OPTIONAL) Verify AddonConfig Resources for configuration accuracy:

  • List all addonConfigs in the workload cluster's namespace:
    kubectl get AddonConfig -n <workload cluster namespace>

     

  • View the YAML for the addonConfig:
    kubectl get AddonConfig <addonconfig name> -n <workload cluster namespace> -o yaml

 

 

Powered by Wolken Software