Configurar serviços

Última atualização: 1 de setembro de 2026

Criado para:

Admin
Desenvolvedor

O arquivo services.yaml define os serviços com suporte e usados pelo Adobe Commerce na infraestrutura em nuvem, como MySQL, Redis ou Valkey, Elasticsearch ou OpenSearch. Não é necessário assinar provedores de serviços externos.

NOTE

O arquivo .magento/services.yaml é gerenciado localmente no diretório .magento do seu projeto. Durante a implantação, o Adobe Commerce na infraestrutura em nuvem usa essa configuração para provisionar serviços compatíveis com o ambiente de destino. O diretório .magento é removido do servidor remoto após a implantação, portanto, services.yaml não existe no ambiente implantado.

O script de implantação usa os arquivos de configuração no diretório .magento para provisionar o ambiente com os serviços configurados. Um serviço ficará disponível para o aplicativo se for incluído na propriedade relationships do arquivo .magento.app.yaml. O arquivo services.yaml contém os valores de tipo e disco. O tipo de serviço define o serviço nome e versão.

A configuração do serviço em .magento/services.yaml é separada das dependências do pacote PHP e Composer definidas em composer.json e bloqueadas em composer.lock.

Quando as alterações de serviço se aplicam

Alterar uma configuração de serviço faz com que uma implantação provisione o ambiente com os serviços atualizados, o que afeta os seguintes ambientes:

Todos os ambientes iniciais, incluindo Produção master
Ambientes de integração Pro

Suporte a serviços profissionais

Para solicitar e concluir uma atualização de serviço Pro em Preparo ou Produção, siga estas etapas:

Para instalar ou atualizar os serviços somente nos ambientes Staging e Production, envie um tíquete de Suporte da Adobe Commerce.

No ticket, especifique as alterações de serviço necessárias, inclua os arquivos .magento.app.yaml e .magento/services.yaml atualizados e observe a versão do PHP de destino.

A versão do PHP, as atualizações do Composer, as extensões e as configurações do ambiente são alterações de autoatendimento. O Adobe pode precisar atualizar o agente New Relic para compatibilidade de versão do PHP. Consulte configurações do PHP em Configuração do aplicativo.

note important
IMPORTANT
Ao selecionar o campo Environment no formulário de tíquete, use a nomenclatura de ambiente do Adobe. Por exemplo, selecione Preparo mesmo se você chamar esse ambiente de Desenvolvimento internamente. Você pode mencionar seu nome interno na descrição, mas o campo Environment deve usar a nomenclatura da Adobe.

Confirme o agendamento da atualização por meio do processo de duas partes da Adobe: primeiro você confirma a data e a hora solicitadas e, em seguida, o suporte a envia à equipe de infraestrutura para confirmação final.

As alterações na produção (somente Pro) exigem um aviso de pelo menos dois dias úteis, exceto nos finais de semana. Por exemplo, a equipe de infraestrutura em nuvem deve reconhecer uma atualização de segunda-feira até a quarta-feira anterior. Espere um lead time adicional durante o pico da demanda. Para evitar atrasos, responda à solicitação inicial pelo menos 48 horas antes da janela. A atualização não é considerada programada até que você receba a confirmação final.

note
NOTE
Fornecer janelas de manutenção em UTC. As atualizações de preparo não são agendadas com antecedência e normalmente são concluídas no mesmo dia da solicitação.
Após uma atualização do RabbitMQ, reimplante o ambiente para reinicializar as filas de mensagens.

Valide a atualização em um ambiente de Preparo ou Integração antes de agendá-la na Produção.

Problemas causados por módulos de terceiros, código personalizado ou compatibilidade de dependência geralmente surgem durante a reimplantação que segue uma atualização de serviço. Para validar várias atualizações de serviço, uma ordem razoável é Valkey ou Redis, RabbitMQ, OpenSearch e MariaDB. Esta não é uma sequência obrigatória. Os upgrades de bancos de dados têm o maior impacto operacional e merecem a maior cautela.

A Adobe não garante a duração exata de uma janela de manutenção de Produção com antecedência, pois o tempo depende do ambiente e dos serviços envolvidos. Use o tempo que leva a atualização em preparo como uma estimativa prática ao planejar a janela Produção.
Reimplante o ambiente depois que o Adobe concluir a atualização do serviço para que a alteração entre em vigor, mesmo que a versão do aplicativo Adobe Commerce não seja alterada.

Se a atualização incluir o OpenSearch, também planeje uma reindexação completa. A Adobe não pode garantir tempo de inatividade zero para uma atualização de serviço. Portanto, planeje uma janela de manutenção que permita tempo para reimplantar, reindexar, se necessário, e validar a loja e o administrador antes de reabrir o site.

Disponibilidade do cliente durante atualizações

Um representante de sua equipe ou parceiro de implementação deve estar disponível online durante a janela de atualização de Produção agendada. O agendamento durante um período de tráfego baixo não tira as mãos da atualização. O Adobe gerencia a atualização da infraestrutura em nuvem, mas não pode validar o comportamento do aplicativo, as integrações, o código personalizado ou os fluxos de trabalho de negócios.

O representante disponível deve poder:

Monitorar a loja e as transações comerciais críticas durante e após a atualização.
Responda às perguntas do Suporte da Adobe ou da equipe de Infraestrutura em Nuvem.
Confirme se as integrações, extensões, personalizações, trabalhos cron, filas e outras funções específicas do cliente estão funcionando conforme o esperado.
Validar fluxos de trabalho críticos para os negócios, como check-out, exibições de catálogo, pesquisa, logon e processamento de pedido.
Relatar comportamento inesperado prontamente, enquanto o contexto de atualização e os logs ainda estão disponíveis.

TIP

Para projetos Pro, as atualizações de serviço na produção também exigem programação antecipada e um processo de confirmação em duas partes com o suporte da Adobe. Consulte Suporte a serviços profissionais.

Modo de manutenção

O modo de manutenção não substitui a disponibilidade do cliente. O modo de manutenção bloqueia o acesso da loja, mas não valida serviços de aplicativos, integrações, filas, trabalhos cron, check-out ou outras funções específicas do cliente.

Se o trabalho planejado exigir o modo de manutenção, coordene o uso com o Suporte da Adobe e siga as instruções para essa atualização. Depois, confirme se a loja e os workflows críticos estão funcionando normalmente antes de considerar o trabalho como concluído.

Serviços padrão e compatíveis

A infraestrutura do Adobe Commerce na nuvem é compatível com os seguintes serviços, que podem ser configurados para o seu projeto:

NOTE

Atualizar RabbitMQ sequencialmente entre as versões disponíveis. Por exemplo, não atualize da 3.9 diretamente para a 4.1.

Para garantir que suas filas de mensagens personalizadas sejam recriadas no RabbitMQ depois da atualização para uma nova versão, acione uma implantação completa.

Exibir versões e serviços configurados

Você pode exibir exemplos de definições de serviço e valores de disco no arquivo de modelo atual services.yaml . As versões padrão e compatíveis do serviço dependem da versão do Adobe Commerce e do modelo de nuvem atual.

O exemplo a seguir mostra definições de serviço no arquivo de configuração services.yaml:

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

Valores de serviço

Forneça a ID de serviço e a configuração de tipo de serviço type: <name>:<version>. Se o serviço usar armazenamento persistente, você deverá fornecer um valor de disco.

Usar o seguinte formato:

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

`service-id`

O valor service-id identifica o serviço no projeto. Você só pode usar caracteres alfanuméricos minúsculos: a a z e 0 a 9, como valkey.

O valor service-id é usado na propriedade relationships do arquivo de configuração .magento.app.yaml:

relationships:
    valkey: "valkey:valkey"

Você pode nomear várias instâncias de cada tipo de serviço. Por exemplo, você pode usar várias instâncias Valkey, uma para sessão e outra para cache.

valkey:
    type: valkey:<version>

valkey2:
    type: valkey:<version>

Renomeando um serviço no arquivo services.yaml:

O serviço existente antes de criar um serviço com o novo nome especificado.
Todos os dados existentes para o serviço são removidos. A Adobe recomenda que você faça backup do ambiente de Início antes de alterar o nome de um serviço existente.

`type`

O valor type especifica o nome e a versão do serviço. Por exemplo:

mysql:
    type: mysql:10.4

`disk`

O valor disk especifica o tamanho do armazenamento de disco persistente (em MB) a ser alocado para o serviço. Os serviços que usam armazenamento persistente, como o MySQL, devem fornecer um valor de disco. Os serviços que usam memória em vez de armazenamento persistente, como Valkey, não exigem um valor de disco.

mysql:
    type: mysql:10.4
    disk: 5120

A quantidade de armazenamento padrão atual por projeto é de 5 GB ou 5120 MB. Você pode distribuir essa quantidade entre seu aplicativo e cada um de seus serviços.

Relacionamentos de serviço

Em projetos de infraestrutura na nuvem do Adobe Commerce, as relações do serviço configuradas no arquivo .magento.app.yaml determinam quais serviços estão disponíveis para o seu aplicativo.

Você pode recuperar os dados de configuração de todas as relações de serviço da variável de ambiente $MAGENTO_CLOUD_RELATIONSHIPS. Os dados de configuração incluem o nome, o tipo e a versão do serviço, juntamente com todos os detalhes de conexão necessários, como o número da porta e as credenciais de logon.

Verificar relações do ambiente de desenvolvimento local

No ambiente de desenvolvimento local, mostre as relações do ambiente ativo.

code language-bash
`magento-cloud relationships`

Confirme os service e type da resposta. A resposta fornece informações de conexão, como endereço IP e número da porta.

Resposta de amostra abreviada

code language-yaml
`valkey: - ... type: 'valkey:8.0' port: 6379 opensearch: - ... type: 'opensearch:3' port: 9200 database: - ... type: 'mysql:11.8' port: 3306`

Verificar relações em ambientes remotos

Use o SSH para fazer logon no ambiente remoto.

Listar os dados de configuração de relacionamentos para todos os serviços configurados no ambiente.

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

ou use o seguinte comando ece-tools para exibir relações:

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

Confirme os service e type da resposta. A resposta fornece informações de conexão, como endereço IP, número da porta e credenciais de nome de usuário e senha necessárias.

Versões de serviço

As versões implantadas e testadas na infraestrutura em nuvem determinam a versão do serviço e o suporte à compatibilidade do Adobe Commerce na infraestrutura em nuvem, que às vezes diferem das versões compatíveis com implantações locais do Adobe Commerce. Consulte Requisitos do sistema no guia Instalação para obter uma lista de dependências de software de terceiros que a Adobe testou com versões específicas do Adobe Commerce e do Magento Open Source.

Verificações de EOL de software

Durante o processo de implantação, o pacote ece-tools verifica as versões de serviço instaladas em relação às datas de fim da vida útil (EOL) de cada serviço.

Se uma versão do serviço estiver dentro de três meses da data EOL, uma notificação será exibida no log de implantação.
Se a data EOL estiver no passado, uma notificação de aviso será exibida.

Para manter a segurança da loja, atualize as versões de software instaladas antes que elas atinjam o fim da vida útil. Você pode examinar as datas de fim de vida útil no arquivo de eol.yaml das ferramentas ece.

Migrar para o OpenSearch

WARNING

O Elasticsearch 7 e posterior não é compatível com o Adobe Commerce na infraestrutura em nuvem. O Adobe Commerce 2.4.4 e posterior é compatível com o serviço OpenSearch.

Para o Adobe Commerce versão 2.4.4 e posterior, consulte Configurar o serviço OpenSearch.

Alterar versão do serviço

É possível atualizar a versão do serviço instalada para compatibilidade com a versão do Adobe Commerce implantada no ambiente de nuvem.

Não é possível fazer o downgrade da versão de serviço de um serviço instalado diretamente. No entanto, é possível criar um serviço com a versão necessária. Consulte Rebaixar versão de serviço.

Atualizar versão do serviço instalado

Você pode atualizar a versão do serviço instalado atualizando a configuração do serviço no arquivo services.yaml.

Alterar o valor type do serviço no arquivo .magento/services.yaml:

Definição do serviço original

code language-yaml
`mysql: type: mysql:11.8 disk: 2048`

Definição de serviço atualizada

code language-yaml
`mysql: type: mysql:12.3 disk: 5120`

Adicionar, confirmar e enviar por push as alterações de código.

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>`

Versão de downgrade

Não é possível fazer o downgrade de um serviço instalado diretamente. Você tem duas opções:

Renomeie um serviço existente com a nova versão, que remove o serviço e os dados existentes, e adiciona um novo.
Crie um serviço e salve os dados do serviço existente.

Ao alterar a versão do serviço, você deve atualizar a configuração do serviço no arquivo services.yaml e atualizar as relações no arquivo .magento.app.yaml.

Fazer downgrade de uma versão de serviço renomeando um serviço existente

Renomeie o serviço existente no arquivo .magento/services.yaml e altere a versão.

note warning
WARNING
A renomeação de um serviço existente o substitui e exclui todos os dados. Se precisar manter os dados, crie um serviço em vez de renomear o existente.

Por exemplo, para baixar a versão do MariaDB para o serviço mysql da versão 10.4 para 10.3, altere a configuração existente do service-id e do type.

Definição original de services.yaml

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

Nova definição services.yaml

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

Atualizar as relações no arquivo .magento.app.yaml.

Configuração original de .magento.app.yaml

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

Atualização da configuração .magento.app.yaml

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

Adicionar, confirmar e enviar por push as alterações de código.

Fazer downgrade de um serviço criando um serviço

Adicione uma definição de serviço ao arquivo services.yaml para seu projeto com a especificação de versão rebaixada. Consulte mysql2 no seguinte exemplo:

services.yaml

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

Para usar o novo serviço, altere a configuração de relações no arquivo .magento.app.yaml.

Configuração original de .magento.app.yaml

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

Nova configuração .magento.app.yaml

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

Adicionar, confirmar e enviar por push as alterações de código.

recommendation-more-help

commerce-on-cloud-help-cloud-guide