Migrate to Astro Private Cloud 1.0 from 0.37
This guide provides instructions to migrate from Astro Private Cloud (APC) 0.37.6 to 1.0.0, including transitioning from STAN to JetStream and preparing your environment for Airflow 3 Deployments.
Prerequisites
- Upgrade to APC 0.37.6 if you are on an earlier version.
- Back up your platform database and configuration.
- Verify that all platform and Airflow deployment Pods are healthy.
- (Optional) Capture logs or metrics from your NATS and STAN instances.
If you experience any issues during your migration to 1.0, refer to the Debug migration guide.
Manual DNS and load balancer update required
When upgrading from Astro Private Cloud (APC) 0.x.x to 1.0.0, APC creates a new control plane NGINX ingress Service (astronomer-cp-nginx) and a new LoadBalancer. The previous ingress and LoadBalancer are replaced.
You must:
- Update all DNS records to the new load balancer IP address.
- Update firewall, allowlist, and security rules to point to the new public endpoint.
- Re-issue or update any TLS/SSL certificates that reference the previous LoadBalancer hostname, if applicable.
This change occurs because the control plane ingress Service name changes from astronomer-nginx (0.x) to astronomer-cp-nginx (1.0), which causes Kubernetes to provision a new external LoadBalancer with a new public IP/hostname. Prepare these updates before performing the upgrade.
Example (your output will vary by cloud/provider):
Step 1: Delete existing STAN and NATS StatefulSets
Before upgrading to version 1.0.0, you must migrate from STAN to JetStream. In your cluster, run the following commands to remove legacy STAN components before JetStream is initialized:
Step 2: Restart NATS and Houston Worker
After you complete the platform upgrade and all Pods are running, restart your workers to ensure the new JetStream components and Houston workers are connected and synchronized:
Step 3: Upgrade to APC 1.0.0 from 0.37.6
To upgrade to Astro Private Cloud (APC) 1.0.0 from version 0.37.6, you must first configure your deployment to run in unified plane mode. In 1.0.0, the control plane and data plane can run separately, but unified mode is recommended for upgrades and simplified operation. Unified mode does not prevent separate data planes from being added later.
Update your values.yaml with the following configuration:
Once this is set, perform a standard Helm upgrade using your existing release name and namespace:
This will upgrade your existing 0.37.6 installation to 1.0.0 on the same cluster. Make sure you’ve completed the pre-upgrade checks (backups, JetStream transition, etc.) before running the upgrade command.
Step 4: Airflow 3 configuration
Before you can create Airflow 3 Deployments, update your cluster’s override configuration to include the latest airflowLocalSettings snippet.
If you skip creating the cluster configuration override, your Airflow 3 Deployment creation will fail with the following error:
Step 5: Upgrade all Airflow deployments
Once you have validated that all platform Pods in APC 1.0 are healthy and running, you must upgrade every Airflow deployment to ensure compatibility with 1.0.
There are multiple ways to trigger these upgrades:
-
If you only have a few deployments, set the
astronomer.houston.upgradeDeployments.enabled=trueHelm flag to automatically upgrade all Airflow deployments: -
If you have many Airflow deployments, you can upgrade them using one of the following approaches:
- Upgrade each deployment manually from the Astro UI.
- Use an automated mechanism such as the Houston API or the Astro CLI’s astro deploy command for programmatic or bulk upgrades.
Step 6: Post-upgrade validation
After you complete your upgrade, validate your upgrade works as expected by completing the following steps: