Skip to content

Commit ea7f114

Browse files
JSticklerJStickler
committed
OSSMDOC-551: Migrating from ServiceMeshExtension to WasmPlugin.
1 parent 1dee6a9 commit ea7f114

File tree

4 files changed

+130
-6
lines changed

4 files changed

+130
-6
lines changed

‎modules/ossm-extensions-migrating-to-wasmplugin.adoc

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
////
2+
This module included in the following assemblies:
3+
*service_mesh_/v2x/ossm-extensions.adoc
4+
////
5+
:_content-type: PROCEDURE
6+
[id="ossm-extensions-migrating-to-wasmplugin_{context}"]
7+
= Migrating to `WasmPlugin` resources
8+
9+
To upgrade your WebAssembly extensions from the `ServiceMeshExtension` API to the `WasmPlugin` API, you rename your plug-in file.
10+
11+
.Prerequisites
12+
13+
* `ServiceMeshControlPlane` is upgraded to version 2.2 or later.
14+
15+
[CAUTION]
16+
====
17+
Because both plug-ins will be called for every request, you might want to remove your existing `ServiceMeshExtension` resource before creating the new `WasmPlugin` resource. You might get undesired results having two plug-ins active at the same time.
18+
====
19+
20+
.Procedure
21+
22+
. Update your container image. If the plug-in is already in `/plugin.wasm` inside the container, skip to the next step. If not:
23+
24+
.. Ensure the plug-in file is named `plugin.wasm`. You must name the extension file `plugin.wasm`.
25+
26+
.. Ensure the plug-in file is located in the root (/) directory. You must store extension files in the root of the container filesystem..
27+
28+
.. Rebuild your container image and push it to a container registry.
29+
30+
. Remove the `ServiceMeshExtension` resource and create a `WasmPlugin` resource that refers to the new container image you built.

‎modules/ossm-extensions-migration-overview.adoc

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
////
2+
This module included in the following assemblies:
3+
*service_mesh_/v2x/ossm-extensions.adoc
4+
////
5+
:_content-type: CONCEPT
6+
[id="ossm-extensions-migration-overview_{context}"]
7+
= Migrating from `ServiceMeshExtension` to `WasmPlugin` resources
8+
9+
The `ServiceMeshExtension` API is deprecated as of {SMProductName} version 2.2 and will be removed in a future release. If you are using the `ServiceMeshExtention` API, you must migrate to the `WasmPlugin` API to continue using your WebAssembly extensions.
10+
11+
The APIs are very similar. The migration consists of two steps:
12+
13+
. Renaming your plug-in file and updating the module packaging.
14+
15+
. Creating a `WasmPlugin` resource that references the updated container image.
16+
17+
[id="ossm-extensions-migration-api-changes_{context}"]
18+
== API changes
19+
20+
The new `WasmPlugin` API is similar to the `ServiceMeshExtension`, but with a few differences, especially in the field names:
21+
22+
23+
.Field changes between `ServiceMeshExtensions` and `WasmPlugin`
24+
[options="header"]
25+
[cols="a, a"]
26+
|===
27+
|ServiceMeshExtension |WasmPlugin
28+
|`spec.config`
29+
|`spec.pluginConfig`
30+
31+
|`spec.workloadSelector`
32+
|`spec.selector`
33+
34+
|`spec.image`
35+
|`spec.url`
36+
37+
//Question about the case here, is WasmPlugin app caps?
38+
|`spec.phase` valid values: PreAuthN, PostAuthN, PreAuthZ, PostAuthZ, PreStats, PostStats
39+
|`spec.phase` valid values: <empty>, AUTHN, AUTHZ, STATS
40+
|===
41+
42+
The following is an example of how a `ServiceMeshExtension` resource could be converted into a `WasmPlugin` resource.
43+
44+
.ServiceMeshExtension resource
45+
[source,yaml]
46+
----
47+
apiVersion: maistra.io/v1
48+
kind: ServiceMeshExtension
49+
metadata:
50+
name: header-append
51+
namespace: istio-system
52+
spec:
53+
workloadSelector:
54+
labels:
55+
app: httpbin
56+
config:
57+
first-header: some-value
58+
another-header: another-value
59+
image: quay.io/maistra-dev/header-append-filter:2.2
60+
phase: PostAuthZ
61+
priority: 100
62+
----
63+
64+
.New WasmPlugin resource equivalent to the ServiceMeshExtension above
65+
[source,yaml]
66+
----
67+
apiVersion: extensions.istio.io/v1alpha1
68+
kind: WasmPlugin
69+
metadata:
70+
name: header-append
71+
namespace: istio-system
72+
spec:
73+
selector:
74+
matchLabels:
75+
app: httpbin
76+
url: oci://quay.io/maistra-dev/header-append-filter:2.2
77+
phase: STATS
78+
pluginConfig:
79+
first-header: some-value
80+
another-header: another-value
81+
----
82+
83+
[id="ossm-extensions-migration-format-changes_{context}"]
84+
== Container image format changes
85+
86+
The new `WasmPlugin` container image format is similar to the `ServiceMeshExtensions`, with the following differences:
87+
88+
* The `ServiceMeshExtension` container format required a metadata file named `manifest.yaml` in the root directory of the container filesystem. The `WasmPlugin` container format does not require a `manifest.yaml` file.
89+
90+
* The `.wasm` file (the actual plug-in) that previously could have any filename now must be named `plugin.wasm` and must be located in the root directory of the container filesystem.

‎modules/ossm-extensions-ref-wasmplugin.adoc

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -137,7 +137,7 @@ The `PullPolicy` object specifies the pull behavior to be applied when fetching
137137
|If an existing version of the image has been pulled before, that will be used. If no version of the image is present locally, we will pull the latest version.
138138
139139
|Always
140-
|We will always pull the latest version of an image when applying this plugin.
140+
|Always pull the latest version of an image when applying this plug-in.
141141
|===
142142
143143
`Struct` represents a structured data value, consisting of fields which map to dynamically typed values. In some languages, Struct might be supported by a native representation. For example, in scripting languages like JavaScript a struct is represented as an object.
@@ -152,22 +152,22 @@ The `PullPolicy` object specifies the pull behavior to be applied when fetching
152152
|Map of dynamically typed values.
153153
|===
154154
155-
`PluginPhase` specifies the phase in the filter chain where the plugin will be injected.
155+
`PluginPhase` specifies the phase in the filter chain where the plug-in will be injected.
156156
157157
.PluginPhase
158158
[options="header"]
159159
[cols="a, a"]
160160
|===
161161
| Field | Description
162162
|<empty>
163-
|Control plane decides where to insert the plugin. This will generally be at the end of the filter chain, right before the Router. Do not specify PluginPhase if the plugin is independent of others.
163+
|Control plane decides where to insert the plug-in. This will generally be at the end of the filter chain, right before the Router. Do not specify PluginPhase if the plug-in is independent of others.
164164
165165
|AUTHN
166-
|Insert plugin before Istio authentication filters.
166+
|Insert plug-in before Istio authentication filters.
167167
168168
|AUTHZ
169-
|Insert plugin before Istio authorization filters and after Istio authentication filters.
169+
|Insert plug-in before Istio authorization filters and after Istio authentication filters.
170170
171171
|STATS
172-
|Insert plugin before Istio stats filters and after Istio authorization filters.
172+
|Insert plug-in before Istio stats filters and after Istio authorization filters.
173173
|===

‎service_mesh/v2x/ossm-extensions.adoc

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,3 +26,7 @@ include::modules/ossm-extensions-smextension-format.adoc[leveloffset=+1]
2626
include::modules/ossm-extensions-ref-smextension.adoc[leveloffset=+1]
2727

2828
include::modules/ossm-extensions-smextension-deploy.adoc[leveloffset=+2]
29+
30+
include::modules/ossm-extensions-migration-overview.adoc[leveloffset=+1]
31+
32+
include::modules/ossm-extensions-migrating-to-wasmplugin.adoc[leveloffset=+2]

0 commit comments

Comments
 (0)