A blog by the Brick Factory The Brick Factory
Drupal Blog Post Header

A step-by-step guide to configuration management in Drupal 8

One of the best improvements in Drupal 8 is the new configuration management system. This post explains how things have changed from Drupal 7, and provides a step-by-step walk of Drupal 8 configuration management.

Configuration in Drupal 7

If you’ve spent much time site building or programming in Drupal 7, you probably have worked with the Features module. This module was originally created as a way to package config to easily create reusable functionality on multiple Drupal sites. But it evolved to be used for a much larger task: deploying configuration that is stored in the database between environments for the same site (commonly pushed to a code repository like git).

Our Brick Factory team started using Features for our Drupal 7 builds around four years ago, and it has saved us a bunch of time and headaches.  Before Features, we had to remember the configuration changes we made on the dev environment so we could manually re-apply them on the staging and live servers (which is loads of fun!). Features made it very simple to do this and not have to remember all of the config changes.

The Features module did fill a huge need, but it also came with some unique problems:

  • Learning Curve: The learning curve was steep. For us to get comfortable with the concepts and the flow, it took around a year of experience using the module across different projects.
  • Organization: It seemed like people had different ideas in how Feature modules should be organized across the Drupal community. From my experience, I think grouping into small feature modules prevents a lot of issues in the future, especially with large sites.
  • Overwritten Status: The overwritten status could mean multiple things. Did someone update config on live manually? Or did someone push changes to the feature modules and forget to revert? What was changed? This led to a lot of confusion.

Configuration Management in Drupal 8

The configuration management system in Drupal 8 solves a lot of the headaches we encountered with Features in Drupal 7. The learning curve is greatly reduced, the organizational structure for the configuration is already defined and the nebulous “overwritten” status is cleared up. It does take some time playing with it to understand the flow, but our experience is that the learning curve is much less steep than with Features in Drupal 7.

Below I explain how to use the Configuration Management system in Drupal 8. I know it probably seems like a very complicated process, but once you go through it a few times, it should clear up how this system works.

Content vs Configuration

Similar to Features in D7, it is important to understand what is considered configuration and what is considered content in D8.  The only thing the configuration management system handles is configuration. Here are a few things that are considered configuration:

  • Content Types
  • Block Types
  • Everything under Admin -> Configuration
  • Everything under Admin -> Appearance,
  • Views.

Here are a few things that are considered content and are not touched with this system:

  • Nodes
  • Custom blocks added on admin/structure/block/block-content
  • Users
  • Content for other entities

Moving content from environment to environment (not config) requires a different module flow (one example would be the Deploy module) and isn’t handled by configuration management.

Get Familiar with the Drupal 8 Configuration Management System

Hands on learning is really the only way to understand Drupal 8 configuration management.  I suggest setting up a new, sandbox D8 site or using a development D8 site locally so that you can experiment without having to worry about breaking anything.  Once you have your environment set up work through some common use cases.  

Step #1: Enable Configuration Management and go to Synchronization admin page

Make sure the “Configuration Manager” module is enabled. Clear Drupal cache after you enable the module, which is included with Drupal 8 core.

Go to the Synchronize admin page: /admin/config/development/configuration. This is an important area because it not only tells you the config files that have changed between the active configuration (what is in the Drupal db) and what is staged (in the config YAML files), but also allows you to click on each row to view the exact differences. This is extremely useful  because if you think the client or another developer might have updated configuration on live, you can see exactly what was done. Even when using Drush for exporting/importing configuration, I still find this area extremely valuable.

Step #2: Export Your Active Configuration

Before you can sync configuration between environments, you need to first do a full export of your active configuration. This generates the configuration YAML files in your config_files directory. By default this directory is in your user uploaded directory, but can be changed in your settings file.

There are two ways to export your active configuration to the config YAML files in your sync directory:

  1. Run drush config-export (or drush cex)
  2. Go to the Synchronize admin page, click on the Export tab -> Full Archive and download the exported file. You then need to manually extract the compressed file and move those files into your config_files directory.
    Once you do this, the Synchronize admin page should not list any differences between your Active configuration (Drupal db) and the Staging configuration (config YAML files). At this point you can commit the config YAML files to your repository.

Once you do this, the Synchronize admin page should not list any differences between your Active configuration (Drupal db) and the Staging configuration (config YAML files). At this point you can commit the config YAML files to your repository.

Note: You cannot import the configuration files into other Drupal 8 sites with core. It has to be done on the same site. However, it can be the same site on different environments. So if someone sets up a new Drupal 8 site locally where they go through the Drupal installation process…they will not be able to import your site configuration. They will need to download the DB either from a dev environment or your local and start from that DB.

Note: If your hosting provider allows this, I recommend moving your config_files directory outside of your document root.

Step #3: Understanding Exporting and Importing Configuration

If you have used Features in Drupal 7, this should be familiar. There are two ways to handle configuration:

Export

This is what you did in Step #2. The idea is that you are taking all of the configuration defined in your Drupal database and converting it to YAML config files. I suggest using the drush cex command to make this simple. You would do this if you update config in your local Drupal website.

Import

Export provides a way to go from the Drupal database to config files. Import does the exact opposite. It imports the configuration from the config YAML files into your Drupal database. To do this you can click on the “Import All” button on the Synchronization page, or use the drush command: drush config-import (or drush cim).

The key element to understanding the concept is that when you drush cex (export), you are having your config files wiped out and match your Drupal database config exactly. When you run drush cim, you are wiping out the configuration in your Drupal database and having it match what is in your config files exactly. This is important because you need to understand when you should run each of these commands. See the How to Avoid Issues section below for a way to easily avoid this problem.

For example, if you apply a config in the Drupal admin, and then run drush cim you are going to wipe out the configuration change you just madein the Drupal admin. If you pull in config file changes from your code repository, apply a change in the Drupal config admin area and then run drush cex you will wipe out the new changes that were pushed to the repository.

The drush based workflow doc page is a good reference for more info.

Step #4: Play with It!

At this point your active configuration should 100% match your staging configuration. It is time to understand what happens when your Drupal config changes and when your staging config files change.

Drupal Config Changes (Drupal database)

Let’s make a very basic change in our Drupal db configuration and see what happens.

(1) In the rupal admin area, make a simple config change. For example, go to /admin/config/system/site-information and update the Site Name field.

(2) Go back to the Synchronize admin page and notice what happens:

Configuration-Synchronization-Changed1

It is telling you your active and staging config do not match. Click on the View Differences button to see what has changed:

Configuration-Synchronization-Changed2

(3) On the left it is telling you what was changed in your Drupal DB configuration. On the right it is showing you what is defined in the config files (staged).

(4) At this point seeing what happens when you run drush cex or drush cim is the best way to understand how things work. If you export what is in your active configuration will also be in your staged configuration (which is probably what you want in this case). If you import, the change you just made will get wiped out and it will go back to what is in your configuration files.

Note: This illustrates the idea that if you pull in changed config files and update Drupal config in the admin right after that, you are going to be in a pickle in that you will either have to wipe out the changes in the config files or wipe out the changes you just made in the Drupal config! Later in the article I document a process in avoiding this scenario.

Staged Config Changes (config YAML files)

Now we need to see what happens when the config files are changed. This would happen if someone exported new config they made locally and pushed to the repository. In this case you usually want to make sure your Active configuration gets updated with what is in the config files so you don’t wipe out their changes.

(1) Let’s make the same change we did in the Drupal admin, directly to the config files. Now you don’t necessarily have to get comfortable working with the config files directly, but it does help to have a basic understanding in how the YAML works.

(2) Go to your config_files directory and open the system.site.yml file. Change the value under the “name” key to something different.

(3) Go to the admin synchronization page and click the View Differences button. It should look like this:

Configuration-Synchronization-Changed3

Notice how the change in this case appears in the Staged column? That is because the change was done in the configuration files and not in the Drupal admin area.

(4) To get your active configuration to match what is in the config files, you need to run drush cim. If you run drush cex at this point, it will wipe out what was in the config files.

How to Avoid Issues: The safe flow of configuration between people and environments

It may seem confusing, but if you are working on a team where multiple people are working on configuration changes, there is a process you can have everyone follow that minimizes the risk of people wiping out each other configuration changes.

  • Before you apply any configuration, pull down the latest code from your repository. Run drush cim and import all configuration into your local drupal database. This will have your local drupal site match 100% what is in the configuration files.
  • Apply your Drupal configuration change.
  • Run drush cex to update the config files with your changes.
  • Pull in code if someone else pushed to the repo and then push your changes. If someone updated the same configuration during this time, you may have a merge conflict to deal with.
  • Pull and run drush cim on the dev environment.


If everyone on your team follows this flow, it should avoid most problems. We’ve had 4-6 people working on the same site, all doing different configuration changes, and it has gone very smoothly!

Common Problems

When there are a bunch of people working and pushing config on a site, sometimes you can find yourself in a situation where running drush cim doesn’t clear up the pending configuration in an environment. I’ve discovered in our cases, regenerating the config from that site usually fixes the problem. This happens with us in staging environments where for some reason certain config sometimes will not revert to what is in the config files after a drush cim. You want to make sure that this is in an environment that is not behind your current dev/staging environments (if it is behind, I suggest grabbing the db from dev/staging instead). Once you pull down the db, run drush cex and take a look at what kind of things change. If content isn’t changing and it is minor configuration tweaks, that usually is fine and you can push that up to the repo and the problem site should reset after another drush cim.

If configuration ends up getting updated on live directly, you should probably grab that db from live and run drush cex before applying updates to the site. One way to prevent config from getting updated on live is to install the Configuration Read-only module. The one complication is that you want to make sure this gets disabled on your local so that site builders and developers can make changes to the configuration. We will probably end up using this across the board as we develop more Drupal 8 sites.

Have you used the Drupal 8 Configuration Management system yet? Did I miss any details in this article that you think we should add? Please let us know! The more we get familiar with this system in Drupal 8, the more we love it and we hope other people discover this functionality as well.

Like this post?

Join our list to have posts like this delivered to your inbox a few times a month.

Comment(s)