Four Kitchens: Managing configuration in Drupal upstreams

Image removed.

Mike Goulding

Senior Drupal Engineer

Mike has been part of the Four Kitchens crew since 2018, where he works as a senior engineer and tech lead for a variety of Drupal and WordPress projects.

January 1, 1970

A common time-saver for organizations managing multiple Drupal sites is reducing to shared code in a concept called an upstream. This can be done through a hosting provider, continuous integration tooling, or old-fashioned copy-and-paste. (But don’t do that!)

This saves time by having most of the code shared by these sites stored in a single repository while allowing the sites to be somewhat unique from each other. It also avoids some of the overhead and pitfalls of a traditional Drupal multisite installation — something that several hosting providers haven’t been keen on recently.

A struggle that occurs when using the upstream technique is deploying a global configuration that should apply to all or some of the sites without removing what is uniquely theirs. In previous versions of Drupal, this was done using the Features module, and that is something that can still be done with some success. However, Features does come with some downsides regarding managing different configurations across sites.

In the setup described above, this becomes especially troublesome when configurations between sites need to be overridden. One site has a different field added to the blog content type, and the features import process can become painfully complex to deal with by itself.

So, what option do I suggest for upstreams and organizations managing multiple sites? Configuration Split. In particular, the latest iteration of this module, 2.x, which allows for easier conditional splitting and importing of configuration.

What is Configuration Split?

Configuration Split, or Config Split, as it is better known, has been around for a while, enabling many excellent uses. A quick example of how this module has been used would be enabling various modules and configuration between different environments for a site. It allows for importing different configuration files into a Drupal site based on certain set conditions.

Specifically, it allows for splitting up configuration into different groups that can be set to inactive or active programmatically. This is an improvement from both using the Features module and using other custom code to enable and disable things manually on different sites or environments.

Using Config Split simplifies configuration management by keeping development-specific modules and settings separate from the main site configuration. This helps maintain a cleaner environment on production and allows for automatic installation and removal of development-only features.

Additionally, Config Split can also be used for version control purposes. By splitting configuration into different groups, it becomes easier to track changes and roll back to previous configurations, if needed. This is especially useful for larger sites with multiple developers working on different features or environments.

Config Split 1.x

The initial release of Config Split opened up opportunities to do something different with Drupal configuration that wasn’t possible before with the default configuration management system. By allowing different groups of configuration that can be activated and deactivated, it empowers teams to easily bring different configurations to different situations.

Some common uses that we saw early on were enabling specific development modules and settings for use only in local development environments. This was previously something that would have to be built into tooling locally to script out. Now it just happens because of a condition placed into settings. It took some guesswork out of what would be enabled on which environment, and that was a big help.

The ecosystem for Config Split includes more than just enabling and disabling certain configuration. Another big part is Config Ignore, which makes it possible to have configuration that isn’t changed on import. The earliest version of this module was more conceptual than it is now, but it still provided a way to avoid exporting and importing changing configuration (like blocks), that was meant to exist only on live environments. When paired with Config Split, this offered great control over which configuration would be active and in-use in specific environments.

Stacking, patching, and more

Though it may seem in conflict with the glowing review above, Config Split didn’t always mean that managing configuration was easier or simpler. In fact, it often meant that there were even more configuration files to manage, and parsing changes to a file in a code review would make even the most senior engineer groan. It solved bigger problems than it caused, but there were still downsides that gave teams pause and sparked discussion of whether there was a better way.

Thankfully, there is a better way! The newest version of Config Split, 2.x, brought many big changes that make this easier to manage, along with a few useful bonuses. One improvement was the concept of patches for partial configuration splits. Partial changes from the default configuration can now be represented with much smaller yaml files that only show what was added and/or removed instead of repeating the entire file. This makes code reviews of the changes much, much easier to deal with!

Along with additional improvements to how configuration imports and exports when splits are involved, another addition in the newer version of the module is stackable configuration. This means that splits that would previously have been in conflict, like adding a field and changing a label to a content type from different split groups, can now work together. This also means that test environments can better represent live environments while still enabling development modules and logging output without the configuration import complaining during the build.

This isn’t always the silver bullet for all of your problems. As we’ve discussed recently, there can be some steps that need documentation and considerations for maintenance to fully make use of Config Split on a build. This is especially something to consider when updates to other modules in use have updates that affect multiple configuration files.

Using Config Split to manage multiple sites

Recently, we have taken these improvements from Config Split and applied them to managing multiple sites and upstreams. Using set conditions like environmental variables or site names, we can use splits for features or configurations that are unique to individual sites in the project. In some ways this can feel like a stretch on the intended use case for the module, but it solves the problem well in the cases we have used it. I’ll illustrate more in a specific example where this has been used.

Let’s take a project where an organization is going to have multiple similar but unique websites. They have a small team, and want to manage these sites from a single repository to make deployments quick, but don’t want to prevent the sites from being somewhat different. In some ways, a Drupal multisite can resolve part of this issue, but there are hosting limitations for that. Additionally, the multisite doesn’t completely avoid the issue of configuration differences, as those sites would still be using different databases.

In this situation, we use a single repository and use a continuous integration tool like CircleCI to push the code from that repository to the different sites where they are hosted. In this repository, we set up Config Split for each site in the project and the global configuration based on an example or default site. This way, configuration and features that should be available for the whole project can be developed in one place and deployed to each site. We can also make small changes to sites that make them different without incurring a lot of extra weight.

In a single repository configuration, we have different settings.php files that are loaded based on environmental variables so that each site always imports the correct information. This allows for differences in settings, content types, fields, and other aspects of the site. All of this with just one repository to manage and deployed to different instances without the duplication of effort and review between them. Sites can share similar architecture and have some differences without requiring a lot of overhead. The changed files are easy to review at a glance, knowing that only what is or should be different will be present.

We’ll talk about this more as time goes on and the module continues to grow. Adding this module to the toolbox for a Drupal site really can make managing one or more sites easier and more consistent. Should existing sites using features or something similar move to Config Split? I strongly feel that it is simpler to manage and that the workflow is more enjoyable.

The post Managing configuration in Drupal upstreams appeared first on Four Kitchens.