Mastering Configuration Synchronization in Drupal 10

Introduction

Drupal’s Configuration Management system, introduced in Drupal 8 and refined in Drupal 10, allows developers to manage site configurations in a standardized and predictable manner. Whether you are working in a team or managing multiple environments (like development, staging, and production), Configuration Synchronization ensures consistency and reliability across all setups. This blog will guide you through the entire process of Configuration Synchronization in Drupal 10, covering necessary modules, commands, and best practices.

What is Drupal Configuration Synchronization?

Drupal Configuration Synchronization is the process of managing and synchronizing site configuration between different environments (e.g., development, staging, production). Configuration in Drupal refers to settings that determine how a site behaves, including content types, views, fields, and user permissions. Unlike content, which changes frequently and is stored in the database, configuration is more stable and is typically managed as code.

Configuration synchronization ensures that the settings and configuration across multiple environments are consistent, allowing for predictable behavior and reducing the chances of configuration drift, where different environments might have different settings due to manual changes or oversight.

Why Do We Need Configuration Synchronization?

Configuration synchronization is essential for several reasons:

• Consistency Across Environments: It ensures that all environments (development, staging, production) are identical in terms of configuration, which is crucial for testing and deploying updates.
• Version Control: By exporting configuration into code, it can be versioned using Git or another version control system, allowing teams to track changes, roll back to previous versions, and collaborate more effectively.
• Disaster Recovery: In case of accidental deletion or misconfiguration, you can quickly restore the site to a previous state using the configuration stored in the code.
• Deployment: When deploying changes from a development environment to production, configuration synchronization makes it easy to apply these changes without manual intervention, reducing the risk of errors.
• Rapid Development: Configuration synchronization allows for the reuse of configurations across different environment and reduce development cost.

Understanding Drupal Configuration

In Drupal 10, configuration data is stored in YAML files. These files contain settings for content types, views, taxonomy vocabularies, and more. The configuration is stored in the config directory within the site’s files directory, typically located at sites/default/files/config_HASH/sync, where HASH is a unique identifier generated by Drupal.

When you export your site’s configuration, Drupal writes these settings into YAML files that can be stored in a version control system. Conversely, importing configuration reads these files and applies the settings to the site.

What Data Will Be Considered as Configuration?

In Drupal, the State API is used to store temporary or internal site information that isn’t part of the site’s main configuration. This data is not meant to be synchronized across different environments like development or production. Instead, it’s used for things that are specific to a particular environment or session.

State Data vs. Configuration Data:

• Configuration Data: These are settings that define how your site works, like content types, views, and user permissions. This data is stored in YAML files and synchronized across all your environments.
• State Data: This is more like temporary or environment-specific information. It’s saved in the database and is not synchronized across environments.

Examples of Configuration Data:

• Content Types: Definitions of different content types like Articles or Events.
• Views: Configurations for custom views, such as lists of content or user profiles.
• Taxonomy Vocabularies: Definitions of terms and categories used for tagging content.
• User Roles and Permissions: Settings that control user access and permissions on the site.
• Menu Structures: Configuration for the main navigation menu and submenus.

Examples of State Data:

• Last Cron Run Time: Records when the last automated task (cron job) was performed.
• Module Settings: Temporary settings used by modules, such as feature toggles or user preferences.
• User Login Status: Information related to active user sessions or login statuses.
• Cache Data: Data stored temporarily to improve site performance, like cached views or pages.
• Temporary File Paths: Paths for files used temporarily during operations, like import/export tasks.

Configuration Management System in Drupal

Drupal’s Configuration Management System (CMS) revolves around the concept of the active configuration and the staged configuration.
Active Configuration: This is the configuration that the site is currently using. It is stored in the database and is automatically updated when you make changes through the Drupal UI.

Staged Configuration: This refers to a configuration that has been exported to YAML files and is ready to be imported back into the site. The staged configuration is typically stored in the sync directory.

The Config file locations are mapped in the settings.php file, It is recommended to have the configuration files out of the root directory.

$settings['config_sync_directory'] = '../config/sync';

Configuration Workflow

The typical workflow for managing configuration in Drupal involves three main steps: exporting, versioning, and importing.
Export Configuration: Export the current site configuration to YAML files.
Version Configuration: Add the exported files to version control (e.g., Git) and push changes to a remote repository.
Import Configuration: Import the configuration on another environment (e.g., staging or production) to apply the changes.

Configuration Export

Exporting configuration is the first step in the configuration management workflow. This process writes the active configuration to YAML files in the sync directory.

Exporting Configuration

1. Navigate to the site’s admin interface: Configuration > Development > Configuration synchronization.
2. Click on the Export tab.
3. You can export the entire configuration or specific parts of it.
4. Click Export to download the tar.gz file containing all the YAML configuration files.

drupal config export

Alternatively, you can use Drush, a command-line shell and scripting interface for Drupal, to export configuration:

drush config-export OR drush cex

config export

This command exports the entire configuration to the sync directory.

Configuration Import

After exporting and versioning the configuration, you’ll want to import it into another environment. This process reads the YAML files from the sync directory and updates the active configuration in the database.

Importing Configuration

1. Navigate to the site’s admin interface: Configuration > Development > Configuration synchronization.
2. Click on the Import tab.
3. You can choose to import the entire configuration or specific parts.
4. If you are importing a complete set of configurations, make sure you have the relevant YAML files prepared.
5. Upload the tar.gz file containing the YAML configuration files. This file is usually the result of a configuration export from another environment.

drupal config import

Alternatively, you can use Drush, a command-line shell and scripting interface for Drupal, to import configuration:

drush config-import OR drush cim

This command imports the configuration from the sync directory and applies it to the active configuration.

Config Split

Config Split is a contributed module in Drupal that allows for the management of different configurations in different environments. It is particularly useful for handling configurations that should vary between environments (e.g., development, staging, and production).

you can install config split module using command line -

composer require drupal/config_split

drush en config_split

Use Case Example:

Let Suppose we have a Drupal site that requires different email settings in development and production environments. The goal is to ensure that email functionalities are configured appropriately for testing and live use.

Using Config Split, you can create different configuration splits for your environments:

Development Split: Create a configuration split for development with settings for a test email address.
Production Split: Create a configuration split for production with settings for real email addresses.

How It Works:

• You define multiple configuration splits in the Config Split settings.
• Each split specifies which configuration settings should be included or excluded.
• During the export and import process, Drupal uses these splits to manage environment-specific configurations seamlessly.

How to Segregate Configuration Between Non-Prod and Prod Environments?

To effectively manage and segregate configuration between non-production (e.g., local, dev, qa, prod) and production environments, follow these practices:
1. Navigate to the site’s admin interface: Configuration > Development > Configuration Split Settings.
2. Click Add Configuration Split Settings.
3. Enter the label and the folder name, Select the modules you want to split and click save.

Drupal Config Split

Use Different Configuration Directories:
Configure Drupal to use different sync directories for different environments. For example, in your settings.php file, you can specify different directories for non-production and production environments:

// Configure the Config Split module for different environments
$config['config_split.config_split.local_split']['status'] = FALSE;
$config['config_split.config_split.dev_split']['status'] = TRUE;
$config['config_split.config_split.qa_split']['status'] = FALSE;
$config['config_split.config_split.prod_split']['status'] = FALSE;

Note: You should adjust the true/false status of the configuration splits based on your current environment. For example, if you are in the dev environment, you would enable dev_split and disable others.
Make sure your directory structure for the configuration is correctly set up to match the config_sync_directory path specified in the settings.php file:

Conclusion

Drupal 10’s Configuration Synchronization system is a powerful tool that ensures consistency across different environments, simplifies deployment, and enhances collaboration through version control. By understanding and properly utilizing the export and import processes, you can maintain a stable and predictable Drupal site across development, staging, and production environments.With this approach, you’ll have a robust workflow that minimizes the risk of configuration drift and keeps your Drupal site’s configuration under control.