Migrate from unified mode to a split control plane and data plane

Astro Private Cloud (APC) supports three provisioning modes, set by global.plane.mode in the APC Helm chart:

unified — the control plane and data plane run in the same cluster and namespace. This is the legacy default for existing APC installations.
control — control plane components only, managing one or more remote data planes.
data — data plane components only, registered with and managed by a remote control plane.

A split control plane and data plane (CP/DP) is a prerequisite for capabilities such as data plane failover, multi-cluster management, and dedicated Airflow clusters. This document describes how to migrate an existing unified-mode installation to split mode within the same cluster, with no Airflow downtime and no data loss. The migration is a two-phase process:

Control plane migration — Put the cluster into maintenance mode, then run a Helm upgrade that switches global.plane.mode from unified to control. The existing cluster becomes a standalone control plane. Airflow Deployments keep running throughout, but the platform accepts no updates from the API or UI during the transition.
Data plane provisioning and re-association — Provision a new data plane in the same cluster, verify its endpoints, and bind the new data plane back to the control plane.

Deployment domains don’t change during the migration. The split data plane reuses the existing global.baseDomain and ingress controller, so Airflow Deployment URLs stay identical to the prior unified installation.

Migration steps at a glance

Upgrade the cluster to APC 2.1, the minimum version eligible for the CP/DP split.
Enable maintenance mode on the cluster to block Deployment provisioning calls during the migration.
Upgrade the platform from unified to control mode.
Provision a new data plane in the same namespace.
Re-bind the control plane to the data plane’s internal gRPC and metadata endpoints.
Disable maintenance mode and resume Airflow Deployment operations.

Prerequisites

An APC platform running in unified mode, upgraded to APC 2.1 or later. APC 2.1 is the minimum version eligible for the CP/DP split.
The Cluster Admin or System Admin role. Only these roles can put a cluster into maintenance mode.
Access to the platform Helm release and kubectl access to the cluster.
A backup of the platform metadata database and your current Helm values, taken before you begin.
A record of your existing unified-mode Helm values. You reuse most of them and change only the keys shown in this document.

If your unified installation uses in-cluster Elasticsearch for logging, you must enable shared Elasticsearch during the migration (shown in Phase 1) so that Airflow task and component logs survive the mode change.

Phase 1: Migrate the control plane

Enable maintenance mode

Put the cluster into maintenance mode so that Deployment mutations are blocked during the cutover. This also cordons existing Airflow Deployments so that the Helm upgrade doesn’t re-roll them.

mutation {
  cordonCluster(clusterId: "<cluster-id>", reason: "maintenance") {
    id
    isCordoned
    cordonedAt
  }
}

While maintenance mode is active, the platform blocks REST API calls, GraphQL mutations, and Astro CLI operations that change Airflow Deployment state on the cluster, and returns cluster is under maintenance. Existing Airflow Deployments keep running: Dag runs, task execution, the triggerer, and schedulers are unaffected.

Update the Helm values for control mode

Change the following keys in your existing platform values. Keep all other unified-mode values unchanged.

global:
  baseDomain: <base-domain>  # unchanged from your unified install
  plane:
    mode: "control"          # switched from "unified"
  # Enable only if your unified install uses in-cluster Elasticsearch logging.
  # Keeps Elasticsearch running in control mode as a shared log store.
  sharedElasticsearch:
    enabled: true
astronomer:
  houston:
    upgradeDeployments:
      enabled: false         # disables the upgrade deployments job

(Optional) Bring Your Own ingress controller or OpenShift

If you run your own ingress controller or Red Hat OpenShift, enable the auth sidecar and set your ingress annotations instead. Adjust the annotations to match your ingress controller class.

global:
  baseDomain: <base-domain>  # unchanged from your unified install
  plane:
    mode: "control"          # switched from "unified"
  # Enable only if your unified install uses in-cluster Elasticsearch logging.
  # Keeps Elasticsearch running in control mode as a shared log store.
  sharedElasticsearch:
    enabled: true
  authSidecar:
    enabled: true
  extraAnnotations:
    # set according to your ingress controller class configuration
    openshift-default.kubernetes.io/ingress.class: openshift-default
    route.openshift.io/termination: edge
astronomer:
  houston:
    upgradeDeployments:
      enabled: false         # disables the upgrade deployments job

Applying these values runs a Helm upgrade, which upgrades every Airflow Deployment on an uncordoned cluster. Confirm the cluster is in maintenance mode (the previous step) before you apply, and set --set astronomer.houston.upgradeDeployments.enabled=false.

If your unified install uses in-cluster Elasticsearch, you must set global.sharedElasticsearch.enabled: true. Without this flag, Elasticsearch is torn down when the cluster switches to control mode and historical logs become unavailable.

Run the Helm upgrade

Apply the updated values with a Helm upgrade and wait for the release to reach a deployed state. The data plane components are removed and the cluster is reconfigured as a standalone control plane.After the upgrade, Airflow Deployments are no longer explorable in the UI. This is expected: the data plane internal API isn’t available in control-only mode, so calls to it return an error until you provision and bind the new data plane in Phase 2. Existing Airflow workloads continue to run.

Phase 2: Provision the data plane and re-associate

Provision the data plane

Install a new data plane release in the same namespace. For a same-cluster data plane:

Leave global.plane.domainPrefix empty so that the data plane reuses the existing global.baseDomain.
Set global.nginx.enabled: false so that the data plane reuses the existing ingress controller instead of installing its own.
Set the ingress class annotation so that traffic routes to the existing controller.

global:
  baseDomain: <base-domain>                   # same as the control plane
  plane:
    mode: "data"
    domainPrefix: ""                          # reuse the existing baseDomain
  sharedElasticsearch:
    enabled: true                             # match the control plane setting
  extraAnnotations:
    kubernetes.io/ingress.class: "<control-plane-release-name>-nginx"
  nginx:
    enabled: false                            # reuse the control plane's ingress controller
  postgresql:
    enabled: false
  tlsSecret: astronomer-tls
  ssl:
    enabled: true
    mode: "require"

(Optional) Bring Your Own ingress controller or OpenShift

If you run your own ingress controller or Red Hat OpenShift, enable the auth sidecar and set your ingress annotations instead. Adjust the annotations to match your ingress controller class.

global:
  baseDomain: <base-domain>                   # same as the control plane
  plane:
    mode: "data"
    domainPrefix: ""                          # reuse the existing baseDomain
  sharedElasticsearch:
    enabled: true                             # match the control plane setting
  authSidecar:
    enabled: true
  extraAnnotations:
    # set according to your ingress controller class configuration
    openshift-default.kubernetes.io/ingress.class: openshift-default
    route.openshift.io/termination: edge

(Optional) In-cluster hosted registry with a StatefulSet

If your data plane uses an in-cluster registry hosted with a StatefulSet, include the following block in the data plane values so it reuses the control plane’s registry.

astronomer:
  registry:
    enabled: true
    fullnameOverride: <control-plane-release-name>-registry

Don’t set global.plane.domainPrefix. Setting it generates a new set of Deployment base domains, which causes widespread downtime, forces a Deployment upgrade, and changes user-facing URLs.

The data plane and control plane share one ingress controller in split mode. If you use the default ingress controller, set the global.extraAnnotations ingress class to the control plane’s ingress class (<control-plane-release-name>-nginx) so that traffic routes to the existing controller.

Use a different Helm release name from the original unified release. Wait for the data plane Pods to become ready.

Re-bind the control plane to the data plane

Point the control plane at the new data plane’s internal API (gRPC) and metadata endpoints with the updateCluster mutation.

mutation {
  updateCluster(
    id: "<cluster-id>"
    commanderEndpoint: "commander.<global-baseDomain>:443"
    metadataEndpoint: "http://<dataplane-release-name>-commander.<namespace>.svc.cluster.local.:8880"
  ) {
    id
  }
}

Cluster metadata reconciles automatically after updateCluster, so the split-mode configuration is refreshed without a separate manual sync.

The metadata and gRPC endpoint values appear in the post-install output of the data plane Helm release. Copy those values into the updateCluster mutation.

Disable maintenance mode

Take the cluster out of maintenance mode to restore normal operations.

mutation {
  uncordonCluster(clusterId: "<cluster-id>") {
    id
    isCordoned
    cordonedAt
  }
}

Verify the migration

Confirm the following after the cutover:

The control plane and data plane Pods are running and healthy.
Each Airflow Deployment is running and reachable at its existing domain. The same-cluster data plane reuses baseDomain, so URLs are unchanged.
Airflow task logs and component logs are continuous across the migration with no gap. This confirms the shared Elasticsearch configuration.
Metrics history is intact.
The cluster is out of maintenance mode and Deployment mutations succeed again. Create or update a test Deployment to confirm.

Roll back

You can roll back a CP/DP split setup to a unified installation with the following steps.

Enable maintenance mode

Put the cluster into maintenance mode so that Deployment mutations are blocked during the cutover. This also cordons existing Airflow Deployments so that the Helm upgrade doesn’t re-roll them.

mutation {
  cordonCluster(clusterId: "<cluster-id>", reason: "maintenance") {
    id
    isCordoned
    cordonedAt
  }
}

Uninstall the split data plane Helm release

helm uninstall <dataplane-release-name> --debug

Upgrade the control plane back to unified

Change the following keys in your control plane platform values to switch from split back to unified mode.

global:
  baseDomain: <base-domain>  # unchanged from your split install
  plane:
    mode: "unified"          # switched from "control"
astronomer:
  houston:
    upgradeDeployments:
      enabled: false         # disables the upgrade deployments job

Apply the values with a Helm upgrade:

helm upgrade <control-plane-release-name> -f config.yaml --no-hooks

Running with --no-hooks skips the blocking jobs for the missing components. After the Helm upgrade completes, all components return to normal.

Re-bind the metadata and gRPC endpoints

Point the control plane at the data plane’s internal API (gRPC) and metadata endpoints with the updateCluster mutation.

mutation {
  updateCluster(
    id: "<cluster-id>"
    commanderEndpoint: "<control-plane-release-name>-commander.<namespace>.svc.cluster.local:50051"
    metadataEndpoint: "http://<control-plane-release-name>-commander.<namespace>.svc.cluster.local.:8880"
  ) {
    id
  }
}

Disable maintenance mode

Take the cluster out of maintenance mode to restore normal operations.

mutation {
  uncordonCluster(clusterId: "<cluster-id>") {
    id
    isCordoned
    cordonedAt
  }
}

Verify the rollback

Confirm that the return to unified mode is complete:

The control plane and data plane components are healthy.
Airflow Deployments are accessible and you can update them.
Airflow task logs and component logs are continuous across the migration with no gap. This confirms the shared Elasticsearch configuration.
Metrics history is intact.
The cluster is out of maintenance mode and Deployment mutations succeed again. Create or update a test Deployment to confirm.

After migration

A same-cluster split satisfies the prerequisite for disaster recovery: the Deployments are now eligible for failover. Enabling failover is a separate procedure and requires a separate destination cluster; it isn’t provided by this migration. See Enable data plane failover.

Overview

Architecture

Upgrade to Astro Private Cloud 2.0

Install Astro Private Cloud

Develop Dags

Airflow administration

Airflow 3

Deploy Dags

Manage Deployments

Platform administration

Manage Platform resources

Security and compliance

APC API

Platform Observability

Release notes

Reference

Migrate from unified mode to a split control plane and data plane

Migration steps at a glance

Prerequisites

Phase 1: Migrate the control plane

Phase 2: Provision the data plane and re-associate

Verify the migration

Roll back

Verify the rollback

After migration

​Migration steps at a glance

​Prerequisites

​Phase 1: Migrate the control plane

​Phase 2: Provision the data plane and re-associate

​Verify the migration

​Roll back

​Verify the rollback

​After migration

Migration steps at a glance

Prerequisites

Phase 1: Migrate the control plane

Phase 2: Provision the data plane and re-associate

Verify the migration

Roll back

Verify the rollback

After migration