Acquia vcs config directory vs. Drupal 8/9 sync directory

Issue

Can you explain how the Acquia 'vcs' configuration directory type differs from the regular Drupal 8 'sync' directory?

Resolution

By default, Drupal 8 uses the sync configuration directory type for Configuration Management. This type defines the configuration directory located under the path/to/docroot/sites/sitename/files/config_HASH path. Acquia Cloud introduces an additional configuration directory type named vcs to allow you to track Configuration Management changes under version control.

$config_directories['vcs']

Technically, both sync and vcs are array keys referencing a configuration directory type. For convenience we will sometimes refer to them as 'configuration directories'. Let's explore their differences.

Drupal 8.8.0 deprecated $config_directories. The sync directory and vcs directory paths are defined as values in the $settings array:

$settings['config_sync_directory'] = 'your/config/sync/directory/path'
$settings['config_vcs_directory'] = 'your/config/vcs/directory/path'

Drupal's 'sync' configuration directory type

• Pros: It's the Configuration Management directory type that Drupal core, contributed modules, and tools expect you're using by default.
• Cons: When you are developing locally, there's only one config_HASH directory for each site. On Acquia Cloud, though, there is one config_HASH directory per environment, as if your Dev, Stage and Production environments were different sites. This is to improve security but we understand this can also be a little confusing.  

For example:

drwxr-s---  4 testsite testsite      33 Mar 20  2017 config_847d661c3a69a99fad20815f14136a4795f
drwxr-s---  4 testsite testsite      33 May 14  2017 config_89b38cf7d3340f31c128e9187fd43d536c7
drwxr-s---  4 testsite testsite      33 Apr 25  2017 config_a1d04c1c71ec0d30747c758b482b3ecab1e

To find the correct hash for an environment, use:

$ drush @sitename.env status | grep Sync | awk '{print $NF}'

Acquia Cloud's 'vcs' configuration directory type

The Acquia-declared vcs configuration directory type follows Drupal 8's best practices by allowing you to both track Configuration Management changes under version control and relocate the Configuration Management directory outside of the Drupal docroot. It is expected to be located at the same level as your Acquia Cloud docroot.

lrwxrwxrwx  1 root     testsite     19 Jun 29 06:56 acquia-files -> /mnt/gfs/testsite
-r--r-----  1 www-data testsite   1685 Jun 29 06:56 composer.json
-r--r-----  1 www-data testsite 188977 Jun 29 06:56 composer.lock
dr-xr-s---  6 www-data testsite   4096 Jun 29 06:56 config
dr-xr-s---  7 www-data testsite   4096 Jun 29 06:56 docroot
dr-xr-s--- 33 www-data testsite   4096 Jun 29 06:56 vendor

Additionally, it should follow the convention /config/sitename where 'sitename' is the site name you have declared under sites. For example, create /config/default if you have /sites/default/ or /config/mysite.com if you have sites/mysite.com. See Configuration management for Drupal 8 for additional information.

• Pros: It lives within the Git repository, so config changes can be tracked under version control. It is also portable as it travels with your codebase across environments.
• Cons:
  • The Acquia Cloud platform expects the config/sitename configuration directory to exist. It will return warnings on your Drupal status page if it cannot find it. Additionally, it will prevent you from running update.php from within the user interface.
  • Unless you're in Live Development, Acquia Cloud operates in a read-only mode. As such, the /config/sitename configuration directory is read-only, so all changes need to be performed within the normal code deployment workflow.

Because there are two different locations defined for Configuration Management on Acquia Cloud, when you run Drush config-export or config-import commands, you may see an additional prompt asking you to define whether you are using vcs or sync:

$ drush config-import
Choose a source.
 [0]  :  Cancel
 [1]  :  sync
 [2]  :  vcs

You can also pass the source/destination configuration directory type directly in the Drush command. For example:

 $ drush config-import vcs

Additional notes:

• The vcs configuration directory type can be added to settings.php on Acquia Cloud Site Factory, with a post-settings-php hook. See Hooks in Acquia Cloud Site Factory.