Configurare il servizio Valkey

Valkey è una soluzione di cache back-end opzionale per Adobe Commerce sull’infrastruttura cloud. Valkey è richiesto quando si esegue l’override della configurazione predefinita della cache in Adobe Commerce 2.4.9 e versioni successive, o nelle versioni patch successive a 2.4.5-p16, 2.4.6-p14, 2.4.7-p9 e 2.4.8-p4.

Utilizzare le istruzioni seguenti per la configurazione del servizio negli ambienti di integrazione Pro e negli ambienti Starter, incluso il ramo master.

Configura Valkey

Per sostituire Redis con Valkey, aggiornare i seguenti file:

Configurare il servizio

In .magento/services.yaml, sostituire la definizione del servizio Redis con una definizione del servizio Valkey. Sostituisci <version> con una versione di Valkey supportata dalla versione di Adobe Commerce e dal modello Cloud corrente.

cache:
  type: valkey:<version>

Esempio

cache:
  type: valkey:8.0

La versione di esempio non è universale. Le versioni predefinite e supportate effettive dipendono dalla versione di Adobe Commerce e dal modello Cloud corrente. Utilizza la versione specificata dal modello di progetto corrente. Per ulteriori informazioni, vedere Configurare i servizi.

Non presumere che la cache e i dati della sessione persistano quando si modifica il valore type da redis:<version> a valkey:<version>, anche quando si mantiene lo stesso ID servizio. Considera la migrazione come creazione di una nuova cache: la cache esistente e i dati della sessione non vengono conservati e gli utenti vengono disconnessi al termine della migrazione.

Configurare la relazione di servizio

In .magento.app.yaml configurare la relazione tra l’applicazione e il servizio Valkey:

relationships:
  valkey: "cache:valkey"

La chiave di relazione valkey è il nome utilizzato dall’applicazione per accedere al servizio. Il valore cache:valkey fa riferimento all’ID servizio e al tipo di servizio definiti in .magento/services.yaml.

runtime:
      extensions:
          - redis

Eseguire il commit e distribuire le modifiche

Aggiungi, esegui il commit e invia le modifiche di configurazione:

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

Al termine della distribuzione, verificare che la relazione del servizio Valkey sia disponibile.

Personalizzare la configurazione Valkey

Per i consigli relativi a cache, sessione, L2 e connessione di replica, vedere Best practice per la configurazione del servizio Valkey e Redis nella Guida alle best practice per l’implementazione della playbook.

Verifica la relazione di servizio

Per visualizzare l’oggetto MAGENTO_CLOUD_RELATIONSHIPS decodificato, eseguire il comando seguente da un contenitore di applicazioni dopo la distribuzione della configurazione:

Utilizza SSH per connettersi all’ambiente cloud remoto, quindi esegui:

echo "$MAGENTO_CLOUD_RELATIONSHIPS" | base64 -d | json_pp

Il comando visualizza tutte le relazioni di servizio configurate. Per identificare i dettagli di connessione Valkey, individuare la relazione valkey.

Output di esempio

L’esempio abbreviato seguente mostra la relazione valkey. Non è uno schema universale.

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

L’output varia in base all’ambiente e alla configurazione del servizio. Non inserire nel codice rigido nomi host, porte, indirizzi IP, nomi di cluster, versioni di servizi, nomi utente o password di questo esempio. Utilizzare i valori restituiti da MAGENTO_CLOUD_RELATIONSHIPS nell’ambiente di destinazione.

Se jq è disponibile, visualizzare solo la relazione Valkey:

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

Per ulteriori informazioni sulle relazioni tra i servizi, vedere Configurare i servizi.

Utilizzo di Valkey CLI

Supponendo che la relazione Valkey sia denominata valkey, utilizzare l’host e la porta restituiti da MAGENTO_CLOUD_RELATIONSHIPS per connettersi a Valkey:

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

Esempio

valkey-cli -h valkey.internal -p 6379

Scarica la versione installata di 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> ...

Risoluzione dei problemi di Valkey

Gli errori di pulizia della cache fanno riferimento a Redis in una cache configurata con Valkey

Un errore di pulizia della cache pre-distribuzione può visualizzare il codice di errore [107] (clean-redis-cache) e un messaggio Connection to Redis anche quando il servizio cache è configurato come Valkey. ece-tools utilizza questo codice di errore e questo messaggio per il passaggio di pulizia della cache indipendentemente dal fatto che il servizio cache di backup sia Redis o Valkey.

Se l’errore sottostante è un errore DNS, ad esempio Name or service not known per l’host di relazione, il passaggio di distribuzione è stato eseguito prima che la relazione di servizio fosse disponibile oppure il nome della relazione in .magento.app.yaml non corrisponde all’ID del servizio in .magento/services.yaml. Vedere Verificare la relazione del servizio.