Configure Astro Private Cloud | Astronomer Documentation

Astro Private Cloud (APC) 1.x uses two customer-facing configuration layers:

values.yaml, which you apply with Helm.
Cluster configuration, which APC stores in the platform database and which you set per data plane cluster from the Astro UI or the Houston API.

Use this document to decide which knob to change and what to expect after you apply the change.

What changed from APC 0.x

In APC 0.x, you set most application configuration in values.yaml and applied it with Helm. In APC 1.x, configuration that varies per data plane cluster moves out of values.yaml and into the platform database, where you manage it as cluster configuration through the Astro UI or the Houston API.

The reason for the change is that APC 1.x supports multiple data planes from one control plane. A single values.yaml on the control plane can’t express different Deployment defaults for different data plane clusters, so APC 1.x stores per-cluster deployments.* values in the database instead. The control plane reads cluster configuration from the database and pushes it down to each data plane.

For an upgraded environment, your existing values.yaml still sets platform defaults. Per-cluster deployments.* values are seeded into the database the first time you register or update each data plane cluster. After that, you change them through cluster configuration, not by editing values.yaml.

To edit cluster configuration in the Astro UI or automate it with the Houston updateCluster mutation, see Data plane overrides. This page only covers where each setting lives; the editing steps and the example mutation are on that page.

Where each setting lives in 1.x

Use this matrix to find where to change a setting in APC 1.x.

Setting category	Control plane `values.yaml`	Data plane `values.yaml`	Cluster configuration (Astro UI or Houston API)
Identity provider and authentication (`astronomer.houston.config.auth`)	Yes	No	No
Platform services (registry, email, cleanup jobs)	Yes	No	No
Ingress (control plane endpoints and data plane endpoints such as Commander, Elasticsearch proxy, Prometheus, registry, and Deployment ingresses)	Yes	Yes	No
Platform-wide Deployment defaults (`astronomer.houston.config.deployments.*`)	Yes	No	No
Per-cluster Deployment behavior (`deployments.*` for one data plane)	No	No	Yes
Data plane chart version, namespace pool metadata	No	Set at install, then synced by APC	Synced from data plane
Data plane node selectors, tolerations, and other infrastructure values	No	Yes	No
Custom resources for Airflow Deployments (`helm.airflow.extraObjects`)	No	No	Yes

values.yaml always covers control-plane platform settings. Cluster configuration always covers per-cluster deployments.* values. Data plane infrastructure values stay in the data plane values.yaml. See Helm configuration reference for the full list of values.yaml keys.

Where to see effective configuration

For values.yaml, run helm get values <release> -n <namespace> on the control plane or data plane. This shows what you applied through Helm.
For cluster configuration, open the cluster in the Astro UI and review Current Configuration, which is the read-only effective view for that cluster. To edit it, see Data plane overrides.
For the merged result on a Deployment, the cluster value wins for any deployments.* key the cluster has saved. Everywhere else, the values.yaml value applies.

Use the right configuration knob

Use values.yaml when you want to change:

Sign-in configuration, such as auth.
Platform services, such as registry, email, and cleanup jobs.
Ingress on the control plane, and on each data plane (each data plane values.yaml sets its own ingress endpoints for Commander, Elasticsearch proxy, Prometheus, registry, and Deployment ingresses).
The default value for a Deployment setting across the platform.

Use cluster configuration when you want to change:

A deployments.* setting for one data plane cluster only.
The behavior of Deployments in one cluster without changing the platform default for other clusters.

If your goal is to change a setting for one data plane, use cluster configuration. If your goal is to change it everywhere, use values.yaml and Helm.

What happens when you run Helm

When you update values.yaml and run a Helm upgrade:

Platform-level settings change after the Helm upgrade finishes.
Platform defaults under astronomer.houston.config.deployments change.
Saved cluster configuration doesn’t change just because you ran Helm.

If a cluster already has its own saved value for the same deployments.* key, that cluster keeps its saved value until you update the cluster configuration through Astro Private Cloud.

This is the source of the most common confusion in APC 1.x: customers run a Helm upgrade, expect one data plane cluster to change, and then don’t see the result because that cluster still has its own override for the same deployments.* key.

In APC 1.x, cluster configuration is the final layer for deployments.*.

Every Deployment is registered to a data plane cluster. The platform default for those deployment settings is what you set in values.yaml. If you save a value in a cluster’s Configuration Override, that value applies to the cluster and to all Deployments on that cluster for that key instead of the matching default from values.yaml alone. If you don’t set a key in the cluster override, the value from values.yaml still applies.

In the Astro UI (1.x)

For a data plane cluster, open Clusters, select the cluster, then use Configuration Override (as in Data plane overrides). In APC 1.x you only use Helm (values.yaml) and the cluster; there are no separate workspace or deployment configuration screens like in 2.0.

On a cluster, you make changes in Configuration Override and you review Current Configuration as read-only (defaults, or after you save, a read-only, git-style view of what was added or modified). See the UI sections in Data plane overrides. A Deployment on that cluster still uses the values.yaml default for a key the cluster hasn’t set, and the value from the cluster override when it is set, as described earlier on this page.

Decide where to change a setting

Use values.yaml for examples like these:

Enable or disable an identity provider.
Change a cleanup schedule.
Change the default Deployment behavior for all clusters.

Use cluster configuration for examples like these:

Enable a deployment feature only for the prod-us-east data plane.
Keep one regulated cluster on a different Deployment setting than the rest of the platform.
Override a platform default you had set in values.yaml.

Example: Helm upgrade versus cluster configuration

Assume you want to control whether Deployment rollbacks are enabled.

You set the platform default in values.yaml:

1 astronomer:
2   houston:
3     config:
4       deployments:
5         deploymentLifecycle:
6           deployRollback:
7             enabled: false

You run a Helm upgrade.
The platform default changes to false.
Clusters without a saved cluster value for deployments.deploymentLifecycle.deployRollback.enabled now use false.
Your prod-us-east cluster still uses true because its cluster configuration already stores that key in the database.

Result:

Helm changed the platform default.
The cluster-specific value still won for prod-us-east.
To change prod-us-east, you must update the cluster configuration, not just rerun Helm.

What APC can update separately

APC can refresh some data plane metadata separately from a Helm upgrade. For example, it can sync values such as data plane chart version or namespace pool metadata back into the cluster record.

This isn’t the same as replacing your saved cluster override. If you want to change a saved deployments.* value for a cluster, update the cluster configuration directly.

Summary

Use values.yaml for platform-wide settings and platform-wide deployment defaults.
Use cluster configuration for deployments.* settings that should differ for one data plane cluster.
If both layers set the same deployments.* key, the cluster value wins in APC 1.x.