diff --git a/modules/ossm-configuring-the-threescale-wasm-auth-module.adoc b/modules/ossm-configuring-the-threescale-wasm-auth-module.adoc index 6cabc8cce74c..40330e9510a6 100644 --- a/modules/ossm-configuring-the-threescale-wasm-auth-module.adoc +++ b/modules/ossm-configuring-the-threescale-wasm-auth-module.adoc @@ -7,11 +7,10 @@ Cluster administrators on {product-title} can configure the `threescale-wasm-auth` module to authorize HTTP requests to 3scale API Management through an application binary interface (ABI). The ABI defines the interaction between host and the module, exposing the hosts services, and allows you to use the module to process proxy requests. -[id="the-service-mesh-extension_{context}"] -== The Service Mesh extension +[id="the-wasmplugin-api-extension_{context}"] +== The WasmPlugin API extension - -{SMProductShortName} provides a custom resource definition to specify and apply Proxy-WASM extensions to sidecar proxies, known as xref:../../service_mesh/v2x/ossm-extensions.adoc#ossm-extensions[`ServiceMeshExtension`]. {SMProductShortName} applies this custom resource to the set of workloads that require HTTP API management with 3scale. +{SMProductShortName} provides a custom resource definition to specify and apply Proxy-WASM extensions to sidecar proxies, known as xref:../../service_mesh/v2x/ossm-extensions.adoc#ossm-extensions-wasmplugin-format_ossm-extensions[`WasmPlugin`]. {SMProductShortName} applies this custom resource to the set of workloads that require HTTP API management with 3scale. ifdef::openshift-enterprise[] See xref:../../operators/understanding/crds/crd-extending-api-with-crds.adoc#crd-extending-api-with-crds[custom resource definition] for more information. @@ -26,43 +25,38 @@ Configuring the WebAssembly extension is currently a manual process. Support for * Identify a Kubernetes workload and namespace on your {SMProductShortName} deployment that you will apply this module. * You must have a 3scale tenant account. See link:https://www.3scale.net/signup[SaaS] or link:https://access.redhat.com/documentation/en-us/red_hat_3scale_api_management/2.11/html-single/installing_3scale/index#install-threescale-on-openshift-guide[3scale 2.11 On-Premises] with a matching service and relevant applications and metrics defined. -* If you apply the module to the `productpage` microservice in the `bookinfo` namespace, see the xref:../../service_mesh/v1x/prepare-to-deploy-applications-ossm.html#ossm-tutorial-bookinfo-overview_deploying-applications-ossm-v1x[Bookinfo sample application]. +* If you apply the module to the `` microservice in the `bookinfo` namespace, see the xref:../../service_mesh/v1x/prepare-to-deploy-applications-ossm.html#ossm-tutorial-bookinfo-overview_deploying-applications-ossm-v1x[Bookinfo sample application]. ** The following example is the YAML format for the custom resource for `threescale-wasm-auth` module. -This example refers to the upstream Maistra version of {SMProductShortName}, ServiceMeshExtension API. You must declare the namespace where the `threescale-wasm-auth` module is deployed, alongside a `WorkloadSelector` to identify the set of applications the module will apply to: +This example refers to the upstream Maistra version of {SMProductShortName}, `WasmPlugin` API. You must declare the namespace where the `threescale-wasm-auth` module is deployed, alongside a `selector` to identify the set of applications the module will apply to: + [source,yaml] ---- -apiVersion: maistra.io/v1 -kind: ServiceMeshExtension +apiVersion: extensions.istio.io/v1alpha1 +kind: WasmPlugin metadata: - name: threescale-wasm-auth - namespace: bookinfo <1> + name: + namespace: <1> spec: - workloadSelector: <2> + selector: <2> labels: - app: productpage - config: - image: registry.redhat.io/openshift-service-mesh/3scale-auth-wasm-rhel8:0.0.1 - phase: PostAuthZ + app: + pluginConfig: + url: oci://registry.redhat.io/3scale-amp2/3scale-auth-wasm-rhel8:0.0.3 + phase: AUTHZ priority: 100 ---- <1> The `namespace`. -<2> The `WorkloadSelector`. -* The `spec.config` field depends on the module configuration and it is not populated in the previous example. Instead, the example uses the `` placeholder value. You can use the format of this custom resource example. -** The `spec.config` field varies depending on the application. All other fields persist across multiple instances of this custom resource. As examples: +<2> The `selector`. +* The `spec.pluginConfig` field depends on the module configuration and it is not populated in the previous example. Instead, the example uses the `` placeholder value. You can use the format of this custom resource example. +** The `spec.pluginConfig` field varies depending on the application. All other fields persist across multiple instances of this custom resource. As examples: + -- -*** `image`: Only changes when newer versions of the module are deployed. +*** `url`: Only changes when newer versions of the module are deployed. *** `phase`: Remains the same, since this module needs to be invoked after the proxy has done any local authorization, such as validating OpenID Connect (OIDC) tokens. -- -* After you have the module configuration in `spec.config` and the rest of the custom resource, apply it with the `oc apply` command: +* After you have the module configuration in `spec.pluginConfig` and the rest of the custom resource, apply it with the `oc apply` command: + [source,terminal] ---- $ oc apply -f threescale-wasm-auth-bookinfo.yaml ---- - -[role="_additional-resources"] -.Additional resources -* xref:../../service_mesh/v2x/ossm-extensions.adoc#ossm-smextensions-deploy_ossm-extensions[Deploying `ServiceMeshExtension` resources] -* link:https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources[Custom Resources] diff --git a/modules/ossm-threescale-configuring-the-threescale-webassembly-module.adoc b/modules/ossm-threescale-configuring-the-threescale-webassembly-module.adoc index 59da041e809a..259801db1e3c 100644 --- a/modules/ossm-threescale-configuring-the-threescale-webassembly-module.adoc +++ b/modules/ossm-threescale-configuring-the-threescale-webassembly-module.adoc @@ -14,4 +14,4 @@ The prerequisites are a set of minimum mandatory fields in all cases: * For the 3scale account and authorization service: the `backend-listener` URL. * For the list of services to handle: the service IDs and at least one credential look up method and where to find it. * You will find examples for dealing with `userkey`, `appid` with `appkey`, and OpenID Connect (OIDC) patterns. -* The WebAssembly module uses the settings you specified in the static configuration. For example, if you add a mapping rule configuration to the module, it will always apply, even when the 3scale Admin Portal has no such mapping rule. The rest of the `ServiceMeshExtension` resource exists around the `spec.config` YAML entry. +* The WebAssembly module uses the settings you specified in the static configuration. For example, if you add a mapping rule configuration to the module, it will always apply, even when the 3scale Admin Portal has no such mapping rule. The rest of the `WasmPlugin` resource exists around the `spec.pluginConfig` YAML entry. diff --git a/modules/ossm-threescale-webassembly-module-api-object.adoc b/modules/ossm-threescale-webassembly-module-api-object.adoc index 1c9da5dec924..cc95f0cbc52a 100644 --- a/modules/ossm-threescale-webassembly-module-api-object.adoc +++ b/modules/ossm-threescale-webassembly-module-api-object.adoc @@ -15,13 +15,13 @@ A non-existent or unsupported version of the `api` object renders the 3scale Web .The `api` top-level string example [source,yaml] ---- -apiVersion: maistra.io/v1 -kind: ServiceMeshExtension +apiVersion: extensions.istio.io/v1alpha1 +kind: WasmPlugin metadata: - name: threescale-wasm-auth - namespace: bookinfo + name: + namespace: spec: - config: + pluginConfig: api: v1 ... ---- diff --git a/modules/ossm-threescale-webassembly-module-backend-object.adoc b/modules/ossm-threescale-webassembly-module-backend-object.adoc index 88a9d9a12b80..d35f24ad03d2 100644 --- a/modules/ossm-threescale-webassembly-module-backend-object.adoc +++ b/modules/ossm-threescale-webassembly-module-backend-object.adoc @@ -9,12 +9,12 @@ The `backend` top-level object specifies how to access the 3scale Service Manage [source,yaml] ---- -apiVersion: maistra.io/v1 -kind: ServiceMeshExtension +apiVersion: extensions.istio.io/v1alpha1 +kind: WasmPlugin metadata: - name: threescale-wasm-auth + name: spec: - config: + pluginConfig: ... backend: name: backend diff --git a/modules/ossm-threescale-webassembly-module-configuration.adoc b/modules/ossm-threescale-webassembly-module-configuration.adoc index dbd4ea00e916..3635e0427a5f 100644 --- a/modules/ossm-threescale-webassembly-module-configuration.adoc +++ b/modules/ossm-threescale-webassembly-module-configuration.adoc @@ -5,14 +5,14 @@ [id="ossm-threescale-webassembly-module-configuration_{context}"] = The 3scale WebAssembly module configuration -The `ServiceMeshExtension` custom resource spec provides the configuration that the `Proxy-WASM` module reads from. +The `WasmPlugin` custom resource spec provides the configuration that the `Proxy-WASM` module reads from. -The spec is embedded in the host and read by the `Proxy-WASM` module. Typically, the configurations are in the JSON file format for the modules to parse, however the `ServiceMeshExtension` resource can interpret the spec value as YAML and convert it to JSON for consumption by the module. +The spec is embedded in the host and read by the `Proxy-WASM` module. Typically, the configurations are in the JSON file format for the modules to parse, however the `WasmPlugin` resource can interpret the spec value as YAML and convert it to JSON for consumption by the module. -If you use the `Proxy-WASM` module in stand-alone mode, you must write the configuration using the JSON format. Using the JSON format means using escaping and quoting where needed within the `host` configuration files, for example `Envoy`. When you use the WebAssembly module with the `ServiceMeshExtension` resource, the configuration is in the YAML format. In this case, an invalid configuration forces the module to show diagnostics based on its JSON representation to a sidecar's logging stream. +If you use the `Proxy-WASM` module in stand-alone mode, you must write the configuration using the JSON format. Using the JSON format means using escaping and quoting where needed within the `host` configuration files, for example `Envoy`. When you use the WebAssembly module with the `WasmPlugin` resource, the configuration is in the YAML format. In this case, an invalid configuration forces the module to show diagnostics based on its JSON representation to a sidecar's logging stream. [IMPORTANT] ==== -The `EnvoyFilter` custom resource is not a supported API, although it can be used in some 3scale Istio adapter or {SMProductShortName} releases. Using the `EnvoyFilter` custom resource is not recommended. Use the `ServiceMeshExtension` API instead of the `EnvoyFilter` custom resource. +The `EnvoyFilter` custom resource is not a supported API, although it can be used in some 3scale Istio adapter or {SMProductShortName} releases. Using the `EnvoyFilter` custom resource is not recommended. Use the `WasmPlugin` API instead of the `EnvoyFilter` custom resource. If you must use the `EnvoyFilter` custom resource, you must specify the spec in JSON format. ==== diff --git a/modules/ossm-threescale-webassembly-module-credentials-object.adoc b/modules/ossm-threescale-webassembly-module-credentials-object.adoc index 948e96de8500..0ed075015c78 100644 --- a/modules/ossm-threescale-webassembly-module-credentials-object.adoc +++ b/modules/ossm-threescale-webassembly-module-credentials-object.adoc @@ -11,12 +11,12 @@ All fields are optional, but you must specify at least one, `user_key` or `app_i [source,yaml] ---- -apiVersion: maistra.io/v1 -kind: ServiceMeshExtension +apiVersion: extensions.istio.io/v1alpha1 +kind: WasmPlugin metadata: - name: threescale-wasm-auth + name: spec: - config: + pluginConfig: ... services: - credentials: diff --git a/modules/ossm-threescale-webassembly-module-lookup-queries.adoc b/modules/ossm-threescale-webassembly-module-lookup-queries.adoc index 956f636944ca..76b4c81d13f4 100644 --- a/modules/ossm-threescale-webassembly-module-lookup-queries.adoc +++ b/modules/ossm-threescale-webassembly-module-lookup-queries.adoc @@ -13,12 +13,12 @@ A `lookup query` is made up of a single field, a source object, which can be one [source,yaml] ---- -apiVersion: maistra.io/v1 -kind: ServiceMeshExtension +apiVersion: extensions.istio.io/v1alpha1 +kind: WasmPlugin metadata: - name: threescale-wasm-auth + name: spec: - config: + pluginConfig: ... services: - credentials: diff --git a/modules/ossm-threescale-webassembly-module-mapping-rule-object.adoc b/modules/ossm-threescale-webassembly-module-mapping-rule-object.adoc index 3818361c75ae..c999cc7acf6a 100644 --- a/modules/ossm-threescale-webassembly-module-mapping-rule-object.adoc +++ b/modules/ossm-threescale-webassembly-module-mapping-rule-object.adoc @@ -47,12 +47,12 @@ The example below uses a `GET` request to a path, `/products/1/sold`, that match .`mapping_rules` `GET` request example [source,yaml] ---- -apiVersion: maistra.io/v1 -kind: ServiceMeshExtension +apiVersion: extensions.istio.io/v1alpha1 +kind: WasmPlugin metadata: - name: threescale-wasm-auth + name: spec: - config: + pluginConfig: ... mapping_rules: - method: GET diff --git a/modules/ossm-threescale-webassembly-module-minimal-working-configuration.adoc b/modules/ossm-threescale-webassembly-module-minimal-working-configuration.adoc index 8e774af7f479..be79f5e0459e 100644 --- a/modules/ossm-threescale-webassembly-module-minimal-working-configuration.adoc +++ b/modules/ossm-threescale-webassembly-module-minimal-working-configuration.adoc @@ -9,28 +9,29 @@ The following is an example of a 3scale WebAssembly module minimal working confi [source,yaml] ---- -apiVersion: maistra.io/v1 -kind: ServiceMeshExtension +apiVersion: extensions.istio.io/v1alpha1 +kind: WasmPlugin metadata: - name: threescale-auth + name: spec: - image: registry.redhat.io/openshift-service-mesh/3scale-auth-wasm-rhel8:0.0.1 - phase: PostAuthZ + url: oci://registry.redhat.io/3scale-amp2/3scale-auth-wasm-rhel8:0.0.3 + imagePullSecret: + phase: AUTHZ priority: 100 - workloadSelector: + selector: labels: - app: productpage - config: + app: + pluginConfig: api: v1 system: - name: system-name + name: upstream: name: outbound|443||multitenant.3scale.net url: https://istiodevel-admin.3scale.net/ timeout: 5000 - token: atoken + token: backend: - name: backend-name + name: upstream: name: outbound|443||su1.3scale.net url: https://su1.3scale.net/ @@ -39,49 +40,28 @@ spec: - no_body services: - id: '2555417834780' - token: service_token authorities: - "*" credentials: + user_key: + - query_string: + keys: + - + - header: + keys: + - app_id: - - header: - keys: - - app_id - - query_string: - keys: - - app_id - - application_id + - query_string: + keys: + - + - header: + keys: + - app_key: - - header: - keys: - - app_key - - query_string: - keys: - - app_key - - application_key - user_key: - - query_string: - keys: - - user_key - - header: - keys: - - user_key - mapping_rules: - - method: GET - pattern: "/" - usages: - - name: Hits - delta: 1 - - method: GET - pattern: "/o{*}c" - usages: - - name: oidc - delta: 1 - - name: Hits - delta: 1 - - method: any - pattern: "/{anything}?bigsale={*}" - usages: - - name: sale - delta: 5 ----- + - query_string: + keys: + - + - header: + keys: + - +---- \ No newline at end of file diff --git a/modules/ossm-threescale-webassembly-module-services-object.adoc b/modules/ossm-threescale-webassembly-module-services-object.adoc index a50e4d3b9d04..ef9887c5326d 100644 --- a/modules/ossm-threescale-webassembly-module-services-object.adoc +++ b/modules/ossm-threescale-webassembly-module-services-object.adoc @@ -13,12 +13,12 @@ The `services` field is required. It is an array that must contain at least one [source,yaml] ---- -apiVersion: maistra.io/v1 -kind: ServiceMeshExtension +apiVersion: extensions.istio.io/v1alpha1 +kind: WasmPlugin metadata: - name: threescale-wasm-auth + name: spec: - config: + pluginConfig: ... services: - id: "2555417834789" @@ -46,7 +46,7 @@ a|`token` a|This `token` can be found in the proxy configuration for your service in System or you can retrieve the it from System with following `curl` command: `curl \https:///admin/api/services//proxy/configs/production/latest.json?access_token=" \| jq '.proxy_config.content.backend_authentication_value` -|Yes +|Optional a|`authorities` |An array of strings, each one representing the _Authority_ of a _URL_ to match. These strings accept glob patterns supporting the asterisk (_*_), plus sign (_+_), and question mark (_?_) matchers. @@ -58,5 +58,5 @@ a|`credentials` a|`mapping_rules` |An array of objects representing mapping rules and 3scale methods to hit. -|Yes +|Optional |=== diff --git a/modules/ossm-threescale-webassembly-module-system-object.adoc b/modules/ossm-threescale-webassembly-module-system-object.adoc index 3a5e230205cc..498483558e60 100644 --- a/modules/ossm-threescale-webassembly-module-system-object.adoc +++ b/modules/ossm-threescale-webassembly-module-system-object.adoc @@ -11,17 +11,16 @@ When you provide static configuration objects in addition to the `system` object [source,yaml] ---- -apiVersion: maistra.io/v1 -kind: ServiceMeshExtension +apiVersion: extensions.istio.io/v1alpha1 +kind: WasmPlugin metadata: - name: threescale-wasm-auth + name: spec: - ... - config: + pluginConfig: system: - name: saas_porta + name: upstream: - token: myaccount_token + token: ttl: 300 ... ---- diff --git a/service_mesh/v2x/ossm-threescale-webassembly-module.adoc b/service_mesh/v2x/ossm-threescale-webassembly-module.adoc index a99bb9259c0c..01c595731685 100644 --- a/service_mesh/v2x/ossm-threescale-webassembly-module.adoc +++ b/service_mesh/v2x/ossm-threescale-webassembly-module.adoc @@ -38,6 +38,11 @@ endif::[] include::modules/ossm-configuring-the-threescale-wasm-auth-module.adoc[leveloffset=+1] +[role="_additional-resources"] +.Additional resources +* xref:../../service_mesh/v2x/ossm-extensions.adoc#ossm-extensions-migration-overview_ossm-extensions[Migrating from `ServiceMeshExtension` to `WasmPlugin` resources] +* link:https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources[Custom Resources] + include::modules/ossm-threescale-applying-external-service-entry-objects.adoc[leveloffset=+1] include::modules/ossm-threescale-webassembly-module-configuration.adoc[leveloffset=+1] @@ -68,4 +73,4 @@ include::modules/ossm-threescale-webassembly-module-mapping-rule-object.adoc[lev include::modules/ossm-threescale-webassembly-module-examples-for-credentials-use-cases.adoc[leveloffset=+1] -include::modules/ossm-threescale-webassembly-module-minimal-working-configuration.adoc[leveloffset=+1] +include::modules/ossm-threescale-webassembly-module-minimal-working-configuration.adoc[leveloffset=+1] \ No newline at end of file