Drupal 9 Configuration Introduction

We dive into the Drupal Configuration Management system and the best practices for configuration in Drupal 9.

This blog was originally posted on June 26, 2020 at 

The Drupal Configuration Management System is one of the best additions to Drupal 8 (and continues to be present in Drupal 9). However, it also represents one of the most consistent sources of confusion (and frustration), particularly for people coming from D7 (where Features was the only game in town) or other content management systems that might not require such a concept.

What is Configuration? 

Configuration is the collection of admin settings that determine how the site functions, as opposed to the content of the site.

Put another way, Drupal uses its database to store settings and definitions for much of its functionality. Despite being in the databases, this is not content. Here are some examples of things Drupal treats as config:

  • Site name
  • Active / Default theme(s)
  • Content Type / Field / Display Mode / View Definitions
  • Roles and Permissions
  • etc.

Note that in many cases, configuration defines entities. For instance, if I define an article content type, that definition as well as the content type’s fields, display modes, etc. are all config. But the actual articles that I will create are content. Likewise, if I have a view that displays all my published articles, this is stored in configuration. However, Drupal only displays something to the end user if there is content in place.   (Otherwise, we would just have a view page with nothing on it).

While Drupal stores this configuration in the database, it also provides a mechanism for exporting and storing configuration in the file system as YAML files. Here's an easy way to keep track:

  • active configuration (what is actually being used by Drupal) is in the database
  • All configurations stored in YAML files are inactive (but still important)

Types of Configuration

Of the above examples of configuration, these fall into two general categories:

  • Simple / Site Configuration
  • Entity Configuration

Entity config is used to define entities and is significantly more complex. Typically, simple config has a single config file associated with it. For example, the system settings live in a single file called On the other hand, Entity config usually spans many files to accomplish everything necessary. Defining a content type, for instance, could easily create 20-30 separate configuration files! Between the actual entity definition (i.e. the various display modes (including the form), and all the fields and field storage (if necessary).

How Should You Use Configuration? 

One of the biggest drawbacks to storing configuration in the database is that you lose many of the benefits of following software development best practices. You know, little things like:

  • reviewing changes before they go live
  • storing changes in version control
  • syntax and quality checking

By using Git to store all of your configuration files, having a development workflow that involves checking code changes for coding standards, testing changes prior to deploying them,  you can largely resolve these issues! The YAML files give you the ability to do development, follow best practices, and import the configuration into the database(s) of your site(s) once you’ve deployed.

Screen Shot 2020-06-26 at 11.09.32 AM.png

There are a couple of ways to facilitate this import process. While Drupal provides a configuration import config directly in the UI, as with many Drupal UI tools, it’s not nearly as efficient as doing it with Drush! I strongly recommend importing config with the following command:

drush config-import

Let’s introduce the concept of configuration management workflow here. Usually, the workflow would be something like:

  • Define a change that needs to be made (this could be a bug fix, new feature, etc.)
  • Make that change locally (in a VM)
  • Export your configuration (using Drush)
  • Commit your change(s)
  • Open a Pull Request
  • Allow continuous integration to run (if using)
  • Test results
  • Commit Pull Request
  • Deploy change(s)
  • Import configuration (using Drush)

Here’s an example of a pull request that changes configuration. In this case, I updated a view to include some webform changes. Remember, this YAML file is not going to be active on your site(s) until it is both deployed and imported!

Why Is Managing Drupal Configuration So Hard? 

There are some not insignificant challenges in the configuration workflow I just proposed. In an ideal world, developers are working locally, CI is running automatically and deployments are all running the same basic configuration management workflow to change config. If you don’t have these things in place, making these changes does require some additional time and effort. If you’re using an automation tool like Acquia Build and Launch Tools (BLT) then you’re a big jump ahead. If not, then you may have a problem. Why?

You have to make sure that all of the stages of your workflow are happening in the same order every time. This represents yet another significant investment in DevOps that your team may (or may not) have the skill set / resources / time to implement.

BLT (and other similar tools) automate much of the workflow. For instance, whenever you deploy using BLT, it will:

  • Update your database
  • Import your configuration
  • Flush your caches.

If you aren’t using BLT, and you have different people on your team performing the above operations in different order(s), then you will have different results! In other words, if I test your code updating the database, then importing the config, but you deploy it importing the config then import the database, we will likely have different results. Maybe it passes for me locally, but breaks your site during the deployment. This is obviously a problem. It gets even more complicated if you’re running a multisite codebase (because you’re tracking configuration for multiple sites and trying to update multiple sites and their databases simultaneously during deployments).

Configuration management workflow is all about trying to make sure that all the things are the same and done in the same way, every time, everywhere. That’s non-trivial if you don’t have an automation tool, continuous integration and a robust deployment strategy.

I’ll dig into how to develop a Configuration Management Strategy and some best practices surrounding common configuration modules such as Config Split, Config Ignore and more in future posts. 

Featured Resources

View More Resources