1.19. Extensions
Vous pouvez utiliser des extensions WebAssembly pour ajouter de nouvelles fonctionnalités directement dans les proxies Red Hat OpenShift Service Mesh. Cela vous permet de déplacer encore plus de fonctionnalités courantes hors de vos applications, et de les mettre en œuvre dans un langage unique qui se compile en bytecode WebAssembly.
Les extensions WebAssembly ne sont pas prises en charge sur les systèmes IBM zSystems et IBM Power.
1.19.1. Vue d'ensemble des modules WebAssembly
Les modules WebAssembly peuvent être exécutés sur de nombreuses plates-formes, y compris les proxies, et disposent d'un large support linguistique, d'une exécution rapide et d'un modèle de sécurité "sandboxé" par défaut.
Les extensions Red Hat OpenShift Service Mesh sont des filtres HTTP Envoy, ce qui leur confère un large éventail de capacités :
- Manipulation du corps et des en-têtes des demandes et des réponses.
- Demandes HTTP hors bande adressées à des services qui ne se trouvent pas sur le chemin de la demande, tels que l'authentification ou la vérification de la politique.
- Stockage de données sur le canal latéral et files d'attente pour que les filtres communiquent entre eux.
Lors de la création de nouvelles extensions WebAssembly, utilisez l'API WasmPlugin. L'API ServiceMeshExtension était obsolète dans Red Hat OpenShift Service Mesh version 2.2 et a été supprimée dans Red Hat OpenShift Service Mesh version 2.3.
L'écriture d'une extension Red Hat OpenShift Service Mesh comporte deux parties :
- Vous devez écrire votre extension à l'aide d'un SDK qui expose l'API proxy-wasm et la compiler en un module WebAssembly.
- Vous devez ensuite placer le module dans un conteneur.
Langues prises en charge
Vous pouvez utiliser n'importe quel langage qui compile le bytecode WebAssembly pour écrire une extension Red Hat OpenShift Service Mesh, mais les langages suivants ont des SDK existants qui exposent l'API proxy-wasm afin qu'elle puisse être consommée directement.
| Langue | Responsable de la maintenance | Référentiel |
|---|---|---|
| AssemblyScript | solo.io | |
| C | équipe proxy-wasm (Communauté Istio) | |
| Aller | tetrate.io | |
| Rouille | équipe proxy-wasm (Communauté Istio) |
1.19.2. WasmPlugin format du conteneur
Istio prend en charge les images de l'Open Container Initiative (OCI) dans son mécanisme Wasm Plugin. Vous pouvez distribuer vos plugins Wasm en tant qu'image de conteneur et vous pouvez utiliser le champ spec.url pour faire référence à l'emplacement d'un registre de conteneurs. Par exemple, quay.io/my-username/my-plugin:latest.
Étant donné que chaque environnement d'exécution (runtime) d'un module WASM peut avoir des paramètres de configuration spécifiques au runtime, une image WASM peut être composée de deux couches :
-
plugin.wasm (Obligatoire) - Couche de contenu. Cette couche consiste en un binaire
.wasmcontenant le bytecode de votre module WebAssembly, qui sera chargé par le runtime. Vous devez nommer ce fichierplugin.wasm. - runtime-config.json (Facultatif) - Couche de configuration. Cette couche se compose d'une chaîne au format JSON qui décrit les métadonnées du module pour le système d'exécution cible. La couche de configuration peut également contenir des données supplémentaires, en fonction de l'environnement d'exécution cible. Par exemple, la configuration d'un filtre WASM Envoy contient les root_ids disponibles sur le filtre.
1.19.3. Référence API WasmPlugin
L'API WasmPlugins fournit un mécanisme pour étendre la fonctionnalité fournie par le proxy Istio à travers des filtres WebAssembly.
Vous pouvez déployer plusieurs WasmPlugins. Les paramètres phase et priority déterminent l'ordre d'exécution (dans le cadre de la chaîne de filtrage d'Envoy), ce qui permet de configurer des interactions complexes entre les WasmPlugins fournis par l'utilisateur et les filtres internes d'Istio.
Dans l'exemple suivant, un filtre d'authentification met en œuvre un flux OpenID et remplit l'en-tête Authorization avec un jeton Web JSON (JWT). L'authentification Istio consomme ce jeton et le déploie sur la passerelle d'entrée. Le fichier WasmPlugin se trouve dans le système de fichiers sidecar du proxy. Notez le champ url.
apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
name: openid-connect
namespace: istio-ingress
spec:
selector:
matchLabels:
istio: ingressgateway
url: file:///opt/filters/openid.wasm
sha256: 1ef0c9a92b0420cf25f7fe5d481b231464bc88f486ca3b9c83ed5cc21d2f6210
phase: AUTHN
pluginConfig:
openid_server: authn
openid_realm: ingress
Voici le même exemple, mais cette fois-ci, une image OCI (Open Container Initiative) est utilisée à la place d'un fichier dans le système de fichiers. Notez les champs url, imagePullPolicy, et imagePullSecret.
apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
name: openid-connect
namespace: istio-system
spec:
selector:
matchLabels:
istio: ingressgateway
url: oci://private-registry:5000/openid-connect/openid:latest
imagePullPolicy: IfNotPresent
imagePullSecret: private-registry-pull-secret
phase: AUTHN
pluginConfig:
openid_server: authn
openid_realm: ingress| Field | Type | Description | Exigée |
|---|---|---|---|
| spec.selector | Sélecteur de charge de travail |
Critères utilisés pour sélectionner l'ensemble spécifique de pods/VMs sur lesquels cette configuration de plugin doit être appliquée. Si elle est omise, cette configuration sera appliquée à toutes les instances de charge de travail dans le même espace de noms. Si le champ | Non |
| spec.url | chaîne de caractères |
URL d'un module Wasm ou d'un conteneur OCI. Si aucun schéma n'est présent, la valeur par défaut est | Non |
| spec.sha256 | chaîne de caractères |
Somme de contrôle SHA256 qui sera utilisée pour vérifier le module Wasm ou le conteneur OCI. Si le champ | Non |
| spec.imagePullPolicy | Politique d'attraction |
Le comportement d'extraction à appliquer lors de la récupération d'une image OCI. Ne s'applique que lorsque les images sont référencées par un tag au lieu d'un SHA. La valeur par défaut est | Non |
| spec.imagePullSecret | chaîne de caractères |
Informations d'identification à utiliser pour l'extraction d'images OCI. Le nom d'un secret dans le même espace de noms que l'objet | Non |
| spec.phase | PluginPhase |
Détermine l'endroit de la chaîne de filtrage où cet objet | Non |
| spec.priority |
|
Détermine l'ordre des objets | Non |
| spec.pluginName | chaîne de caractères | Le nom du plugin utilisé dans la configuration d'Envoy. Certains modules Wasm peuvent avoir besoin de cette valeur pour sélectionner le plugin Wasm à exécuter. | Non |
| spec.pluginConfig | Structure | La configuration qui sera transmise au plugin. | Non |
| spec.pluginConfig.verificationKey | chaîne de caractères | Clé publique utilisée pour vérifier les signatures des images OCI ou des modules Wasm signés. Elle doit être fournie au format PEM. | Non |
L'objet WorkloadSelector spécifie les critères utilisés pour déterminer si un filtre peut être appliqué à un proxy. Les critères de correspondance comprennent les métadonnées associées à un proxy, les informations sur l'instance de charge de travail telles que les étiquettes attachées au pod/VM, ou toute autre information que le proxy fournit à Istio au cours de l'échange initial. Si plusieurs conditions sont spécifiées, toutes les conditions doivent correspondre pour que l'instance de charge de travail soit sélectionnée. Actuellement, seul le mécanisme de sélection basé sur les étiquettes est pris en charge.
| Field | Type | Description | Exigée |
|---|---|---|---|
| matchLabels | map<chaîne, string> | Une ou plusieurs étiquettes qui indiquent un ensemble spécifique de pods/VMs sur lesquels une politique doit être appliquée. La portée de la recherche d'étiquettes est limitée à l'espace de noms de configuration dans lequel la ressource est présente. | Oui |
L'objet PullPolicy spécifie le comportement de traction à appliquer lors de la récupération d'une image OCI.
| Valeur | Description |
|---|---|
| <empty> |
La valeur par défaut est |
| S'il n'est pas présent | Si une version existante de l'image a déjà été extraite, elle sera utilisée. Si aucune version de l'image n'est présente localement, nous utiliserons la version la plus récente. |
| Always | Utilisez toujours la dernière version d'une image lorsque vous utilisez ce plugin. |
Struct représente une valeur de données structurée, composée de champs qui correspondent à des valeurs typées dynamiquement. Dans certains langages, les structures peuvent être représentées de manière native. Par exemple, dans les langages de script comme JavaScript, une structure est représentée comme un objet.
| Field | Type | Description |
|---|---|---|
| champs | map<string, Value> | Carte de valeurs typées dynamiquement. |
PluginPhase spécifie la phase de la chaîne de filtrage dans laquelle le plugin sera injecté.
| Field | Description |
|---|---|
| <empty> | Le plan de contrôle décide de l'endroit où insérer le plugin. Il se trouve généralement à la fin de la chaîne de filtrage, juste avant le routeur. Ne pas spécifier PluginPhase si le plugin est indépendant des autres. |
| AUTHN | Insérer le plugin avant les filtres d'authentification Istio. |
| AUTHZ | Insérer le plugin avant les filtres d'autorisation Istio et après les filtres d'authentification Istio. |
| STATS | Insérer le plugin avant les filtres de statistiques Istio et après les filtres d'autorisation Istio. |
1.19.3.1. Déploiement des ressources WasmPlugin
Vous pouvez activer les extensions Red Hat OpenShift Service Mesh en utilisant la ressource WasmPlugin. Dans cet exemple, istio-system est le nom du projet de plan de contrôle Service Mesh. L'exemple suivant crée un filtre openid-connect qui exécute un flux OpenID Connect pour authentifier l'utilisateur.
Procédure
Créez l'exemple de ressource suivant :
Exemple plugin.yaml
apiVersion: extensions.istio.io/v1alpha1 kind: WasmPlugin metadata: name: openid-connect namespace: istio-system spec: selector: matchLabels: istio: ingressgateway url: oci://private-registry:5000/openid-connect/openid:latest imagePullPolicy: IfNotPresent imagePullSecret: private-registry-pull-secret phase: AUTHN pluginConfig: openid_server: authn openid_realm: ingressAppliquez votre fichier
plugin.yamlavec la commande suivante :$ oc apply -f plugin.yaml
1.19.4. ServiceMeshExtension format du conteneur
Vous devez avoir un fichier .wasm contenant le bytecode de votre module WebAssembly et un fichier manifest.yaml à la racine du système de fichiers du conteneur pour que votre image de conteneur soit une image d'extension valide.
Lors de la création de nouvelles extensions WebAssembly, utilisez l'API WasmPlugin. L'API ServiceMeshExtension était obsolète dans Red Hat OpenShift Service Mesh version 2.2 et a été supprimée dans Red Hat OpenShift Service Mesh version 2.3.
manifest.yaml
schemaVersion: 1 name: <your-extension> description: <description> version: 1.0.0 phase: PreAuthZ priority: 100 module: extension.wasm
| Field | Description | Exigée |
|---|---|---|
| schemaVersion |
Utilisé pour la version du schéma du manifeste. Actuellement, la seule valeur possible est | Ce champ est obligatoire. |
| nom | Le nom de votre extension. | Ce champ n'est qu'une métadonnée et est actuellement inutilisé. |
| description | La description de votre extension. | Ce champ n'est qu'une métadonnée et est actuellement inutilisé. |
| version | La version de votre extension. | Ce champ n'est qu'une métadonnée et est actuellement inutilisé. |
| phase | La phase d'exécution par défaut de votre extension. | Ce champ est obligatoire. |
| priorité | La priorité par défaut de votre extension. | Ce champ est obligatoire. |
| module | Le chemin relatif de la racine du système de fichiers du conteneur vers votre module WebAssembly. | Ce champ est obligatoire. |
1.19.5. Référence de ServiceMeshExtension
L'API ServiceMeshExtension fournit un mécanisme permettant d'étendre les fonctionnalités fournies par le proxy Istio au moyen de filtres WebAssembly. L'écriture d'une extension WebAssembly comporte deux parties :
- Écrivez votre extension à l'aide d'un SDK qui expose l'API proxy-wasm et compilez-la dans un module WebAssembly.
- L'emballer dans un récipient.
Lors de la création de nouvelles extensions WebAssembly, utilisez l'API WasmPlugin. L'API ServiceMeshExtension, qui était obsolète dans Red Hat OpenShift Service Mesh version 2.2, a été supprimée dans Red Hat OpenShift Service Mesh version 2.3.
| Field | Description |
|---|---|
| metadata.namespace |
Le champ |
| spec.workloadSelector |
Le champ |
| spec.config | Il s'agit d'un champ structuré qui sera transmis à l'extension, la sémantique dépendant de l'extension que vous déployez. |
| spec.image | Un URI d'image conteneur pointant vers l'image qui contient l'extension. |
| spec.phase |
La phase détermine à quel endroit de la chaîne de filtrage l'extension est injectée, par rapport aux fonctionnalités existantes d'Istio telles que l'authentification, l'autorisation et la génération de métriques. Les valeurs valides sont : PreAuthN, PostAuthN, PreAuthZ, PostAuthZ, PreStats, PostStats. Ce champ prend par défaut la valeur définie dans le fichier |
| spec.priority |
Si plusieurs extensions ayant la même valeur |
1.19.5.1. Déploiement des ressources ServiceMeshExtension
Vous pouvez activer les extensions Red Hat OpenShift Service Mesh en utilisant la ressource ServiceMeshExtension. Dans cet exemple, istio-system est le nom du projet de plan de contrôle Service Mesh.
Lors de la création de nouvelles extensions WebAssembly, utilisez l'API WasmPlugin. L'API ServiceMeshExtension a été obsolète dans Red Hat OpenShift Service Mesh version 2.2 et supprimée dans Red Hat OpenShift Service Mesh version 2.3.
Pour un exemple complet qui a été construit en utilisant le SDK Rust, jetez un coup d'œil au header-append-filter. Il s'agit d'un simple filtre qui ajoute un ou plusieurs en-têtes aux réponses HTTP, avec leurs noms et valeurs extraits du champ config de l'extension. Vous trouverez un exemple de configuration dans l'extrait ci-dessous.
Procédure
Créez l'exemple de ressource suivant :
Exemple de ressource ServiceMeshExtension extension.yaml
apiVersion: maistra.io/v1 kind: ServiceMeshExtension metadata: name: header-append namespace: istio-system spec: workloadSelector: labels: app: httpbin config: first-header: some-value another-header: another-value image: quay.io/maistra-dev/header-append-filter:2.1 phase: PostAuthZ priority: 100Appliquez votre fichier
extension.yamlavec la commande suivante :$ oc apply -f <extension>.yaml
1.19.6. Migration des ressources ServiceMeshExtension vers WasmPlugin
L'API ServiceMeshExtension, qui était obsolète dans Red Hat OpenShift Service Mesh version 2.2, a été supprimée dans Red Hat OpenShift Service Mesh version 2.3. Si vous utilisez l'API ServiceMeshExtension, vous devez migrer vers l'API WasmPlugin pour continuer à utiliser vos extensions WebAssembly.
Les API sont très similaires. La migration se fait en deux étapes :
- Renommer votre fichier de plugin et mettre à jour l'emballage du module.
-
Création d'une ressource
WasmPluginqui fait référence à l'image de conteneur mise à jour.
1.19.6.1. Modifications de l'API
La nouvelle API WasmPlugin est similaire à l'API ServiceMeshExtension, mais avec quelques différences, notamment en ce qui concerne les noms des champs :
| ServiceMeshExtension | WasmPlugin |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
Voici un exemple de conversion d'une ressource ServiceMeshExtension en ressource WasmPlugin.
Ressource ServiceMeshExtension
apiVersion: maistra.io/v1
kind: ServiceMeshExtension
metadata:
name: header-append
namespace: istio-system
spec:
workloadSelector:
labels:
app: httpbin
config:
first-header: some-value
another-header: another-value
image: quay.io/maistra-dev/header-append-filter:2.2
phase: PostAuthZ
priority: 100
Nouvelle ressource WasmPlugin équivalente au ServiceMeshExtension ci-dessus
apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
name: header-append
namespace: istio-system
spec:
selector:
matchLabels:
app: httpbin
url: oci://quay.io/maistra-dev/header-append-filter:2.2
phase: STATS
pluginConfig:
first-header: some-value
another-header: another-value
1.19.6.2. Modifications du format de l'image du conteneur
Le nouveau format d'image du conteneur WasmPlugin est similaire à celui de ServiceMeshExtensions, avec les différences suivantes :
-
Le format de conteneur
ServiceMeshExtensionnécessite un fichier de métadonnées nommémanifest.yamldans le répertoire racine du système de fichiers du conteneur. Le format de conteneurWasmPluginne nécessite pas de fichiermanifest.yaml. -
Le fichier
.wasm(le plugin proprement dit), qui pouvait auparavant avoir n'importe quel nom de fichier, doit désormais être nomméplugin.wasmet se trouver dans le répertoire racine du système de fichiers du conteneur.
1.19.6.3. Migration vers les ressources WasmPlugin
Pour mettre à jour vos extensions WebAssembly de l'API ServiceMeshExtension à l'API WasmPlugin, vous devez renommer votre fichier de plugin.
Conditions préalables
-
ServiceMeshControlPlaneest mis à niveau vers la version 2.2 ou une version ultérieure.
Procédure
Mettez à jour l'image de votre conteneur. Si le plugin est déjà dans
/plugin.wasmà l'intérieur du conteneur, passez à l'étape suivante. Si ce n'est pas le cas :-
Veillez à ce que le fichier du plugin soit nommé
plugin.wasm. Vous devez nommer le fichier d'extensionplugin.wasm. - Assurez-vous que le fichier d'extension se trouve dans le répertoire racine (/). Vous devez stocker les fichiers d'extension à la racine du système de fichiers du conteneur...
- Reconstruisez votre image de conteneur et envoyez-la dans un registre de conteneurs.
-
Veillez à ce que le fichier du plugin soit nommé
-
Supprimez la ressource
ServiceMeshExtensionet créez une ressourceWasmPluginqui fait référence à la nouvelle image de conteneur que vous avez créée.
