frontend-gray plug-in - API Gateway - Centre de documentation Alibaba Cloud

Le plug-in frontend-gray permet les déploiements canaris pour les utilisateurs frontaux. Il prend en charge les tests A/B Test et garantit la stabilité des versions grâce à des stratégies de déploiement progressif (grayscale), de monitoring et de rollback.

Attributs d'exécution

Phase d'exécution du plug-in : Authentication phase. Priorité d'exécution du plug-in : 1000.

Champs

Nom

Type de données

Exigences

Valeur par défaut

Description

grayKey

string

Facultatif

L'identifiant unique d'un utilisateur, extrait d'un cookie ou d'un en-tête de requête (par exemple, userid). Si ce paramètre n'est pas spécifié, le système utilise rules[].grayTagKey et rules[].grayTagValue pour faire correspondre les règles de déploiement canari.

useManifestAsEntry

boolean

Facultatif

false

Indique s'il faut utiliser un fichier manifeste comme point d'entrée de l'application. Définissez cette valeur sur true pour les architectures micro-frontend, où différentes versions des ressources frontales sont chargées en fonction du contenu du fichier manifeste.

localStorageGrayKey

string

Facultatif

L'identifiant utilisateur unique issu de localStorage pour l'authentification JSON Web Token (JWT). S'il est configuré, grayKey est ignoré.

graySubKey

string

Facultatif

Les informations d'identité utilisateur peuvent être au format JSON. Par exemple, userInfo:{ userCode:"001" }. Dans ce cas, définissez graySubKey sur userCode pour extraire l'identifiant.

storeMaxAge

int

Facultatif

60 * 60 * 24 * 365

La durée maximale de stockage du cookie défini par la passerelle, en secondes. La valeur par défaut est d'un an.

cookieDomain

string

Facultatif

Le domaine du cookie. Utilisez ce paramètre pour partager les cookies entre sous-domaines. Par exemple, « .example.com ».

indexPaths

array of strings

Facultatif

Chemins toujours traités par le plug-in. Les motifs Glob sont pris en charge. Par exemple, dans un scénario micro-frontend, une requête XHR vers /resource/**/manifest-main.json doit être acheminée via le plug-in.

skippedPaths

array of strings

Facultatif

Chemins à exclure du traitement par ce plug-in. Les motifs Glob sont pris en charge. Par exemple, dans un scénario de réécriture, une requête XHR vers /api/** peut produire des résultats inattendus si elle est traitée par le plug-in.

skippedByHeaders

map of string to string

Facultatif

Exclut les requêtes du traitement en fonction des valeurs des en-têtes. skippedPaths est prioritaire sur cette configuration. Les requêtes de pages HTML ne sont pas affectées.

rules

array of object

Obligatoire

Règles de déploiement canari qui associent les utilisateurs aux versions de déploiement.

rewrite

object

Facultatif

La configuration de réécriture, généralement utilisée pour les interfaces Object Storage Service (OSS) et CDN.

baseDeployment

object

Facultatif

La configuration de la règle de référence.

grayDeployments

array of object

Facultatif

Règles d'activation et versions cibles pour les déploiements canaris.

backendGrayTag

string

Facultatif

x-mse-tag

Le tag pour la version de déploiement canari backend. S'il est configuré, un cookie est défini avec la valeur ${backendGrayTag}:${grayDeployments[].backendVersion}.

uniqueGrayTag

string

Facultatif

x-higress-uid

Lorsque le déploiement canari basé sur un pourcentage est activé, la passerelle génère un identifiant unique et le stocke dans un cookie pour assurer l'affinité de session. Le backend peut également utiliser cette valeur pour le traçage complet du déploiement canari.

injection

object

Facultatif

Injecte des informations globales dans le code HTML de la page d'accueil. Par exemple, <script>window.global = {...}</script>.

Le tableau suivant décrit les champs contenus dans rules.

Nom

Type de données

Exigences

Valeur par défaut

Description

name

string

Obligatoire

Un nom unique pour la règle. Ce champ est associé à grayDeployments[].name.

grayKeyValue

array of string

Facultatif

Une liste d'autorisation d'ID utilisateur pour cette règle.

grayTagKey

string

Facultatif

La clé de tag utilisée pour catégoriser les utilisateurs, extraite des cookies.

grayTagValue

array of string

Facultatif

La valeur de tag utilisée pour catégoriser les utilisateurs, extraite des cookies.

Le tableau suivant décrit les champs contenus dans rewrite.

indexRouting (réécriture de la page d'accueil) et fileRouting (réécriture de fichier) utilisent tous deux la mise en correspondance par préfixe. Par exemple, /app1: /mfe/app1/{version}/index.html signifie que les requêtes avec le préfixe /app1 sont acheminées vers /mfe/app1/{version}/index.html. {version} est un espace réservé remplacé dynamiquement par baseDeployment.version ou grayDeployments[].version lors de l'exécution.

{version} est un mot réservé remplacé dynamiquement par la version frontale issue de baseDeployment.version ou grayDeployments[].version.

Nom

Type de données

Exigences

Valeur par défaut

Description

host

string

Facultatif

L'adresse hôte. Pour OSS, utilisez un endpoint VPC.

indexRouting

map of string to string

Facultatif

Définit la règle de routage pour réécrire la page d'accueil. Chaque clé correspond à un chemin d'accès de la page d'accueil et la valeur au fichier cible de la redirection. Par exemple, la clé /app1 correspond à la valeur /mfe/app1/{version}/index.html. Si la version active est 0.0.1 et que le chemin d'accès est /app1, la requête est redirigée vers /mfe/app1/0.0.1/index.html.

fileRouting

map of string to string

Facultatif

Définit la règle de routage pour réécrire les fichiers de ressources. Chaque clé correspond à un chemin d'accès d'une ressource et la valeur au fichier cible de la redirection. Par exemple, la clé /app1/ correspond à la valeur /mfe/app1/{version}. Si la version active est 0.0.1 et que le chemin d'accès est /app1/js/a.js, la requête est redirigée vers /mfe/app1/0.0.1/js/a.js.

Le tableau suivant décrit les champs contenus dans baseDeployment.

Nom

Type de données

Exigences

Valeur par défaut

Description

version

string

Obligatoire

La version de référence.

backendVersion

string

Facultatif

La version de déploiement canari backend, qui est écrite dans un cookie avec la key définie sur ${backendGrayTag}.

versionPredicates

string

Facultatif

Similaire à version, mais prend en charge plusieurs versions, en mappant différentes versions selon les routes. Généralement utilisé dans les scénarios micro-frontend où une application principale gère plusieurs micro-applications.

Le tableau suivant décrit les champs contenus dans grayDeployments.

Nom

Type de données

Exigences

Valeur par défaut

Description

version

string

Obligatoire

Le numéro de version du déploiement canari. Cette version est utilisée lorsque la règle de déploiement canari correspond. Pour les déploiements hors CDN, l'en-tête x-higress-tag est ajouté.

versionPredicates

string

Facultatif

backendVersion

string

Facultatif

La version de déploiement canari backend. L'en-tête x-mse-tag est ajouté aux requêtes XHR/Fetch envoyées au backend.

name

string

Obligatoire

Le nom de la règle. Ce champ est associé à rules[].name.

enabled

boolean

Facultatif

Indique s'il faut activer cette règle.

weight

int

Facultatif

Le pourcentage de trafic acheminé vers la version de déploiement canari. Par exemple, 50.

Exemples de configuration

Configuration de base (déploiement canari par utilisateur)

grayKey: userid
rules:
- name: inner-user
  grayKeyValue:
  - '00000001'
  - '00000005'
- name: beta-user
  grayKeyValue:
  - '00000002'
  - '00000003'
  grayTagKey: level
  grayTagValue:
  - level3
  - level5
baseDeployment:
  version: base
grayDeployments:
  - name: beta-user
    version: gray
    enabled: true

L'identifiant utilisateur unique dans le cookie est userid. La règle de déploiement canari actuelle est nommée beta-user.

Si les conditions suivantes sont remplies, la version version: gray est utilisée. Sinon, la version version: base est utilisée.

Le userid dans le cookie est 00000002 ou 00000003.
Le level dans le cookie est level3 ou level5.

Déploiement progressif par pourcentage

grayKey: userid
rules:
- name: inner-user
  grayKeyValue:
  - '00000001'
  - '00000005'
baseDeployment:
  version: base
grayDeployments:
  - name: inner-user
    version: gray
    enabled: true
    weight: 80

Le poids total de toutes les règles de déploiement canari est de 100 %. Dans cet exemple, la version de déploiement canari a un poids de 80 % et la version de référence a un poids de 20 %.

Stockage des informations utilisateur au format JSON

grayKey: appInfo
graySubKey: userId
rules:
- name: inner-user
  grayKeyValue:
  - '00000001'
  - '00000005'
- name: beta-user
  grayKeyValue:
  - '00000002'
  - '00000003'
  grayTagKey: level
  grayTagValue:
  - level3
  - level5
baseDeployment:
  version: base
grayDeployments:
  - name: beta-user
    version: gray
    enabled: true

Le cookie contient des données appInfo au format JSON. Le champ userId est l'identifiant unique. La règle de déploiement canari actuelle est nommée beta-user. Si les conditions suivantes sont remplies, la version version: gray est utilisée. Sinon, la version version: base est utilisée.

Le userid dans le cookie est 00000002 ou 00000003.
Le level dans le cookie est level3 ou level5.

Informations utilisateur dans LocalStorage

Le plug-in de passerelle nécessite un identifiant utilisateur unique. Étant donné que HTTP ne peut transférer ces informations que dans un en-tête, si les informations utilisateur sont stockées dans LocalStorage, injectez un script dans la page d'accueil pour les copier dans un cookie.

(function() {
	var grayKey = '@@X_GRAY_KEY';
	var cookies = document.cookie.split('; ').filter(function(row) {
		return row.indexOf(grayKey + '=') === 0;
	});

	try {
		if (typeof localStorage !== 'undefined' && localStorage !== null) {
			var storageValue = localStorage.getItem(grayKey);
			var cookieValue = cookies.length > 0 ? decodeURIComponent(cookies[0].split('=')[1]) : null;
			if (storageValue && storageValue.indexOf('=') < 0 && cookieValue !== storageValue) {
				document.cookie = grayKey + '=' + encodeURIComponent(storageValue) + '; path=/;';
				window.location.reload();
			}
		}
	} catch (error) {
		//
	}
})();

Configuration de réécriture

Cette configuration est généralement utilisée dans les scénarios de déploiement CDN. {version} est remplacé dynamiquement par la version réelle lors de l'exécution.

grayKey: userid
rules:
- name: inner-user
  grayKeyValue:
  - '00000001'
  - '00000005'
- name: beta-user
  grayKeyValue:
  - '00000002'
  - '00000003'
  grayTagKey: level
  grayTagValue:
  - level3
  - level5
rewrite:
  host: frontend-gray.oss-cn-shanghai-internal.aliyuncs.com
  notFoundUri: /mfe/app1/dev/404.html
  indexRouting:
    /app1: '/mfe/app1/{version}/index.html'
    /: '/mfe/app1/{version}/index.html',
  fileRouting:
    /: '/mfe/app1/{version}'
    /app1/: '/mfe/app1/{version}'
baseDeployment:
  version: base
grayDeployments:
  - name: beta-user
    version: gray
    enabled: true

indexRouting : réécriture de la page d'accueil

Les requêtes vers /app1, /app123, /app1/index.html, /app1/xxx et /xxxx sont toutes acheminées vers /mfe/app1/{version}/index.html.

fileRouting : configuration du routage des fichiers

Les mappages de fichiers suivants sont actifs.

/js/a.js => /mfe/app1/v1.0.0/js/a.js
/js/template/a.js => /mfe/app1/v1.0.0/js/template/a.js
/app1/js/a.js => /mfe/app1/v1.0.0/js/a.js
/app1/js/template/a.js => /mfe/app1/v1.0.0/js/template/a.js

Injection de code dans la page d'accueil HTML

grayKey: userid
rules:
- name: inner-user
  grayKeyValue:
  - '00000001'
  - '00000005'
baseDeployment:
  version: base
grayDeployments:
  - name: beta-user
    version: gray
    enabled: true
injection:
  head: 
    - <script>console.log('Header')</script>
  body:
    first:
      - <script>console.log('hello world before')</script>
      - <script>console.log('hello world before1')</script>
    last:
      - <script>console.log('hello world after')</script>
      - <script>console.log('hello world after2')</script>

Le champ injection injecte du code dans la page d'accueil HTML : dans la balise head, ou aux positions first et last au sein de la balise body.