Merge pull request #54995 from dfennessy/THREESCALE-8781

THREESCALE-8781: Updates for 3scale-auth-wasm.

Author: kelbrown20

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 `<product_page>` 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: <threescale_wasm_plugin_name>
+  namespace: <bookinfo> <1>
 spec:
-  workloadSelector: <2>
+  selector: <2>
     labels:
-      app: productpage
-  config: <yaml_configuration>
-  image: registry.redhat.io/openshift-service-mesh/3scale-auth-wasm-rhel8:0.0.1
-  phase: PostAuthZ
+      app: <product_page>
+  pluginConfig: <yaml_configuration>
+  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 `<yaml_configuration>` 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 `<yaml_configuration>` 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]

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.

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: <threescale_wasm_plugin_name>
+  namespace: <bookinfo>
 spec:
-  config:
+  pluginConfig:
     api: v1
 ...
 ----

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: <threescale_wasm_plugin_name>
 spec:
-  config:
+  pluginConfig:
     ...
     backend:
       name: backend

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.
 ====

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: <threescale_wasm_plugin_name>
 spec:
-  config:
+  pluginConfig:
     ...
     services:
     - credentials:

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: <threescale_wasm_plugin_name>
 spec:
-  config:
+  pluginConfig:
     ...
     services:
     - credentials:

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: <threescale_wasm_plugin_name>
 spec:
-  config:
+  pluginConfig:
     ...
     mapping_rules:
       - method: GET

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: <threescale_wasm_plugin_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: <optional_pull_secret_resource>
+  phase: AUTHZ
   priority: 100
-  workloadSelector:
+  selector:
     labels:
-      app: productpage
-  config:
+      app: <product_page>
+  pluginConfig:
     api: v1
     system:
-      name: system-name
+      name: <system_name>
       upstream:
         name: outbound|443||multitenant.3scale.net
         url: https://istiodevel-admin.3scale.net/
         timeout: 5000
-      token: atoken
+      token: <token>
     backend:
-      name: backend-name
+      name: <backend_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:
+                - <user_key>
+          - header:
+              keys:
+                - <user_key>
         app_id:
-        - header:
-            keys:
-            - app_id
-        - query_string:
-            keys:
-            - app_id
-            - application_id
+          - query_string:
+              keys:
+                - <app_id>
+          - header:
+              keys:
+                - <app_id>
         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:
+                - <app_key>
+          - header:
+              keys:
+                - <app_key>
+----

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: <threescale_wasm_plugin_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://<system_host>/admin/api/services/<service_id>/proxy/configs/production/latest.json?access_token=<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
 |===