Tips from the Dev Team: Using Config Split and Config Ignore to Fine-Tune Your Configuration Management Process

One of the challenges with configuration management is that there can be a fuzzy line between what is content and what is configuration. Content should not be exported as configuration: Editors and web designers should be free to change that content without it being overridden when the configuration is imported again.

Some elements are easy to divide into configuration and content: A menu is a configuration, but menu links are content. Block placement is configuration but custom block content is content. A taxonomy vocabulary is a configuration, but the term items are content.

But there are some types of elements that are a little fuzzier. Take, for example, a webform. A form is a configuration, but it also has content fields such as an instructions field and a thank-you message.

On the O8 website, we found that there were some configuration items that changed often on production while the marketing team did their work. Every time we pushed new configuration to production we would have to make sure to export these changes and commit them to git without accidentally overwriting the new configuration we were trying to deploy. We needed a better solution.

Developers also commonly use several utility modules while doing their work: we also need to make sure that this configuration is not enabled on production.

Luckily, there are a few additional modules we can use to solve these problems: Config Split and Config Ignore.

Config split is an excellent way to create a set of configurations that should only be enabled in certain environments. The classic use case for this is for modules and settings that are only needed for development work.

Follow these steps to implement a development-only config split:

1. Download and install Config Filter and Config Split modules

2. Move your main configuration directory to a subdirectory if it isn’t already in one (e.g. config/sync). Edit your settings.php file and change the update the main config directories path to the new subdirectory:

$config_directories[CONFIG_SYNC_DIRECTORY] = '../config/sync';

3. Create a directory for your new config split (e.g. confg/dev)

4. Set up the config split:

Make sure the machine name of your split matches the name of the folder you set up in step 3.

5. Add your development modules to the config split settings. In this case, we are going to completely split the configuration for Database Logging, Devel, Kint and Stage File Proxy modules.

As you can see, it is possible to export individual configuration items here, or even use wildcards to select sets of configuration.

6. To enable this split on your development environment only, add the following line to your settings.local.php file:

$config['config_split.config_split.dev']['status'] = TRUE;

7. Export your configuration using drush csex.

You should see that your development modules have been exported to the dev directory set up in step 3. A normal config export using drush cex should respect your config split, but there may be a bug with some versions of drush that prevents this from working. Always make sure to check the unchanged files list in git to make sure your dev config hasn’t accidentally been exported to the main sync directory. If it has, just run drush csex again.

More detailed instructions can be found in the Drupal documentation, including an explanation of when you could choose a Conditional Split instead of Complete Split as described above.

We could have used a config split for our web forms as well, but this presented a few logistical issues. We really don’t need to enable or disable this config in certain environments - we just need to prevent it from being overwritten on production. Config Ignore is a much better fit for this purpose.

Config Ignore simply prevents configuration from being imported. The process for setting this up is simple.

Follow these steps to implement a development-only config split:

1. In your development site, download and install Config Ignore module.

2. On the config ignore configuration screen, add the entries that you don’t want to ignore on import:

These machine names match the names of the yml files that are normally exported in a config export and displayed on the Configuration Synchronization screen when there are changes to import. As you can see with the web form example, you can use wildcards here.

3. Export configuration and deploy to production.

4. If changes are made to the ignored configuration items, you’ll see something like this when you try to import configuration:

The Configuration 2.0 initiative is a new effort to improve configuration management in Drupal core. Some of the work going on in that initiative will integrate functionality currently provided by config filter and config split (planned for Drupal 8.7), along with fixes for some other ongoing headaches for developers. Find out more about the Configuration Management 2.0 initiative here and here.