Skip to content

Commit 3b65bc3

Browse files
abrennan89abrennan89
authored
Merge pull request #36249 from dfennessy/THREESCALE-7497
THREESCALE-7497: Removal of 3scale Istio adapter docs to add 3scale WebAssembly docs.
2 parents e724897 + 614818d commit 3b65bc3

20 files changed

+1010
-1
lines changed

‎_topic_map.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2787,6 +2787,8 @@ Topics:
27872787
File: ossm-federation
27882788
- Name: Extensions
27892789
File: ossm-extensions
2790+
- Name: The 3scale WebAssembly module
2791+
File: ossm-threescale-webassembly-module
27902792
- Name: Using the 3scale Istio adapter
27912793
File: threescale-adapter
27922794
- Name: Troubleshooting Service Mesh

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

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
// Module included in the following assembly:
2+
//
3+
// service_mesh/v2x/ossm-threescale-webassembly-module.adoc
4+
5+
[id="ossm-configuring-the-threescale-wasm-auth-module_{context}"]
6+
= Configuring the threescale-wasm-auth module
7+
8+
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.
9+
10+
[id="the-service-mesh-extension_{context}"]
11+
== The Service Mesh extension
12+
13+
{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.
14+
15+
[NOTE]
16+
====
17+
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.
18+
====
19+
20+
.Prerequisites
21+
22+
* Identify a Kubernetes workload and namespace on your {ProductShortName} deployment that you will apply this module.
23+
* 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.
24+
* 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].
25+
** The following example is the YAML format for the custom resource for `threescale-wasm-auth` module.
26+
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:
27+
+
28+
[source,yaml]
29+
----
30+
apiVersion: maistra.io/v1
31+
kind: ServiceMeshExtension
32+
metadata:
33+
name: threescale-wasm-auth
34+
namespace: bookinfo <1>
35+
spec:
36+
workloadSelector: <2>
37+
labels:
38+
app: productpage
39+
config: <yaml_configuration>
40+
image: registry.redhat.io/openshift-service-mesh/3scale-auth-wasm-rhel8:0.0.1
41+
phase: PostAuthZ
42+
priority: 100
43+
----
44+
<1> The `namespace`.
45+
<2> The `WorkloadSelector`.
46+
* 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.
47+
** The `spec.config` field varies depending on the application. All other fields persist across multiple instances of this custom resource. As examples:
48+
+
49+
--
50+
*** `image`: Only changes when newer versions of the module are deployed.
51+
*** `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.
52+
--
53+
* After you have the module configuration in `spec.config` and the rest of the custom resource, apply it with the `oc apply` command:
54+
+
55+
[source,terminal]
56+
----
57+
$ oc apply -f threescale-wasm-auth-bookinfo.yaml
58+
----
59+
60+
.Additional resources
61+
* xref:../../service_mesh/v2x/ossm-extensions.adoc#ossm-extensions-deploy_ossm-extensions[Deploying extensions]
62+
* link:https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources[Custom Resources]

‎modules/ossm-extensions-wasm-deploy.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
.Example ServiceMeshExtension resource extension.yaml
1111
[source,yaml]
1212
----
13-
apiVersion: maistra.io/v1alpha1
13+
apiVersion: maistra.io/v1
1414
kind: ServiceMeshExtension
1515
metadata:
1616
name: header-append

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

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
// Module included in the following assembly:
2+
//
3+
// service_mesh/v2x/ossm-threescale-webassembly-module.adoc
4+
5+
[id="ossm-threescale-applying-external-service-entry-objects_{context}"]
6+
= Applying 3scale external ServiceEntry objects
7+
8+
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.
9+
10+
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.
11+
12+
.Procedure
13+
14+
* Apply the following external `ServiceEntry` custom resources to your cluster:
15+
+
16+
.Custom resource for 3scale Hosted backend
17+
[source,terminal]
18+
----
19+
apiVersion: networking.istio.io/v1beta1
20+
kind: ServiceEntry
21+
metadata:
22+
name: threescale-saas-backend
23+
spec:
24+
hosts:
25+
- su1.3scale.net
26+
ports:
27+
- number: 443
28+
name: https
29+
protocol: HTTPS
30+
location: MESH_EXTERNAL
31+
resolution: DNS
32+
----
33+
+
34+
.Custom resource for 3scale Hosted system
35+
[source,terminal]
36+
----
37+
apiVersion: networking.istio.io/v1beta1
38+
kind: ServiceEntry
39+
metadata:
40+
name: threescale-saas-system
41+
spec:
42+
hosts:
43+
- multitenant.3scale.net
44+
ports:
45+
- number: 443
46+
name: https
47+
protocol: HTTPS
48+
location: MESH_EXTERNAL
49+
resolution: DNS
50+
----
51+
+
52+
You can use the `oc apply` command with either of the following methods to apply the objects:
53+
54+
** Save the objects to one or more files, and then use the following syntax:
55+
+
56+
[source,terminal]
57+
----
58+
$ oc apply -f <filename.yml>
59+
----
60+
61+
** To apply the objects without first saving them to a file, use the following command:
62+
+
63+
[source,terminal]
64+
----
65+
$ echo -n "<filename.yml>" | oc apply -f -
66+
----
67+
68+
Alternatively, you can deploy an in-mesh 3scale service. To do this, change the location of these services in the custom resources.
69+
70+
.Additional resources
71+
* xref:../../service_mesh/v2x/ossm-traffic-manage.adoc#ossm-routing-se_routing-traffic[`ServiceEntry` documentation]

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

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
// Module included in the following assembly:
2+
//
3+
// service_mesh/v2x/ossm-threescale-webassembly-module.adoc
4+
5+
[id="threescale-configuring-the-threescale-webassembly-module_{context}"]
6+
= Configuring the 3scale WebAssembly module
7+
8+
The architecture of the 3scale WebAssembly module configuration depends on the 3scale account and authorization service, and the list of services to handle.
9+
10+
.Prerequisites
11+
12+
The prerequisites are a set of minimum mandatory fields in all cases:
13+
14+
* For the 3scale account and authorization service: the `backend-listener` URL.
15+
* For the list of services to handle: the service IDs and at least one credential look up method and where to find it.
16+
* You will find examples for dealing with `userkey`, `appid` with `appkey`, and OpenID Connect (OIDC) patterns.
17+
* 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

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
// Module included in the following assembly:
2+
//
3+
// service_mesh/v2x/ossm-threescale-webassembly-module.adoc
4+
5+
[id="ossm-threescale-webassembly-module-api-object_{context}"]
6+
= The 3scale WebAssembly module api object
7+
8+
The `api` top-level string from the 3scale WebAssembly module defines which version of the configuration the module will use.
9+
10+
[NOTE]
11+
====
12+
A non-existent or unsupported version of the `api` object renders the 3scale WebAssembly module inoperable.
13+
====
14+
15+
.The `api` top-level string example
16+
[source,yaml]
17+
----
18+
apiVersion: maistra.io/v1
19+
kind: ServiceMeshExtension
20+
metadata:
21+
name: threescale-wasm-auth
22+
namespace: bookinfo
23+
spec:
24+
config:
25+
api: v1
26+
...
27+
----
28+
29+
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

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
// Module included in the following assembly:
2+
//
3+
// service_mesh/v2x/ossm-threescale-webassembly-module.adoc
4+
5+
[id="ossm-threescale-webassembly-module-backend-object_{context}"]
6+
= The 3scale WebAssembly module backend object
7+
8+
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.
9+
10+
[source,yaml]
11+
----
12+
apiVersion: maistra.io/v1
13+
kind: ServiceMeshExtension
14+
metadata:
15+
name: threescale-wasm-auth
16+
spec:
17+
config:
18+
...
19+
backend:
20+
name: backend
21+
upstream: <object>
22+
...
23+
----
24+
25+
.`backend` object fields
26+
|===
27+
|Name |Description |Required
28+
29+
a|`name`
30+
|An identifier for the 3scale backend, currently not referenced elsewhere.
31+
|Optional
32+
33+
a|`upstream`
34+
|The details about a network host to be contacted. This must refer to the 3scale Account Management API host, known, system.
35+
|Yes. The most important and required field.
36+
|===

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

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
// Module included in the following assembly:
2+
//
3+
// service_mesh/v2x/ossm-threescale-webassembly-module.adoc
4+
5+
[id="ossm-threescale-webassembly-module-configuration_{context}"]
6+
= The 3scale WebAssembly module configuration
7+
8+
The `ServiceMeshExtension` custom resource spec provides the configuration that the `Proxy-WASM` module reads from.
9+
10+
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.
11+
12+
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.
13+
14+
[IMPORTANT]
15+
====
16+
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.
17+
If you must use the `EnvoyFilter` custom resource, you must specify the spec in JSON format.
18+
====

‎modules/ossm-threescale-webassembly-module-credentials-object.adoc

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
// Module included in the following assembly:
2+
//
3+
// service_mesh/v2x/ossm-threescale-webassembly-module.adoc
4+
5+
[id="ossm-threescale-webassembly-module-credentials-object_{context}"]
6+
= The 3scale WebAssembly module credentials object
7+
8+
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.
9+
10+
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.
11+
12+
[source,yaml]
13+
----
14+
apiVersion: maistra.io/v1
15+
kind: ServiceMeshExtension
16+
metadata:
17+
name: threescale-wasm-auth
18+
spec:
19+
config:
20+
...
21+
services:
22+
- credentials:
23+
user_key: <array_of_lookup_queries>
24+
app_id: <array_of_lookup_queries>
25+
app_key: <array_of_lookup_queries>
26+
...
27+
----
28+
29+
.`credentials` object fields
30+
|===
31+
|Name |Description |Required
32+
33+
a|`user_key`
34+
|This is an array of lookup queries that defines a 3scale user key. A user key is commonly known as an API key.
35+
|Optional
36+
37+
a|`app_id`
38+
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`.
39+
|Optional
40+
41+
a|`app_key`
42+
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.
43+
|Optional
44+
|===

0 commit comments

Comments
 (0)