Information for:

# Configuration split¶

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

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

1. Navigate to /admin/config/development/performance, and then enable caching and aggregation.

2. Run the following command:

drush en config_split -y

3. Run the following command:

drush config-export -y

4. 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:

1. Navigate to /admin/config/development/performance.

2. Disable caching and aggregation.

3. 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:

1. Run the following command:

mkdir -p ../config/envs/local

2. Navigate to /admin/config/development/configuration/config-split/add

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

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

6. Run the following command:

drush cr


This Drush command allows the configuration split to recognize the local split is active. You rely on Acquia BLT to display the split as active on local computers using a settings.php include.

With your local split ready, continue the following process:

1. Navigate to /admin/config/development/performance and disable caching and aggregation.

2. 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¶

Acquia 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 Cloud Platform pipelines feature 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

Acquia 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 Acquia BLT to enable the split, when appropriate, through a settings.php include. If you are using Acquia 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¶ 1. Create a blog content type. 2. Run the following command: mkdir -p ../config/features/blog  3. 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  4. 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. 5. 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. 6. 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: 1. Visit /admin/config/development/configuration/config-split and enable Blog split. 2. 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¶ 1. Run the command mkdir -p ../config/site2 to ensure you have the following configuration directories: • config/default • config/site2 2. 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 an Acquia BLT command against a multisite, include the website configuration value. For instance, blt setup --define site=site2. Acquia BLT also allows you to create website-specific configuration. For more information, see Multisite. ## Profile split¶ Acquia BLT does not supports install profile- (or just profile-) based splits. The recommended workflow is to use the Profile Split Enable module to support this capability. If you are using multisite, you may want to use several installation profiles for your application. Acquia 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, Acquia BLT configures the minimal configuration split to active, if the split exists. Typically, you store profile splits in config/profiles/[profile_name]. ## 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.