Astronomer releases are made generally available to Software customers on a quarterly basis as part of a long-term support (LTS) release model.
This guide provides steps for upgrading your Astronomer Software platform from v0.23.x to v0.25, which is the latest available LTS release.
A few important notes before you start:
- You must be on Astronomer Software v0.23.x in order to upgrade to Astronomer v0.25+. If you are running a version of Astronomer that's lower than v0.23, submit a request to Astronomer Support and our team will help you define an alternate upgrade path.
- The guidelines below only apply to users who are upgrading to the Astronomer v0.25 series for the first time. Once you've completed the upgrade to any v0.25 version, you'll be free to upgrade to subsequent v0.25.x patch versions as they are released by our team. For instructions, read Upgrade to a Patch Version.
Step 1: Check Version Compatibility
Ensure that the following software is updated to the appropriate version:
Kubernetes: Your version must be 1.17 or 1.18. If you need to upgrade Kubernetes, contact your cloud provider's support or your Kubernetes administrator.
Airflow Images: You must be using an Astronomer Certified Airflow image, and the version of your image must be 1.10.5 or greater. In addition, your image should be in the following format:
For example, all of the following images would work for this upgrade:
<build-number>are optional, we recommend including them for most upgrades. If you have your own build, test, and publish workflows that are layered on top of the Astronomer Airflow images, then removing
<build-number>is appropriate because images including
Helm: Your version must be 3.6 or greater.
Step 2: Check Permissions
Minor version upgrades can be initiated only by a user with System Admin permissions on Astronomer. To confirm you're an Astronomer SysAdmin, confirm that you have access to System Admin features in the Software UI:
You also need permission to create Kubernetes resources. To confirm you have those permissions, run the following commands:
kubectl auth can-i create pods --namespace <your-astronomer-namespace>
kubectl auth can-i create sa --namespace <your-astronomer-namespace>
kubectl auth can-i create jobs --namespace <your-astronomer-namespace>
If all commands return
yes, then you have the appropriate Kubernetes permissions.
Step 3: Backup Your Database
Backup your entire Astronomer database instance using your cloud provider's functionality for doing so, or make a backup request to your database administrator based on your organization's guidelines.
Step 4: Check the Status of Your Kubernetes Pods
Before you proceed with the upgrade, ensure that the Kubernetes Pods in your platform namespace are healthy. To do so, run:
kubectl get pods -n <your-astronomer-namespace>
All pods should be in either the
Completed state. If any of your pods are in a
CrashLoopBackOff state or are otherwise unhealthy, make sure that's expected behavior before you proceed.
Step 5: Switch to Your Default Namespace
Switch to the default namespace in your Kubernetes context by running the following command:
kubectl config set-context --current --namespace=default
Step 6: Upgrade Astronomer
Run the following command to begin the upgrade process:
kubectl apply -f https://raw.githubusercontent.com/astronomer/astronomer/release-0.25/migrations/scripts/lts-to-lts/0.23-to-0.25/manifests/upgrade-0.23-to-0.25.yaml
While your platform is upgrading, monitor your pods to ensure that no errors occur. To do so, first find the names of your pods by running the following command:
kubectl get pods | grep upgrade-astronomer
Then, run the following command for each pod you find:
kubectl logs <your-pod-name>
Step 7: Confirm That the Upgrade Was Successful
If the upgrade was successful, you should be able to:
- Log in to Astronomer at
- See Workspaces and Airflow Deployments in the Software UI.
- Access the Settings tab for each of your Deployments in the Software UI.
- See metrics on the Metrics tab in the Software UI.
- Successfully run
$ astro deployusing the Astronomer CLI.
- Open the Airflow UI for each of your Deployments
- Access logs for your DAGs in the Airflow UI.
Step 8: Clean Up Kubernetes Resources
We recommend cleaning up any remaining Kubernetes resources after your upgrade. To do so, run the following command:
kubectl delete -f https://raw.githubusercontent.com/astronomer/astronomer/release-0.25/migrations/scripts/lts-to-lts/0.23-to-0.25/manifests/upgrade-0.23-to-0.25.yaml
Step 9: Upgrade the Astronomer CLI to v0.25
To ensure reliability and full access to features included in Astronomer Software v0.25, all users must upgrade to v0.25 of the Astronomer CLI. We recommend the latest available version, though you may choose to install a particular patch release within the v0.25 series.
To upgrade to the latest available v0.25 version of the Astronomer CLI, run:
curl -sSL https://install.astronomer.io | sudo bash -s -- v0.25.0
To do so via Homebrew, run:
brew install email@example.com
Earlier versions of the Astronomer CLI are backwards incompatible with Astronomer v0.25. All team members within your organization must upgrade the Astronomer CLI individually before taking any further action on the platform or in a local Airflow environment. For a detailed breakdown of CLI changes between versions, refer to Astronomer CLI releases. For detailed install guidelines and more information on the Astronomer CLI, refer to Astronomer CLI Quickstart.
Roll Back to Software v0.23
If you encounter an issue during your upgrade that requires you to recover your original platform, you can roll back to Astronomer v0.23. To do so:
- Apply the rollback automation script by running the following command:
kubectl apply -f https://raw.githubusercontent.com/astronomer/astronomer/release-0.25/migrations/scripts/lts-to-lts/0.23-to-0.25/manifests/rollback-0.23-to-0.25.yaml
This restores the platform database and the Helm state of the Astronomer Helm chart.
Wait a few minutes for your platform to come back up.
Confirm that the rollback completed. To do so, watch your pods until they have stabilized; every pod in your Astronomer namespace should be
Runningwith full readiness or
Completed. You can check the status of your pods using the following command:
watch kubectl get pods -n <your-astronomer-namespace>
- Clean up any remaining Kubernetes resources after your rollback. To do so, run the following command:
kubectl delete -f https://raw.githubusercontent.com/astronomer/astronomer/release-0.25/migrations/scripts/lts-to-lts/0.23-to-0.25/manifests/rollback-0.23-to-0.25.yaml