THREESCALE-7497: Removal of 3scale Istio adapter docs to add 3scale WebAssembly docs.

_topic_map.yml

@@ -2785,6 +2785,8 @@ Topics:
     File: ossm-federation
   - Name: Extensions
     File: ossm-extensions
+  - Name: The 3scale WebAssembly module
+    File: ossm-threescale-webassembly-module    
   - Name: Using the 3scale Istio adapter
     File: threescale-adapter
   - Name: Troubleshooting Service Mesh

modules/ossm-configuring-the-threescale-wasm-auth-module.adoc

@@ -0,0 +1,62 @@
+// Module included in the following assembly:
+//
+// service_mesh/v2x/ossm-threescale-webassembly-module.adoc
+
+[id="ossm-configuring-the-threescale-wasm-auth-module_{context}"]
+= Configuring the threescale-wasm-auth module
+
+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
+
+{ProductShortName} provides a xref:../../operators/understanding/crds/crd-extending-api-with-crds.adoc#crd-extending-api-with-crds[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`]. {ProductShortName} applies this custom resource to the set of workloads that require HTTP API management with 3scale.
+
+[NOTE]
+====
+Configuring the the WebAssembly extension is currently a manual process. Support for fetching the configuration for services from the 3scale system will be available in a future release.
+====
+
+.Prerequisites
+
+* Identify a Kubernetes workload and namespace on your {ProductShortName} 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].
+** 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 {ProductShortName}, 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:
++
+[source,yaml]
+----
+apiVersion: maistra.io/v1
+kind: ServiceMeshExtension
+metadata:
+  name: threescale-wasm-auth
+  namespace: bookinfo <1>
+spec:
+  workloadSelector: <2>
+    labels:
+      app: productpage
+  config: <yaml_configuration>
+  image: registry.redhat.io/openshift-service-mesh/3scale-auth-wasm-rhel8:0.0.1
+  phase: PostAuthZ
+  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:
++
+--
+*** `image`:  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:
++
+[source,terminal]
+----
+$ oc apply -f threescale-wasm-auth-bookinfo.yaml
+----
+
+.Additional resources
+* xref:../../service_mesh/v2x/ossm-extensions.adoc#ossm-extensions-deploy_ossm-extensions[Deploying extensions]
+* link:https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources[Custom Resources]

modules/ossm-extensions-wasm-deploy.adoc

@@ -10,7 +10,7 @@
 .Example ServiceMeshExtension resource extension.yaml
 [source,yaml]
 ----
-apiVersion: maistra.io/v1alpha1
+apiVersion: maistra.io/v1
 kind: ServiceMeshExtension
 metadata:
   name: header-append

modules/ossm-threescale-applying-external-service-entry-objects.adoc

@@ -0,0 +1,71 @@
+// Module included in the following assembly:
+//
+// service_mesh/v2x/ossm-threescale-webassembly-module.adoc
+
+[id="ossm-threescale-applying-external-service-entry-objects_{context}"]
+= Applying 3scale external ServiceEntry objects
+
+To have the `threescale-wasm-auth` module authorize requests against 3scale, the module must have access to 3scale services. You can accomplish this within {ProductName} and Istio by applying an external `ServiceEntry` object.
+
+The custom resources set up the service entries for access from within {ProductShortName} to 3scale Hosted (SaaS) for the backend and system components of the Service Management API and the Account Management API. The Service Management API receives queries for the authorization status of each request. The Account Management API provides API management configuration settings for your services.
+
+.Procedure
+
+* Apply the following external `ServiceEntry` custom resources to your cluster:
++
+.Custom resource for 3scale Hosted backend
+[source,terminal]
+----
+apiVersion: networking.istio.io/v1beta1
+kind: ServiceEntry
+metadata:
+  name: threescale-saas-backend
+spec:
+  hosts:
+  - su1.3scale.net
+  ports:
+  - number: 443
+    name: https
+    protocol: HTTPS
+  location: MESH_EXTERNAL
+  resolution: DNS
+----
++
+.Custom resource for 3scale Hosted system
+[source,terminal]
+----
+apiVersion: networking.istio.io/v1beta1
+kind: ServiceEntry
+metadata:
+  name: threescale-saas-system
+spec:
+  hosts:
+  - multitenant.3scale.net
+  ports:
+  - number: 443
+    name: https
+    protocol: HTTPS
+  location: MESH_EXTERNAL
+  resolution: DNS
+----
++
+You can use the `oc apply` command with either of the following methods to apply the objects:
+
+** Save the objects to one or more files, and then use the following syntax:
++
+[source,terminal]
+----
+$ oc apply -f <filename.yml>
+----
+
+** To apply the objects without first saving them to a file, use the following command:
++
+[source,terminal]
+----
+$ echo -n "<filename.yml>" | oc apply -f -
+----
+
+Alternatively, you can deploy an in-mesh 3scale service. To do this, change the location of these services in the custom resources.
+
+.Additional resources
+* xref:../../service_mesh/v2x/ossm-traffic-manage.adoc#ossm-routing-se_routing-traffic[`ServiceEntry` documentation]

modules/ossm-threescale-configuring-the-threescale-webassembly-module.adoc

@@ -0,0 +1,17 @@
+// Module included in the following assembly:
+//
+// service_mesh/v2x/ossm-threescale-webassembly-module.adoc
+
+[id="threescale-configuring-the-threescale-webassembly-module_{context}"]
+= Configuring the 3scale WebAssembly module
+
+The architecture of the 3scale WebAssembly module configuration depends on the 3scale account and authorization service, and the list of services to handle.
+
+.Prerequisites
+
+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.

modules/ossm-threescale-webassembly-module-api-object.adoc

@@ -0,0 +1,29 @@
+// Module included in the following assembly:
+//
+// service_mesh/v2x/ossm-threescale-webassembly-module.adoc
+
+[id="ossm-threescale-webassembly-module-api-object_{context}"]
+= The 3scale WebAssembly module api object
+
+The `api` top-level string from the 3scale WebAssembly module defines which version of the configuration the module will use.
+
+[NOTE]
+====
+A non-existent or unsupported version of the `api` object renders the 3scale WebAssembly module inoperable.
+====
+
+.The `api` top-level string example
+[source,yaml]
+----
+apiVersion: maistra.io/v1
+kind: ServiceMeshExtension
+metadata:
+  name: threescale-wasm-auth
+  namespace: bookinfo
+spec:
+  config:
+    api: v1
+...
+----
+
+The `api` entry defines the rest of the values for the configuration. The only accepted value is `v1`. New settings that break compatibility with the current configuration or need more logic that modules using `v1` cannot handle, will require different values.

modules/ossm-threescale-webassembly-module-backend-object.adoc

@@ -0,0 +1,36 @@
+// Module included in the following assembly:
+//
+// service_mesh/v2x/ossm-threescale-webassembly-module.adoc
+
+[id="ossm-threescale-webassembly-module-backend-object_{context}"]
+= The 3scale WebAssembly module backend object
+
+The `backend` top-level object specifies how to access the 3scale Service Management API for authorizing and reporting HTTP requests. This service is provided by the _Backend_ component of 3scale.
+
+[source,yaml]
+----
+apiVersion: maistra.io/v1
+kind: ServiceMeshExtension
+metadata:
+  name: threescale-wasm-auth
+spec:
+  config:
+    ...
+    backend:
+      name: backend
+      upstream: <object>
+    ...
+----
+
+.`backend` object fields
+|===
+|Name |Description |Required
+
+a|`name`
+|An identifier for the 3scale backend, currently not referenced elsewhere.
+|Optional
+
+a|`upstream`
+|The details about a network host to be contacted. This must refer to the 3scale Account Management API host, known, system.
+|Yes. The most important and required field.
+|===

modules/ossm-threescale-webassembly-module-configuration.adoc

@@ -0,0 +1,18 @@
+// Module included in the following assembly:
+//
+// service_mesh/v2x/ossm-threescale-webassembly-module.adoc
+
+[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 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.
+
+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.
+
+[IMPORTANT]
+====
+The `EnvoyFilter` custom resource is not a supported API, although it can be used in some 3scale Istio adapter or {ProductShortName} releases. Using the `EnvoyFilter` custom resource is not recommended. Use the `ServiceMeshExtension` 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

@@ -0,0 +1,44 @@
+// Module included in the following assembly:
+//
+// service_mesh/v2x/ossm-threescale-webassembly-module.adoc
+
+[id="ossm-threescale-webassembly-module-credentials-object_{context}"]
+= The 3scale WebAssembly module credentials object
+
+The `credentials` object is a component of the `service` object. `credentials` specifies which kind of credentials to be looked up and the steps to perform this action.
+
+All fields are optional, but you must specify at least one, `user_key` or `app_id`. The order in which you specify each credential is irrelevant because it is pre-established by the module. Only specify one instance of each credential.
+
+[source,yaml]
+----
+apiVersion: maistra.io/v1
+kind: ServiceMeshExtension
+metadata:
+  name: threescale-wasm-auth
+spec:
+  config:
+    ...
+    services:
+    - credentials:
+        user_key: <array_of_lookup_queries>
+        app_id: <array_of_lookup_queries>
+        app_key: <array_of_lookup_queries>
+    ...
+----
+
+.`credentials` object fields
+|===
+|Name |Description |Required
+
+a|`user_key`
+|This is an array of lookup queries that defines a 3scale user key. A user key is commonly known as an API key.
+|Optional
+
+a|`app_id`
+a|This is an array of lookup queries that define a 3scale application identifier. Application identifiers are provided by 3scale or by using an identity provider like link:https://access.redhat.com/products/red-hat-single-sign-on[Red Hat Single Sign-On (RH-SS0)], or OpenID Connect (OIDC). The resolution of the lookup queries specified here, whenever it is successful and resolves to two values, it sets up the `app_id` and the `app_key`.
+|Optional
+
+a|`app_key`
+a|This is an array of lookup queries that define a 3scale application key. Application keys without a resolved `app_id` are useless, so only specify this field when `app_id` has been specified.
+|Optional
+|===