ECE-Tools 2002.1.3 docs and release notes (#8161)

bdenham · oshmyheliuk · maeker12 · web-flow · commit 739bed8aa063 · 2020-11-04T14:29:38.000-06:00
* MCLOUD-6939: Errors occur running magento commands in composer cloud docker installation (#8007) * Added variable to skip composer dump-autoload command processing when deploying a Magento Cloud project to a Cloud Docker environment. * MCLOUD-7072: Add CLI command for generating .magento.env.yaml (#8040) * MCLOUD-7072: Add CLI commands for creating and updating .magento.env.yaml * Apply suggestions from code review Co-authored-by: Barny Shergold <barny.shergold@vaimo.com> Co-authored-by: Margaret Eker <meker@adobe.com> * MCLOUD-6805: ECE-Tools release notes WIP: updating variables * MCLOUD-6805: ECE-Tools release notes First draft * MCLOUD-6805: ECE-Tools release notes Fixed double slash on link * added links to two hot fixes * Update services-mysql.md (#8144) Co-authored-by: Margaret Eker <meker@adobe.com> * Update Magento Cloud Docker instructions for adding custom PHP extensions (#8145) * [Doc] Adding new PHP extensions #155 (#7929) * Clean up instructions for adding PHP extensions - Move extension configuration attribute descriptions and examples to a separate section * Fixed markdown syntax * Fix link definitions * Fix link syntax * Apply suggestions from code review Co-authored-by: Yevhen Miroshnychenko <miroshny@adobe.com> Co-authored-by: Barny Shergold <barny.shergold@vaimo.com> Co-authored-by: hguthrie <hguthrie@users.noreply.github.com> * MCLOUD-6805: ECE-Tools release notes Updated entry for MCLOUD-7098 * MCLOUD-6805: ECE-Tools release notes Fixed merge conflicts * Added docs for SKIP_COMPOSER_DUMP_AUTOLOAD * Apply suggestions from code review Co-authored-by: Margaret Eker <meker@adobe.com> * MCLOUD-6805: ECE-Tools release notes Added release notes entry for #7191 * Update error-codes information with current info (#8152) * Update error-codes information with current info - Replaced file with error-code.md file generated from the ece-tools package * Fixed error messages * Add source file for generating the error code ref Co-authored-by: Barny Shergold <barny.shergold@vaimo.com> * Fixed comment syntax on internal note * MCLOUD-6805: ECE-Tools release notes Added release not for MCLOUD-7193 * MCLOUD-6805: ECE-Tools release notes Fixed silly empty bullet * MCLOUD-6805: ECE-Tools release notes Per review, updated additional ece-tools docs changes that are unassociated with the release notes. * MCLOUD-6805: ECE-Tools release notes Per review, removed extra space from yaml code block. * MCLOUD-6805: ECE-Tools release notes Per review, tweaking the wording for writeable Cloud Docker environments. * MCLOUD-6805: ECE-Tools release notes Per review, forgot to clarify the pronoun that. * MCLOUD-6805: ECE-Tools release notes Per review, removed extra space, missed it first time around. * MCLOUD-6805: ECE-Tools release notes Ordered 'new' release note before fixed * MCLOUD-6805: ECE-Tools release notes Added links to documentation. * MCLOUD-6805: ECE-Tools release notes Added links to documentation. * Apply suggestions from code review Co-authored-by: Margaret Eker <meker@adobe.com> Co-authored-by: Oleksandr Shmyheliuk <oshmyheliuk@magento.com> Co-authored-by: maeker12 <{ID}+{username}@users.noreply.github.com> Co-authored-by: jfrontain <frontain@adobe.com> Co-authored-by: Andrii Shevtsov <ashevtsov@magento.com> Co-authored-by: Margaret Eker <meker@adobe.com> Co-authored-by: Yevhen Miroshnychenko <miroshny@adobe.com> Co-authored-by: Barny Shergold <barny.shergold@vaimo.com> Co-authored-by: hguthrie <hguthrie@users.noreply.github.com>
diff --git a/src/_data/var.yml b/src/_data/var.yml
@@ -9,7 +9,7 @@
 # Enterprise Cloud Edition (ECE)  ---> Commerce Cloud
 # Enterprise Edition for B2B      ---> Commerce for B2B
 
-#NOTE: The new product name variables use the old product name abbreviations (e.g., ce, ee, ece, b2b). 
+#NOTE: The new product name variables use the old product name abbreviations (e.g., ce, ee, ece, b2b).
 
 # Product Name variables
 
@@ -21,11 +21,11 @@ mbi: Magento Business Intelligence
 # Cloud product name variables
 
 ece: Magento Commerce Cloud
-ece-release-date: August 5, 2020
+ece-release-date: November 9, 2020
 csuite: Magento Commerce Cloud Suite
 ct: ece-tools
 ct-repo: magento/ece-tools
-ct-release: 2002.1.2
+ct-release: 2002.1.3
 mcp-prod: Magento Cloud Patches
 mcp-package: magento/magento-cloud-patches
 mcp-release: 1.0.8
diff --git a/src/_includes/cloud/error-codes.md b/src/_includes/cloud/error-codes.md
@@ -1,4 +1,4 @@
-<!-Note: The error code tables in this file are auto-generated from source code. To request changes to error code descriptions or suggestions, submit a GitHub issue to the magento/ece-tools repository.->
+<!--Note: This topic is auto-generated from the https://github.com/magento/ece-tools/blob/e3b13ca023afe324cd93d0caa2fd62d5683b60b9/config/schema.error.yaml source code. To request changes to error code descriptions or suggestions, submit a GitHub issue to the magento/ece-tools repository.-->
 
 ## Critical Errors
 
@@ -71,9 +71,10 @@ Critical errors indicate a problem with the Magento Commerce Cloud project confi
 | 129 | install-update: reset-password | Unable to read reset password template |  |
 | 130 | install-update: cache_type | Command failed: `php ./bin/magento cache:enable` | Command `php ./bin/magento cache:enable` runs only when Magento was installed but `./app/etc/env.php` file was absent or empty at the beginning of the deployment. Check the `cloud.log` for more information. Add `VERBOSE_COMMANDS: '-vvv'` into `.magento.env.yaml` for more detailed command output. |
 | 131 | install-update | The `crypt/key`  key value does not exist in the `./app/etc/env.php` file or the `CRYPT_KEY` cloud environment variable | This error occurs if the `./app/etc/env.php` file is not present when Magento deployment begins, or if the `crypt/key` value is undefined. If you migrated the database from another environment, retrieve the crypt key value from that environment. Then, add the value to the [CRYPT_KEY](https://devdocs.magento.com/cloud/env/variables-deploy.html#crypt_key) cloud environment variable in your current environment. See [Add the Magento encryption key](https://devdocs.magento.com/cloud/setup/first-time-setup-import-import.html#encryption-key). If you accidentally removed the `./app/etc/env.php` file, use the following command to restore it from the backup files created from a previous deployment: `./vendor/bin/ece-tools backup:restore` CLI command ." |
-| 132 |  | Can not connect to the Elasticsearch service | Check that credentials for elasticsearch are correct and service is running |
+| 132 |  | Can not connect to the Elasticsearch service | Check for valid Elasticsearch credentials and verify that the  service is running |
 | 133 | validate-config | Remove Magento Braintree module configuration which is no longer supported in Magento 2.4 and later versions. | Support for the Braintree module is no longer included with Magento 2.4.0 and later. Remove the CONFIG__STORES__DEFAULT__PAYMENT__BRAINTREE__CHANNEL variable from the variables section of the .magento.app.yaml file. For Braintree support, use an official Braintree Payments extension from the Magento Marketplace instead. |
 | 134 | validate-config | Magento 2.4.0 requires Elasticsearch service to be installed | Install Elasticsearch service |
+| 135 | validate-config | The search engine must be set to Elasticsearch for Magento >= 2.4.0 | Check the SEARCH_CONFIGURATION variable for the `engine` option. If it is configured, remove the option, or set the value to "elasticsearch". |
 
 ### Post-deploy stage
 
diff --git a/src/cloud/env/variables-build.md b/src/cloud/env/variables-build.md
@@ -184,6 +184,21 @@ stage:
 {:.bs-callout-info}
 Because Baler is currently in alpha release, we do not recommend using it in Production environments.
 
+### `SKIP_COMPOSER_DUMP_AUTOLOAD`
+
+-  **Default**— _Not set_
+-  **Version**—Magento 2.1.4 and later
+
+Set to `true` to skip the `composer dump-autoload` command during a {{ site.data.var.mcd-prod }} installation. This variable is only relevant for {{ site.data.var.mcd-prod }} containers with writable file systems. In such cases, skipping the command prevents errors from other commands trying to access code from the deleted `generated` directory.
+
+When Magento runs `composer dump-autoload`, it creates autoload files with links to generated classes in the `generated` folder. In production environments with read-only files systems, this is not a problem. However, for {{ site.data.var.mcd-prod }} installations with writable file systems (created only for testing and development using `./vendor/bin/ece-docker build:compose --with-test`), you can run the `bin/magento -n setup:upgrade` command without the `--keep-generated` option, which deletes the `generated` directory. If the directory is deleted, the `composer dump-autoload` command fails because the autoload contains links to files in the deleted directory.
+
+```yaml
+stage:
+  build:
+    SKIP_COMPOSER_DUMP_AUTOLOAD: true
+```
+
 ### `SKIP_SCD`
 
 -  **Default**— _Not set_
diff --git a/src/cloud/project/magento-env-yaml.md b/src/cloud/project/magento-env-yaml.md
@@ -67,3 +67,48 @@ When a failure occurs because of an unexpected value in the `.magento.env.yaml`
 ```
 
 Make any corrections, commit, and push the changes. If you do not receive an error message, then the changes to your configuration file pass the validation.
+
+## Create configuration file from CLI
+
+You can generate a `.magento.env.yaml` configuration file for a Cloud environment using the following `ece-tools` CLI commands.
+
+```bash
+php ./vendor/bin/ece-tools cloud:config:create     # Creates a new configuration file
+```
+
+```bash
+php ./vendor/bin/ece-tools cloud:config:update     # Updates values in the configuration file
+```
+
+Both commands require a single argument, a JSON-formatted array that specifies a value for at least one build, deploy, or post-deploy variable. For example, the following command sets values for the `SCD_THREADS` and `CLEAN_STATIC_FILES` variables.
+
+```bash
+php vendor/bin/ece-tools cloud:config:create '{"stage":{"build":{"SCD_THREADS":5}, "deploy":{"CLEAN_STATIC_FILES":false}}}'
+```
+
+This command creates a new .magento.env.yaml file with the following settings:
+
+```yaml
+stage:
+  build:
+    SCD_THREADS: 5
+  deploy:
+    CLEAN_STATIC_FILES: false
+```
+
+You can use the `cloud:config:update` command to update the new file. For example, the following command changes the `SCD_THREADS` value and adds the `SCD_COMPRESSION_TIMEOUT` configuration:
+
+```bash
+php vendor/bin/ece-tools cloud:config:update '{"stage":{"build":{"SCD_THREADS":3, "SCD_COMPRESSION_TIMEOUT":1000}}}'
+```
+
+The updated file contains the following configuration:
+
+```yaml
+stage:
+  build:
+    SCD_THREADS: 3
+    SCD_COMPRESSION_TIMEOUT: 1000
+  deploy:
+    CLEAN_STATIC_FILES: false
+```
diff --git a/src/cloud/reference/ece-tools-reference.md b/src/cloud/reference/ece-tools-reference.md
@@ -19,39 +19,45 @@ php ./vendor/bin/ece-tools list
 
 ```terminal
 Available commands:
-  build                    Builds application
-  db-dump                  Creates backup of database
-  deploy                   Deploys application
-  help                     Displays help for a command
-  list                     Lists commands
-  patch                    Applies custom patches
+  build                    Builds application.
+  db-dump                  Creates database backups.
+  deploy                   Deploys application.
+  help                     Displays help for a command.
+  list                     Lists commands.
+  patch                    Applies custom patches.
   post-deploy              Performs after deploy operations.
-  run                      Execute scenario(s)
+  run                      Execute scenario(s).
  backup
-  backup:list              Shows the list of backup files
+  backup:list              Shows the list of backup files.
   backup:restore           Restore important configuration files. Run backup:list to show the list of backup files
- build
-  build:generate           Generates all necessary files for build stage
-  build:transfer           Transfer generated files into init directory
+ build.
+  build:generate           Generates all necessary files for build stage.
+  build:transfer           Transfers generated files into init directory.
+ cloud
+  cloud:config:create      Creates a `.magento.env.yaml` file with the specified build, deploy, and post-deploy variable configuration. Overwrites any existing `.magento,.env.yaml` file.
+  cloud:config:update      Updates the existing `.magento.env.yaml` file with the specified configuration. Creates `.magento.env.yaml` file if it does not exist.
  config
   config:dump              [dump] Dump configuration for static content deployment.
  cron
-  cron:disable             Disable all Magento cron processes and kills currently running
-  cron:enable              Enable Magento cron processes
-  cron:kill                Kill all Magento cron processes
+  cron:disable             Disable all Magento cron processes and kills currently running.
+  cron:enable              Enable Magento cron processes.
+  cron:kill                Kill all Magento cron processes.
   cron:unlock              Unlock cron jobs that stuck in "running" state.
  dev
   dev:git:update-composer  Updates composer for deployment from git.
  env
-  env:config:show          Display encoded cloud configuration environment variables
+  env:config:show          Display encoded cloud configuration environment variables.
+ error
+  error:show               Display info about error by error id or info about all errors from the last deployment.
  module
-  module:refresh           Refresh config to enable newly added modules
+  module:refresh           Refresh config to enable newly added modules.
  wizard
-  wizard:ideal-state       Verifies ideal state of configuration
-  wizard:master-slave      Verifies master-slave configuration
-  wizard:scd-on-build      Verifies SCD on build configuration
-  wizard:scd-on-demand     Verifies SCD on demand configuration
-  wizard:scd-on-deploy     Verifies SCD on deploy configuration
+  wizard:ideal-state       Verifies ideal state of configuration.
+  wizard:master-slave      Verifies master-slave configuration.
+  wizard:scd-on-build      Verifies SCD on build configuration.
+  wizard:scd-on-demand     Verifies SCD on demand configuration.
+  wizard:scd-on-deploy     Verifies SCD on deploy configuration.
+  wizard:split-db-state    Verifies ability to split DB and whether DB was already split or not.
 ```
 {:.no-copy}
 
diff --git a/src/cloud/release-notes/ece-release-notes.md b/src/cloud/release-notes/ece-release-notes.md
@@ -17,10 +17,41 @@ The `{{site.data.var.ct}}` package uses the following release versioning sequenc
 {:.bs-callout-info}
 See [Upgrades and patches]({{ site.baseurl }}/cloud/project/project-upgrade-parent.html) for information about updating to the latest release of the `{{site.data.var.ct}}` package.
 
-## v2002.1.2
+## v2002.1.3
 *Release date: {{ site.data.var.ece-release-date }}*<br/>
 
-<!--Add release notes below-->
+**Infrastructure updates**–
+
+-  {:.new}Added ece-tools support for the read-only `pub/static` directory when static content is set to deploy in the build stage.<!--MC-37699-->
+
+-  {:.new}Added support for Elasticsearch 7.9 and Redis 6 for compatibility with upcoming Magento releases.<!--MCLOUD-7191-->
+
+-  {:.fix}Updated the ece-tools `composer.json` to add a required dependency for the Magento Quality Patches package. This fixes a circular dependency that existed between the ece-tools and magento-cloud-patches packages.<!--MCLOUD-6910-->
+
+**Validation and log improvements**–
+
+-  {:.new}Added search-engine validation to ensure that `elasticsearch` is set for {{site.data.var.ece }} 2.4 and later. If the validation fails, the deployment is stopped with a critical error message suggesting fixes for the issue. See [Critical Errors, Deploy stage]({{ site.baseurl }}/cloud/reference/ece-tools-error-reference.html#deploy-stage).<!--MCLOUD-6937-->
+
+-  {:.new}Added Elasticsearch validation to check the compatibility between the Elasticsearch service version and the Magento version.<!--MCLOUD-7193-->
+
+-  {:.new}Updated the Elasticsearch compatibility error message to show the versions of Elasticsearch that are compatible with the Magento Elasticsearch module. The error message now provides the specific Elasticsearch versions to install in your Cloud infrastructure so that it is compatible with the Elasticsearch module used by your version of Magento. See [Warning Errors, Deploy stage]({{ site.baseurl }}/cloud/reference/ece-tools-error-reference.html#deploy-stage-1).<!--MCLOUD-6698-->
+
+-  {:.new}Added warning errors `2026` and `2027` for invalid `MAGE_MODE` environment variable setting. The only valid value is `production`. Before this fix, `MAGE_MODE` could be set to `developer` without deployment errors, only to cause errors later when trying to write to read-only files. See [Warning Errors]({{ site.baseurl }}/cloud/reference/ece-tools-error-reference.html#warning-errors).<!--MCLOUD-6708-->
+
+-  {:.fix}Fixed validation for Redis, RabbitMQ and MySQL services to ensure these versions are compatible with the Magento version. Valid versions of these services are now written to the `cloud.log`.<!--MCLOUD-7098-->
+
+-  {:.fix}Updated the `cloud.log` to include the concurrent requests limit for sending requests during cache warmup. This value is configured in the [WARM_UP_CONCURRENCY]({{ site.baseurl }}/cloud/env/variables-post-deploy.html#warm_up_concurrency) post-deploy variable.<!--MCLOUD-5563-->
+
+**CLI command updates**–
+
+-  {:.new}Added CLI commands (`cloud:config:create` and `cloud:config:update`) to create and update the `.magento.env.yaml` file with a configuration that can include one or more build, deploy, and post-deploy variables. See [Create configuration file from CLI]({{ site.baseurl }}/cloud/project/magento-env-yaml.html#create-configuration-file-from-cli).<!--MCLOUD-7072-->
+
+**Environment variable updates**–
+
+-  {:.new}Added the [SKIP_COMPOSER_DUMP_AUTOLOAD]({{ site.baseurl }}/cloud/env/variables-build.html#skip_composer_dump_autoload) build variable. Setting the variable to `true` stops Magento from running the `composer dump-autoload` command during a {{ site.data.var.mcd-prod }} installation. The variable is only relevant to {{ site.data.var.mcd-prod }} containers with writable file systems (created for testing and development using `./vendor/bin/ece-docker build:compose --with-test`). With such installations, skipping the `composer dump-autoload` command prevents errors when running other commands that try to access files from a deleted `generated` directory.<!--MCLOUD-6939-->
+
+## v2002.1.2
+*Release date: August 5, 2020*<br/>
 
 **Validation and log improvements**–
 
@@ -87,7 +118,7 @@ See [Upgrades and patches]({{ site.baseurl }}/cloud/project/project-upgrade-pare
       {:.no-copy}
       <!--MCLOUD-4077-->
 
-   -  {:.new}**Added validation for Zend Framework dependencies**–Added compoer dependency validation for the Zend Framework which has migrated to the Laminas project. If the required dependencies are missing, the following error message displays during the build process.
+   -  {:.new}**Added validation for Zend Framework dependencies**–Added composer dependency validation for the Zend Framework which has migrated to the Laminas project. If the required dependencies are missing, the following error message displays during the build process.
 
       ```text
       Required configuration is missing from the autoload section of the composer.json file.
