#Upgrade Alauda AI

This procedure describes the migration from the Alauda AI 2.3.x deployment model to the Alauda AI 2.8.x deployment model. Read the complete procedure before starting. The upgrade changes the deployment form of several components, and some components require migration rather than an in-place upgrade.

#Prepare the Upgrade Packages

Upload the Alauda AI 2.8.x operator package and all required dependency packages before starting the upgrade. Upload packages to the cluster where the corresponding component will run. For the common package download, violet setup, and upload procedure, see Upload Packages.

The required package set depends on the features enabled in the existing environment. At minimum, prepare the following packages for an Alauda AI 2.8.x environment:

The exact package filenames and versions are delivered with the Alauda AI 2.8.x release. Do not substitute packages from Alauda AI 2.3.x.

#Uploading operator packages

The common package guide includes the violet push command, external-registry options, and a multi-package upload example. Use Upload Packages to upload each package using the filename and target-cluster information supplied with the Alauda AI 2.8.x release.

#Pre-Upgrade Operations

Complete the following operations before upgrading Alauda AI.

#Preserve existing resources

Review the migration requirements for each component and preserve the resources that must survive the migration. The components in this upgrade are designed to retain their data; keep the data in place rather than recreating it where possible. At a minimum, preserve and record:

• AmlCluster resources and their current YAML configuration.
• Custom resources managed by Workbench, MLflow, LWS, KServe, and other enabled components.
• Workspaces, WorkspaceKind resources, the aml-workbench-config ConfigMap, and user PVCs.
• MLflow metadata and artifact-storage configuration.
• Inference-service configuration and model-storage configuration.
• Any component-specific secrets, ConfigMaps, RoleBindings, and authorization policies.

Use the component-specific backup instructions before uninstalling the old deployment form. For example, the Workbench upgrade guide backs up Workbench resources and requires preserving user PVCs.

#Check the target cluster

Confirm that:

1. The target cluster is healthy and has sufficient capacity for the new operators and their operands.
2. The target cluster can pull images from the configured registry.
3. The required storage classes and persistent volumes are available.
4. The platform administrator credentials can upload packages and install Operators through OperatorHub.
5. The global cluster can be accessed with kubectl for the global migration steps described below.

#Remove Cluster Plugins

Alauda AI 2.8.x changes several components from Cluster Plugins to Operators. These deployment forms do not support an in-place upgrade. Before upgrading Alauda AI, remove the old Cluster Plugin versions of the components that are installed in the existing environment:

• Alauda AI Essentials from the global cluster.
• Alauda Build of LeaderWorkerSet from the target cluster.
• Alauda AI Workbench from the target cluster.
• MLflow from the target cluster.

Use the following common procedure:

1. Record the existing custom resources and configuration for the components that are installed.
2. Preserve the related user data, including Workbench PVCs, MLflow databases and artifacts, and workloads managed by LeaderWorkerSet.
3. In Administrator > Marketplace > Cluster Plugins, select the relevant cluster:
   • Select the global cluster and uninstall Alauda AI Essentials, if it is installed.
   • Select the target cluster and uninstall the installed Alauda Build of LeaderWorkerSet, Alauda AI Workbench, and MLflow Cluster Plugins.
4. Do not delete the preserved PVCs, databases, object-storage artifacts, or custom resources unless the component-specific migration procedure explicitly requires it.
5. After the old Cluster Plugins are removed, enable the replacement components through the Alauda AI 2.8.x deployment model. The upgraded AmlCluster installs and reconciles Alauda Build of LeaderWorkerSet when lws.managementState is Managed. Install the replacement Operators and create their custom resources for Alauda AI Workbench and MLflow as described in their component-specific documentation.

The existing cluster-scoped AmlCluster resource named default controls the Alauda AI deployment configuration. After upgrading Alauda AI, use this resource to configure components managed by Alauda AI, including Alauda Build of LeaderWorkerSet. Components delivered as independent Operators, such as Workbench and MLflow, are deployed and configured through their own Operator custom resources.

For Workbench-specific data-preservation requirements, see Migrating from the Workbench Cluster Plugin. For the replacement Operator custom resources, see Install Workbench and Install MLflow.

#Prepare the Global Cluster

Alauda AI 2.8.x uses the single-cluster application architecture. Global resources are no longer supplied by the old Alauda AI Essentials (aml-global) Cluster Plugin.

The following commands must run against the global cluster, not the cluster where the Alauda AI workloads run. Complete them after uninstalling the old Alauda AI Essentials Cluster Plugin.

#Run global-install.sh

Download the global-install.sh script supplied with the Alauda AI 2.8.x documentation or release package. On the global cluster, run it with the name of the cluster where Alauda AI is installed:

kubectl config use-context <global-cluster-context>
bash global-install.sh <target-cluster-name>

The script creates or verifies the global OAuth2Client, OIDC Secret, and ProductEntry resources used by Alauda AI. Verify the resources after the script completes:

kubectl get oauth2client -n cpaas-system
kubectl get productentry

The Alauda AI entry should be available in the platform console after the platform synchronizes the new ProductEntry.

#Run migrate-roles.sh

Run the migrate-roles.sh script supplied with the Alauda AI 2.8.x release on the global cluster after the old Alauda AI Essentials plugin has been removed.

Use the command-line usage and arguments provided by the delivered script. The exact invocation is intentionally not included until the release script is added to the documentation package. Confirm that the script completes successfully and that the migrated namespace permissions are present before continuing.

#Upgrade Alauda AI

1. Log in to the Web Console and open the Administrator view.
2. Go to Marketplace > OperatorHub.
3. Select the target cluster.
4. Open Alauda AI.
5. Review the available version and select the Alauda AI 2.8.x version.
6. Confirm the upgrade and wait for the OperatorHub installation status to become Installed.

During the upgrade, the existing cluster-scoped AmlCluster resource named default is upgraded automatically. The upgraded AmlCluster automatically enables the following components:

• PostgreSQL
• Alauda Cache Service for Redis OSS
• Alauda Build of Authorino
• Alauda Build of KServe
• Alauda Build of LeaderWorkerSet

You can manually enable the following optional components in the AmlCluster configuration when they are required:

• MLflow Operator
• Alauda AI Workbench Operator
• Alauda Build of Serving Runtime

For the AmlCluster configuration, registry settings, component options, and installation details, see Install Alauda AI.

#Post-Upgrade Operations

#Verify Alauda AI

Check the status of the cluster-scoped AmlCluster resource:

kubectl get amlcluster default

The resource should be Ready:

NAME      PHASE   READY   REASON
default   Ready   True    Reconciled

#Verify KServe

If Alauda Build of KServe is installed, verify the KServe instance:

kubectl get kserve default-kserve -n kserve-operator

The instance should report DEPLOYED: True:

NAME             DEPLOYED   REASON
 default-kserve   True       UpgradeSuccessful

#Verify Operators and migrated components

Verify the OperatorHub and workload status for every installed dependency:

• Confirm each required component is Installed and its ClusterServiceVersion reports Succeeded.
• Confirm the PostgreSQL, Redis, and Authorino services required by enabled features are ready.
• Confirm the LWS controller is running and a representative distributed workload can start.
• Confirm the MLflow tracking server is ready and can access existing metadata and artifacts.
• Confirm the Workbench custom resource is ready, existing Workspaces and PVCs are present, and a test Workbench can be opened.
• Confirm existing KServe inference services and representative model requests work as expected.
• On the global cluster, confirm the OAuth2Client and ProductEntry resources created by global-install.sh, and verify that users can open Alauda AI through the platform entry.

#Verify data preservation

Confirm that the following data is still available before declaring the upgrade complete:

• User PVCs and Workbench home directories.
• Existing Workspaces and retained WorkspaceKind resources.
• MLflow metadata and model artifacts.
• Existing inference-service configuration and model data.
• Distributed-workload configuration and checkpoints.

If a component does not reconcile successfully, stop further migration and use the component-specific backup and rollback procedure. Do not delete CRDs while custom resources still exist; deleting a CRD can also delete the custom resources stored in the cluster.