> ## Documentation Index
> Fetch the complete documentation index at: https://docs.macstadium.com/llms.txt
> Use this file to discover all available pages before exploring further.
# How to upgrade your Orka cluster
> Upgrade your Orka cluster via a MacStadium support ticket with a scheduled maintenance window. Covers upgrade types, prep steps, and post-upgrade tasks.
When MacStadium is hosting your Orka environment, Orka upgrades require a scheduled maintenance window. Some Orka upgrades might require additional preparation on your side.
## Requesting an upgrade
1. Check the release notes for the version that you want to upgrade to. Complete the suggested preparation, if any.
2. Submit a ticket through the MacStadium portal.
3. Schedule a time for the maintenance window that works for you through the link provided in the ticket.
* The suggested time(s) must be Monday through Thursday, 9am or 1pm EST, depending on availability in the [MacStadium Global Operations calendar](https://calendly.com/macstadium-global-operations/orka-upgrade).
4. After the upgrade is complete, you might need to [download and install](/orka/orka-overview/tools-integrations) a new Orka CLI version and/or restore any missing resources (based on the type of upgrade).
## Types of upgrades
### New Orka releases
This is the most common type of Orka upgrade. Orka releases bring new CLI and API versions with new features, improved functionality, and critical bug fixes.
#### **Preparing for the upgrade**
Make sure that during the maintenance window there are no running workflows (for example, deploying a VM and running a build.).\
As part of this upgrade, you might need to [download and install](/orka/orka-overview/tools-integrations) a new Orka CLI version.
Service Account tokens must be regenerated after this upgrade. Any automated workflows using service account tokens will fail until tokens are regenerated with `orka3 serviceaccount token `.
| Aspect | Notes |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Maintenance window | Up to 3 hours. Must be scheduled with the MacStadium support team. |
| Access to the environment | During the maintenance window, the environment is inaccessible. After the maintenance window, access is restored. You can reach your environment at the original IP, Orka domain, or external custom domain. |
| Orka users | Orka users persist. |
| Service Accounts | Your custom service accounts persist. |
| VMs and VM configs | VM configs persist. VMs may be deleted. After the upgrade completes, you can redeploy them from the respective VM configs. |
| Images and ISOs | Images and ISOs persist. |
| Image cache (Apple silicon nodes) | The image cache is removed from each node. |
| Namespaces | Your custom namespaces persist. |
| RoleBindings | Your custom permissions persist. |
| Kubernetes Pods and services | Your custom Pods and services persist. |
#### Patch version upgrades
Orka patch releases (for example, 3.5.0 → 3.5.2) deliver bug fixes and stability improvements between minor releases. Patch upgrades are zero-downtime — no preparation is required, and running VMs and workflows are not interrupted.
**Adding nodes to your cluster requires the latest patch version.** If your cluster is on an older patch version, node additions will fail. Request a patch upgrade before submitting a node add request.
| Aspect | Notes |
| --------------------------------- | ------------------------------------------------ |
| Maintenance window | None required. Patch upgrades are zero-downtime. |
| Access to the environment | Uninterrupted throughout the upgrade. |
| Orka users | Persist. |
| Service Accounts | Persist. Tokens do not need to be regenerated. |
| VMs and VM configs | Persist. Running VMs are not affected. |
| Images and ISOs | Persist. |
| Image cache (Apple silicon nodes) | Persists. |
| Namespaces and RoleBindings | Persist. |
### Virtualization and orchestration layer upgrades (Kubernetes, Docker, or Linux)
Occasionally, the Orka team upgrades the components of the virtualization and orchestration layer to a newer version. The version in Orka might run a few versions behind the latest and greatest release to ensure that the virtualization layer and orchestration layer are stable and bug-free.
#### **Preparing for the upgrade**
* Make sure that during the maintenance window there are no running workflows (for example, deploying a VM and running a build.).
* If this is a Kubernetes upgrade and you are working with the Kubernetes layer directly, make sure to address any deprecated APIs.
Service Account tokens must be regenerated after this upgrade. Any automated workflows using service account tokens will fail until tokens are regenerated with `orka3 serviceaccount token `.
| Aspect | Notes |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Maintenance window | Up to 3 hours. Must be [scheduled](/orka/orka-upgrades-and-release-notes/orka-upgrades#requesting-an-upgrade) with the MacStadium support team. |
| Access to the environment | During the maintenance window, the environment is inaccessible. After the maintenance window, access is restored. You can reach your environment at the original IP, Orka domain, or external custom domain. |
| Orka users | Orka users persist. |
| Service Accounts | Your custom service accounts persist. |
| VMs and VM configs | VM configs persist. VMs are deleted. After the upgrade completes, you can redeploy them from the respective VM configs. |
| Registry credentials | Registry credentials do not persist and will need to be regenerated after the upgrade. |
| Images & ISOs | Images and ISOs persist. |
| Image cache (Apple silicon nodes) | The image cache is removed from each node. |
| Namespaces | Your custom namespaces persist. |
| RoleBindings | Your custom permissions persist. |
| Kubernetes Pods and services | Your custom Pods and services are lost. You need to recreate them. |