Information for: DEVELOPERS   PARTNERS

Configuration split

Config split is the standard Configuration Management Strategy provided by Acquia BLT. Acquia BLT does support other options for configuration management (or none), see Configuration management with Acquia 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.

  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
  4. Save your field changes.

  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: {  }
    blacklist: {  }
    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 Acquia Cloud 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
    blacklist:
      - 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
    blacklist: {  }
    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 lightning profile, Acquia BLT configures the lightning 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 blacklist the same configuration – If you want to export blacklisted 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 (blacklist) – Blacklisted splits are blacklisted from config/default. If a given split is active, and the split defines a configuration setting in its blacklist, 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). If you want to customize the behavior, you can use the graylist feature described in Advanced Drupal 8 Configuration Management (CMI) Workflows.

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.