Configurar o serviço Valkey

Valkey é uma solução de cache de back-end opcional para o Adobe Commerce na infraestrutura em nuvem. O Valkey é necessário ao substituir a configuração de cache padrão no Adobe Commerce 2.4.9 e posterior, ou em versões de patch posteriores a 2.4.5-p16, 2.4.6-p14, 2.4.7-p9 e 2.4.8-p4.

Use as instruções a seguir para a configuração do serviço em ambientes Pro Integration e Starter, incluindo a ramificação master.

Configurar Valkey

Para substituir Redis por Valkey, atualize os seguintes arquivos:

Configurar o serviço

Em .magento/services.yaml, substitua a definição do serviço Redis por uma definição de serviço Valkey. Substitua <version> por uma versão do Valkey com suporte pela sua versão do Adobe Commerce e pelo modelo atual do Cloud.

cache:
  type: valkey:<version>

Exemplo

cache:
  type: valkey:8.0

A versão de exemplo não é universal. As versões padrão e compatíveis do serviço dependem da versão do Adobe Commerce e do modelo atual da Cloud. Use a versão especificada pelo modelo de projeto atual. Consulte Configurar serviços para obter mais informações.

Não presuma que os dados de cache e sessão persistem quando você altera o valor type de redis:<version> para valkey:<version>, mesmo quando mantém a mesma ID de serviço. Trate a migração como a criação de um novo cache: não há garantia de preservação dos dados existentes do cache e da sessão, e os usuários são desconectados após a conclusão da migração.

Configurar o relacionamento de serviço

Em .magento.app.yaml, configure a relação entre o aplicativo e o serviço Valkey:

relationships:
  valkey: "cache:valkey"

A chave de relação valkey é o nome usado pelo aplicativo para acessar o serviço. O valor cache:valkey faz referência à ID de serviço e ao tipo de serviço definidos em .magento/services.yaml.

runtime:
      extensions:
          - redis

Confirmar e implantar as alterações

Adicionar, confirmar e enviar as alterações de configuração:

git add .magento/services.yaml .magento.app.yaml
git commit -m "Enable Valkey service"
git push origin <branch-name>

Depois que a implantação for concluída, verifique se o relacionamento de serviço da Valkey está disponível.

Personalizar a configuração do Valkey

Para obter recomendações de cache, sessão, L2 e conexão de réplica, consulte Práticas recomendadas para a configuração do serviço Valkey e Redis no Guia de Práticas Recomendadas do Manual de Implementação.

Verificar o relacionamento de serviço

Para exibir o objeto MAGENTO_CLOUD_RELATIONSHIPS decodificado, execute o seguinte comando em um contêiner de aplicativo após implantar a configuração:

Use o SSH para se conectar ao ambiente de nuvem remoto e execute:

echo "$MAGENTO_CLOUD_RELATIONSHIPS" | base64 -d | json_pp

O comando exibe todos os relacionamentos de serviço configurados. Para identificar os detalhes da conexão Valkey, localize a relação valkey.

Exemplo de saída

O exemplo abreviado a seguir mostra a relação valkey. Não é um esquema universal.

{
   "database" : [
      {
         "host" : "database.internal",
         "port" : 3306,
         "path" : "main",
         "scheme" : "mysql"
      }
   ],
   "opensearch" : [
      {
         "host" : "opensearch.internal",
         "port" : 9200,
         "path" : null,
         "scheme" : "http"
      }
   ],
   "valkey" : [
      {
         "host" : "valkey.internal",
         "port" : 6379,
         "path" : null,
         "scheme" : "valkey"
      }
   ]
}

A saída varia de acordo com a configuração do ambiente e do serviço. Não codifique nomes de host, portas, endereços IP, nomes de cluster, versões de serviço, nomes de usuário ou senhas deste exemplo. Use os valores retornados por MAGENTO_CLOUD_RELATIONSHIPS no ambiente de destino.

Se jq estiver disponível, exibir somente a relação Valkey:

printf '%s' "$MAGENTO_CLOUD_RELATIONSHIPS" \
  | base64 -d \
  | jq '{valkey: .valkey}'

Para obter mais informações sobre relações de serviço, consulte Configurar serviços.

Uso da CLI do Valkey

Supondo que sua relação com Valkey tenha o nome valkey, use o host e a porta retornados por MAGENTO_CLOUD_RELATIONSHIPS para se conectar ao Valkey:

valkey-cli -h <host> -p <port>

Exemplo

valkey-cli -h valkey.internal -p 6379

Obter a versão instalada do Valkey

valkey-cli -h <host> -p <port> info | grep version

valkey_version:<installed-version>
gcc_version:<gcc-version>

valkey-server -v

Valkey server v=<installed-version> ...

Solução de problemas do Valkey

Erros de limpeza de cache fazem referência a Redis em um cache configurado pelo Valkey

Uma falha na limpeza do cache de pré-implantação pode exibir o código de erro [107] (clean-redis-cache) e uma mensagem Connection to Redis mesmo quando o serviço cache está configurado como Valkey. ece-tools usa este código de erro e mensagem para a etapa de limpeza de cache, independentemente de o serviço de cache de backup ser Redis ou Valkey.

Se o erro subjacente for uma falha de DNS, como Name or service not known, para o host de relação, a etapa de implantação foi executada antes de a relação de serviço estar disponível, ou o nome da relação em .magento.app.yaml não corresponde à ID de serviço em .magento/services.yaml. Consulte Verificar a relação de serviço.