> ## Documentation Index
> Fetch the complete documentation index at: https://astronomer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Astro Private Cloud

Astro Private Cloud (APC) 2.x uses four customer-facing configuration layers:

* A platform-wide `values.yaml`, which you apply with Helm.
* Cluster configuration, which you set for one data plane cluster.
* Workspace overrides, which apply to all Deployments in one Workspace.
* Deployment overrides, which apply to one Deployment.

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

## Use the right configuration layer

Use `values.yaml` when you want to change:

* Sign-in configuration, such as `auth`.
* Platform services, such as registry, ingress, email, and cleanup jobs.
* The default value for a Deployment setting across the platform.

Use cluster configuration when you want to change:

* A `deployments.*` setting for every Deployment in one data plane cluster.
* A cluster-specific exception to the platform default.

Use a Workspace override when you want to change:

* A `deployments.*` setting for every Deployment in one Workspace.
* One Workspace without affecting other Workspaces in the same cluster.

Use a Deployment override when you want to change:

* A `deployments.*` setting for one Deployment only.
* One Deployment without changing the rest of the Workspace.

If your goal is "change this everywhere," use `values.yaml`. If your goal is "change this for one cluster, one workspace, or one Deployment," use the most specific override that matches the scope you want.

## 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, Workspace, and Deployment overrides don't change.

If a cluster, Workspace, or Deployment already has its own saved value for the same `deployments.*` key, that saved value stays in effect until you update that specific override through Astro Private Cloud API or UI.

APC 2.x chooses the final value in this order:

1. Platform default
2. Cluster configuration
3. Workspace override
4. Deployment override

```mermaid actions={true} wrap theme={null}
flowchart TD
  platformHelm["Platform (Helm / values.yaml default)"] --> clusterConfig[Cluster configuration]
  clusterConfig --> workspaceConfig[Workspace override]
  workspaceConfig --> deploymentConfig[Deployment override]
```

Treat the preceding list as priority from top to bottom. If the same setting is set in more than one place, the lower line (closer to a single Deployment) is usually what applies. A few settings can be changed only in `values.yaml` or only at the cluster; for those rules, see [Config governance](/docs/astro-private-cloud/v-2-x/config-governance).

## In the Astro UI (2.0)

Use the Astro UI when you aren't using the APC API or your own automation:

* Data plane (cluster): In **Clusters**, open a cluster, then use **Configuration Override** (and related sections on the cluster page). This matches [Data plane overrides](/docs/astro-private-cloud/v-2-x/override-data-plane-cluster).
* Workspace: In a Workspace, go to **Settings**, then **Configuration Overrides**, and edit the YAML for all Deployments in that Workspace in that cluster.
* Deployment: In a Deployment, open **Configuration Overrides** and edit the YAML for a single Deployment.

<Note>
  On a data plane cluster, you edit in **Configuration Override** and you read **Current Configuration** as read-only (defaults, or after you save, a read-only, git-style view of what was added or modified), as in [Data plane overrides](/docs/astro-private-cloud/v-2-x/override-data-plane-cluster). In Workspace and Deployment settings, the **Configuration Overrides** editor is different: it shows the override stored for that workspace or that Deployment. In every case, the platform still combines the four layers in the order above. Who can open and edit these pages depends on your [role and permissions](/docs/astro-private-cloud/v-2-x/role-permission-reference). Platform administrators can [change role permissions](/docs/astro-private-cloud/v-2-x/manage-platform-users#customize-role-permissions) in `values.yaml`.
</Note>

## 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.

Use a Workspace override for examples like these:

* Keep one business unit on a different Deployment default than the rest of the cluster.
* Change one Workspace without affecting other Workspaces in the same cluster.

Use a Deployment override for examples like these:

* Test a different Deployment setting on one Deployment.
* Make a one-off exception for a single team or environment.

## Example: Same setting at all four levels

Assume you want to control whether Deployment rollbacks are enabled.

1. You set the platform default in `values.yaml`:

```yaml wrap theme={null}
astronomer:
  houston:
    config:
      deployments:
        deploymentLifecycle:
          deployRollback:
            enabled: false
```

2. The `prod-us-east` cluster overrides the same key to `true`.
3. The `finance` Workspace overrides the same key back to `false`.
4. One Deployment in the `finance` Workspace overrides the same key to `true`.

Result:

* The specific Deployment uses `true`.
* Other Deployments in the `finance` Workspace use `false`.
* Other Deployments in `prod-us-east` use `true`.
* Clusters without a more specific override use the platform default of `false`.

If you run another Helm upgrade and leave the cluster, Workspace, or Deployment override in place, those more specific saved values still win.

## Use the highest scope that matches your goal

To keep configuration manageable:

* Use `values.yaml` for shared defaults.
* Use cluster configuration only when one data plane cluster truly needs a different value.
* Use Workspace overrides only when one Workspace truly needs a different value.
* Use Deployment overrides sparingly for exceptions.

## Important limits

Not every key under the platform `deployments` tree can be set in every override tier, and some keys are blocklisted at the Workspace or Deployment level. The Astro UI and API reject those writes.

* Workspace overrides: `authSideCar`, `logging` can't be set.
* Deployment overrides: `authSideCar`, `logging`, and `namespaceManagement` can't be set.

Rationale, API errors, `DELETE_KEY`, and `strictSchemaCheck` are covered starting at [Blocklisted keys](/docs/astro-private-cloud/v-2-x/config-governance#blocklisted-keys) in [Config governance](/docs/astro-private-cloud/v-2-x/config-governance).

To create or change overrides with automation, use the `updateCluster`, `updateWorkspaceDeploymentsConfig`, and `updateDeploymentConfig` GraphQL mutations, which are described in the same [Config governance](/docs/astro-private-cloud/v-2-x/config-governance) page.

## 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 saved cluster, Workspace, or Deployment overrides. If you want to change a saved value under the platform `deployments` tree, update the specific override at the scope where it is stored.

## Related documents

* [Config governance](/docs/astro-private-cloud/v-2-x/config-governance)
* [Helm configuration reference](/docs/astro-private-cloud/v-2-x/helm-config-reference)
* [Apply a config change](/docs/astro-private-cloud/v-2-x/apply-platform-config)
* [Data plane overrides](/docs/astro-private-cloud/v-2-x/override-data-plane-cluster)
* [Astro Private Cloud user role and permission reference](/docs/astro-private-cloud/v-2-x/role-permission-reference)