Scenario-based deployment
With ece-tools
2002.1.0 and later, you can use the scenario-based deployment feature to customize the default deployment behavior.
This feature uses scenarios and steps in the configuration:
-
Scenario configuration–Each deployment hook is a scenario, which is an XML configuration file that describes the sequence and configuration parameters to complete deployment tasks. You configure the scenarios in the
hooks
section of the.magento.app.yaml
file. -
Step configuration–Each scenario uses a sequence of steps that programmatically describe the operations required to complete deployment tasks. You configure the steps in an XML-based scenario configuration file.
Adobe Commerce on cloud infrastructure provides a set of default scenarios and default steps in the ece-tools
package. You can customize deployment behavior by creating custom XML configuration files to override or customize the default configuration. You can also use scenarios and steps to run code from custom modules.
Add scenarios using build and deploy hooks
You add the scenarios for building and deploying Adobe Commerce to the hooks
section of the .magento.app.yaml
file. Each hook specifies the scenarios to run during each phase. The following example shows the default scenario configuration.
magento.app.yaml
hooks
hooks:
build: |
set -e
php ./vendor/bin/ece-tools run scenario/build/generate.xml
php ./vendor/bin/ece-tools run scenario/build/transfer.xml
deploy: |
php ./vendor/bin/ece-tools run scenario/deploy.xml
post_deploy: |
php ./vendor/bin/ece-tools run scenario/post-deploy.xml
ece-tools
2002.1.x, there is a new hooks configuration format. The legacy format from ece-tools
2002.0.x releases is still supported. However, you must update to the new format to use the scenario-based deployment feature.Review scenario steps
In the hook configuration, each scenario is an XML file that contains steps to run build, deploy, or post-deploy tasks. For example, the scenario/transfer
file includes three steps: compress-static-content
, clear-init-directory
, and backup-data
scenario/transfer.xml
<?xml version="1.0"?>
<scenario xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:ece-tools:config/scenario.xsd">
<step name="compress-static-content" type="Magento\MagentoCloud\Step\Build\CompressStaticContent" priority="100"/>
<step name="clear-init-directory" type="Magento\MagentoCloud\Step\Build\ClearInitDirectory" priority="200"/>
<step name="backup-data" type="Magento\MagentoCloud\Step\Build\BackupData" priority="300">
<arguments>
<argument name="logger" xsi:type="object">Psr\Log\LoggerInterface</argument>
<argument name="steps" xsi:type="array">
<item name="static-content" xsi:type="object" priority="100">Magento\MagentoCloud\Step\Build\BackupData\StaticContent</item>
<item name="writable-dirs" xsi:type="object" priority="200">Magento\MagentoCloud\Step\Build\BackupData\WritableDirectories</item>
</argument>
</arguments>
</step>
</scenario>
Extend a default scenario
The following example extends the default deploy scenario by appending additional deploy configuration files to the hook configuration.
hooks:
deploy: |
php ./vendor/bin/ece-tools run scenario/deploy.xml vendor/<vendor-name>/<module-name>/deploy.xml vendor/<vendor-name>/<module-name>/deploy2.xml
During deployment, the custom scenarios merge with the default scenario-based on the following rules:
-
Scenarios are prioritized based on their sequence in the hook definition with the last scenario listed having the highest priority.
In the example, the scenarios have the following priority:
vendor/vendor-name/module-name/deploy2.xml
vendor/vendor-name/module-name/deploy.xml
scenario/deploy.xml
(default or baseline scenario)
-
The steps in the highest priority scenario override steps with the same name in the other scenarios. New steps are added to the configuration. The same rules apply for more than two scenarios with each scenario being prioritized from right to left, for example (C → B → A).
Remove default steps
You remove steps from default scenarios using the skip
parameter.
For example, to skip the enable-maintenance-mode
and set-production-mode
steps in the default deploy scenario, create a configuration file that includes the following configuration.
vendor/vendor-name/module-name/deploy-custom-mode-config.xml
<?xml version="1.0"?>
<scenario xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:ece-tools:config/scenario.xsd">
<step name="enable-maintenance-mode" skip="true" />
<step name="set-production-mode" skip="true" />
</scenario>
To use the custom configuration file, update the default .magento.app.yaml
file.
.magento.app.yaml
with custom deploy scenario
hooks:
build: |
set -e
php ./vendor/bin/ece-tools run scenario/build/generate.xml
php ./vendor/bin/ece-tools run scenario/build/transfer.xml
deploy: |
php ./vendor/bin/ece-tools run scenario/deploy.xml vendor/vendor-name/module-name/deploy-custom-mode-config.xml
post_deploy: |
php ./vendor/bin/ece-tools run scenario/post-deploy.xml
Replace default steps
Custom scenarios can replace default steps to provide custom implementation. To do so, use the default step name as the name for the custom step.
For example, in the default deploy scenario the enable-maintenance-mode
step runs the default EnableMaintenanceMode PHP script.
<step name="enable-maintenance-mode" type="Magento\MagentoCloud\Step\EnableMaintenanceMode" priority="300"/>
To override this step, create a custom scenario configuration file to run a different script when the enable-maintenance-mode
step runs.
<?xml version="1.0"?>
<scenario xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:ece-tools:config/scenario.xsd">
<scenario>
<step name="enable-maintenance-mode" type="VendorName\VendorModule\Step\CustomEnableMaintenanceMode" priority="300"/>
</scenario>
Change the step priority
Custom scenarios can change the priority of default steps. The following step changes the priority of the enable-maintenance-mode
step from 300
to 10
so that the step runs earlier in the deploy scenario.
<?xml version="1.0"?>
<scenario xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:ece-tools:config/scenario.xsd">
<scenario>
<step name="enable-maintenance-mode" type="Magento\MagentoCloud\Step\EnableMaintenanceMode" priority="10"/>
</scenario>
In this example, the enable-maintenance-mode
step moves to the beginning of the scenario because it has a lower priority than all other steps in the default deploy scenario.
Example: Extend the deploy scenario
The following example customizes the default deploy scenario with the following changes:
- Replaces the
remove-deploy-failed-flag
step with a custom step - Skips the
clean-redis-cache
substep in the pre-deploy step - Skips the
unlock-cron-jobs
step - Skips the
validate-config
step to disable critical validators - Adds a new pre-deploy step
vendor/vendor-name/module-name/deploy-extended.xml
<?xml version="1.0"?>
<scenario xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:ece-tools:config/scenario.xsd">
<!-- Replace "remove-deploy-failed-flag" step with custom step -->
<step name="remove-deploy-failed-flag" type="Vendor\ModuleName\Step\Deploy\RemoveDeployFailedFlag" priority="100"/>
<!-- Skip "clean-redis-cache" sub-step in pre-deploy step -->
<step name="pre-deploy" type="Magento\MagentoCloud\Step\Deploy\PreDeploy" priority="200">
<arguments>
<argument name="logger" xsi:type="object">Psr\Log\LoggerInterface</argument>
<argument name="steps" xsi:type="array">
<item name="clean-redis-cache" xsi:type="object" skip="true"/>
</argument>
</arguments>
</step>
<!-- Skip step "unlock-cron-jobs" -->
<step name="unlock-cron-jobs" skip="true"/>
<!-- Skip critical validators -->
<step name="validate-config" type="Magento\MagentoCloud\Step\ValidateConfiguration" priority="300">
<arguments>
<argument name="logger" xsi:type="object">Psr\Log\LoggerInterface</argument>
<argument name="validators" xsi:type="array">
<item name="critical" xsi:type="array">
<item name="database-configuration" xsi:type="object" skip="true"/>
<item name="search-configuration" xsi:type="object" skip="true"/>
</item>
</argument>
</arguments>
</step>
<!-- Add new step into the beginning of the deploy scenario -->
<step name="new-pre-deploy-step" type="Vendor\ModuleName\Step\Deploy\PreDeploy" priority="10"/>
</scenario>
To use this script in your project, add the following configuration to the .magento.app.yaml
file for your Adobe Commerce on cloud infrastructure project:
hooks:
build: |
set -e
php ./vendor/bin/ece-tools run scenario/build/generate.xml
php ./vendor/bin/ece-tools run scenario/build/transfer.xml
deploy: |
php ./vendor/bin/ece-tools run scenario/deploy.xml vendor/vendor-name/module-name/deploy-extended.xml
post_deploy: |
php ./vendor/bin/ece-tools run scenario/post-deploy.xml
ece-tools
GitHub repository to determine which scenarios and steps to customize for your project build, deploy, and post-deploy tasks.Add a custom module to extend ece-tools
The ece-tools
package provides default API interfaces that follow Semantic Version standards. All API interfaces are marked with @api annotation. You can replace the default API implementation with your own by creating a custom module and modifying the default code as needed.
To use the custom module with Adobe Commerce on cloud infrastructure, you must register your module in the extensions list for the ece-tools
package. The registration process is similar to the process that you use to register modules in Adobe Commerce.
To register a module with the ece-tools
package:
-
Create or extend the
registration.php
file in the root of your module.code language-php?start_inline=1 \Magento\MagentoCloud\ExtensionRegistrar::register('module-name', __DIR__);
-
Update the
autoload
section for your module configuration file to include theregistration.php
file to autoload module files incomposer.json
.code language-json { "name": "vendor/ece-tools-extend", "description": "Extension for ece-tools", "type": "magento2-component", "version": "1.0.0", "license": "OSL-3.0", "autoload": { "files": [ "registration.php" ], "psr-4": { "Vendor\\EceToolExtend\\": "src/" } } }
-
Add the
config/services.xml
file into your module. This configuration is merged overconfig/services.xml
fromece-tools
package.code language-xml <?xml version="1.0" encoding="UTF-8" ?> <container xmlns="http://symfony.com/schema/dic/services" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd"> <services> <defaults autowire="true" autoconfigure="true" public="true"/> <prototype namespace="Vendor\EceToolExtend\" resource="../src/*" exclude="../src/{Test}"/> <!-- Use your own implementation of EnvironmentDataInterface --> <service id="Magento\MagentoCloud\Config\EnvironmentDataInterface" alias="Vendor\EceToolExtend\Config\CustomEnvironmentData" /> </services> </container>
To learn more about dependency injection, see Symfony Dependency Injection.