With the introduction of Drupal 8, there have been some fundamental changes that significantly simplify deployment. These include, for example, the complete overhaul of Drupal's configuration management: content and configuration have been clearly separated and the option of saving configuration in YAML files has been created. The configuration is still cached in the database, but the file-based approach means that configuration changes can now be easily exported or imported.
If you need a consistent configuration across all installations of a Drupal website, Drupal 8's configuration management works great. However, you face a problem if you want to configure certain modules differently on local installations than on the live or staging system and vice versa. This is because regardless of whether the configuration of the different installations is different or not, either the same or a modified version of the configuration exists in all existing directories. This means that all configuration files must be compared with each other for each deployment. This process takes time and is also more prone to errors. In addition, the same file exists multiple times in the system.
The introduction of "Config Split" now offers the advantage that a configuration file only has to be stored once again in the split if it differs from the sync directory. If there is a configuration in the currently active split, this has priority and is used, otherwise the configuration from the sync directory is used.
In the following, we would like to give you instructions on how to perform a clean conversion from config directories to config split. Our example contains three output directories: sync, staging and live.
The aim is that after the conversion, cross-environment configurations are saved in the sync directory, while environment-specific configurations are saved in the corresponding split.
2. prepare the system
First of all, you should bring your system up to date. Make sure that all existing configuration directories are up to date, that database updates have been carried out, etc.
2.1 The settings.local.php
Your settings.local.php should look like this:
As we need to install config_split in the next step and make some settings, all split configurations should be commented out for the time being.
2.2 Install Config Split
Before we start the conversion process, it is worth clarifying a few terms.
Blacklist: The blacklist contains configuration elements that are explicitly managed by the split in question. These elements are removed from the sync directory. This means that you can save this configuration in one or more splits, but not in the sync directory.
Greylist: Configuration elements from the greylist are not removed from the sync directory, unlike the blacklist. If a configuration exists in the currently active split, this has priority and is used. If there is no configuration in the currently active split, the configuration from the sync directory is used.
If all necessary updates have been carried out, config_split can be installed and activated next.
A few settings must then be made. The module settings can be found under: Configuration -> Development -> Configuration Split settings.
Click on "Add Configuration Split setting" and make the following settings for "live".
- Folder: ../config/default/splits/live
- Status: Not active
Make sure that the machine name of the created split matches the directory in your system.
Repeat the same for "staging" and "development":
- ../config/default/splits/staging
- ../config/default/splits/dev
Now export the new config_split configuration by executing "drush cex sync -y".
3. create "live" configuration
3.1 live config_split configuration
Here you need to determine all modules that are only used on the live system.
The best way to do this is to compare the "sync" and "live" directories.
core.extension.yml:
- Copy the modules config_split and config_filter from core.extension.yml from sync to live
- Now determine all modules that exist for live but not for sync and add them to config_split.config_split.live.yml under "modules"
- Now determine all modules that are available for sync but not for live and add them to config_split.config_split.dev.yml under "modules"
- Add all files with differences to the "Greylist"
Here you can see an example of what your config_split.config_split.live.yml could look like:
3.2 Filling the "live" split directory
- Remove all $config_directories except "sync" from your settings.local.php.
- Copy the config_split*.yml files into your "live" directory
- Execute a config import: drush cim -y
- Now force a live split by commenting $config['config_split.config_split.live']['status'] = TRUE; . All other splits remain uncommented
- Change the target directory of the $config_directories['sync'] from "sync" to "live":
Now carry out the following steps:
- Create the "live" split directory: /config/default/splits/live
- Execute: cr; drush csex -y
- Now move all files in the greylist (manually) from the "live" directory to the "live" split directory.
- The /config/default/splits/live directory should now be filled with the "live" configuration
- A "cr; drush cim" should not show any changes
- Now all splits in the settings.local.php are commented out again
4. Create "staging" configuration
Repeat the steps above, with the exception that you now replace "live" with "staging".
5. create "dev" configuration
You have already set up the "dev" split configuration in the previous steps.
5.1 Filling the "dev" split directory
- Make sure that your settings.local.php looks like this:
- Execute a "cr; drush cim -y"
- Now force a dev split by commenting $config['config_split.config_split.dev']['status'] = TRUE; . All other splits remain uncommented
- Create the split directory "dev": /config/default/splits/dev
- Execute a "cr; drush csex -y"
- The /config/default/splits/dev directory should now be filled with the "dev" configuration
- All modules that only exist for dev should have been automatically removed from core.extension.yml
- The execution of "cr; drush cim" should not show any changes
6 Complete the conversion
- Now remove the live and staging directories
- Your settings.local.php should now look like this:
- Execute "cr; drush cim -y"
You can now deploy the changes, make the server-side settings and put Config Split into operation.
7 Conclusion & summary
As you can see in our example, a few steps are necessary for the conversion to use config_split. However, we would like to emphasize at this point that the effort required for the conversion is worthwhile, as Config Split has many advantages. Once the conversion has been completed, the team saves a lot of effort when working with different configurations. It also makes it possible to fully automate the test setup and deployment.
Do you still have an outdated Drupal version? Here you can find out everything about the Drupal 9 upgrade and the Drupal 10 upgrade.
