1. Documentation
    2. history bug_report picture_as_pdf
×

Using the 3scale WebAssembly module

The threescale-wasm-auth module runs on integrations of 3scale API Management 2.11 or later with Red Hat OpenShift Service Mesh 2.1.0 or later.

The threescale-wasm-auth module is a WebAssembly module that uses a set of interfaces, known as an application binary interfaces (ABI). This is defined by the Proxy-WASM specification to drive any piece of software that implements the ABI so it can authorize HTTP requests against 3scale.

As an ABI specification, Proxy-WASM defines the interaction between a piece of software named host and another named module, program, or extension. The host exposes a set of services used by the module to perform a task, and in this case, to process proxy requests.

The host environment is composed of a WebAssembly virtual machine interacting with a piece of software, in this case, an HTTP proxy.

The module itself runs in isolation to the outside world except for the instructions it runs on the virtual machine and the ABI specified by Proxy-WASM. This is a safe way to provide extension points to software: the extension can only interact in well-defined ways with the virtual machine and the host. The interaction provides a computing model and a connection to the outside world the proxy is meant to have.

Compatibility

The threescale-wasm-auth module is designed to be fully compatible with all implementations of the Proxy-WASM ABI specification. At this point, however, it has only been thoroughly tested to work with the Envoy reverse proxy.

Usage as a stand-alone module

Because of its self-contained design, it is possible to configure this module to work with Proxy-WASM proxies independently of Service Mesh, as well as 3scale Istio adapter deployments.

Prerequisites

  • The module works with all supported 3scale releases, except when configuring a service to use OpenID connect (OIDC), which requires 3scale 2.11 or later.

Configuring the threescale-wasm-auth module

Cluster administrators on OpenShift Container Platform 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.

The Service Mesh extension

Service Mesh provides a custom resource definition to specify and apply Proxy-WASM extensions to sidecar proxies, known as ServiceMeshExtension. Service Mesh applies this custom resource to the set of workloads that require HTTP API management with 3scale.

See custom resource definition for more information.

Configuring 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 Service Mesh deployment that you will apply this module.

  • You must have a 3scale tenant account. See SaaS or 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 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 Service Mesh, 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:

      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:

    $ oc apply -f threescale-wasm-auth-bookinfo.yaml
Additional resources

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 do this within Red Hat OpenShift Service Mesh by applying an external ServiceEntry object and a corresponding DestinationRule object for TLS configuration to use the HTTPS protocol.

The custom resources (CRs) set up the service entries and destination rules for secure access from within Service Mesh 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

  1. Apply the following external ServiceEntry CR and related DestinationRule CR for 3scale Hosted backend to your cluster:

    1. Add the ServiceEntry CR to a file called service-entry-threescale-saas-backend.yml:

      ServiceEntry CR
      apiVersion: networking.istio.io/v1beta1
kind: ServiceEntry
metadata:
  name: service-entry-threescale-saas-backend
spec:
  hosts:
  - su1.3scale.net
  ports:
  - number: 443
    name: https
    protocol: HTTPS
  location: MESH_EXTERNAL
  resolution: DNS

    2. Add the DestinationRule CR to a file called destination-rule-threescale-saas-backend.yml:

      DestinationRule CR
      apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: destination-rule-threescale-saas-backend
spec:
  host: su1.3scale.net
  trafficPolicy:
    tls:
      mode: SIMPLE
      sni: su1.3scale.net

    3. Apply and save the external ServiceEntry CR for the 3scale Hosted backend to your cluster, by running the following command:

      $ oc apply -f service-entry-threescale-saas-backend.yml

    4. Apply and save the external DestinationRule CR for the 3scale Hosted backend to your cluster, by running the following command:

      $ oc apply -f destination-rule-threescale-saas-backend.yml

  2. Apply the following external ServiceEntry CR and related DestinationRule CR for 3scale Hosted system to your cluster:

    1. Add the ServiceEntry CR to a file called service-entry-threescale-saas-system.yml:

      ServiceEntry CR
      apiVersion: networking.istio.io/v1beta1
kind: ServiceEntry
metadata:
  name: service-entry-threescale-saas-system
spec:
  hosts:
  - multitenant.3scale.net
  ports:
  - number: 443
    name: https
    protocol: HTTPS
  location: MESH_EXTERNAL
  resolution: DNS

    2. Add the DestinationRule CR to a file called destination-rule-threescale-saas-system.yml:

      DestinationRule CR
      apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: destination-rule-threescale-saas-system
spec:
  host: multitenant.3scale.net
  trafficPolicy:
    tls:
      mode: SIMPLE
      sni: multitenant.3scale.net

    3. Apply and save the external ServiceEntry CR for the 3scale Hosted system to your cluster, by running the following command:

      $ oc apply -f service-entry-threescale-saas-system.yml

    4. Apply and save the external DestinationRule CR for the 3scale Hosted system to your cluster, by running the following command:

      $ oc apply -f <destination-rule-threescale-saas-system.yml>

Alternatively, you can deploy an in-mesh 3scale service. To deploy an in-mesh 3scale service, change the location of the services in the CR by deploying 3scale and linking to the deployment.

Additional resources

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.

The EnvoyFilter custom resource is not a supported API, although it can be used in some 3scale Istio adapter or Service Mesh 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.

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.

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.

A non-existent or unsupported version of the api object renders the 3scale WebAssembly module inoperable.
The api top-level string example
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.