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.
https://www.drupal.org/docs/configuration-management
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 config. But, it 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 does store this configuration in the database, it also provides a mechanism for exporting and storing configuration in the file system as YAML files. An easy way to keep track:
active configuration (what is actually being used by Drupal) is in the database
all configuration stored in YAML files is 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. The system settings live in a single file called system.site.yml (for example). 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. node.type.page.yml) the various display modes (including the form), and all of the fields as well as 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
etc.
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, etc. 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.
There are a couple of ways to facilitate this import process. While Drupal does provide 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-importLet’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 all of these things in place, they aren’t just snap and make it happen changes. If you’re using a tool for automation 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, all the time. This represents yet another significant investment in DevOps that your team may (or may not) have the skillset / 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, therefore, 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.
How are you currently using config to support your projects? What are some of the common problems you run into?
Related Content
I hit a couple of issues updating to Drupal 9.3, so I wanted to share my experience. Config changes incoming!