How-To: Upgrade Radius on Kubernetes

Learn how to upgrade Radius on Kubernetes
Categories:
Tags:

Radius supports in-place upgrades on Kubernetes clusters using the rad upgrade kubernetes command. This command upgrades the Radius control plane while preserving your existing environments and applications.

Prerequisites

Step 1: Upgrade the rad CLI

First, ensure you have the latest version of the rad CLI:

The rad CLI manages your applications, resources, and environments. You can install it on your local machine with the following installation scripts:


wget -q "https://raw.githubusercontent.com/radius-project/radius/main/deploy/install.sh" -O - | /bin/bash

To try out an unstable release visit the edge docs.


curl -fsSL "https://raw.githubusercontent.com/radius-project/radius/main/deploy/install.sh" | /bin/bash

To try out an unstable release visit the edge docs.


Run the following in a PowerShell window:

iwr -useb "https://raw.githubusercontent.com/radius-project/radius/main/deploy/install.ps1" | iex

You may need to refresh your $PATH environment variable to access rad:

$Env:Path = [System.Environment]::GetEnvironmentVariable("Path","User")

To try out an unstable release visit the edge docs.


Radius offers a free Codespace option for getting up and running with a Radius environment in seconds:

Open in GitHub Codespaces


Azure Cloud Shell is an interactive, authenticated, browser-accessible shell for managing Azure resources.

Azure Cloud Shell for bash doesn’t have a sudo command, so users are unable to install Radius to the default /usr/local/bin installation path. To install the rad CLI to the home directory, run the following commands:

export RADIUS_INSTALL_DIR=./
wget -q "https://raw.githubusercontent.com/radius-project/radius/main/deploy/install.sh" -O - | /bin/bash

You can now run the rad CLI with ./rad.

PowerShell for Cloud Shell is currently not supported.


Visit Radius GitHub releases to select and download a specific version of the rad CLI.

You may be prompted for your sudo password during installation, as the installer places the rad binary under /usr/local/bin. If you are unable to sudo you can install the rad CLI to another directory by setting the RADIUS_INSTALL_DIR environment variable with your intended install path. Make sure you add this to your path (Unix, Windows) if you wish to reference it via rad, like in the docs.

Verify the rad CLI is installed correctly by running rad version.

Example output:

RELEASE     VERSION     BICEP       COMMIT
0.50.0      v0.50        0.28.1     2e60bfb46de73ec5cc70485d53e67f8eaa914ba7

Step 2: Upgrade Radius control plane

Use the rad upgrade kubernetes command to upgrade Radius in your cluster:

# Upgrade to the latest version matching your CLI
rad upgrade kubernetes

# Upgrade to a specific version
rad upgrade kubernetes --version 0.49.0

# Upgrade with custom configuration
rad upgrade kubernetes --set key=value

Preflight checks

The upgrade process automatically runs preflight checks to ensure your cluster is ready for the upgrade. These checks include:

  • Kubernetes connectivity and permissions: Verifies connection to the cluster and required RBAC permissions
  • Helm connectivity and installation status: Confirms Radius is installed via Helm and can be upgraded
  • Version compatibility validation: Ensures the target version is compatible with your current version
  • Cluster resource availability: Checks for sufficient resources (optional warning)
  • Custom configuration validation: Validates any custom Helm values

To skip preflight checks (not recommended):

rad upgrade kubernetes --skip-preflight

To run only preflight checks without upgrading:

rad upgrade kubernetes --preflight-only

Step 3: Verify the upgrade

After the upgrade completes, verify that Radius is running the new version:

# Check Radius version
rad version

# Verify pods are running
kubectl get pods -n radius-system

# Check your environments are still available
rad env list

Important considerations

CRD updates

Note: Due to a Helm limitation, Custom Resource Definitions (CRDs) are only installed during the initial Radius installation and are not automatically updated during upgrades.

If a Radius upgrade includes CRD changes (typically in major version upgrades), you may need to manually update the CRDs. Check the release notes for specific instructions when CRD updates are required.

Breaking changes

While Radius supports in-place upgrades, breaking changes may still occur between major versions. Always review the release notes before upgrading to understand any breaking changes or migration steps required.

Rollback capability

If an upgrade encounters issues, you can rollback to a previous version using the rad rollback kubernetes command.

It’s recommended to backup your environment configurations before upgrading, which you may do with something like rad env show -o json > env-backup.json.

Alternative: Fresh installation

If you prefer to do a fresh installation instead of an in-place upgrade, follow these steps:

  1. Delete all existing Radius Environments:

    # List all environments
rad env list

# Delete each environment
rad env delete <environment-name>

  2. Uninstall Radius:

    rad uninstall kubernetes

  3. Install the latest version:

    rad install kubernetes

  4. Create new environments and deploy your applications

Next steps