Skip to main content
info@drupalodyssey.com
Friday, November 20, 2026
Contact

Main navigation

  • Home
  • Services
  • Insights
  • Notebook
  • About
Search
Development

Architecting Drupal Configuration Management for Multi-Tier and Multi-Site (ACSF) Deployments

November 20, 2026

Config management at single-site scale is tractable. At multi-tier plus multi-site scale — especially on Acquia Cloud Site Factory — it’s where production incidents are born. The pattern is deceptively straightforward: export your configuration locally, commit it to Git, import it on each upstream environment. What’s less obvious is where that pattern breaks, how it breaks quietly, and what the right architectural decisions look like before you’re running drush config:set on production at 2am.

This post covers the full stack: the standard multi-tier CMI workflow, environment separation using Config Split 2.x and core's own exclusion mechanism, three CI/CD conflict scenarios with concrete resolution paths, plain Drupal multi-site, and ACSF — including factory hooks, site duplication scrubbing, and what comes after BLT.

Bottom Line for Stakeholders

Decision Recommendation
Config sync directory Outside webroot, version-controlled, read-only on production
Env-specific module separation config_exclude_modules for simple cases; Config Split 2.x for key-level patching
CI/CD pre-deploy check drush config:status fails the build on live config drift
ACSF tenant variance Config Ignore for per-site overrides; factory hooks for lightweight runtime values only
Tooling Acquia CLI + Composer scripts — BLT is EOL

The Core Mechanics

$settings['config_sync_directory'] lives outside the webroot, committed to version control. That's the foundation. Drupal core's default.settings.php recommends a path outside the public docroot [1]. On Acquia production, the codebase is read-only by design, so your sync directory can only be written from a local environment. The database is writable. The codebase isn't. Know which bucket you're in.

drush deploy standardizes what happens after a code push: database updates, then config import, then cache rebuild, then deploy hooks, then cache warming as of Drupal 11.2 [2]. The order is load-bearing. drush updatedb runs before drush config:import specifically because config entities require entity schema to exist before they can be saved. Run them in the wrong order and you'll get cascading errors that look like config failures but are actually schema failures. drush deploy handles this correctly by design.

Two Flavors of settings.php Override

Here's where it gets interesting. $config overrides inject runtime values that bypass the configuration storage layer entirely. Set $config['system.performance']['css']['preprocess'] = FALSE; on dev and CSS aggregation is off — but drush cex won't see that change, because the override never touched the database [1]. Useful for per-environment toggles. The critical constraint: you cannot use $config to enable or disable modules. Overriding core.extension is explicitly unsupported by Drupal core. Use it for values, not for module lists.

For module exclusion, core's $settings['config_exclude_modules'] is the right tool for the simple case. Add devel and stage_file_proxy to the array and their entire dependency trees are excluded from export and invisible to drush config:import on environments where the array isn't set [3]. It's a full-module toggle — you can't surgically exclude individual config keys. That's where Config Split 2.x [4] earns its keep.

The jump from 1.x to 2.x matters: 1.x required the Config Filter module as a dependency. 2.x uses Drupal core's configuration transformer API with zero external dependencies [4]. And 2.x supports key-level patching — you can split individual settings keys out of a config file into an environment-specific patch, rather than moving entire config objects.

Activation from settings.php:

// In settings.php for the development environment
$config['config_split.config_split.development']['status'] = TRUE;

A plain drush config:import picks it up from there — no special command is needed once the split is active.

CI/CD: Three Failure Scenarios Worth Knowing

Production config drift, concurrent branch conflicts, and site UUID mismatches. These are the three CMI failure modes that catch teams by surprise. Each has a clean detection and resolution path.

Scenario 1: Config changed on live. Someone made a UI change directly on production. It's in the database, not in Git. Your next deployment will overwrite it. The right pre-deploy CI check:

# Fail the build if active config differs from sync storage
drush config:status 2>&1 | grep -v "No differences"

drush config:status reports differences between the active config in the database and the sync directory [2]. If your CI pipeline runs this before deployment and fails on output, you catch the drift before it's clobbered. If the live change was intentional, export it (drush cex), commit it, and treat it as a real change.

Scenario 2: Two feature branches touching the same config. YAML merge conflicts in Git. Standard Git tooling flags them, but here's the trap: a text-only resolution of a YAML conflict can produce a file that's syntactically valid but semantically broken. Resolve the conflict at the text level, then drush config:import on a local environment to validate, then drush config:export to produce a clean, Drupal-normalized version. Commit that. Never commit a hand-merged YAML file without validating it in a running Drupal instance.

Scenario 3: Site UUID mismatch. You set up a fresh environment from a database copy, or installed Drupal fresh and tried to import config from an existing site. Drupal's StorageComparer::validateSiteUuid() compares the UUID in system.site:uuid between the sync storage and the target database, and it refuses to proceed if they don't match [1].

Prevention: install with drush site:install --existing-config [2]. This installs Drupal using the YAML files in your config sync directory as the authoritative source, so the resulting database's UUID already matches your config.

Remediation when you're already in the hole:

UUID=$(grep "^uuid:" config/sync/system.site.yml | awk '{print $2}')
drush config:set system.site uuid "$UUID"
drush cr

After that, drush config:import proceeds normally. Rebuild caches after the UUID update — there are entity ID relationships that need to be re-resolved.

Plain Multi-Site: The Baseline

Before ACSF, there's standard Drupal core multi-site. sites/sites.php maps HTTP request domain and port combinations to directories under sites/, each with its own settings.php [1]:

// sites/sites.php
$sites['staging.client-a.com'] = 'client-a';
$sites['staging.client-b.com'] = 'client-b';

Each site directory has its own settings.php, its own $settings['config_sync_directory'] path pointing to its own config tree, its own database. Full isolation. Full management overhead. For two or three sites that need very different configurations, this is the right choice. For thirty sites that share a codebase and 90% of their configuration, it's the wrong one. That's ACSF.

ACSF: One Codebase, One Sync Directory

The fundamental ACSF architectural constraint: all factory sites share one codebase and one configuration sync directory [5]. There is no per-site config tree. When you deploy to an ACSF factory, every site on that factory imports the same configuration from the same sync directory. Your config needs to represent what every site shares, and you need a mechanism to protect the things that legitimately differ between sites.

Config Ignore is that mechanism. Acquia's own documentation uses shield.settings as the concrete example — if you want each site to have its own Shield credentials, add shield.settings to Config Ignore's pattern list, and config import leaves that config object untouched on each site [5][6]. The site keeps whatever value is in its database. The shared factory config doesn't overwrite it.

The warning is worth taking seriously: overuse Config Ignore and you end up with untracked site-specific drift you can't audit. Use it for genuine tenant-level differences — credentials, branding tokens, a site-specific API endpoint. If a config difference is meant to eventually merge into the shared config, Config Ignore isn't the right answer.

Factory hooks (factory-hooks/post-settings-php/) handle per-site runtime injection. These are PHP files included by ACSF's sites/g/settings.php on every Drupal bootstrap request via acsf_hooks_includes() [5][7]. Each hook file runs for every request. That means two hard constraints: no file I/O, no database queries. Violate them and you've added blocking overhead to every single page load across all factory sites.

<?php
// factory-hooks/post-settings-php/site-variables.php
$site_data = $GLOBALS['gardens_site_settings'];
// Lightweight runtime assignment -- no I/O, no database queries
$settings['site_name_override'] = $site_data['site']['name'];

Don't remap $settings['config_sync_directory'] to a per-site path in a factory hook. The whole point of ACSF's architecture is a single shared sync directory. Routing config imports to per-site directories defeats the factory model entirely. Keep factory hooks for lightweight runtime variables.

Cloning a Site: Duplication Scrub

When you clone an ACSF site, Drupal's normal config system isn't what handles the cleanup — ACSF's duplication scrub does. The command is drush acsf-duplication-scrub-batch, and it runs event handlers that reset site-specific state [7].

If you need to hook into the scrub process — to clear custom state, reset an external integration, re-initialize a per-site value — the available alter hooks are hook_acsf_duplication_scrub_context_alter, hook_acsf_duplication_scrub_remaining_counts_alter, hook_acsf_duplication_scrub_admin_roles_alter, and hook_acsf_duplication_scrub_preserved_users_alter [7]. These are the hooks that actually exist in acsf_duplication/acsf_duplication.api.php. There is no generic hook_acsf_duplication_scrub().

The State API: Config's Escape Hatch

drush state:set system.maintenance_mode 1 --input-format=integer. drush state:get system.cron_last.

State is stored in the key_value database table. It's never exported by drush cex. It doesn't appear in your sync directory. It doesn't get imported on a peer environment. The distinction matters most on ACSF: if a value needs to differ between factory sites and changes at runtime rather than at deploy time, the State API is the right answer. Config Ignore protects config objects at import time; the State API holds operational state that config management was never designed to touch. They're not competing solutions. They're different tools for different categories of data.

After BLT

Acquia BLT reached end of life on December 31, 2024, and it doesn't support Drupal 11+ [8]. If you're on a project still running BLT, the migration path is Acquia CLI (ACLI) for Acquia-specific operations, Composer scripts for build orchestration, and your CI/CD pipeline for deployment automation. Don't add it to any new project. Don't add it to anything planning a Drupal 11 migration.

The architecture itself isn't complex. The failure modes are. Know where each tool's boundary sits — config management vs. runtime state, shared factory config vs. per-site overrides, Config Ignore vs. factory exclusion — and the multi-tier, multi-site deployment story holds together. Get those boundaries wrong and you're doing archaeology on a production incident instead.

Working through ACSF config architecture on an active project? Drop a comment below or find me on the Drupal Slack — I want to hear how you're handling the edge cases.

Sources

[1] https://git.drupalcode.org/project/drupal/-/blob/11.x/sites/default/default.set… - Drupal core: default.settings.php
[2] https://www.drush.org/13.x/deploycommand/ - Drush 13: deploy command
[3] https://www.drupal.org/node/3079028 - Drupal change record: config_exclude_modules
[4] https://www.drupal.org/project/config_split - Config Split project
[5] https://docs.acquia.com/site-factory/help/90611-implement-config-mgmt-site-fact… - Acquia: Configuration management in Site Factory, part 3
[6] https://www.drupal.org/project/config_ignore - Config Ignore project
[7] https://git.drupalcode.org/project/acsf/-/blob/8.x-2.x-release/acsf_init/lib/si… - acsf module source: sites/g/settings.php
[8] https://docs.acquia.com/acquia-cloud-platform/help/90196-blt-eol-resources - Acquia: BLT end-of-life
Author

Ron Ferguson

 

Next Blog

Ad - Header (728*90 AD)

Ad - Sidebar (300 x 600 AD)

Ad - Sidebar (300 x 250 AD)

Newsletter

Subscribe my Newsletter for new blog and tips.

Menu

  • Home
  • Services
  • Insights
  • Notebook
  • Portfolio
  • Resources
  • About

Legal

  • Privacy Policy
  • Terms & Conditions
  • Disclaimer
  • Cookies

I specialize in custom development, performance tuning, and reliable maintenance, delivering clean code and strategic solutions that scale with your business. Ready to discuss your project?

E: info@drupalodyssey.com
Fort Worth, TX

© 2026 All Rights Reserved.

Proud supporter of active military, veterans and first responders.