MAGECLOUD-3813 ece-tools reference

_data/toc/cloud-guide.yml

@@ -38,6 +38,9 @@ pages:
         - label: Magento Cloud CLI
           url: /cloud/reference/cli-ref-topic.html
 
+        -  label: ece-tools package
+           url: /cloud/reference/ece-tools-reference.html
+
         - label: Git
           url: /cloud/reference/git-integration.html
 

_includes/cloud/note-ece-tools-release-info.md

@@ -1,2 +1,2 @@
-{: .bs-callout .bs-callout-info}
+{: .bs-callout-info}
 For current {{ site.data.var.ece }} release information, see [Release notes for ece-tools]({{ page.baseurl }}/cloud/release-notes/cloud-tools.html).

guides/v2.1/cloud/bk-cloud.md

@@ -22,7 +22,7 @@ Amazon Web Services (AWS) powers the underlying Infrastructure as a Service (Iaa
 
 ## {{site.data.var.ct}} package
 
-The `{{site.data.var.ct}}` package is a scalable deployment tool that simplifies the Cloud upgrade process. In 2018, we deprecated the `magento-cloud-configuration` and `ece-patches` packages in favor of providing a single package. We encourage all customers to [upgrade to use `{{site.data.var.ct}}`]({{page.baseurl}}/cloud/project/ece-tools-upgrade-project.html) as soon as possible to benefit from the package features, such as commands to create a backup of the database, apply custom patches, and verify environment configuration. 
+The [`{{site.data.var.ct}}` package][ece] is a scalable deployment tool that simplifies the Cloud upgrade process. In 2018, we deprecated the `magento-cloud-configuration` and `ece-patches` packages in favor of providing a single package. We encourage all customers to [upgrade to use `{{site.data.var.ct}}`]({{page.baseurl}}/cloud/project/ece-tools-upgrade-project.html) as soon as possible to benefit from the package features, such as commands to create a backup of the database, apply custom patches, and verify environment configuration. 
 
 <!-- Link definitions -->
 
@@ -31,3 +31,5 @@ The `{{site.data.var.ct}}` package is a scalable deployment tool that simplifies
 
 [Cloud Stack]: {{site.baseurl}}/common/images/cloud/CloudStack.png
 {: width="804px" height="721px"}
+
+[ece]: {{page.baseurl}}/cloud/reference/ece-tools-reference.html

guides/v2.1/cloud/docker/docker-quick-reference.md

@@ -22,28 +22,6 @@ Resume Docker environment | `docker-compose start`
 List images | `docker-compose images`
 List containers and ports | `docker-compose ps`, or `docker ps`
 
-## ece-tools
-
-Action | Command
-:----- | :------
-Builds the docker environment in [production mode]({{page.baseurl}}/cloud/docker/docker-config.html#launch-modes) by default and verifies configured service versions. | `docker:build`
-Builds the docker environment in [developer mode]({{page.baseurl}}/cloud/docker/docker-config.html#launch-modes). | `docker:build --mode="developer"`
-Convert PHP configuration files to Docker ENV files. | `docker:config:convert`
-
-The following example lists the `{{site.data.var.ct}}` Docker commands:
-
-```bash
-php ./vendor/bin/ece-tools list | grep docker
-```
-
-```terminal
- docker
-  docker:build              Build docker configuration
-  docker:build:integration  Build test docker configuration
-  docker:config:convert     Convert raw config to .env files configuration
-```
-{: .no-copy}
-
 ### Build options
 
 | Option       | Key              | Available values

guides/v2.1/cloud/env/variables-cloud.md

@@ -13,7 +13,7 @@ functional_areas:
 Environment variables that are specific to {{site.data.var.ece}} use the `MAGENTO_CLOUD_*` prefix:
 
 Variable | Description
------------ | ---------------
+-------- | ---------------
 `MAGENTO_CLOUD_APP_DIR` | The absolute path to the application directory.
 `MAGENTO_CLOUD_APPLICATION` | A base64-encoded JSON object that describes the application. It maps to the `.magento.app.yaml` file content and has subkeys.
 `MAGENTO_CLOUD_APPLICATION_NAME` | The name of the application configured in the `.magento.app.yaml` file.
@@ -25,13 +25,13 @@ Variable | Description
 `MAGENTO_CLOUD_TREE_ID` | The tree ID for the application, which corresponds to the SHA of the tree in Git.
 `MAGENTO_CLOUD_VARIABLES` | A base64-encoded JSON object with key-value pairs, such as `"key":"value"`.
 
-{:.bs-callout .bs-callout-warning}
+{:.bs-callout-warning}
 To [add environment variables to override configuration settings]({{ site.baseurl }}/guides/v2.2/config-guide/prod/config-reference-var-name.html) using the [Project Web Interface]({{ page.baseurl }}/cloud/project/project-webint-basic.html#project-conf-env-var), you must prepend the variable name with `env:` as in the following example.
 ![Environment variable example]({{ site.baseurl }}/common/images/cloud_env_var_example.png)
 
 Since values can change over time, it is best to inspect the variable at runtime and use it to configure your application. For example, we use the `MAGENTO_CLOUD_RELATIONSHIPS` variable to retrieve environment-related relationships as follows:
 
-```php
+```php?start_inline=1
 /**
   * Get relationships information from MagentoCloud environment variable.
   *
@@ -41,4 +41,25 @@ Since values can change over time, it is best to inspect the variable at runtime
     {
         return json_decode(base64_decode($_ENV["MAGENTO_CLOUD_RELATIONSHIPS"]), true);
     }
-```
+```
+
+#### To view environment variables:
+
+You can use the `env:config:show` command from [the `{{site.data.var.ct}}` package]({{page.baseurl}}/cloud/reference/ece-tools-reference.html) to show a list of variables for the current environment.
+
+```bash
+php ./vendor/bin/ece-tools env:config:show variables
+```
+
+Sample output for the `variables` option:
+
+```terminal
+Magento Cloud Environment Variables:
++-----------------------------------+----------------------------------+
+| Variable name                     | Value                            |
++-----------------------------------+----------------------------------+
+| ADMIN_EMAIL                       | magentoadmin@company.com         |
+| ADMIN_PASSWORD                    | 123123q                          |
++-----------------------------------+----------------------------------+
+```
+{: .no-copy}

guides/v2.1/cloud/env/variables-deploy.md

@@ -332,7 +332,7 @@ stage:
 -  **Default**—_Not set_
 -  **Version**—Magento 2.1.4 and later
 
-You can configure specific locales per theme as long as the theme is not excluded using the `SCD_EXCLUDE_THEMES` variable during deployment. This is ideal if you want to speed up the deployment process by reducing the amount of unnecessary theme files. For example, you can deploy the _magento/backend_ theme in English and a custom theme in other languages.
+You can configure specific locales per theme as long as the theme is not excluded using the [`SCD_EXCLUDE_THEMES` variable](#scd_exclude_themes) during deployment. This is ideal if you want to speed up the deployment process by reducing the amount of unnecessary theme files. For example, you can deploy the _magento/backend_ theme in English and a custom theme in other languages.
 
 The following example deploys the `Magento/backend` theme with three locales:
 
@@ -461,7 +461,7 @@ stage:
 -  **Default**—`true`
 -  **Version**—Magento 2.1.4 and later
 
-Generates symlinks for static content. This setting is vital in the Pro Production environment for the three-node cluster. When this variable is set to `false`, it must copy every file during the deployment, which increases deployment time.
+Generates symlinks for static content. This setting is vital in the Pro Production environment for the three-node cluster. When this variable is set to `false`, it must copy every file during the deployment, which increases deployment time. Setting the [`SCD_ON_DEMAND` variable]({{page.baseurl}}/cloud/env/variables-global.html#scd_on_demand) to `true` disables this variable.
 
 If you generate static content during the build phase, it creates a symlink to the content folder.
 If you generate static content during the deploy phase, it writes directly to the content folder.

guides/v2.1/cloud/reference/ece-tools-reference.md

@@ -0,0 +1,111 @@
+---
+group: cloud-guide
+title: ece-tools reference
+functional_areas:
+  - Cloud
+---
+
+The `{{site.data.var.ct}}` package is a set of scripts and tools designed to manage and deploy {{site.data.var.ece}} projects. The `{{site.data.var.ct}}` package simplifies many {{site.data.var.ece}} processes, such as Docker environment deployment, cron management, and project verification. You can view and contribute to the open-source [ece-tools repository on Github](https://github.com/magento/ece-tools).
+
+{% include cloud/note-ece-tools-package.md %}
+
+The `{{site.data.var.ct}}` package is compatible with {{site.data.var.ee}}—starting with version 2.1.4—and contains scripts and {{site.data.var.ece}} commands designed to help manage your code and automatically build and deploy your projects.
+
+#### To list the available `{{site.data.var.ct}}` commands:
+
+```bash
+php ./vendor/bin/ece-tools list
+```
+
+## Build and deploy
+
+The `{{site.data.var.ct}}` package performs operations for the build, deploy, and post-deploy stages for launching your {{site.data.var.ece}} application. By default, these commands are in the [hooks property][hooks] of the `.magento.app.yaml` configuration file.
+
+## Docker configuration generator
+
+The `{{site.data.var.ct}}` package provides all the commands necessary to [launch a Docker development environment]({{page.baseurl}}/cloud/docker/docker-config.html). 
+
+Command | Action
+:------ | :------
+`docker:build` | Builds the docker environment in [production mode][mode] by default and verifies configured service versions.
+`docker:build --mode="developer"` | Builds the docker environment in [developer mode][mode].
+`docker:config:convert` | Convert PHP configuration files to Docker ENV files.
+
+The following example lists the `{{site.data.var.ct}}` Docker commands:
+
+```bash
+php ./vendor/bin/ece-tools list | grep docker
+```
+
+Sample response:
+
+```terminal
+ docker
+  docker:build              Build docker configuration
+  docker:config:convert     Convert raw config to .env files configuration
+```
+{: .no-copy}
+
+## Services, routes, and variables
+
+You can use the `{{site.data.var.ct}}` package to display detailed information about the Base64-encoded [Cloud variables][cloudvar] used in any Cloud environment. The following command shows all services, routes, and variables.
+
+```bash
+php ./vendor/bin/ece-tools env:config:show
+```
+
+To display a specific set of information, use the following format:
+
+```bash
+php ./vendor/bin/ece-tools env:config:show <option>
+```
+
+-  `services`—Displays the relationship data from the `MAGENTO_CLOUD_RELATIONSHIPS` environment variable, defined in the `services.yaml` file.
+-  `routes`—Displays the configured routes for the project using the `MAGENTO_CLOUD_ROUTES` environment variable.
+-  `variables`—Displays the configured variables for the project using the `MAGENTO_CLOUD_VARIABLES` environment variable.
+
+Sample output for the `services` option:
+
+```terminal
+Magento Cloud Services:
++-----------------------------------+----------------------------------+
+| Service Configuration             | Value                            |
++-----------------------------------+----------------------------------+
+| database:                                                            |
++-----------------------------------+----------------------------------+
+| host                              | 127.0.0.1                        |
+| password                          | <password>                       |
+| port                              | 3306                             |
++-----------------------------------+----------------------------------+
+| elasticsearch:                                                       |
++-----------------------------------+----------------------------------+
+| host                              | 127.0.0.1                        |
+| port                              | 9200                             |
+...
+```
+{: .no-copy}
+
+## Verify environment configuration
+
+There is a set of verification commands available to help evaluate the configuration of your project. See [Smart wizards][wizard] in the _Optimize deployment_ section for a detailed description of each wizard command. The `wizard:ideal-state` command runs automatically during the build phase.
+
+#### To verify the ideal state of your project:
+
+```bash
+./vendor/bin/ece-tools wizard:ideal-state
+```
+
+Sample output:
+
+```terminal
+Ideal state is configured
+```
+{:.no-copy}
+
+{% include cloud/note-ece-tools-release-info.md %}
+
+<!-- link definitions -->
+[mode]: {{page.baseurl}}/cloud/docker/docker-config.html#launch-modes
+[hooks]: {{page.baseurl}}/cloud/project/project-conf-files_magento-app.html#hooks
+[cloudvar]: {{page.baseurl}}/cloud/env/variables-cloud.html
+[wizard]: {{page.baseurl}}/cloud/deploy/smart-wizards.html

guides/v2.1/cloud/release-notes/cloud-tools.md

@@ -10,19 +10,6 @@ redirect_from:
 ---
 <!-- 2.1 release notes -->
 
-<!-- Assigning liquid variables for placeholder values
-{% assign base_url = "{{base_url}}" %}
-{% assign unsecure_base_url = "{{unsecure_base_url}}" %}
--->
-
-The `{{site.data.var.ct}}` package is compatible with {{site.data.var.ee}} version 2.1.4 and later to provide a rich set of features you can use to manage your {{site.data.var.ece}} project. It contains scripts and {{site.data.var.ece}} commands designed to help manage your code and automatically build and deploy your projects.
-
-You can list the available `{{site.data.var.ct}}` commands using:
-
-```bash
-php ./vendor/bin/ece-tools list
-```
-
 The following updates describe the latest improvements to the `{{site.data.var.ct}}` package, which uses the following version sequence: `200<major>.<minor>.<patch>`. See [Upgrades and patches]({{ site.baseurl }}/guides/v2.1/cloud/project/project-upgrade-parent.html) for information about updating to the latest release of the `{{site.data.var.ct}}` package.
 
 The release notes include:
@@ -42,6 +29,12 @@ The release notes include:
 
 -   {:.fix}<!-- MAGECLOUD-3545/Github#455 -->Added the `pub/static/.htaccess` file to the exclude list.
 
+-   {:.fix}<!-- MAGECLOUD-3178 -->Fixed an error when all validation messages were showing as Critical if at least one critical level validator returned an error.
+
+-   {:.fix}<!-- MAGECLOUD-3075 -->Fixed an issue that caused a deployment failure if the Magento base URL did not exist in the database.
+
+-   {:.new}<!-- MAGECLOUD-3451 -->Added a new command to the `{{site.data.var.ct}}` package that displays environment services, routes, or variables. See [Services, routes, and variable]({{page.baseurl}}/cloud/reference/ece-tools-reference.html#services-routes-and-variables). [Thanks to Vladimir Kerkhoff](https://github.com/magento/ece-tools/pull/486).
+
 ## v2002.0.19
 
 -   {:.fix}<!-- MAGECLOUD-3668 -->Fixed an issue that overwrites the `env.php` file during a deploy, resulting in a loss of custom configurations.  This update ensures that {{site.data.var.ece}} updates the `env.php` file with every deployment, while preserving custom configurations.

guides/v2.2/cloud/env/variables-cloud.md

@@ -13,7 +13,7 @@ functional_areas:
 Environment variables that are specific to {{site.data.var.ece}} use the `MAGENTO_CLOUD_*` prefix:
 
 Variable | Description
------------ | ---------------
+-------- | ---------------
 `MAGENTO_CLOUD_APP_DIR` | The absolute path to the application directory.
 `MAGENTO_CLOUD_APPLICATION` | A base64-encoded JSON object that describes the application. It maps to the `.magento.app.yaml` file content and has subkeys.
 `MAGENTO_CLOUD_APPLICATION_NAME` | The name of the application configured in the `.magento.app.yaml` file.
@@ -26,7 +26,7 @@ Variable | Description
 `MAGENTO_CLOUD_VARIABLES` | A base64-encoded JSON object with key-value pairs, such as `"key":"value"`.
 `MAGENTO_CLOUD_LOCKS_DIR` | Provides the path to the mount point for the lock provider on the Cloud infrastructure. The lock provider prevents the launch of duplicate cron jobs and cron groups.
 
-{:.bs-callout .bs-callout-warning}
+{: .bs-callout-warning}
 To [add environment variables to override configuration settings]({{ site.baseurl }}/guides/v2.2/config-guide/prod/config-reference-var-name.html) using the [Project Web Interface]({{ page.baseurl }}/cloud/project/project-webint-basic.html#project-conf-env-var), you must prepend the variable name with `env:` as in the following example.
 ![Environment variable example]({{ site.baseurl }}/common/images/cloud_env_var_example.png)
 
@@ -43,3 +43,24 @@ Since values can change over time, it is best to inspect the variable at runtime
         return json_decode(base64_decode($_ENV["MAGENTO_CLOUD_RELATIONSHIPS"]), true);
     }
 ```
+
+#### To view environment variables:
+
+You can use the `env:config:show` command from [the `{{site.data.var.ct}}` package]({{page.baseurl}}/cloud/reference/ece-tools-reference.html) to show a list of variables for the current environment.
+
+```bash
+php ./vendor/bin/ece-tools env:config:show variables
+```
+
+Sample output for the `variables` option:
+
+```terminal
+Magento Cloud Environment Variables:
++-----------------------------------+----------------------------------+
+| Variable name                     | Value                            |
++-----------------------------------+----------------------------------+
+| ADMIN_EMAIL                       | magentoadmin@company.com         |
+| ADMIN_PASSWORD                    | 123123q                          |
++-----------------------------------+----------------------------------+
+```
+{: .no-copy}

guides/v2.2/cloud/env/variables-deploy.md

@@ -391,7 +391,7 @@ stage:
 -  **Default**—_Not set_
 -  **Version**—Magento 2.1.4 and later
 
-You can configure multiple locales per theme as long as the theme is not excluded using the `SCD_EXCLUDE_THEMES` variable during deployment. This is ideal if you want to speed up the deployment process by reducing the amount of unnecessary theme files. For example, you can deploy the _magento/backend_ theme in English and a custom theme in other languages.
+You can configure multiple locales per theme as long as the theme is not excluded using the [`SCD_EXCLUDE_THEMES` variable](#scd_exclude_themes) during deployment. This is ideal if you want to speed up the deployment process by reducing the amount of unnecessary theme files. For example, you can deploy the _magento/backend_ theme in English and a custom theme in other languages.
 
 The following example deploys the `Magento/backend` theme with three locales:
 
@@ -551,7 +551,7 @@ stage:
 -  **Default**—`true`
 -  **Version**—Magento 2.1.4 and later
 
-Generates symlinks for static content. This setting is vital in the Pro Production environment for the three-node cluster. When this variable is set to `false`, it must copy every file during the deployment, which increases deployment time. Setting `SCD_ON_DEMAND` to `true` disables this variable.
+Generates symlinks for static content. This setting is vital in the Pro Production environment for the three-node cluster. When this variable is set to `false`, it must copy every file during the deployment, which increases deployment time. Setting the [`SCD_ON_DEMAND` variable]({{page.baseurl}}/cloud/env/variables-global.html#scd_on_demand) to `true` disables this variable.
 
 If you generate static content during the build phase, it creates a symlink to the content folder.
 If you generate static content during the deploy phase, it writes directly to the content folder.

guides/v2.2/cloud/reference/ece-tools-reference.md

@@ -0,0 +1 @@
+../../../v2.1/cloud/reference/ece-tools-reference.md