Config governance

Astro Private Cloud (APC) 2.0 uses config governance to describe how platform operators and, where allowed, workspace and deployment admins control and change platform and deployment-level settings. If you are choosing which layer to edit first (Helm, cluster, workspace, or deployment), start with the shorter guide, Configure Astro Private Cloud, then return here for rules, blocklists, and API detail. For tabular defaults and allowed values under astronomer.houston.config.deployments, see Helm configuration reference.

Config governance in Astro Private Cloud enables settings under the deployments section of the Helm values file to be overridden at the Cluster, Workspace, or Deployment level, allowing for fine-grained control over the configuration of each Apache Airflow Deployment.

Config governance uses a layered deep merge of deployments (cluster, workspace, and deployment layers on top of the platform default), so effective values for those keys resolve predictably. Settings outside the deployments section (such as the astronomer, global, webserver, and nats sections) can only be changed in the Helm values files, and not in the three deployment override layers.

Overview

For settings under the deployments section, config governance resolves values by merging four tiers, where each subsequent tier overrides the previous for keys it sets:

Platform (Helm / values.yaml default) → Cluster → Workspace → Deployment

When APC resolves a configuration value for a Deployment, it starts with the platform defaults, merges in any cluster-level overrides, then workspace-level overrides, and finally deployment-level overrides. Later tiers always win for any key they set.

What can be configured

Config governance applies to all settings under the deployments.* part of the platform config in your values.yaml (under astronomer.houston.config). This includes:

Blocklisted keys

Certain configuration keys can’t be overridden at the workspace or deployment level because they are tightly coupled to platform or cluster infrastructure.

Workspace-level blocklist

The following keys can’t be set in workspace-level overrides:

Deployment-level blocklist

The following keys can’t be set in deployment-level overrides (superset of workspace blocklist):

If you attempt to set a blocklisted key, the API returns a BlocklistedDeploymentConfigKeysError with the offending key names.

DELETE_KEY and strict schema validation

The string "DELETE_KEY" is a merge sentinel for cluster, workspace, and deployment deploymentsConfigOverride objects. When you set a key’s value to "DELETE_KEY", the control plane removes that key from the stored override (or a whole subtree, if you set a parent to "DELETE_KEY"), so the effective value falls back to the next tier. Use it with the updateCluster, updateWorkspaceDeploymentsConfig, and updateDeploymentConfig GraphQL mutations. See Override data plane cluster configurations for the cluster case. You can’t use "DELETE_KEY" to remove keys that are required in the platform’s default deployments object.

The astronomer.houston.strictSchemaCheck.enabled value in your platform values file controls whether deployment override payloads are validated against a JSON schema. When this is true (the default in the 2.0 Astronomer Helm chart), unknown top-level domain keys and invalid types are rejected. When false, that validation is skipped, which is useful in edge cases such as Git-Sync relay metrics where you need helm keys the schema doesn’t list yet. After you change the flag, apply it with a Helm upgrade of the control plane.

Cluster-level configuration

Cluster-level overrides apply to all Deployments within a specific data plane cluster. This is useful for setting cluster-specific defaults like resource limits, executor configurations, or feature flags that should apply uniformly to all Deployments in a given cluster.

For instructions on configuring cluster-level overrides, see Override data plane cluster configurations.

Workspace-level configuration

Workspace-level overrides apply to all Deployments within a specific workspace. This allows Workspace Admins to customize settings for their team without affecting other Workspaces.

Add or update workspace configuration

You can set workspace configuration overrides using the Astro UI or the APC API.

1
mutation {
2
  updateWorkspaceDeploymentsConfig(
3
    workspaceUuid: "<workspace-id>"
4
    deploymentsConfigOverride: {
5
      deploymentLifecycle: {
6
        deployRollback: {
7
          enabled: true
8
        }
9
      }
10
    }
11
    reason: "Enable deploy rollback for all deployments in this workspace"
12
  ) {
13
    id
14
    config
15
  }
16
}

1
mutation {
2
  updateWorkspaceDeploymentsConfig(
3
    workspaceUuid: "<workspace-id>"
4
    deploymentsConfigOverride: {
5
      deploymentLifecycle: {
6
        deployRollback: {
7
          enabled: "DELETE_KEY"
8
        }
9
      }
10
    }
11
    reason: "Remove deploy rollback override, revert to cluster/platform default"
12
  ) {
13
    id
14
    config
15
  }
16
}

Delete workspace configuration

Deleting workspace configuration removes all workspace-level overrides, reverting all Deployments in the workspace to use cluster-level and platform-level defaults.

1
mutation {
2
  deleteWorkspaceDeploymentsConfig(
3
    workspaceUuid: "<workspace-id>"
4
    reason: "Revert workspace to cluster defaults"
5
  ) {
6
    id
7
    config
8
    deletedAt
9
  }
10
}

Deployment-level configuration

Deployment-level overrides apply to a single Deployment. This is the most granular tier and takes the highest precedence. Use this to customize a specific Deployment’s behavior without affecting other Deployments in the same workspace.

Add or update deployment configuration

You can set deployment configuration overrides using the Astro UI or the APC API.

1
mutation {
2
  updateDeploymentConfig(
3
    deploymentUuid: "<deployment-id>"
4
    deploymentsConfigOverride: {
5
      airflowComponents: {
6
        triggerer: {
7
          enabled: false
8
        }
9
      }
10
    }
11
    reason: "Disable triggerer for this specific deployment"
12
  ) {
13
    id
14
    config
15
  }
16
}

1
mutation {
2
  updateDeploymentConfig(
3
    deploymentUuid: "<deployment-id>"
4
    deploymentsConfigOverride: {
5
      airflowComponents: {
6
        triggerer: {
7
          enabled: "DELETE_KEY"
8
        }
9
      }
10
    }
11
    reason: "Remove triggerer override, revert to workspace/cluster default"
12
  ) {
13
    id
14
    config
15
  }
16
}

Delete deployment configuration

Deleting deployment configuration removes all deployment-level overrides, reverting the Deployment to use workspace-level, cluster-level, and platform-level defaults.

1
mutation {
2
  deleteDeploymentConfig(
3
    deploymentUuid: "<deployment-id>"
4
    reason: "Revert to workspace/cluster defaults"
5
  ) {
6
    id
7
    config
8
    deletedAt
9
  }
10
}

Effective configuration

The effective configuration for a Deployment is the result of merging all four tiers. The Astro UI doesn’t include a dedicated screen for the fully merged result or a per-key source tier readout (Platform, Cluster, Workspace, or Deployment). You retrieve that from the GraphQL API instead.

The Deployment type exposes the merged deployments object on effectiveConfig (the final value after the Platform through Deployment merge). It also exposes configOverrides for the deployment tier only, when you need the fourth layer in isolation. For cluster- and workspace-level override payloads, use the corresponding GraphQL queries or fields on those objects in your client.

For example, workspaceDeployment can return the merged result alongside deployment-level overrides:

1
query {
2
  workspaceDeployment(
3
    releaseName: "<release-name>"
4
    workspaceUuid: "<workspace-id>"
5
  ) {
6
    id
7
    label
8
    effectiveConfig
9
    configOverrides {
10
      config
11
    }
12
  }
13
}

To work out the source tier for a given key, compare the merged effectiveConfig to each tier’s contribution (platform defaults, cluster and workspace override records, and configOverrides as appropriate). The API doesn’t label each key with a tier, but the underlying data is all available for inspection with GraphQL.

See also Example GraphQL API queries for workspaceDeployment request parameters and related patterns.

How merge works

Configuration merging uses a deep merge strategy:

1. Start with the platform’s default deployments object from your control plane values.yaml (astronomer.houston.config).
2. Deep-merge cluster-level overrides (if the Deployment’s cluster has overrides).
3. Deep-merge workspace-level overrides (if the Deployment’s workspace has overrides).
4. Deep-merge deployment-level overrides (if the Deployment has its own overrides).

For any key that appears at multiple tiers, the lowest tier wins (Deployment > Workspace > Cluster > Platform). For nested objects, the merge is recursive — you only need to specify the keys you want to override, and all other keys at that level are preserved from the parent tier.

Example

Given the following configuration at each tier:

Platform default:

1
deployments:
2
  deploymentLifecycle:
3
    deployRollback:
4
      enabled: false
5
      deployRevisionReportNumberOfDays: 90
6
      dagTarballVersionValidation:
7
        enabled: true

Cluster override:

1
deploymentLifecycle:
2
  deployRollback:
3
    enabled: true

Workspace override:

1
deploymentLifecycle:
2
  deployRollback:
3
    deployRevisionReportNumberOfDays: 30

The effective configuration for Deployments in this workspace and cluster would be:

1
deploymentLifecycle:
2
  deployRollback:
3
    enabled: true                        # from Cluster
4
    deployRevisionReportNumberOfDays: 30 # from Workspace
5
    dagTarballVersionValidation:         # from Platform; not set at Cluster or Workspace
6
      enabled: true

Configurable domains reference

The following table lists the top-level configuration domains under deployments and their availability at each override tier.

Best practices

• Keep overrides minimal: Only set values that need to differ from the parent tier. Fewer overrides mean less configuration drift and easier debugging.
• Use workspace-level overrides for team defaults: If all Deployments in a workspace need a common setting (like enabling deploy rollback), set it at the workspace level rather than on each Deployment individually.
• Use deployment-level overrides for exceptions: Reserve deployment-level overrides for cases where a single Deployment needs to deviate from workspace defaults.
• Use the DELETE_KEY mechanism: Remove individual keys from an override without deleting the entire configuration. This is more precise than deleting and recreating the override.
• Review effective configuration: In the GraphQL API (for example Deployment.effectiveConfig on workspaceDeployment), compare the merged result after making changes to confirm that the merge produced the expected result.