Upgrade indirect mode Azure Arc data controller using the CLI

This article describes how to upgrade an indirectly connected Azure Arc-enabled data controller using the Azure CLI (az).

Important

This article does not apply to a directly connected Azure Arc-enabled data controller. For the latest information about how to upgrade a directly connected data controller, see the release notes.

Prerequisites

You will need an indirect mode data controller with the imageTag v1.0.0_2021-07-30 or later.

To check the version, run:

kubectl get datacontrollers -n -o custom-columns=BUILD:.spec.docker.imageTag

Install tools

Before you can proceed with the tasks in this article you need to install:

Examples in this article use angle brackets < ... > to identify values that you need to replace before you run the script. Replace the brackets and the values inside the brackets.

View available images and chose a version

Pull the list of available images for the data controller with the following command:

az arcdata dc list-upgrades --k8s-namespace <namespace> –-use-k8s

The command above returns output like the following example:

Found 2 valid versions.  The current datacontroller version is v1.0.0_2021-07-30.
v1.1.0_2021-11-02
v1.0.0_2021-07-30

Upgrade data controller

This section shows how to upgrade a data controller in indirect mode.

Note

Some of the data services tiers and modes are generally available and some are in preview. If you install GA and preview services on the same data controller, you can't upgrade in place. To upgrade, delete all non-GA database instances. You can find the list of generally available and preview services in the Release Notes.

Indirect mode

You will need to connect and authenticate to a Kubernetes cluster and have an existing Kubernetes context selected prior to beginning the upgrade of the Azure Arc data controller.

You can perform a dry run first. The dry run validates the registry exists, the version schema, and the private repository authorization token (if used). To perform a dry run, use the --dry-run parameter in the az arcdata dc upgrade command. For example:

az arcdata dc upgrade --desired-version <version> --k8s-namespace <namespace> --dry-run --use-k8s

The output for the preceding command is:

Preparing to upgrade dc arcdc in namespace arc to version 20211024.1.
Preparing to upgrade dc arcdc in namespace arc to version 20211024.1.
****Dry Run****
Arcdata Control Plane would be upgraded to: 20211024.1

To upgrade the data controller, run the az arcdata dc upgrade command. If you don't specify a target image, the data controller will be upgraded to the latest version. The following example uses a local variable ($version) to use the version you selected previously (View available images and chose a version).

az arcdata dc upgrade --desired-version $version --k8s-namespace <namespace> --use-k8s

The output for the preceding command shows the status of the steps:

Preparing to upgrade dc arcdc in namespace arc to version 20211024.1.
Preparing to upgrade dc arcdc in namespace arc to version 20211024.1.
Creating service account: arc:cr-upgrade-worker
Creating cluster role: arc:cr-upgrade-worker
Creating cluster role binding: arc:crb-upgrade-worker
Cluster role binding: arc:crb-upgrade-worker created successfully.
Cluster role: arc:cr-upgrade-worker created successfully.
Service account arc:cr-upgrade-worker has been created successfully.
Creating privileged job arc-elevated-bootstrapper-job

Monitor the upgrade status

You can monitor the progress of the upgrade with kubectl or CLI.

kubectl

kubectl get datacontrollers --namespace <namespace>
kubectl get monitors --namespace <namespace>

The upgrade is a two-part process. First the controller is upgraded, then the monitoring stack is upgraded. During the upgrade, use kubectl get monitors -n <namespace> -w to view the status. The output will be:

NAME           STATUS     AGE
monitorstack   Updating   36m
monitorstack   Updating   36m
monitorstack   Updating   39m
monitorstack   Updating   39m
monitorstack   Updating   41m
monitorstack   Ready      41m

CLI

 az arcdata dc status show --k8s-namespace <namespace> --use-k8s

The upgrade is a two-part process. First the controller is upgraded, then the monitoring stack is upgraded. When the upgrade is complete, the output will be:

Ready

Troubleshoot upgrade problems

If you encounter any troubles with upgrading, see the troubleshooting guide.