Configuration split

Note

Acquia will end support for BLT on December 31, 2024. For more information on how to replace your BLT implementation with updated functionality, see You don’t need BLT on Acquia Cloud.

Config split is the standard Configuration Management Strategy provided by BLT.

For more information, review Managing Configuration with Config Split.

Example Scenarios¶

Assume there is a kitchen sink website requiring all the preceding types of splits. The website is a multisite application and it will be hosted in several environments. The various environments must share some default configuration between all sites. The environments must allow some features, such as blog enablement, on some sites and not others.

Default configuration¶

Start by exporting the default configuration for the application. The default configuration is the configuration imported for your application, by default, even if no splits are defined or active. The default configuration will be shared by all websites using the application.

For the sake of the tutorial, let’s focus on one configuration setting: system.performance The system.performance setting controls caching and aggregation settings for Drupal core.

Navigate to /admin/config/development/performance, and then enable caching and aggregation.
Run the following command:
```
drush en config_split -y
```
Run the following command:
```
drush config-export -y
```
Run the following command:
```
drush cr
```

Running the preceding drush commands will populate ../config/default with all configuration for the website. The configuration setting ../config/default/system.performance.yml now exists and contains the following configuration (a partial representation):

cache:
  page:
   max_age: 3600
css:
  preprocess: true
  gzip: true
js:
  preprocess: true
  gzip: true

Test overriding and reverting¶

You can test the process of importing configuration by completing the following steps:

Navigate to /admin/config/development/performance.
Disable caching and aggregation.
Run the following command:
```
drush config-import
```

Caching and aggregation will be re-enabled, congruent with the prior exported configuration.

The preceding example is the simplest use case for the configuration management system.

Environment split¶

By default, you want caching, CSS, and JavaScript aggregation enabled on all environments, but you want the local environment to be an exception. You must disable caching and aggregation on local machines to speed up the development process.

To create the local environment exception, you will create a local configuration split. The following command blt recipes:config:init:splits will create the local configuration split, and automate your other environment splits. To create the “local” split manually, complete the following process:

Run the following command:
```
mkdir -p ../config/envs/local
```
Navigate to /admin/config/development/configuration/config-split/add
In the user interface, enter values for the following fields:
- label: Local
- folder: ../config/envs/local
- Navigate to Conditional Split > Configuration items > Select system.performance
Save your field changes.

Run the following command:

drush config-export -y

The Drush command will export the configuration definition for the split itself, which is stored in config/default/config_split.config_split.local.yml. The file must contain the following settings:

uuid: ...
langcode: en
status: true
dependencies: {  }
id: local
label: Local
folder: ../config/envs/local
module: {  }
theme: {  }
denylist: {  }
graylist:
  - system.performance
graylist_dependents: true
graylist_skip_equal: true
weight: 0

Run the following command:
```
drush cr
```
This Drush command allows the configuration split to recognize the local split is active. You rely on BLT to display the split as active on local computers using a settings.php include.

With your local split ready, continue the following process:

Navigate to /admin/config/development/performance and disable caching and aggregation.
Run the following command:
```
drush csex
```
With the local split being active, the Drush command will export the local split system.performance settings to ../config/envs/local/system.performance.yml, and must contain the following configuration:
```
cache:
page:
  max_age: 0
css:
preprocess: false
gzip: false
js:
preprocess: false
gzip: false
```

Supported environment splits¶

BLT has built-in support for the following environment splits:

Split	Environment	File path
`local`	Any non-Acquia, non-Travis environment	`../config/envs/local`
`ci`	Acquia Pipelines or Travis CI	`../config/envs/ci`
`dev`	Acquia Dev environment	`../config/envs/dev`
`stage`	Acquia Staging environment	`../config/envs/stage`
`prod`	Acquia Prod environment	`../config/envs/prod`
`ah_other`	Any Acquia environment not listed here	`../config/envs/ah_other`

BLT will mark only the preceding splits as enabled if they exist, and won’t create the splits for you.

Note

The folder is relative to the Drupal docroot.
You configure active to zero because you don’t want configuration management to manage whether the split is active. Instead, you will rely on BLT to enable the split, when appropriate, through a settings.php include. If you are using BLT, the include must load for you as a consequence of including blt.settings.php in your settings.php file. You may override the logic by configuring $split in settings.php before including blt.settings.php.
Even on your local environment, after running drush config-import, the local configuration split has a status of active (overwritten). The status is normal and doesn’t point to a problem. The fact the local configuration split is active is an override of the exported active: 0 setting in the split itself. It doesn’t necessarily mean the configuration which the split controls is actually overridden.

Feature split¶

Consider you are creating a multisite Drupal application. You want Site A and Site B to have blogs, and Site C to have no blog. You must manage the blog feature itself through configuration management.

To create the feature split, you will create a blog configuration split active on Site A and Site B, but not on Site C.

Creating a feature split¶

Create a blog content type.
Run the following command:
```
mkdir -p ../config/features/blog
```

From /admin/config/development/configuration/config-split/add, add the following code:

status: false
label: Blog
folder: ../config/features/blog
denylist:
  - core.base_field_override.node.blog_entry.promote
  - core.entity_form_display.node.blog_entry.default
  - core.entity_view_display.node.blog_entry.default
  - core.entity_view_display.node.blog_entry.teaser
  - field.field.node.blog_entry.body
  - node.type.blog_entry
  - system.action.user_add_role_action.blog_entry_creator
  - system.action.user_add_role_action.blog_entry_reviewer
  - system.action.user_remove_role_action.blog_entry_creator
  - system.action.user_remove_role_action.blog_entry_reviewer
  - user.role.blog_entry_creator
  - user.role.blog_entry_reviewer
graylist: {  }
graylist_dependents: true
graylist_skip_equal: true
weight: 0

Visit /admin/config/development/configuration/ignore, and then add the following line to Configuration entity names to ignore:
```
config_split.config_split.blog:status
```
The preceding code will instruct the configuration management system to ignore the status of the blog configuration split. Ignoring the status will permit you to export a default status of false for the blog split, and still manually enable the split on selected sites without flagging the split as overwritten.
Run the following command:
```
drush config-export -y
```
The configuration for the blog split itself must now exist in ../config/default/config_split.config_split.blog.yml.
Run the following command:
```
drush cr
```

Enabling a feature split¶

Assume you want to enable the blog split for multisite Site 2, to enable the blog feature, complete the following steps:

Visit /admin/config/development/configuration/config-split and enable Blog split.
Import configuration for Site2 by running the following command:
```
drush config-import --uri=site2
```

Issues with the feature split approach¶

The status of the feature split isn’t managed through configuration management. You must enable the split by using the user interface even on a production environment.
It can be difficult to identify all the configuration a given feature must encompass.
It’s not possible to disentangle a single feature from all related configuration. For instance, you may segment the node configuration and fields for the Blog feature, but config/default/search_api.index.content.yml and config/default/views.view.search.yml still contain references to blog_entry in their exported configuration. These references aren’t necessarily problematic, but can be messy.

Multisite split¶

Consider if you want your website to have different cache lifetimes, then the default configuration specifies. You have the following two directories:

docroot/sites/default
docroot/sites/site2

Creating a multisite split¶

Run the command mkdir -p ../config/site2 to ensure you have the following configuration directories:
- config/default
- config/site2

Create a split for Site 2:

status: false
label: Site 2
folder: ../config/site2
denylist: {  }
graylist: {  }
graylist_dependents: true
graylist_skip_equal: true
weight: 0

Running commands against multisites¶

When running a Drush command against a multisite, include the uri option. For example:
```
drush --uri=site2
```
When running a BLT command against a multisite, include the website configuration value. For instance, blt setup --define site=site2. BLT also allows you to create website-specific configuration. For more information, see Multisite.

Profile split¶

If you are using multisite, you may want to use several installation profiles for your application. BLT will evaluate if a split exists having the same name as your active installation profile. For example, if a given website on your application uses the minimal profile, BLT configures the minimal configuration split to active, if the split exists. Typically, you store profile splits in config/profiles/[profile_name].

However, BLT does not support install profile- (or just profile-) based splits. The recommended workflow is to use the Profile Split Enable module to support this capability.

Miscellaneous¶

Exporting to an inactive split¶

When developing locally, you often must export to a split other than local. For instance, you may want to change some of the configuration in the dev split by using the following methods:

Manually changing the configuration files is the most straightforward, but time-consuming method.
Using the drush config-split-export [split] command to export to a specific split. For instance, to export the current configuration on your local server to the dev split, you must run: drush config-split-export dev

Conflicting configuration¶

Greater weight takes precedence: Where possible, you must avoid exporting the same configuration (with different values) to several splits. Exporting the same configuration is sometimes desirable. When two splits define the same configuration, the split with the greater weight will take precedence. The logic is counterintuitive, as the common Drupal convention is for elements with lesser weights to take precedence.

Several splits denylist the same configuration: If you want to export denylisted configuration in more than one split, then you must use the drush config-split-export [split] commands and specify the split to which you would like to export the configuration.

Terminology¶

Complete split (denylist): denylisted splits are denylisted from config/default. If a given split is active, and the split defines a configuration setting in its denylist, the configuration setting won’t export to config/default when drush config-export runs:

Exported to split
Not exported to default configuration

Conditional split (graylist): Graylist splits allow a given configuration setting to export to both the default configuration and also to a split’s configuration (overriding default when active):

Exported to split
Also exported to default configuration

Graylists are also used for configuration intended to be unlocked in production (such as webforms).

Development settings¶

To disable the plug-in discovery cache, add the following code to your local.settings.php file:

$settings['cache']['bins']['discovery'] = 'cache.backend.null';

The preceding code will prevent needing to clear caches to register a status change in a configuration split.

Example Scenarios¶

Default configuration¶

Test overriding and reverting¶

Environment split¶

Supported environment splits¶

Feature split¶

Creating a feature split¶

Enabling a feature split¶

Issues with the feature split approach¶

Multisite split¶

Creating a multisite split¶

Running commands against multisites¶

Profile split¶

Miscellaneous¶

Exporting to an inactive split¶

Conflicting configuration¶

Terminology¶

Development settings¶

Resources¶