Update the upgrade doc and create the rollback doc

.github/config/en-custom.txt

@@ -1322,3 +1322,4 @@ AzureContainerInstanceExtension
 ACIRuntimeProperties
 Preflight
 preflight
+oci

docs/content/guides/operations/kubernetes/kubernetes-rollback/index.md

@@ -0,0 +1,185 @@
+---
+type: docs
+title: "How-To: Rollback Radius on Kubernetes"
+linkTitle: "Rollback Radius on Kubernetes"
+description: "Learn how to rollback Radius to a previous version on Kubernetes"
+weight: 350
+categories: "How-To"
+tags: ["Kubernetes"]
+---
+
+Radius supports rolling back to previous versions on Kubernetes clusters using the `rad rollback kubernetes` command. This feature allows you to quickly revert to a known-good version if issues are encountered after an upgrade.
+
+## Prerequisites
+
+- [Radius installed on Kubernetes cluster]({{< ref "guides/operations/kubernetes/kubernetes-install" >}})
+- [rad CLI]({{< ref howto-rad-cli >}})
+- Previous Radius installation to rollback to
+
+## Understanding Helm revisions
+
+Radius uses Helm for installation and upgrades on Kubernetes. Each installation or upgrade creates a new Helm revision. These revisions serve as restore points that you can rollback to if needed.
+
+To view the revision history:
+
+```bash
+# List all Radius Helm revisions
+helm history radius -n radius-system
+
+# Example output:
+# REVISION  UPDATED                   STATUS      CHART        APP VERSION  DESCRIPTION
+# 1         Mon Oct 2 10:00:00 2024   superseded  radius-0.48  0.48         Install complete
+# 2         Mon Oct 9 11:00:00 2024   superseded  radius-0.49  0.49         Upgrade complete
+# 3         Mon Oct 16 12:00:00 2024  deployed    radius-0.50  0.50         Upgrade complete
+```
+
+## Step 1: Check current version and available revisions
+
+Before rolling back, check your current Radius version and available revisions:
+
+```bash
+# Check current version
+rad version
+
+# List available revisions using rad CLI
+rad rollback kubernetes --list-revisions
+
+# Alternatively, view Helm revision history directly
+helm history radius -n radius-system
+```
+
+## Step 2: Rollback to a previous version
+
+Use the `rad rollback kubernetes` command to rollback to a specific revision:
+
+```bash
+# Rollback to the previous revision (revision 0 or omit --revision flag)
+rad rollback kubernetes
+
+# Rollback to the previous revision explicitly using revision 0
+rad rollback kubernetes --revision 0
+
+# Rollback to a specific revision number
+rad rollback kubernetes --revision 3
+
+# Switch workspace before rolling back (if needed)
+rad workspace switch myworkspace
+rad rollback kubernetes --revision 2
+```
+
+The rollback process will:
+
+1. Revert the Helm release to the specified revision
+2. Restore the previous version's configuration
+3. Restart Radius components with the previous version
+
+## Step 3: Verify the rollback
+
+After the rollback completes, verify that Radius is running the previous version:
+
+```bash
+# Check Radius version
+rad version
+
+# Verify pods are running
+kubectl get pods -n radius-system
+
+# Check Helm release status
+helm status radius -n radius-system
+
+# Verify your environments are still available
+rad env list
+```
+
+## Important considerations
+
+### CRD compatibility
+
+> **Warning:** Custom Resource Definitions (CRDs) are not automatically rolled back due to [Helm limitations](https://helm.sh/docs/chart_best_practices/custom_resource_definitions/).
+>
+> If the newer version introduced CRD changes, rolling back the control plane might result in compatibility issues. In such cases, you may need to:
+>
+> 1. Manually revert CRD changes, or
+> 2. Perform a fresh installation of the desired version
+
+### Data and configuration
+
+- **Environments and applications**: These are preserved during rollback as they are stored as Kubernetes resources
+- **Custom Helm values**: Previous configuration values are restored with the rollback
+- **Workspace configuration**: Local workspace configuration (in ~/.rad) is not affected by rollback
+
+### When rollback might not work
+
+Rollback may not be successful if:
+
+- The previous version's state is corrupted
+- There are incompatible CRD changes between versions
+- Required dependencies are no longer available
+- Breaking changes in the data format between versions
+
+In these cases, a fresh installation may be required.
+
+## Alternative: Fresh installation
+
+If rollback is not possible or encounters issues, you can perform a fresh installation:
+
+1. Backup your environment configurations:
+
+   ```bash
+   rad env show -o json > env-backup.json
+   ```
+
+2. Uninstall Radius completely:
+
+   ```bash
+   rad uninstall kubernetes
+   ```
+
+3. Install the desired version:
+
+   ```bash
+   # Install a specific version using a local chart
+   rad install kubernetes --chart /path/to/radius-chart-<version>
+
+   # Or use Helm directly to install a specific version
+   helm install radius oci://ghcr.io/radius-project/helm-chart --version <chart-version> -n radius-system --create-namespace
+   ```
+
+4. Create new environments and deploy your applications using the backup as reference
+
+## Troubleshooting
+
+### Failed rollback
+
+If the rollback fails, check the Helm rollback status:
+
+```bash
+# Check Helm release status
+helm status radius -n radius-system
+
+# View detailed history
+helm history radius -n radius-system
+
+# Check pod status
+kubectl get pods -n radius-system
+kubectl describe pods -n radius-system
+```
+
+### Manual Helm rollback
+
+If the rad CLI rollback fails, you can use Helm directly:
+
+```bash
+# Rollback using Helm
+helm rollback radius [REVISION] -n radius-system
+
+# Example: rollback to revision 2
+helm rollback radius 2 -n radius-system
+```
+
+## Next steps
+
+- Learn about [upgrading Radius]({{< ref "guides/operations/kubernetes/kubernetes-upgrade" >}})
+- Review [Radius versioning]({{< ref "guides/operations/versioning" >}}) for version compatibility
+- Check [release notes](https://github.com/radius-project/radius/releases) for version-specific information
+- Refer to the [`rad rollback kubernetes`]({{< ref "reference/cli/rad_rollback_kubernetes" >}}) CLI reference docs for more details

docs/content/guides/operations/kubernetes/kubernetes-upgrade/index.md

@@ -1,38 +1,126 @@
 ---
 type: docs
-title: "How-To: Upgrade Radius on Kubernetes "
+title: "How-To: Upgrade Radius on Kubernetes"
 linkTitle: "Upgrade Radius on Kubernetes"
 description: "Learn how to upgrade Radius on Kubernetes"
 weight: 300
 categories: "How-To"
+tags: ["Kubernetes"]
 ---
 
-Radius does not offer backward compatibility with previous releases. Breaking changes may happen between releases and we recommend doing a fresh installation of the latest version of Radius after every release.
+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.
 
-## Step 1 : Delete any existing Radius Environments
+## Prerequisites
 
-To delete any existing Radius Environments, run the following command:
+- [Radius installed on Kubernetes cluster]({{< ref "guides/operations/kubernetes/kubernetes-install" >}})
+- [Latest rad CLI]({{< ref howto-rad-cli >}})
+
+## Step 1: Upgrade the rad CLI
+
+First, ensure you have the latest version of the rad CLI:
+
+{{< read file= "/shared-content/installation/rad-cli/install-rad-cli.md" >}}
+
+## Step 2: Upgrade Radius control plane
+
+Use the [`rad upgrade kubernetes` command]({{< ref rad_upgrade_kubernetes >}}) to upgrade Radius in your cluster:
 
 ```bash
-rad env delete
+# 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
 ```
 
-## Step 2: Uninstall the existing Radius control-plane
+### Preflight checks
+
+The upgrade process automatically runs preflight checks to ensure your cluster is ready for the upgrade. These checks include:
 
-To uninstall the existing Radius control-plane, run the following command:
+- **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):
 
 ```bash
-rad uninstall kubernetes
+rad upgrade kubernetes --skip-preflight
 ```
 
-## Step 3: Install the rad CLI
+To run only preflight checks without upgrading:
 
-{{< read file= "/shared-content/installation/rad-cli/install-rad-cli.md" >}}
+```bash
+rad upgrade kubernetes --preflight-only
+```
+
+## Step 3: Verify the upgrade
+
+After the upgrade completes, verify that Radius is running the new version:
+
+```bash
+# 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](https://helm.sh/docs/chart_best_practices/custom_resource_definitions/), 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](https://github.com/radius-project/radius/releases) 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]({{< ref "guides/operations/kubernetes/kubernetes-rollback" >}}).
+
+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:
+
+   ```bash
+   # List all environments
+   rad env list
+
+   # Delete each environment
+   rad env delete <environment-name>
+   ```
+
+2. Uninstall Radius:
+
+   ```bash
+   rad uninstall kubernetes
+   ```
+
+3. Install the latest version:
 
-## Step 4: Install the Bicep VS Code extension
+   ```bash
+   rad install kubernetes
+   ```
 
-{{< read file= "/shared-content/installation/vscode-bicep/install-vscode-bicep.md" >}}
+4. Create new environments and deploy your applications
 
-## Step 5: Initialize the Radius control-plane and the Radius Environment
+## Next steps
 
-{{< read file= "/shared-content/installation/install-radius/initialize-radius.md" >}}
+- Learn how to [rollback Radius]({{< ref "guides/operations/kubernetes/kubernetes-rollback" >}}) if needed
+- Review [Radius versioning]({{< ref "guides/operations/versioning" >}}) for version compatibility information
+- Refer to the [`rad upgrade`]({{< ref "reference/cli/rad_upgrade_kubernetes" >}}) CLI reference docs for more details