Configuration du service Valkey

Valkey est une solution de cache back-end facultative pour Adobe Commerce sur les infrastructures cloud. Valkey est requis lorsque vous remplacez la configuration de cache par défaut sur Adobe Commerce 2.4.9 et versions ultérieures, ou sur les versions de correctif ultérieures à 2.4.5-p16, 2.4.6-p14, 2.4.7-p9 et 2.4.8-p4.

Utilisez les instructions suivantes pour la configuration du service sur les environnements Pro Integration et les environnements de démarrage, y compris la branche master.

Configurer Valkey

Pour remplacer Redis par Valkey, mettez à jour les fichiers suivants :

Configuration du service

Dans .magento/services.yaml, remplacez la définition de service Redis par une définition de service Valkey. Remplacez <version> par une version Valkey prise en charge par votre version d’Adobe Commerce et votre modèle cloud actuel.

cache:
  type: valkey:<version>

Exemple

cache:
  type: valkey:8.0

La version d’exemple n’est pas universelle. Les versions de service par défaut et prises en charge dépendent de votre version d’Adobe Commerce et du modèle de cloud actuel. Utiliser la version spécifiée par le modèle de projet actuel. Voir Configuration des services pour plus d’informations.

Ne supposez pas que les données du cache et de la session persistent lorsque vous modifiez la valeur de type de redis:<version> en valkey:<version>, même si vous conservez le même ID de service. Traiter la migration comme créant un nouveau cache : la conservation des données existantes du cache et de la session n’est pas garantie, et les utilisateurs sont déconnectés une fois la migration terminée.

Configurer la relation de service

Dans .magento.app.yaml, configurez la relation entre l’application et le service Valkey :

relationships:
  valkey: "cache:valkey"

La clé de relation, valkey, est le nom utilisé par l’application pour accéder au service. La valeur, cache:valkey, fait référence à l’ID de service et au type de service définis dans .magento/services.yaml.

runtime:
      extensions:
          - redis

Validez et déployez les modifications

Ajoutez, validez et transmettez les modifications de configuration :

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

Une fois le déploiement terminé, vérifiez que la relation de service Valkey est disponible.

Personnalisation de la configuration Valkey

Pour les recommandations relatives au cache, à la session, à L2 et à la connexion de réplica, consultez Bonnes pratiques pour la configuration de service Valkey et Redis dans le Guide des bonnes pratiques du playbook d’implémentation.

Vérifier la relation de service

Pour afficher l’objet MAGENTO_CLOUD_RELATIONSHIPS décodé, exécutez la commande suivante à partir d’un conteneur d’applications après le déploiement de la configuration :

Utilisez SSH pour vous connecter à l’environnement cloud distant, puis exécutez :

echo "$MAGENTO_CLOUD_RELATIONSHIPS" | base64 -d | json_pp

La commande affiche toutes les relations de service configurées. Pour identifier les détails de la connexion Valkey, recherchez la relation Valkey.

Exemple de sortie

L’exemple abrégé suivant illustre la relation valkey. Ce n’est pas un schéma universel.

{
   "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"
      }
   ]
}

La sortie varie en fonction de la configuration de l’environnement et du service. Ne codez pas en dur les noms d’hôtes, les ports, les adresses IP, les noms de cluster, les versions de service, les noms d’utilisateur ou les mots de passe à partir de cet exemple. Utilisez les valeurs renvoyées par MAGENTO_CLOUD_RELATIONSHIPS dans l’environnement cible.

Si jq est disponible, afficher uniquement la relation Valkey :

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

Pour plus d’informations sur les relations de service, voir Configuration des services.

Utilisation de l’interface de ligne de commande Valkey

En supposant que votre relation Valkey soit nommée valkey, utilisez l’hôte et le port renvoyés par MAGENTO_CLOUD_RELATIONSHIPS pour vous connecter à Valkey :

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

Exemple

valkey-cli -h valkey.internal -p 6379

Obtenir la version de Valkey installée

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

Résolution des problèmes liés à Valkey

Les erreurs de nettoyage du cache référencent Redis sur un cache configuré par Valkey

Un échec de nettoyage du cache avant déploiement peut afficher le [107] de code d’erreur (clean-redis-cache) et un message d’Connection to Redis, même lorsque le service cache est configuré comme Valkey. ece-tools utilise ce code d’erreur et ce message pour l’étape de nettoyage du cache, que le service de cache de sauvegarde soit Redis ou Valkey.

Si l’erreur sous-jacente est un échec du DNS, par exemple Name or service not known pour l’hôte de relation, l’étape de déploiement s’est exécutée avant que la relation de service ne soit disponible, ou le nom de la relation dans .magento.app.yaml ne correspond pas à l’ID de service dans .magento/services.yaml. Voir Vérifier la relation de service.