Integrate the Configuration Management deployment commands

This document explains how to integrate three console commands that keep configuration values across deployments that reset the database.

Each command is independent. Integrate only the ones your project needs, then see Use the commands together for the case they were designed for.

Prerequisites

Install the Configuration Management feature.

The commands require the following package version:

composer require spryker/configuration:"^1.7.0" --update-with-dependencies

All three commands read the settings map that configuration:sync generates. Run configuration:sync before running any of them.

Register the console commands

Register each command you want to use in ConsoleDependencyProvider.

src/Pyz/Zed/Console/ConsoleDependencyProvider.php

<?php

namespace Pyz\Zed\Console;

use Spryker\Zed\Configuration\Communication\Console\ExportConfigurationConsole;
use Spryker\Zed\Configuration\Communication\Console\ImportEnvironmentConfigurationConsole;
use Spryker\Zed\Configuration\Communication\Console\RestoreConfigurationConsole;

class ConsoleDependencyProvider extends SprykerConsoleDependencyProvider
{
    protected function getConsoleCommands(Container $container): array
    {
        $commands = [
            // ...
            new ExportConfigurationConsole(),
            new ImportEnvironmentConfigurationConsole(),
            new RestoreConfigurationConsole(),
        ];

        return $commands;
    }
}

Export configuration values: configuration:export

vendor/bin/console configuration:export <setting key> [<setting key> ...]

A setting key identifies a setting in the configuration schema. It consists of the feature, tab, group, and setting keys from the schema YAML file, separated by colons: <feature>:<tab>:<group>:<setting>. For example, integrations:google_analytics:tracking:measurement_id.

The command writes the stored values of the specified settings to the export file. It exports a value for every scope in which the setting has one.

The command skips the following settings and reports each of them:

• Secret settings: Settings declared with secret: true in the schema are never written to the export file. To restore them after a deployment, use configuration:import-environment.
• Settings without a stored value: Settings that have no value in the database, for example, because no Back Office user has saved them yet.

Configure the export file path

Both configuration:export and configuration:restore use the path that ConfigurationConfig::getExportFile() returns. By default, this is APPLICATION_ROOT_DIR . '/data/export/configuration-values.json'.

The default works when both commands run on the same filesystem, as in a local Docker SDK environment and in Spryker Cloud. If your deployment runs configuration:export and configuration:restore on filesystems that don’t share this directory, for example, in separate containers, redefine the path on the project level to a location that both commands can access:

src/Pyz/Shared/Configuration/ConfigurationConfig.php

<?php

namespace Pyz\Shared\Configuration;

use Spryker\Shared\Configuration\ConfigurationConfig as SprykerConfigurationConfig;

class ConfigurationConfig extends SprykerConfigurationConfig
{
    public function getExportFile(): string
    {
        return '/mnt/shared/configuration-values.json';
    }
}

The path refers to the filesystem of the container that runs the command, both locally and in production; see Use the commands together.

If the directory does not exist, the command creates it. The directory is created with 0700 permissions and the file with 0600 permissions, so only the user that runs the command can read the file.

Export file format

The export file is a JSON file with the following structure:

{
    "values": [
        {
            "setting_key": "integrations:google_analytics:tracking:measurement_id",
            "scope": "global",
            "scope_identifier": "",
            "value": "G-XXXXXXXXXX"
        }
    ]
}

Restore configuration values: configuration:restore

vendor/bin/console configuration:restore <setting key> [<setting key> ...]

Reads the export file from the path configured in Configure the export file path and saves the values of the specified settings to the database. Values of other settings in the file are left unchanged.

The command skips a setting and reports it if the schema no longer defines the setting or declares it as secret.

The command deletes the export file only if all values are restored successfully. If any value fails to restore, the command keeps the file, so you can fix the error and run the command again.

Import values from environment variables: configuration:import-environment

vendor/bin/console configuration:import-environment <setting key>=<VARIABLE_NAME> [<setting key>=<VARIABLE_NAME> ...] [--scope=<scope> --scope-identifier=<identifier>]

Saves the value of each mapped environment variable as the value of the setting. Use this command for values that must not be written to the export file or committed to the repository, such as credentials, and for values that differ per environment. It also saves you from setting the same values in the Back Office after every deployment, for example, on demo or testing environments: set an environment variable once, and the command imports its value on each deployment. Settings declared with secret: true in the schema are encrypted when saved.

Each argument maps a setting key to the name of the environment variable that holds its value. Pass the variable name, not the value. The command reads each value from the environment, so secret values don’t appear in the command arguments or the deployment recipe.

For example, the following command imports the Google Analytics measurement ID and service account credentials in the global scope:

vendor/bin/console configuration:import-environment \
    integrations:google_analytics:tracking:measurement_id=GA_MEASUREMENT_ID \
    integrations:google_analytics:connection:service_account_credentials_json=GA_SERVICE_ACCOUNT_JSON

Import values for a scope

All mappings of one call are saved in the same scope. By default, this is the global scope. To save values in another scope, pass the scope and its identifier, for example, a store name:

vendor/bin/console configuration:import-environment --scope=store --scope-identifier=DE \
    integrations:google_analytics:tracking:measurement_id=GA_MEASUREMENT_ID_DE

The global scope doesn’t take an identifier; every other scope requires one. To import values for several stores, run the command once per store, with a variable per store.

If an environment variable is not set or is empty, the command skips the setting and reports it. This way, you can use the same recipe in environments that don’t define every variable, for example, in an environment without the AT store.

Use the commands together

These commands support deployments that drop the database tables and so remove the configuration values saved by Back Office users.

Run configuration:export before the deployment drops the tables. After the database is rebuilt, run configuration:sync to regenerate the settings map, then run configuration:import-environment and configuration:restore to restore the values.

In config/install/destructive.yml, add the sections as follows:

• configuration-export: before clean-storage, which drops the database tables.
• configuration: after the database is rebuilt and the data is imported, and before scheduler-start, so that the restored values are published.

config/install/destructive.yml

sections:
    scheduler-clean:
        # ...

    configuration-export:
        configuration-export:
            command: >-
                vendor/bin/console configuration:export
                integrations:google_analytics:tracking:measurement_id
                -vvv --no-ansi

    clean-storage:
        # ...

    init-storages-per-region:
        # ...

    setup-queue:
        # ...

    setup-minimal-data:
        # ...

    clear-and-init-search:
        # ...

    demodata:
        # ...

    configuration:
        configuration-sync:
            command: 'vendor/bin/console configuration:sync -vvv --no-ansi'

        configuration-import-environment:
            command: >-
                vendor/bin/console configuration:import-environment
                integrations:google_analytics:connection:service_account_credentials_json=GA_SERVICE_ACCOUNT_JSON
                -vvv --no-ansi

        configuration-restore:
            command: >-
                vendor/bin/console configuration:restore
                integrations:google_analytics:tracking:measurement_id
                -vvv --no-ansi

    scheduler-start:
        # ...

Both configuration:restore and configuration:import-environment write configuration values. If both commands write the same setting, the command that runs last determines the final value.

Choose the order based on which source must take precedence:

Exit codes

The commands exit with code 1 when they fail, so the deployment stops at that section. For example, a command fails when the export file path is not configured, the export file can’t be written or read, a value can’t be restored or imported, a mapping is invalid, or the settings map is missing.

The commands exit with code 0 when there is nothing to do: no stored values to export, no export file to restore from, or an environment variable that is not set. configuration:export also exits with code 0 when the configuration values table doesn’t exist yet, which is the case on the first destructive deployment.

To continue the deployment even if one of these commands fails, set breakOnFailure: false for the command in the recipe:

        configuration-restore:
            command: 'vendor/bin/console configuration:restore integrations:google_analytics:tracking:measurement_id -vvv --no-ansi'
            breakOnFailure: false

Troubleshooting