DocumentationCommerceCommerce on Cloud Infrastructure Guide

Configure services

Last update: Thu Sep 19 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Admin
  • Developer

The services.yaml file defines the services supported and used by Adobe Commerce on cloud infrastructure, such as MySQL, Redis, and Elasticsearch or OpenSearch. You do not need to subscribe to external service providers.

NOTE
The .magento/services.yaml file is managed locally in the .magento directory of your project. The configuration is accessed during the build process for defining the required service versions in the integration environment only, and gets removed once the deployment has been completed, so you will not find them on the server.

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 type and disk values. Service type defines the service name and version.

Changing a service configuration causes a deployment to provision the environment with the updated services, which affects the following environments:

  • All Starter environments including Production master
  • Pro integration environments
TIP
For Pro projects, you must submit an Adobe Commerce Support ticket to install or update services in Staging and Production environments only.
Indicate the service changes needed, include your updated .magento.app.yaml and services.yaml files, and state the PHP version in the ticket. For self-service changes to PHP version, extensions, or environment settings, see PHP settings in Application configuration.
For changes to a live Production environment (Pro only), a minimum of 48 hours notice is required. This allows the Cloud infrastructure team sufficient time to marshal resources and conduct a secure upgrade. The notice period begins when the Infrastructure team acknowledges the request and schedules the upgrade, excluding weekends. For example, to have service upgrades completed on a Monday, an acknowledgement of the scheduled upgrade must be received by Wednesday. During peak demand periods, it might take more time to process your request.

Default and supported services

The cloud infrastructure supports and deploys the following services:

You can view default versions and disk values in the current, default services.yaml file. The following sample shows the mysql, redis, opensearch or elasticsearch, and rabbitmq services defined in the services.yaml configuration file:

mysql:
    type: mysql:10.4
    disk: 5120

redis:
    type: redis:6.2

opensearch:
    type: opensearch:2  # minor version not required; uses latest
    disk: 1024

rabbitmq:
    type: rabbitmq:3.9
    disk: 1024

Service values

You must provide the service ID and service type configuration type: <name>:<version>. If the service uses persistent storage, then you must provide a disk value.

Use the following format:

<service-id>:
    type: <name>:<version>
    disk: <value-MB>

service-id

The service-id value identifies the service in the project. You can only use lowercase alphanumeric characters: a to z and 0 to 9, such as redis.

This service-id value is used in the relationships property of the .magento.app.yaml configuration file:

relationships:
    redis: "<name>:redis"

You can name multiple instances of each service type. For example, you could use multiple Redis instances—one for session and one for cache.

redis:
    type: redis:<version>

redis2:
    type: redis:<version>

Renaming a service in the services.yaml file permanently removes the following:

  • The existing service before creating a service with the new name you specify.
  • All existing data for the service is removed. Adobe strongly recommends that you backup your Starter environment before you change the name of an existing service.

type

The type value specifies the service name and version. For example:

mysql:
    type: mysql:10.4

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.

mysql:
    type: mysql:10.4
    disk: 5120

The current default storage amount per project is 5 GB, or 512 0MB. You can distribute this amount between your application and each of its services.

Service relationships

In Adobe Commerce on cloud infrastructure projects, service relationships configured in the .magento.app.yaml file determine which services are available to your application.

You can retrieve the configuration data for all service relationships from the $MAGENTO_CLOUD_RELATIONSHIPS environment variable. The configuration data includes service name, type, and version along with any required connection details such as port number and login credentials.

To verify relationships in local environment:

  1. In your local environment, show the relationships for the active environment.

    code language-bash 
    magento-cloud relationships

  2. Confirm the service and type from the response. The response provides connection information, such as the IP address and port number.

    Abbreviated sample response

    code language-yaml 
    redis:
    -
...
        type: 'redis:7.0'
        port: 6379
elasticsearch:
    -
...
        type: 'opensearch:2'
        port: 9200
database:
    -
...
        type: 'mysql:10.6'
        port: 3306

To verify relationships in remote environments:

  1. Use SSH to log in to the remote environment.

  2. List the relationships configuration data for all services configured in the environment.

    code language-bash 
    echo $MAGENTO_CLOUD_RELATIONSHIPS | base64 -d | json_pp

    or, use the following ece-tools command to view relationships:

    code language-bash 
    php ./vendor/bin/ece-tools env:config:show services

  3. Confirm the service and type from the response. The response provides connection information, such as the IP address and port number and any required username and password credentials.

Service versions

Service version and compatibility support for Adobe Commerce on cloud infrastructure is determined by versions deployed and tested on the Cloud infrastructure, and sometimes differ from versions supported by Adobe Commerce on-premises deployments. See System requirements in the Installation guide for a list of third-party software dependencies that Adobe has tested with specific Adobe Commerce and Magento Open Source releases.

Software EOL checks

During the deployment process, the ece-tools package checks installed service versions against the end-of-life (EOL) dates for each service.

  • If a service version is within three months of the EOL date, a notification displays in the deploy log.
  • If the EOL date is in the past, a warning notification displays.

To maintain store security, update installed software versions before they reach EOL. You can review the EOL dates in the ece-tools’ eol.yaml file.

Migrate to OpenSearch

WARNING
Elasticsearch 7.11 and later is not supported for Adobe Commerce on cloud infrastructure. Adobe Commerce versions 2.3.7-p3, 2.4.3-p2, and 2.4.4 and later support the OpenSearch service. The on-premises installations continue to support Elasticsearch.

For Adobe Commerce version 2.4.4 and later, see Set up OpenSearch service.

Change service version

You can upgrade the installed service version for compatibility with the Adobe Commerce version deployed in your Cloud environment.

You cannot downgrade the service version for an installed service directly. However, you can create a service with the required version. See Downgrade service version.

Upgrade installed service version

You can upgrade the installed service version by updating the service configuration in the services.yaml file.

  1. Change the type value for the service in the .magento/services.yaml file:

    Original service definition

    code language-yaml 
    mysql:
    type: mysql:10.3
    disk: 2048

    Updated service definition

    code language-yaml 
    mysql:
    type: mysql:10.4
    disk: 5120

  2. Add, commit, and push your code changes.

    code language-bash 
    git add .magento/services.yaml
    code language-bash 
    git commit -m "Upgrade MySQL from MariaDB 10.3 to 10.4."
    code language-bash 
    git push origin <branch-name>

Downgrade version

You cannot downgrade an installed service directly. You have two options:

  1. Rename an existing service with the new version, which removes the existing service and data, and adds a new one.

  2. Create a service and save the data from the existing service.

When you change the service version, you must update the service configuration in the services.yaml file, and update the relationships in the .magento.app.yaml file.

To downgrade a service version by renaming an existing service:

  1. Rename the existing service in the .magento/services.yaml file and change the version.

    note warning
    WARNING
    Renaming an existing service replaces it and deletes all data. If you need to retain the data, create a service instead of renaming the existing one.

    For example, to downgrade the MariaDB version for the mysql service from version 10.4 to 10.3, change the existing service-id and type configuration.

    Original services.yaml definition

    code language-yaml 
    mysql:
    type: mysql:10.4
    disk: 5120

    New services.yaml definition

    code language-yaml 
    mysql2:
     type: mysql:10.3
     disk: 5120

  2. Update the relationships in the .magento.app.yaml file.

    Original .magento.app.yaml configuration

    code language-yaml 
    relationships:
    database: "mysql:mysql"

    Updated .magento.app.yaml configuration

    code language-yaml 
    relationships:
    database: "mysql2:mysql"

  3. Add, commit, and push your code changes.

To downgrade a service by creating a service:

  1. Add a service definition to the services.yaml file for your project with the downgraded version specification. See mysql2 in the following example:

    services.yaml

    code language-yaml 
    mysql:
    type: mysql:10.4
    disk: 5120
mysql2:
    type: mysql:10.3
    disk: 5120

  2. Change the relationships configuration in the .magento.app.yaml file to use the new service.

    Original .magento.app.yaml configuration

    code language-yaml 
    relationships:
    database: "mysql:mysql"

    New .magento.app.yaml configuration

    code language-yaml 
    relationships:
    database: "mysql2:mysql"

  3. Add, commit, and push your code changes.

recommendation-more-help
05f2f56e-ac5d-4931-8cdb-764e60e16f26