DocumentationCommerceCommerce on Cloud

Configure services

Last update: September 1, 2026

CREATED FOR:

  • Admin
  • Developer

The services.yaml file defines the services supported and used by Adobe Commerce on cloud infrastructure, such as MySQL, Redis or Valkey, 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. During deployment, Adobe Commerce on cloud infrastructure uses this configuration to provision supported services for the target environment. The .magento directory is removed from the remote server after deployment, so services.yaml does not exist on the deployed environment.

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.

Service configuration in .magento/services.yaml is separate from PHP and Composer package dependencies defined in composer.json and locked in composer.lock.

Where service changes apply

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

Pro services support

To request and complete a Pro service upgrade in Staging or Production, follow these steps:

  1. To install or update services in Staging and Production environments only, submit an Adobe Commerce Support ticket.

    In the ticket, specify the required service changes, include the updated .magento.app.yaml and .magento/services.yaml files and note the target PHP version.

    PHP version, Composer updates, extensions, and environment settings are self-service changes. Adobe may need to update the New Relic agent for PHP version compatibility. See PHP settings in Application configuration.

    note important
    IMPORTANT
    When selecting the Environment field in the ticket form, use Adobe’s environment naming. For example, select Staging even if you call that environment Dev internally. You can mention your internal name in the description, but the Environment field must use Adobe’s nomenclature.

  2. Confirm the upgrade schedule through Adobe’s two-part process: you confirm the requested date and time first, then Support submits it to the Infrastructure team for final confirmation.

    Production changes (Pro only) require at least two business days’ notice, excluding weekends. For example, the Cloud Infrastructure team must acknowledge a Monday upgrade by the preceding Wednesday. Expect additional lead time during peak demand. To avoid delays, respond to the initial request at least 48 hours before the window. The upgrade is not considered scheduled until you receive final confirmation.

    note
    NOTE
    Provide maintenance windows in UTC. Staging upgrades are not scheduled in advance and are typically completed the same day as the request.
    After a RabbitMQ upgrade, redeploy the environment to re-initialize the message queues.

  3. Validate the upgrade in a Staging or Integration environment before scheduling it in Production.

    Issues caused by third-party modules, custom code, or dependency compatibility often surface during the redeployment that follows a service upgrade. To validate multiple service upgrades one at a time, a reasonable order is Valkey or Redis, then RabbitMQ, then OpenSearch, then MariaDB. This is not a required sequence. Database upgrades carry the highest operational impact and deserve the most caution.

    Adobe does not guarantee the exact duration of a Production maintenance window in advance, since timing depends on the environment and the services involved. Use the time your Staging upgrade takes as a practical estimate when planning the Production window.

  4. Redeploy the environment after Adobe completes the service upgrade so the change takes effect, even if the Adobe Commerce application version does not change.

    If the upgrade includes OpenSearch, also plan for a full reindex. Adobe cannot guarantee zero downtime for a service upgrade, so plan a maintenance window that allows time to redeploy, reindex if needed, and validate the storefront and Admin before reopening the site.

Customer availability during upgrades

A representative from your team or implementation partner must be available online for the duration of the scheduled Production upgrade window. Scheduling during a low-traffic period does not make the upgrade hands-off. Adobe manages the cloud infrastructure upgrade but cannot validate your application behavior, integrations, custom code, or business workflows.

The available representative must be able to:

  • Monitor the storefront and critical business transactions during and after the upgrade.
  • Respond to questions from Adobe Support or the Cloud Infrastructure team.
  • Confirm that integrations, extensions, customizations, cron jobs, queues, and other customer-specific functions are working as expected.
  • Validate business-critical workflows, such as checkout, catalog views, search, login, and order processing.
  • Report unexpected behavior promptly, while the upgrade context and logs are still available.
TIP
For Pro projects, service upgrades in Production also require advance scheduling and a two-part confirmation process with Adobe Support. See Pro services support.

Maintenance mode

Maintenance mode is not a substitute for customer availability. Maintenance mode blocks storefront access, but does not validate application services, integrations, queues, cron jobs, checkout, or other customer-specific functions.

If the planned work requires maintenance mode, coordinate its use with Adobe Support and follow the instructions for that upgrade. Afterward, confirm that the storefront and critical workflows are operating normally before considering the work complete.

Default and supported services

Adobe Commerce on cloud infrastructure supports the following services, which can be configured for your project:

NOTE
Upgrade RabbitMQ sequentially between available versions. For example, do not upgrade from 3.9 directly to 4.1.
To ensure that your custom message queues are recreated in RabbitMQ after upgrading to a new version, trigger a full deployment.

View configured services and versions

You can view example service definitions and disk values in the current template services.yaml file. Actual default and supported service versions depend on your Adobe Commerce version and current cloud template.

The following example shows service definitions in the services.yaml configuration file:

mysql:
    type: mysql:11.8
    disk: 5120

cache:
    type: valkey:9.0

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

rabbitmq:
    type: rabbitmq:4.3
    disk: 1024

activemq-artemis:
    type: activemq-artemis:2.42
    disk: 1024

Service values

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 valkey.

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

relationships:
    valkey: "valkey:valkey"

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

valkey:
    type: valkey:<version>

valkey2:
    type: valkey:<version>

Renaming a service in the services.yaml file:

  • The existing service before creating a service with the new name you specify.
  • All existing data for the service is removed. Adobe 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 Valkey, do not require a disk value.

mysql:
    type: mysql:10.4
    disk: 5120

The current default storage amount per project is 5 GB, or 5120 MB. 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.

Verify relationships from your local development environment

  1. From your local development 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 
    valkey:
    -
...
        type: 'valkey:8.0'
        port: 6379
opensearch:
    -
...
        type: 'opensearch:3'
        port: 9200
database:
    -
...
        type: 'mysql:11.8'
        port: 3306

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, port number, and required username and password credentials.

Service versions

Versions deployed and tested on the Cloud infrastructure determine service version and compatibility support for Adobe Commerce on cloud infrastructure, which 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 and later is not supported for Adobe Commerce on cloud infrastructure. Adobe Commerce 2.4.4 and later supports the OpenSearch service.

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:11.8
    disk: 2048

    Updated service definition

    code language-yaml 
    mysql:
    type: mysql:12.3
    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 11.8 to 12.3."
    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.

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.

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. To use the new service, change the relationships configuration in the .magento.app.yaml file.

    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
commerce-on-cloud-help-cloud-guide