Disable and Enable Modules per environment with Config Split 'blacklist'

    See more
    • Updated

    Issue

    Config Split is a great way to manage different settings per environment, but its 'blacklist' and 'graylist' settings are sometimes confusing. This article explains how to disable a module (simplesamlphp_auth - Acquia uses this for SSO) in one environment (in this example, local), but enable it in others (in this example, dev) using the 'blacklist' setting. 

    Initial Setup

    To read about how to setup config split on Acquia Cloud see Adding Configuration Split to a Drupal site using BLT and Acquia Cloud. Note that you do not need to use Acquia BLT but there are good explanations there for setting up the /config/default/ directory, and the per-environment directories,/config/envs/prod/ or /config/envs/local/. This article assumes that you already have config_split setup, and that you have default settings and prod and local environment folders.

    Essential Files

    The following files will need to be edited:

    • /config/default/core.extension.yml: The /default/ folder contains settings that are implemented across all environments. Modules listed in this file are installed for ALL environments. If you do not want a module installed in all environments, it should not be listed in core.extension.yml.
    • /config/default/config_split.config_split.prod.yml and /config/default/config_split.config_split.local.yml: These files list what modules should be enabled ('blacklist') or what modules have environment-specific settings ('graylist').
    • /config/envs/prod/simplesamlphp_auth.settings.yml: This file contains the settings for a specific module, and should live in the folder that corresponds to the environment which is being set.

    The core.extension.yml:

    All modules listed in core.extension.yml are enabled across all environments. So, if you do not want a module installed and enabled across all environments, do not list it here! Note that the number is simply the weight of the module. So, in this case, there should be no entry in core.extension.yml that reads simplesamlphp_auth: 0. 

    The config_split.ENV.yml:

    The config_split.ENV.yml files specify what modules should be enabled per environment, and what unique settings which should be applied in that environment. They contain a 'blacklist' and 'graylist' array and their meaning is a bit confusing:

    • Blacklist: Any setting in this array assumes the module is active ONLY in this environment (yes, I agree, this isn't terribly intuitive). Config Split will look for settings file in the corresponding environment-specific folder, i.e., /config/envs/local/ or /config/envs/dev/.
    • Graylist: Any setting in this array assumes the module is shared across environments, but this particular environment has unique settings.

    Getting it working:

    Enable on Prod:

    The module is enabled on prod by listing it in /config/default/config_split.config_split.prod.yml. Under 'module', list the module as it would appear in core.extension.yml, i.e., 'simplesamlphp_auth: 0'. In addition, list its settings file name under 'blacklist'. The 'folder' item indicates where config_split should look for settings files specific to this environment. Your file should look like this:

    uuid: 861d3de2-72ca-4bbb-877e-ba5fc7910b09
langcode: en
status: true
dependencies: {  }
id: prod
label: Prod
description: 'Production environment split'
folder: ../config/envs/prod
module:
  simplesamlphp_auth: 0
theme: {  }
blacklist:
  - simplesamlphp_auth
graylist: {  }
graylist_dependents: true
graylist_skip_equal: true
weight: 0

    Since the goal is to ensure the module is not enabled in the local environment, do not list the module in /config/default/config_split.config_split.local.yml. In the example below, note that two modules are enabled (dblog and devel) but simplesamlphp_auth is not listed. Note also that there are settings for modules enabled only on the local environment under 'blacklist' but one setting for a module that is enabled on all environments but has unique settings in local (system.performance).

    uuid: 7120ab49-c6ec-4589-b25d-f9638f73b941
langcode: en
status: true
dependencies: {  }
id: local
label: Local
description: ''
folder: ../config/envs/local
module:
  dblog: 0
  devel: 0
theme: {  }
blacklist:
  - dblog.settings
  - devel.settings
  - devel.toolbar.settings
  - system.logging
  - system.menu.devel
  - views.view.watchdog
graylist:
  - system.performance
graylist_dependents: true
graylist_skip_equal: true
weight: 0

    Specify the Settings

    The actual settings are specified in a file which lives in the environment specific folder. In this case, move simplesamlphp_auth.settings.yml from /config/default/ (assuming it was put there originally) and put it in /config/envs/prod/simplesamlphp_auth.settings.yml. Now, the production environment will look in this folder for the settings that should be implemented on prod. Note that you can have different settings per environment by duplicating this file into each environment-specific config folder, and modifying its contents.

     

    Topics

    Drupal Projects

    Related articles