Upgrade to Astro Private Cloud 2.0

Upgrade to Astro Private Cloud 2.0 from 1.x

Use this document to upgrade from Astro Private Cloud (APC) 1.x to 2.0. The upgrade primarily involves migrating your values.yaml override file to the new schema and running a Helm upgrade.

If you are upgrading from APC 0.37.x directly to 2.0, use the Upgrade to 2.0 from 0.37 guide instead. That guide covers the additional platform-level steps required when skipping 1.x.

Prerequisites

  • Verify that you are running APC 1.x. If you are on 0.37.x, see the Upgrade to 2.0 from 0.37 guide.

  • Back up your platform database. At minimum, create a snapshot or backup of your PostgreSQL database (RDS snapshot, Azure backup, Cloud SQL backup, or pg_dump).

  • Verify that all platform and Airflow Deployment Pods are healthy:

    $kubectl get pods -n astronomer
    $kubectl get pods -n astronomer-<deployment-release-name>

  • Python 3.10 or later installed on your local computer (required for the values migration script).

  • Install the ruamel.yaml Python package:

    $pip install ruamel.yaml

Step 1: Get the migration script

The migration scripts are located in the bin/ folder of the Astronomer Helm chart repository. Clone the repository and check out the release-2.0 branch:

$git clone https://github.com/astronomer/astronomer.git
$cd astronomer
$git checkout release-2.0

The script you need for this upgrade path is bin/migrate-helm-chart-values-1x-to-2x.py.

Step 2: Migrate your values.yaml

APC 2.0 introduces a unified feature flag schema that reorganizes scattered global.* boolean flags into domain-grouped structures with a consistent .enabled pattern. The migration script also restructures APC API configuration flags under astronomer.houston.config.deployments into nested paths. The migration script automates both transformations.

Back up your override file

$cp my-values.yaml my-values.yaml.backup

Preview changes (dry run)

Run the migration script in dry-run mode to see what will change without modifying any files:

$./bin/migrate-helm-chart-values-1x-to-2x.py --dry-run my-values.yaml

Example output:

Found 12 migration(s) to apply:
  global.rbacEnabled -> global.rbac.enabled
  global.sccEnabled -> global.scc.enabled
  global.openshiftEnabled -> global.openshift.enabled
  global.networkNSLabels -> global.networkNSLabels.enabled
  global.namespaceFreeFormEntry -> global.namespaceManagement.namespaceFreeFormEntry.enabled
  global.taskUsageMetricsEnabled -> global.metricsReporting.taskUsageMetrics.enabled
  global.deployRollbackEnabled -> global.deploymentLifecycle.deployRollback.enabled
  global.features.namespacePools -> global.namespaceManagement.namespacePools
  global.dagOnlyDeployment -> global.deployMechanisms.dagOnlyDeployment
  global.loggingSidecar -> global.logging.loggingSidecar
  astronomer.houston.config.deployments.dagProcessorEnabled -> astronomer.houston.config.deployments.airflowComponents.dagProcessor.enabled
  astronomer.houston.config.deployments.triggererEnabled -> astronomer.houston.config.deployments.airflowComponents.triggerer.enabled

If you see No migrations needed, your file is already compatible with 2.0.

Run the migration

$./bin/migrate-helm-chart-values-1x-to-2x.py --in-place --backup my-values.yaml

This modifies your file directly and creates my-values.yaml.bak as a backup.

Review the migrated file

Open the migrated file and verify the changes look correct. The script preserves YAML comments and formatting.

Step 3: Validate the Helm upgrade (dry run)

Before making any changes to your cluster, run a Helm upgrade dry run to verify that the upgrade will succeed:

$helm upgrade -f migrated-values.yaml -n astronomer astronomer astronomer/astronomer --version 2.0.x --dry-run

Replace 2.0.x with the specific patch version you are upgrading to.

Don’t proceed until the dry run completes successfully. If it fails, resolve the reported errors first.

Step 4: Upgrade to APC 2.0

Perform a standard Helm upgrade using your migrated values file:

$helm upgrade -f migrated-values.yaml -n astronomer astronomer astronomer/astronomer --version 2.0.x

Replace 2.0.x with the specific patch version you are upgrading to.

Airgapped environments

For airgapped environments that can’t access the internet, download the Helm chart .tgz file directly from the Astronomer Helm repository:

https://helm.astronomer.io/astronomer-<version>.tgz

Replace <version> with the specific version you are upgrading to. Upload this file to your internal artifact repository, then reference it in your helm upgrade command.

Step 5: Migrate cluster configuration in the APC database

The Helm values migration Python script updates values.yaml on disk. Separately, the APC database can still store legacy flat deployments keys in each registered cluster’s config and configOverride until the cluster config path migration has run.

That migration is part of the APC API’s yarn migrate script (it invokes migrate-cluster-config-paths along with other jobs). If your control-plane upgrade already runs the full yarn migrate pipeline, this step is usually not a separate manual task.

If the migration hasn’t run or you need to run it again (for example after a failed migrate, or to confirm with a dry run first), you can run the same job independently with yarn migrate-cluster-config-paths from the houston-api pod, with the platform database reachable. Without this database update—whether it ran inside yarn migrate or a standalone run—cluster-level rows might not line up with the 2.0 config governance model.

  • What it does: For every registered cluster, the APC API rewrites stored config / configOverride from old paths to the domain-grouped nested structure (the same renames the Helm migrator applies under astronomer.houston.config.deployments). It also invalidates the cluster details cache in the APC API.

  • When you need a standalone run: For 1.x → 2.0 when you had registered data plane clusters in 1.x, and the cluster rows were never migrated (for example yarn migrate didn’t run, or the step failed). Don’t treat this as a standard 0.37 → 2.0 requirement—you typically have no pre-existing 2.0 cluster records to fix on that path.

  • Command (on a host with the APC API release and DB access):

    $yarn migrate-cluster-config-paths --dry-run
    $yarn migrate-cluster-config-paths

    A dry run reports how many clusters would be updated; a full run applies changes and reports migrated vs skipped counts. Exit is non-zero if any cluster failed.

  • Strict config validation in the APC API: The chart sets astronomer.houston.strictSchemaCheck. For how the 1.x migrator injects it, see the values migration reference section. When strictSchemaCheck.enabled is true, the APC API rejects deployments config overrides with unknown keys or bad types. If you need to allow keys not yet in the generated schema, you can set astronomer.houston.strictSchemaCheck.enabled: false in your platform values.yaml and run another helm upgrade (see Git-Sync relay metrics for a related case).

Step 6: Verify the upgrade

After the upgrade completes, verify that all platform components are running:

$kubectl get pods -n astronomer

All Pods should be in a Running or Completed state. If any Pods are in a CrashLoopBackOff or Error state, see Debug upgrade.

Step 7: Upgrade all Airflow Deployments

After you have validated that all platform Pods are healthy, upgrade your Airflow Deployments to ensure full compatibility with 2.0.

Existing Airflow Deployments typically continue to function after the platform upgrade without immediate action. However, Astronomer recommends upgrading Deployments to ensure full compatibility with the new platform version.

To upgrade Deployments, use one of the following approaches:

  • Astro UI: Upgrade each Deployment manually from the Astro UI by navigating to the Deployment and triggering an upgrade.
  • APC API: Use the APC API upsertDeployment mutation for programmatic or bulk upgrades.
  • Astro CLI: Use the Astro CLI’s astro deploy command.

Values migration reference

bin/migrate-helm-chart-values-1x-to-2x.py applies rules in this order: (1) every global map in the file (values under each global key, including nested charts); (2) astronomer.houston.config flags; (3) astronomer.houston.config.deployments rewrites, plus chart-only key deletions; (4) nginx.cspPolicy; (5) inject astronomer.houston.strictSchemaCheck if missing. The following tables list every rule in bin/helm_chart_values_migration_shared.py that the 1.x script uses. Keep this list aligned with the release-2.0 branch of the Astronomer Helm chart. The script only migrates keys that are present in your file; it doesn’t add keys you didn’t set, except for strictSchemaCheck as noted. Keys with no rule here are left unchanged.

global feature flags

For each global mapping in the document, the old key is removed after migration (or dropped if the new path already exists).

Old pathNew pathType
global.rbacEnabledglobal.rbac.enabledboolean → nested
global.sccEnabledglobal.scc.enabledboolean → nested
global.openshiftEnabledglobal.openshift.enabledboolean → nested
global.networkNSLabelsglobal.networkNSLabels.enabledboolean → nested
global.namespaceFreeFormEntryglobal.namespaceManagement.namespaceFreeFormEntry.enabledboolean → nested
global.taskUsageMetricsEnabledglobal.metricsReporting.taskUsageMetrics.enabledboolean → nested
global.deployRollbackEnabledglobal.deploymentLifecycle.deployRollback.enabledboolean → nested
global.features.namespacePools (subtree)global.namespaceManagement.namespacePoolssubtree move
global.dagOnlyDeployment (subtree)global.deployMechanisms.dagOnlyDeploymentsubtree move
global.loggingSidecar (subtree)global.logging.loggingSidecarsubtree move
global.podDisruptionBudgetsEnabledglobal.podDisruptionBudgets.enabledboolean → nested
global.postgresqlEnabledglobal.postgresql.enabledboolean → nested
global.prometheusPostgresExporterEnabledglobal.prometheusPostgresExporter.enabledboolean → nested
global.nodeExporterEnabledglobal.nodeExporter.enabledboolean → nested
global.manualNamespaceNamesEnabledglobal.namespaceManagement.manualNamespaceNames.enabledboolean → nested
global.enablePerHostIngressglobal.perHostIngress.enabledboolean → nested
global.enableArgoCDAnnotationglobal.argoCD.annotation.enabledboolean → nested
global.disableManageClusterScopedResourcesglobal.manageClusterScopedResources.enabledinverted boolean
global.astronomerEnabledglobal.astronomer.enabledboolean → nested
global.nginxEnabledglobal.nginx.enabledboolean → nested
global.alertmanagerEnabledglobal.alertmanager.enabledboolean → nested
global.grafanaEnabledglobal.grafana.enabledboolean → nested
global.kubeStateEnabledglobal.kubeState.enabledboolean → nested
global.prometheusEnabledglobal.prometheus.enabledboolean → nested
global.elasticsearchEnabledglobal.elasticsearch.enabledboolean → nested
global.vectorEnabledglobal.daemonsetLogging.enabledboolean → nested
global.fluentdEnabledglobal.daemonsetLogging.enabledboolean → nested

astronomer.houston.config (non-deployments) flags and move

Old pathNew pathType
astronomer.houston.config.emailConfirmationastronomer.houston.config.emailConfirmation.enabledboolean → nested
astronomer.houston.config.publicSignupsastronomer.houston.config.publicSignups.enabledboolean → nested
astronomer.houston.config.updateRuntimeCheckEnabledastronomer.houston.config.updateRuntimeCheck.enabledboolean → nested
astronomer.houston.config.updateAirflowCheckEnabledastronomer.houston.config.updateAirflowCheck.enabledboolean → nested
astronomer.houston.config.subdomainHttpsEnabledastronomer.houston.config.subdomainHttps.enabledboolean → nested
astronomer.houston.config.useAutoCompleteForSensitiveFieldsastronomer.houston.config.autoCompleteForSensitiveFields.enabledboolean → nested
astronomer.houston.config.shouldLogUsernameastronomer.houston.config.logUsername.enabledboolean → nested
astronomer.houston.config.disableSSLVerifyastronomer.houston.config.sslVerification.enabledinverted boolean
astronomer.houston.config.auth.openidConnect.idpGroupsImportEnabledastronomer.houston.config.auth.openidConnect.idpGroupsImport.enabledboolean → nested
astronomer.houston.config.auth.openidConnect.idpGroupsRefreshEnabledastronomer.houston.config.auth.openidConnect.idpGroupsRefresh.enabledboolean → nested
astronomer.houston.config.auth.openidConnect.insecureIDPTokenLogastronomer.houston.config.auth.openidConnect.insecureIDPTokenLog.enabledboolean → nested
astronomer.houston.config.webserver.graphqlPlaygroundEnabledastronomer.houston.config.webserver.graphqlPlayground.enabledboolean → nested
astronomer.houston.config.nats.tlsEnabledastronomer.houston.config.nats.tls.enabledboolean → nested
astronomer.houston.config.workers.dplink.debugEnabledastronomer.houston.config.workers.dplink.debug.enabledboolean → nested
astronomer.houston.config.apollo.auditMiddlewareEnabledastronomer.houston.config.apollo.auditMiddleware.enabledboolean → nested
astronomer.houston.config.deployments.mockWebhook.krbEnabledastronomer.houston.config.deployments.mockWebhook.krb.enabledboolean → nested
astronomer.houston.config.helm.rbacEnabledastronomer.houston.config.helm.rbac.enabledboolean → nested
astronomer.houston.config.deployments.mockWebhook.krbRealmastronomer.houston.config.deployments.mockWebhook.krb.realmmove value

nginx.cspPolicy

Old pathNew pathType
nginx.cspPolicy.cdnEnablednginx.cspPolicy.enabledboolean → nested

astronomer.houston.config.deployments path migrations

Let d = astronomer.houston.config.deployments. Migrations run in the order below (same as HOUSTON_DEPLOYMENT_PATH_MIGRATIONS in code). The Transform column names match the code: boolean-to-airflowV3 adds a default minimumAstroRuntimeVersion when converting from a plain boolean, and taskUsageReport-to-taskUsageMetrics maps the legacy task usage object into metricsReporting.taskUsageMetrics. deprecated-unset means the key is removed with no replacement.

Old key (d.<key>)New path (under d)Transform
performanceOptimizationModeEnabledperformanceOptimization.enabledboolean-to-enabled
upsertExtraIniAllowedupsertDeployment.extraIniAllowedmove
logHelmValueslogHelmValues.enabledboolean-to-enabled
airflowV3runtimeManagement.airflowV3boolean-to-airflowV3
customImageShaEnabledruntimeManagement.customImageSha.enabledboolean-to-enabled
enableListAllRuntimeVersionsruntimeManagement.listAllRuntimeVersions.enabledboolean-to-enabled
runtimeEnvOverideSemverCheckruntimeManagement.runtimeEnvOverrideSemverCheckmove (note: old key name spelling)
astroRuntimeReleasesFileruntimeManagement.astroRuntimeReleasesFilemove
airflowMinimumAstroRuntimeVersionruntimeManagement.airflowMinimumAstroRuntimeVersionmove
loggingSidecarlogging.loggingSidecarmove
elasticsearchlogging.elasticsearchmove
configureDagDeploymentdeployMechanisms.configureDagDeployment.enabledboolean-to-enabled
dagOnlyDeploymentdeployMechanisms.dagOnlyDeployment.enabledboolean-to-enabled
nfsMountDagDeploymentdeployMechanisms.nfsMountDagDeployment.enabledboolean-to-enabled
gitSyncDagDeploymentdeployMechanisms.gitSyncDagDeployment.enabledboolean-to-enabled
gitSyncRelaydeployMechanisms.gitSyncRelaymove
triggererEnabledairflowComponents.triggerer.enabledboolean-to-enabled
dagProcessorEnabledairflowComponents.dagProcessor.enabledboolean-to-enabled
disableManageResourceQuotasAndLimitRangesresourceManagement.resourceQuotas.enabledinvert-to-enabled
componentsresourceManagement.componentsmove
executorsresourceManagement.executorsmove
astroUnitresourceManagement.astroUnitmove
maxExtraCapacityresourceManagement.maxExtraCapacitymove
maxPodCapacityresourceManagement.maxPodCapacitymove
sidecarsresourceManagement.sidecarsmove
overProvisioningFactorMemresourceManagement.overProvisioningFactorMemmove
overProvisioningFactorCPUresourceManagement.overProvisioningFactorCPUmove
overProvisioningComponentsresourceManagement.overProvisioningComponentsmove
manualReleaseNamesnamespaceManagement.manualReleaseNames.enabledboolean-to-enabled
manualNamespaceNamesnamespaceManagement.manualNamespaceNames.enabledboolean-to-enabled
namespaceFreeFormEntrynamespaceManagement.namespaceFreeFormEntryobject-or-boolean-to-nested
preDeploymentValidationHooknamespaceManagement.namespaceFreeFormEntry.preDeploymentValidationHookmove
preDeploymentValidationHookTimeoutnamespaceManagement.namespaceFreeFormEntry.preDeploymentValidationHookTimeoutmove
namespaceLabelsnamespaceManagement.namespaceLabelsmove
preCreatedNamespacesnamespaceManagement.preCreatedNamespacesmove
deployRollbackdeploymentLifecycle.deployRollbackobject-or-boolean-to-nested
hardDeleteDeploymentdeploymentLifecycle.hardDeleteDeployment.enabledboolean-to-enabled
cleanupAirflowDbdeploymentLifecycle.cleanupAirflowDbobject-or-boolean-to-nested
databasedatabaseManagement.databasemove
manualConnectionStringsdatabaseManagement.manualConnectionStrings.enabledboolean-to-enabled
pgBouncerResourceCalculationStrategydatabaseManagement.pgBouncerResourceCalculationStrategymove
exposeDockerWebhookEndpointdeploymentImagesRegistry.exposeDockerWebhookEndpoint.enabledboolean-to-enabled
enableUpdateDeploymentImageEndpointdeploymentImagesRegistry.updateDeploymentImageEndpoint.enabledboolean-to-enabled
enableUpdateDeploymentImageEndpointDockerValidationdeploymentImagesRegistry.updateDeploymentImageEndpointDockerValidation.enabledboolean-to-enabled
serviceAccountAnnotationKeydeploymentImagesRegistry.serviceAccountAnnotationKeymove
grafanaUIEnabledmetricsReporting.grafana.enabledboolean-to-enabled
taskUsageReportmetricsReporting.taskUsageMetricstaskUsageReport-to-taskUsageMetrics
paginationmetricsReporting.paginationmove
canUpsertDeploymentFromUIupsertDeployment.allowFromUi.enabledboolean-to-enabled

Removed keys (no replacement, deprecated-unset or chart-only delete)

Key under dReason
upsertDeploymentEnableddeprecated-unset
enableSystemAdminCanCreateDeprecatedAirflowsdeprecated-unset
defaultDistributiondeprecated-unset
astroUnitsEnabledChart-only delete (no 2.x equivalent)
resourceProvisioningStrategyChart-only delete (no 2.x equivalent)
maxPodAuChart-only delete (no 2.x equivalent)

Injected default

PathInjected if missingNotes
astronomer.houston.strictSchemaCheckenabled: trueAddKeyIfMissing in migrate-helm-chart-values-1x-to-2x.py

FAQ

Is the migration idempotent?

Yes. Running the script multiple times on the same file produces the same output. Running it on an already-migrated file reports “No migrations needed” and makes no changes.

What about YAML comments?

The script uses ruamel.yaml in round-trip mode, which preserves comments and formatting. Inline comments transfer to the new key names. Comments on untouched keys are unaffected.

What if I have both old and new keys?

If a key already exists at the new-schema path, the new-schema value takes precedence and the stale old key is removed. For example, if your file contains both global.rbacEnabled: true and global.rbac.enabled: false, the script keeps global.rbac.enabled: false and deletes global.rbacEnabled.

What if I have a full copy of values.yaml instead of just overrides?

The script works on full files, but Astronomer recommends extracting only your customizations into a separate override file. Running the migration on a full copy of the old defaults may carry forward old default values (like image tags) that should be updated to the new chart defaults.

Roll back

If you need to revert the values migration:

  1. Restore your backup:

    $cp my-values.yaml.backup my-values.yaml

  2. To downgrade the chart after a Helm upgrade:

    $helm rollback astronomer <previous-revision> --namespace astronomer