diff --git a/_includes/cloud/pretty-print-services.md b/_includes/cloud/pretty-print-services.md deleted file mode 100644 index 9128af6c0af..00000000000 --- a/_includes/cloud/pretty-print-services.md +++ /dev/null @@ -1,9 +0,0 @@ -#### To verify information used for configurations and settings: - -1. Use SSH to log in to the remote environment. - -1. Create `pretty-print` of all relationships for services and configuration data for that environment. - - ```bash - php -r 'print_r(json_decode(base64_decode($_ENV["MAGENTO_CLOUD_RELATIONSHIPS"])));' - ``` diff --git a/guides/v2.2/cloud/project/project-conf-files_magento-app.md b/guides/v2.2/cloud/project/project-conf-files_magento-app.md index 0d6bf8f958d..0734b0f25a2 100644 --- a/guides/v2.2/cloud/project/project-conf-files_magento-app.md +++ b/guides/v2.2/cloud/project/project-conf-files_magento-app.md @@ -59,17 +59,22 @@ access: ### `relationships` -Defines the service mapping in your application. +Defines the service mapping in the application. -The left-hand side is the name of the relationship as it will be exposed to the application in the `MAGENTO_CLOUD_RELATIONSHIPS` environment variable. The right-hand side is in the form `:`, where `` comes from `.magento/services.yaml` and `` should be the same as the value of `type` declared in that same file. - -Example of valid options are: +The relationship `name` is available to the application in the `MAGENTO_CLOUD_RELATIONSHIPS` environment variable. The `:` relationship maps to the name and type values defined in the `.magento/services.yaml` file. +```yaml +relationships: + : ":" ``` -database: "mysql:mysql" -database2: "mysql2:mysql" -cache: "arediscache:redis" -search: "searchengine:solr" + +The following is an example of the default relationships: + +```yaml +relationships: + database: "mysql:mysql" + redis: "redis:redis" + elasticsearch: "elasticsearch:elasticsearch" ``` See [Services]({{page.baseurl}}/cloud/project/project-conf-files_services.html) for a full list of currently supported service types and endpoints. diff --git a/guides/v2.2/cloud/project/project-conf-files_services-elastic.md b/guides/v2.2/cloud/project/project-conf-files_services-elastic.md index b2cb59abc97..4076fb696e9 100644 --- a/guides/v2.2/cloud/project/project-conf-files_services-elastic.md +++ b/guides/v2.2/cloud/project/project-conf-files_services-elastic.md @@ -41,7 +41,7 @@ functional_areas: For information on how these changes affect your environments, see [Services]({{ page.baseurl }}/cloud/project/project-conf-files_services.html). -1. [Verify the relationships](#verify-relationships) and configure Elasticsearch in the Admin UI. +1. [Verify the relationships]({{page.baseurl}}/cloud/project/project-conf-files_services.html#service-relationships) and configure Elasticsearch in the Admin UI. ### Add Elasticsearch plugins @@ -80,11 +80,5 @@ See [Elasticsearch plugin documentation](https://www.elastic.co/guide/en/elastic {:.bs-callout-info} 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. -## Verify relationships - -{{site.data.var.ece}} uses the [MAGENTO_CLOUD_RELATIONSHIPS]({{ page.baseurl }}/cloud/env/variables-cloud.html) variable to retrieve the environment-related relationships. You must use this information when you [configure Elasticsearch through the Magento Admin]({{page.baseurl}}/config-guide/elasticsearch/configure-magento.html). - -{% include cloud/pretty-print-services.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. \ No newline at end of file diff --git a/guides/v2.2/cloud/project/project-conf-files_services-mysql.md b/guides/v2.2/cloud/project/project-conf-files_services-mysql.md index aa2e07fa613..61403287a19 100644 --- a/guides/v2.2/cloud/project/project-conf-files_services-mysql.md +++ b/guides/v2.2/cloud/project/project-conf-files_services-mysql.md @@ -6,40 +6,77 @@ functional_areas: - Setup --- -The `mysql` service provides data storage. It is based on [MariaDB](https://mariadb.com/), supporting the [XtraDB](https://www.percona.com/software/mysql-database/percona-server/xtradb) storage engine (equivalent to MySQL with InnoDB). +The `mysql` service provides persistent data storage. It is based on [MariaDB](https://mariadb.com/), supporting the [XtraDB](https://www.percona.com/software/mysql-database/percona-server/xtradb) storage engine. -We support MariaDB version 10.0, which includes reimplemented features from MySQL 5.6 and 5.7. +We support MariaDB version 10.2, which includes reimplemented features from MySQL 5.6 and 5.7. -To access the MariaDB database directly, [open an SSH tunnel]({{ page.baseurl }}/cloud/env/environments-start.html#env-start-tunn) and use the following command: +#### To access the MariaDB database directly: + +Using SSH, log in to the remote server and connect to the database. + +For Starter: ```bash -mysql -h database.internal -u user +mysql -h database.internal -u ``` -{% include cloud/service-config-integration-starter.md %} +For Pro, use the db, username, and password from the relationship: + +```bash +mysql -h -p -u -p +``` + +## Enable MySQL + +1. Add the required name, type, and disk value (in MB) to the `.magento/services.yaml` file. + + ```yaml + mysql: + type: mysql:10.2 + disk: 2048 + ``` + +1. Configure the relationships in the `.magento.app.yaml` file. + + ```yaml + relationships: + database: "mysql:mysql" + ``` + +1. Add, commit, and push your code changes. + + ```bash + git add -A && git commit -m "Enable mysql service" && git push origin + ``` + +1. [Verify the relationships]({{page.baseurl}}/cloud/project/project-conf-files_services.html#service-relationships). + +{: .bs-callout-info } +- If you configure one MySQL user, you cannot use the [`DEFINER`](http://dev.mysql.com/doc/refman/5.6/en/show-grants.html) access control mechanism for stored procedures and views. +- MySQL errors such as `PDO Exception 'MySQL server has gone away` are usually the result of exhausting your existing disk space. Be sure you have sufficient space allocated to the service in [`.magento/services.yaml`]({{ page.baseurl }}/cloud/project/project-conf-files_magento-app.html#disk). -## Set up multiple database users {#cloud-appyaml-mysqlusers} +## Set up multiple database users Optionally, you can set up multiple databases as well as multiple users with different permissions. -An _endpoint_ is a user who has privileges you specify. By default, there is one endpoint named `mysql` that has administrator access to all defined databases. To set up multiple databases and users, you must specify multiple endpoints. +An _endpoint_ is a set of credentials (or users) with specific privileges. By default, there is one endpoint named `mysql` that has administrator access to all defined databases. To set up multiple databases and users, you must define multiple endpoints in the services.yaml file and declare the relationships in the .magento.app.yaml file. -{:.bs-callout .bs-callout-warning} +{: .bs-callout-warning} You cannot use multiple _databases_ with {{site.data.var.ee}} at this time. You **can** create multiple endpoints to restrict access to the `main` database. -To specify user access, use the `endpoints` nested array. Each endpoint can have access to one or more schemas (databases), and can have different levels of permission on each. +Use a nested array to define the endpoints for specific user access. Each endpoint can designate access to one or more schemas (databases) and different levels of permission on each. The valid permission levels are: - `ro`: Only SELECT queries are allowed. -- `rw`: SELECT queries as well as INSERT/UPDATE/DELETE queries are allowed. +- `rw`: SELECT queries and INSERT, UPDATE, and DELETE queries are allowed. - `admin`: All queries are allowed, including DDL queries (CREATE TABLE, DROP TABLE, and so on). If no endpoints are defined, a single endpoint named `mysql` has `admin` access to the `main` database. For example: ```yaml -mysqldb: - type: mysql:10.0 +mysql: + type: mysql:10.2 disk: 2048 configuration: schemas: @@ -55,40 +92,19 @@ mysqldb: importer: privileges: main: rw - ``` -In the preceding example, the endpoint (that is, user) `reporter` has `ro` privileges to the `main` database and endpoint `importer` has `rw` access to the `main` database. This means that: +In the preceding example, the `admin` endpoint provides admin-level access to the `main` database, the `reporter` endpoint provides read-only access, and the `importer` endpoint provides read-write access. This means that: - The `admin` user has full control of the database. - The `repoter` user has SELECT privileges only. - The `importer` user has SELECT, INSERT, UPDATE, and DELETE privileges. -## Add MySQL in services.yaml and .magento.app.yaml {#settings} - -To enable MySQL, add the following code with your installed version and allocated disk space in MB to `.magento/services.yaml`. - -```yaml -mysql: - type: mysql:10.0 - disk: 2048 -``` - -To configure the relationships for the environment variable, set a relationship in your `.magento.app.yaml` in the Git branch. For example: +You must add the endpoints defined in the above example to the `relationships` property of the `.magento.app.yaml` file. For example: ```yaml relationships: - database: "mydatabase:mysql" + database: "mysql:admin" + databasereporter: "mysql:reporter" + databaseimporter: "mysql:importer" ``` - -Merge and deploy the code to set the configurations for Redis. For information on how these changes affect your environments, see [`services.yaml`]({{ page.baseurl }}/cloud/project/project-conf-files_services.html). - -{: .bs-callout-info } -- If you configure one MySQL user, you cannot use the [`DEFINER`](http://dev.mysql.com/doc/refman/5.6/en/show-grants.html) access control mechanism for stored procedures and views. -- MySQL errors such as `PDO Exception 'MySQL server has gone away` are usually the result of exhausting your existing disk space. Be sure you have sufficient space allocated to the service in [`.magento/services.yaml`]({{ page.baseurl }}/cloud/project/project-conf-files_magento-app.html#disk). - -## Verify environment-related relationships {#cloud-es-config-mg} - -We use the {{site.data.var.ece}} environment variable [`$MAGENTO_CLOUD_RELATIONSHIPS`]({{ page.baseurl }}/cloud/env/environment-vars_cloud.html), a JSON object, to retrieve environment-related relationships. - -{% include cloud/pretty-print-services.md %} \ No newline at end of file diff --git a/guides/v2.2/cloud/project/project-conf-files_services-rabbit.md b/guides/v2.2/cloud/project/project-conf-files_services-rabbit.md index a49fb151f72..0aede6764c0 100644 --- a/guides/v2.2/cloud/project/project-conf-files_services-rabbit.md +++ b/guides/v2.2/cloud/project/project-conf-files_services-rabbit.md @@ -36,12 +36,6 @@ relationships: Merge and deploy the code to set the configurations for RabbitMQ. For information on how these changes affect your environments, see [`services.yaml`]({{ page.baseurl }}/cloud/project/project-conf-files_services.html). -## Verify environment-related relationships {#cloud-es-config-mg} - -We use the {{site.data.var.ece}} environment variable [`$MAGENTO_CLOUD_RELATIONSHIPS`]({{ page.baseurl }}/cloud/env/environment-vars_cloud.html), a JSON object, to retrieve environment-related relationships. - -{% include cloud/pretty-print-services.md %} - ## Connect to RabbitMQ for debugging {#connect} For debugging purposes, it is useful to directly connect to a service instance in one of the following ways: @@ -68,11 +62,7 @@ You can do this using [SSH tunneling]({{ page.baseurl }}/cloud/env/environments- magento-cloud tunnel:open ``` -1. Pretty-print the relationships. This lets you see which username and password to use, and you can verify the remote service's port. - - ```bash - php -r 'print_r(json_decode(base64_decode($_ENV["MAGENTO_CLOUD_RELATIONSHIPS"])));' - ``` +1. [Verify the relationships]({{page.baseurl}}/cloud/project/project-conf-files_services.html#service-relationships). 1. Enable local port forwarding to RabbitMQ. diff --git a/guides/v2.2/cloud/project/project-conf-files_services-redis.md b/guides/v2.2/cloud/project/project-conf-files_services-redis.md index 2facea2ab40..2058f0db692 100644 --- a/guides/v2.2/cloud/project/project-conf-files_services-redis.md +++ b/guides/v2.2/cloud/project/project-conf-files_services-redis.md @@ -12,40 +12,40 @@ We support Redis versions 2.8, 3.0, and 5.0. Redis 3.0 supports up to 64 differe {% include cloud/service-config-integration-starter.md %} -## Add Redis in configuration files {#settings} +## Enable Redis -To enable Redis, add your installed version and allocated disk space in MB to `.magento/services.yaml` file: +1. Add the required name and type to the `.magento/services.yaml` file. -```yaml -myredis: - type: redis:3.0 -``` + ```yaml + redis: + type: redis:3.2 + ``` -To provide your own Redis configuration, add a `core_config` key in your `.magento/services.yaml` file: + To provide your own Redis configuration, add a `core_config` key in your `.magento/services.yaml` file: -```yaml -cache: - type: redis:3.0 -``` + ```yaml + cache: + type: redis:3.2 + ``` -To configure relationships for an environment variable in your `.magento.app.yaml` file: +1. Configure the relationships in the `.magento.app.yaml` file. -```yaml -runtime: - extensions: - - redis + ```yaml + runtime: + extensions: + - redis -relationships: - redis: "myredis:redis" -``` + relationships: + redis: "redis:redis" + ``` -Merge and deploy the code to set the configurations for Redis. For information on how these changes affect your environments, see [`services.yaml`]({{ page.baseurl }}/cloud/project/project-conf-files_services.html). +1. Add, commit, and push your code changes. -## Verify environment-related relationships {#cloud-es-config-mg} + ```bash + git add -A && git commit -m "Enable redis service" && git push origin + ``` -We use the {{site.data.var.ece}} environment variable [`$MAGENTO_CLOUD_RELATIONSHIPS`]({{ page.baseurl }}/cloud/env/environment-vars_cloud.html), a JSON object, to retrieve environment-related relationships. - -{% include cloud/pretty-print-services.md %} +1. [Verify the relationships]({{page.baseurl}}/cloud/project/project-conf-files_services.html#service-relationships). ## Using the Redis CLI diff --git a/guides/v2.2/cloud/project/project-conf-files_services.md b/guides/v2.2/cloud/project/project-conf-files_services.md index e07d0c30d25..9a28c0e6a1d 100644 --- a/guides/v2.2/cloud/project/project-conf-files_services.md +++ b/guides/v2.2/cloud/project/project-conf-files_services.md @@ -6,96 +6,145 @@ functional_areas: - Setup --- -Use the `services.yaml` file to configure all of your services supported and used by {{site.data.var.ece}}. These services include MySQL, Redis, ElasticSearch (for 2.1.X and later), and so on. You do not need to subscribe to external service providers. This file is located in the `.magento` directory in your project. See the latest sample of the [`services.yaml`](https://github.com/magento/magento-cloud/blob/master/.magento/services.yaml) file. - -When you push your Git branch, our deploy script uses the values defined by configuration files in the `.magento` directory. After deployment, the script deletes the directory and its contents. Your local development environment is not affected. +The `services.yaml` file defines the services supported and used by {{site.data.var.ece}}, such as MySQL, Redis, and ElasticSearch. You do not need to subscribe to external service providers. This file is in the `.magento` directory of your project. {% include cloud/note-pro-using-yaml-support.md %} -## How this file works {#howitworks} - -The `.magento.app.yaml` and `services.yaml` files set the services, applications, and configurations to build and include in an environment. If you add services with specific versions, the initial push and deployment of your branches with these updated files directs the PaaS environment to provision the environment with those services. When you make changes to the services, the environment updates. +The deploy script uses the configuration files in the `.magento` directory to provision the environment with the configured services. A service becomes available to your application if it is included in the `relationships` property of the `.magento.app.yaml` file. The `services.yaml` file contains the service _name_, _type_, and _disk_ values. Changing a service configuration causes a deployment to provision the environment with the updated services. This affects the following environments: - All Starter environments including Production `master` - Pro Integration environments -To install and update services in Pro Staging and Production environments (IaaS), you must enter a [Support ticket]({{ page.baseurl }}/cloud/trouble/trouble.html). Indicate the service changes needed and your updated `.magento.app.yaml` and `services.yaml` files in the ticket. +{:.bs-callout-tip} +For Pro, you must enter a [Support ticket]({{ page.baseurl }}/cloud/trouble/trouble.html) to install or update services in the Staging and Production environments. Indicate the service changes needed and your updated `.magento.app.yaml` and `services.yaml` files in the ticket. + +## Default and supported services -## Default and supported services {#cloud-yaml-services-default} +We support and deploy the following services: + +- [`mysql`]({{ page.baseurl }}/cloud/project/project-conf-files_services-mysql.html) +- [`redis`]({{ page.baseurl }}/cloud/project/project-conf-files_services-redis.html) +- [`elasticsearch`]({{ page.baseurl }}/cloud/project/project-conf-files_services-elastic.html) +- [`rabbitmq`]({{ page.baseurl }}/cloud/project/project-conf-files_services-rabbit.html) -A Cloud template includes the following [default `services.yaml` file](https://github.com/magento/magento-cloud/blob/master/.magento/services.yaml): +You can view default versions and disk values in the the current, [default `services.yaml` file](https://github.com/magento/magento-cloud/blob/master/.magento/services.yaml). The following sample shows the `mysql`, `redis`, and `elasticsearch` services defined in the `services.yaml` configuration file: ```yaml mysql: - type: mysql:10.0 + type: mysql: disk: 2048 redis: - type: redis:3.0 + type: redis: elasticsearch: - type: elasticsearch:6.5 + type: elasticsearch: disk: 1024 ``` -Modify this file to use specific and additional services in your deployment. See the [`type`](#cloud-yaml-services-type) section to see the services we support and deploy for you if you add them to the file. +## Service values -## Service values {#services} - -To add a service, you add the following data to services.yaml: +Minimally, you must provide a `name` and `type` value for each service. If the service uses persistent storage, then you must provide a `disk` value. Use the following format: ```yaml -name: - type: name:version - disk: value +: + type: : + disk: ``` -For example: +### `name` -```yaml -mysql: - type: mysql:10.0 - disk: 2048 -``` +The `name` value identifies the service in the project. You can only use lower case alphanumeric characters: `a` to `z` and `0` to `9`, such as `redis`. -### `name` {#cloud-yaml-services-name} +This _name_ value is used in the `relationships` property of the `.magento.app.yaml` configuration file: -Identifies the service in the project. The `name` can consist only of lower case alphanumeric characters: `a` to `z` and `0` to `9`. For example, Redis is entered as `redis`. +```yaml +relationships: + redis: ":redis" +``` -You can have multiple instances of each service type. For example, you could have multiple Redis instances. For example, we use multiple Redis instances, one for session and one for cache. +You can name multiple instances of each service type. For example, we could use multiple Redis instances—one for session and one for cache. ```yaml redis: - type: redis:3.0 + type: redis: redis2: - type: redis:3.0 + type: redis: ``` -Be aware, if you rename a service in the `services.yaml` file, the following is **permanently removed**: +Renaming a service in the `services.yaml` file **permanently removes** the following: - The existing service before creating a new service with the new name you specify. - All existing data for the service is removed. We strongly recommend you [snapshot your environment]({{ page.baseurl }}/cloud/project/project-webint-snap.html) before you change the name of an existing service. -### `type` {#cloud-yaml-services-type} +### `type` -The `type` of your service in the format: `type:version` +The `type` value specifies the version of the service. For example: -We support and deploy the following services for you: +```yaml +mysql: + type: mysql:10.2 +``` -- [`mysql`]({{ page.baseurl }}/cloud/project/project-conf-files_services-mysql.html) -- [`redis`]({{ page.baseurl }}/cloud/project/project-conf-files_services-redis.html) -- [`elasticsearch`]({{ page.baseurl }}/cloud/project/project-conf-files_services-elastic.html) -- [`rabbitmq`]({{ page.baseurl }}/cloud/project/project-conf-files_services-rabbit.html) +### `disk` + +The `disk` value specifies the size of the persistent disk storage (in MB) to allocate to the service. Services that use persistent storage, such as MySQL, must provide a disk value. Services that use memory instead of persistent storage, such as Redis, do not require a disk value. + +```yaml +mysql: + type: mysql:10.2 + disk: 2048 +``` + +The current default storage amount per project is 5GB, or 5120MB. You can distribute this amount between your application and each of its services. + +## Service relationships + +{{site.data.var.ece}} uses the [`$MAGENTO_CLOUD_RELATIONSHIPS`]({{page.baseurl}}/cloud/env/environment-vars_cloud.html) environment variable to retrieve environment-related relationships. For services to be available to an application in your project, you must specify [*relationships*]({{ page.baseurl }}/cloud/project/project-conf-files_magento-app.html#relationships) between applications and services in the `.magento.app.yaml` file. + +#### To verify relationships in local environment: + +1. In your local environment, show the relationships for the active environment. + + ```bash + magento-cloud relationships + ``` + +1. Confirm the `service` and `type` from the response. The response provides connection information, such as the IP address and port number. + + **Abbreviated sample response**: + + ```terminal + redis: + - + ... + type: 'redis:3.2' + port: 6379 + elasticsearch: + - + ... + type: 'elasticsearch:6.5' + port: 9200 + database: + - + ... + type: 'mysql:10.0' + port: 3306 + + ``` + {:.no-copy} -### `disk` {#cloud-yaml-services-disk} +#### To verify relationships in remote environments: -Specifies the size of the persistent disk storage (in MB) allocated to the service. +1. Use SSH to log in to the remote environment. -For example, the current default storage amount per project is 5GB, or 5120MB. You can distribute this amount between your application and each of its services. +1. Create `pretty-print` to show all relationships for services and configuration data for that environment. -## Using the services + ```bash + php -r 'print_r(json_decode(base64_decode($_ENV["MAGENTO_CLOUD_RELATIONSHIPS"])));' + ``` -For services to be available to an application in your project, you must specify [*relationships*]({{ page.baseurl }}/cloud/project/project-conf-files_magento-app.html#relationships) between applications and services in the `.magento.app.yaml` file. +1. Confirm the `service` and `type` from the response. The response provides connection information, such as the IP address and port number. diff --git a/guides/v2.3/cloud/project/project-conf-files_services-elastic.md b/guides/v2.3/cloud/project/project-conf-files_services-elastic.md index 356dc96919c..b61861da05e 100644 --- a/guides/v2.3/cloud/project/project-conf-files_services-elastic.md +++ b/guides/v2.3/cloud/project/project-conf-files_services-elastic.md @@ -41,7 +41,7 @@ functional_areas: For information on how these changes affect your environments, see [Services]({{ page.baseurl }}/cloud/project/project-conf-files_services.html). -1. [Verify the relationships](#verify-relationships) and configure Elasticsearch in the Admin UI. +1. [Verify the relationships]({{page.baseurl}}/cloud/project/project-conf-files_services.html#service-relationships) and configure Elasticsearch in the Admin UI. ## Elasticsearch plugins @@ -62,29 +62,5 @@ See [Elasticsearch plugin documentation](https://www.elastic.co/guide/en/elastic {:.bs-callout-info} 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. -## Verify relationships - -{{site.data.var.ece}} uses the [MAGENTO_CLOUD_RELATIONSHIPS]({{ page.baseurl }}/cloud/env/variables-cloud.html) variable to retrieve the environment-related relationships. You must use this information when you [configure Elasticsearch through the Magento Admin]({{page.baseurl}}/config-guide/elasticsearch/configure-magento.html). - -#### To print the connection information for Elasticsearch: - -```bash -php -r 'print_r(json_decode(base64_decode($_ENV["MAGENTO_CLOUD_RELATIONSHIPS"])));' -``` - -The response includes all relationships for services and configuration data for that environment; the Elasticsearch information is similar to the following: - -```terminal -"elasticsearch" : [ - { - "host" : "elasticsearch.internal", - "ip" : "250.0.97.96", - "scheme" : "http", - "port" : "9200" - } - ], -``` -{: .no-copy} - {: .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. \ No newline at end of file