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
- label:
- 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: 0Run 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/performanceand 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.performancesettings 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
includemust load for you as a consequence of includingblt.settings.phpin yoursettings.phpfile. You may override the logic by configuring$splitinsettings.phpbefore includingblt.settings.php. - Even on your local environment, after running
drush config-import, the local configuration split has a status ofactive (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 exportedactive: 0setting 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
blogcontent 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: 0Visit
/admin/config/development/configuration/ignore, and then add the following line to Configuration entity names to ignore:config_split.config_split.blog:statusThe 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
falsefor 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-splitand 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.ymlandconfig/default/views.view.search.ymlstill contain references toblog_entryin 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/defaultdocroot/sites/site2
Creating a multisite split
- Run the command
mkdir -p ../config/site2to ensure you have the following configuration directories:config/defaultconfig/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
urioption. 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.