diff --git a/.github/config/en-custom.txt b/.github/config/en-custom.txt index 8a9192cbd..f7c839cbc 100644 --- a/.github/config/en-custom.txt +++ b/.github/config/en-custom.txt @@ -1322,3 +1322,4 @@ AzureContainerInstanceExtension ACIRuntimeProperties Preflight preflight +oci diff --git a/docs/content/guides/operations/kubernetes/kubernetes-rollback/index.md b/docs/content/guides/operations/kubernetes/kubernetes-rollback/index.md new file mode 100644 index 000000000..94214d97a --- /dev/null +++ b/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- + + # Or use Helm directly to install a specific version + helm install radius oci://ghcr.io/radius-project/helm-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 diff --git a/docs/content/guides/operations/kubernetes/kubernetes-upgrade/index.md b/docs/content/guides/operations/kubernetes/kubernetes-upgrade/index.md index b582d3be3..e171d9697 100644 --- a/docs/content/guides/operations/kubernetes/kubernetes-upgrade/index.md +++ b/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 + ``` + +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