Configure services
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. This file is in the .magento
directory of your project.
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
For Pro projects, you must create a Support ticket to install or update services in Staging and Production environments. Indicate the service changes needed and include your updated .magento.app.yaml
and services.yaml
files and PHP version in the ticket. It can take up to 48 hours for the Cloud infrastructure team to update your project.
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:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
mysql:
type: mysql:10.4
disk: 5120
redis:
type: redis:6.2
opensearch:
type: opensearch:1.2
disk: 1024
rabbitmq:
type: rabbitmq:3.9
disk: 1024
Service values
You must provide the
Use the following format:
1
2
3
<service-id>:
type: <name>:<version>
disk: <value-MB>
service-id
The service-id
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
.
This service-id value is used in the relationships
property of the .magento.app.yaml
configuration file:
1
2
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.
1
2
3
4
5
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 snapshot your environment before you change the name of an existing service.
type
The type
value specifies the service name and version. For example:
1
2
mysql:
type: mysql:10.3
Use Service versions
table to see supported services and their versions
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.
1
2
3
mysql:
type: mysql:10.3
disk: 5120
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
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:
-
In your local environment, show the relationships for the active environment.
1
magento-cloud relationships
-
Confirm the
service
andtype
from the response. The response provides connection information, such as the IP address and port number.Abbreviated sample response:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
redis: - ... type: 'redis:5.0' port: 6379 elasticsearch: - ... type: 'elasticsearch:7.7' port: 9200 database: - ... type: 'mysql:10.3' port: 3306
To verify relationships in remote environments:
-
Use SSH to log in to the remote environment.
-
List the relationships configuration data for all services configured in the environment.
1
echo $MAGENTO_CLOUD_RELATIONSHIPS | base64 -d | json_pp
or, use the following ece-tools CLI command to view relationships:
1
php ./vendor/bin/ece-tools env:config:show services
-
Confirm the
service
andtype
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
Version support and compatibility for Adobe Commerce on cloud infrastructure is determined by service versions deployed on the Cloud infrastructure, and in rare cases may differ from the versions supported by Adobe Commerce on-premises deployments. See System requirements in the Installation guide for recommended versions.
Software EOL checks
During the deployment process, ece-tools
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
Elasticsearch 7.11 and later is not supported for Adobe Commerce on cloud infrastructure. Adobe Commerce and Magento Open Source versions 2.4.4, 2.4.3-p2, and 2.3.7-p3 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.
-
Change the
type
value for the service in the.magento/services.yaml
file:Original service definition
1 2 3
mysql: type: mysql:10.2 disk: 2048
Updated service definition
1 2 3
mysql: type: mysql:10.3 disk: 5120
-
Add, commit, and push your code changes.
1
git add -A
1
git commit -m "Upgrade MySQL from MariaDB 10.2 to 10.3."
1
git push origin <branch-name>
Downgrade version
You cannot downgrade an installed service directly. You have two options:
-
Rename an existing service with the new version, which removes the existing service and data, and adds a new one.
-
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:
-
Rename the existing service in the
.magento/services.yaml
file and change the version.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.3 to 10.2, change the existing service-id and type configuration.
Original
services.yaml
definition1 2 3
mysql: type: mysql:10.4 disk: 5120
New
services.yaml
definition1 2 3
mysql2: type: mysql:10.3 disk: 5120
-
Update the relationships in the
.magento.app.yaml
file.Original
.magento.app.yaml
configuration1 2
relationships: database: "mysql:mysql"
Updated
.magento.app.yaml
configuration1 2
relationships: database: "mysql2:mysql"
-
Add, commit, and push your code changes.
To downgrade a service by creating an additional service:
-
Add an additional service definition to the
services.yaml
file for your project with the downgraded version specification. See mysql2 in the following example:services.yaml
1 2 3 4 5 6
mysql: type: mysql:10.4 disk: 5120 mysql2: type: mysql:10.3 disk: 5120
-
Change the relationships configuration in the
.magento.app.yaml
file to use the new service.Original
.magento.app.yaml
configuration1 2
relationships: database: "mysql:mysql"
New
.magento.app.yaml
configuration1 2
relationships: database: "mysql2:mysql"
-
Add, commit, and push your code changes.