Updated best practices and deployment info

_includes/cloud/cloud-elasticsearch-client-compatibility.md

@@ -0,0 +1,7 @@
+The following table lists compatible versions of the Elasticsearch software supported by {{ site.data.var.ee }}.
+
+Elasticsearch service   |  Elasticsearch composer package | Status
+--------- | ------------- | -------------------------
+1.7 – 2.4.x| 2.x.x | deprecated
+5.2.x | 5.x.x | default versions for {{ site.data.var.ee }} versions 2.2.x - 2.2.7 and 2.3.0
+6.x | 6.x | recommended, default versions for {{ site.data.var.ee }} versions 2.2.8 and 2.3.1 and later.

guides/v2.2/cloud/project/project-conf-files_services-elastic.md

@@ -16,8 +16,8 @@ functional_areas:
 
 {% include cloud/service-config-integration-starter.md %}
 
-{: .bs-callout-warning}
-Staging and Production environments that are in the same cluster share a single Elasticsearch instance, so you must specify a unique Elasticsearch prefix for each of these environments.
+{:.bs-callout-tip}
+Magento recommends that you always set up Elasticsearch for your {{ site.data.var.ece }} project even if you plan to configure a third-party search tool for your {{ site.data.var.ee }} application. Setting up Elasticsearch provides a fallback option in the event that the third-party search tool fails.
 
 {:.procedure}
 To enable Elasticsearch:
@@ -30,6 +30,9 @@ To enable Elasticsearch:
        disk: 1024
    ```
 
+   {:.bs-callout-info}
+   For details on determining the correct version to install, see [Elasticsearch software compatibility](#elasticsearch-software-compatibility).
+
 1. Set the `relationships` property in the `.magento.app.yaml` file.
 
    ```yaml
@@ -59,11 +62,120 @@ To enable Elasticsearch:
    bin/magento cache:clean
    ```
 
+## Elasticsearch software compatibility
+
+When you install or upgrade your {{ site.data.var.ece }} project, always check for compatibility between the Elasticsearch service version and the [Elasticsearch PHP](https://github.com/elastic/elasticsearch-php) client for {{ site.data.var.ee }}.
+
+-  **First time setup**–Confirm that the Elasticsearch version specified in the `services.yaml` file is compatible with the Elasticsearch PHP client configured for {{ site.data.var.ee }}.
+
+-  **Project upgrade**–Verify that the Elasticsearch PHP client in the new Magento version is compatible with the Elasticsearch service version installed on the Cloud infrastructure.
+
+{% include cloud/cloud-elasticsearch-client-compatibility.md %}
+
+{:.procedure}
+To check Elasticsearch software compatibility:
+
+1. Use SSH to log in to the remote environment.
+
+1. Check the Composer package version for `elasticsearch/elasticsearch`.
+
+   ```bash
+   composer show elasticsearch/elasticsearch
+   ```
+
+   In the response, check the installed version in the `versions` property.
+
+   ```terminal
+   name     : elasticsearch/elasticsearch
+   descrip. : PHP Client for Elasticsearch
+   keywords : client, elasticsearch, search
+   versions : * v6.7.1
+   type     : library
+   license  : Apache License 2.0 (Apache-2.0) (OSI approved) https://spdx.org    licensesApache-2.0.html#licenseText
+   source   : [git] https://github.com/elastic    elasticsearch-php.git7be453dd36d1b141b779f2cb956715f8e04ac2f4
+   dist     : [zip] https://api.github.com/repos/elastic/elasticsearch-php/zipball/     7be453dd36d1b141b779f2cb956715f8e04ac2f4 7be453dd36d1b141b779f2cb956715f8e04ac2f4
+   path     : /app/vendor/elasticsearch/elasticsearch
+   names    : elasticsearch/elasticsearch
+   ```
+
+   Also, you can find the Elasticsearch PHP client version in the  `composer.lock` file in the environment root directory.
+
+1. From the command line, retrieve the Elasticsearch service connection details.
+
+   ```bash
+   vendor/bin/ece-tools env:config:show services
+   ```
+
+   In the response, find the IP address for the Elasticsearch service endpoint:
+
+   ```terminal
+   | elasticsearch:                                                                                                  |
+   +------------------------------------------+----------------------------------------------------------------------+
+   | username                                 | null                                                                 |
+   | scheme                                   | http                                                                 |
+   | service                                  | elasticsearch                                                        |
+   | fragment                                 | null                                                                 |
+   | ip                                       | 169.254.220.11                                                       |
+   | hostname                                 | dzggu33f75wi3sd24lgwtoupxm.elasticsearch.service._.magentosite.cloud |
+   | public                                   | false                                                                |
+   | cluster                                  | fo3qdoxtla4j4-master-7rqtwti                                         |
+   | host                                     | elasticsearch.internal                                               |
+   | rel                                      | elasticsearch                                                        |
+   | query                                    |                                                                      |
+   | path                                     | null                                                                 |
+   | password                                 | null                                                                 |
+   | type                                     | elasticsearch:6.5                                                    |
+   | port                                     | 9200                                                                 |
+   +------------------------------------------+----------------------------------------------------------------------+
+   ```
+
+1. Retrieve the installed Elasticsearch service `version:number` from the service endpoint.
+
+   ```bash
+   curl -XGET <elasticsearch-service-endopint-ip-address>:9200/
+   ```
+
+   ```terminal
+   {
+      "name" : "-AqGi9D",
+      "cluster_name" : "elasticsearch",
+      "cluster_uuid" : "_yze6-ywSEW1MaAF8ZPWyQ",
+      "version" : {
+        "number" : "6.5.4",
+        "build_flavor" : "default",
+        "build_type" : "deb",
+        "build_hash" : "82a8aa7",
+        "build_date" : "2019-01-23T12:07:18.760675Z",
+        "build_snapshot" : false,
+        "lucene_version" : "7.5.0",
+        "minimum_wire_compatibility_version" : "5.6.0",
+        "minimum_index_compatibility_version" : "5.0.0"
+   },
+   "  tagline" : "You Know, for Search"
+   }
+   ```
+
+1. Check version compatibility between the Elasticsearch service and the PHP client.
+
+   If the versions are incompatible, make one of the following updates to your environment configuration:
+
+   -  Change the Elasticsearch service version in the `services.yaml` file to a version that is compatible with the Elasticsearch PHP client. On Pro Staging and Production environments, you must submit a support ticket to change the Elasticsearch service version.
+
+   -  [Change the Elasticsearch PHP client]({{ page.baseurl }}/config-guide/elasticsearch/es-downgrade.html) to a version that is compatible with the Elasticsearch service version.
+
 ## Restart the Elasticsearch service
 
 If you need to restart the [Elasticsearch](https://www.elastic.co) service, you must contact Magento support.
 
-## Elasticsearch plugins
+## Additional search configuration
+
+-  By default, the search configuration for Cloud environments regenerates each time you deploy. You can use the `SEARCH_CONFIGURATION` deploy variable to retain custom search settings between deployments. See [Deploy variables]({{ page.baseurl }}/cloud/env/variables-deploy.html#search_configuration).
+
+-  {{ site.data.var.ece }} projects provisioned with a shared Production and Staging environment use a single Elasticsearch instance, so you must specify a unique _Elasticsearch Index prefix_ for each of these environments. See [Configure Magento to use Elasticsearch]({{ page.baseurl}}/config-guide/elasticsearch/configure-magento.html) in the _Configuration Guide_.
+
+-  After you set up the Elasticsearch service for your project, use the Magento Admin UI to test the Elasticsearch connection and customize Elasticsearch settings for {{ site.data.var.ee }}.
+
+### Elasticsearch plugins
 
 Optionally, you can add Elasticsearch plugins by adding the `configuration:plugins` section to the `.magento/services.yaml` file. For example, the following code enables the ICU analysis plugin and Python script support plugins.
 
@@ -77,4 +189,4 @@ elasticsearch:
             - lang-python
 ```
 
-If you use the ElasticSuite third-party plugin, you must [update the `{{site.data.var.ct}}` package]({{page.baseurl}}/cloud/project/ece-tools-update.html) to version 2002.0.19 or later.
+If you use the ElasticSuite third-party plugin, you must [update the `{{site.data.var.ct}}` package]({{page.baseurl}}/cloud/project/ece-tools-update.html) to version 2002.0.19 or later.

guides/v2.2/cloud/project/project-conf-files_services.md

@@ -135,7 +135,6 @@ To verify relationships in local environment:
            type: 'mysql:10.0'
            port: 3306
    ```
-   {:.no-copy}
 
 {:.procedure}
 To verify relationships in remote environments:
@@ -170,3 +169,6 @@ Service   |  Magento 2.3  | Magento 2.2
 `rabbitmq`| 3.5, 3.7      | 3.5
 `redis`   | 3.2, 4.0, 5.0 | 3.2, 4.0, 5.0
 `varnish` | Magento 2.3.3 and later—4.0, 5.0, 6.2<br>Magento 2.3.0 to 2.3.2—4.0, 5.0 | 4.0, 5.0
+
+{:.bs-callout-info}
+When you set up the Elasticsearch service, check to ensure that you use a version that is compatible with the installed [Elasticsearch PHP](https://github.com/elastic/elasticsearch-php) client. See [Check Elasticsearch software compatibility]({{ page.baseurl }}/cloud/project/project-conf-files_services-elastic.html#elasticsearch-software-compatibility).

guides/v2.2/cloud/reference/discover-deploy.md

@@ -23,7 +23,7 @@ You can track build and deploy actions in real-time using the terminal or the Pr
 If you are using external GitHub repositories, the log of operations does not display in the GitHub session. However, you can still follow activity in the interface for the external repository and the Project Web Interface. See [Integrations]({{ page.baseurl }}/cloud/integrations/cloud-integrations.html).
 
 {:.bs-callout-info}
-In Integration environments, you cannot view the deploy logs from the Project Web Interface. This feature is available only for Production and Staging environments. However, you can view logs for every phase of the deployment in any environment using the Magento [build and deploy]({{ page.baseurl }}/cloud/project/log-locations.html#build-and-deploy-logs).
+In Integration environments, you cannot view the deploy logs from the Project Web Interface. This feature is available only for Production and Staging environments. However, you can view logs for every phase of the deployment in any environment using the Magento [build and deploy]({{ page.baseurl }}/cloud/project/log-locations.html#build-and-deploy-logs) logs.
 
 ## Project configuration {#cloud-deploy-conf}
 
@@ -72,7 +72,7 @@ We highly recommend the following best practices and considerations for your dep
 
    -  Use the `magento-cloud local:build` command to test the build in your local environment. Identify and fix any issues related to composer dependencies and environment and application configuration before deploying to a remote environment. See [Test build your code locally before deployment]({{ page.baseurl }}/cloud/live/live-sanity-check.html#test-build).
 
-   -  Run the {{ site.data.var.ece }} smart wizard to ensure that your Cloud project configuration follows best practices for build and deployment. See [Smart wizard]({{ page.baseurl }}/cloud/deploy/smart-wizards.html).
+   -  Run the {{ site.data.var.ece }} smart wizard to ensure that your Cloud project configuration follows best practices for build and deployment including static content deployment (SCD) strategy. See [Smart wizard]({{ page.baseurl }}/cloud/deploy/smart-wizards.html).
 
 -  **After completing testing in local and Integration environments, deploy and test in the Staging environment**–See [Deploy code to Staging and Production]({{ page.baseurl }}/cloud/live/stage-prod-migrate.html#code).
 
@@ -106,6 +106,8 @@ Follow best practices for builds and deployment, and use the [Upgrades and patch
 
    -  Make any required updates to environment-specific settings before deploying to the remote environment.
 
+   -  Ensure that the Elasticsearch service version is compatible with the Elasticsearch PHP client version. See [Set up Elasticsearch]({{ page.baseurl }}/cloud/project/project-conf-files_services-elastic.html).
+
 -  **Check database connectivity and available storage in remote environments**–
 
    -  Use SSH to log in to the remote server and verify the connection to the MySQL database. See [Connect to the database]({{ page.baseurl }}/cloud/project/project-conf-files_services-mysql.html#connect-to-the-database).