The 3scale Istio Adapter is an optional adapter that allows you to label a service running within the Red Hat OpenShift Service Mesh and integrate that service with the 3scale API Management solution. It is not required for Red Hat OpenShift Service Mesh.

You can only use the 3scale Istio adapter with Red Hat OpenShift Service Mesh versions 2.0 and below. The Mixer component was deprecated in release 2.0 and removed in release 2.1. For Red Hat OpenShift Service Mesh versions 2.1.0 and later you should use the 3scale WebAssembly module.

If you want to enable 3scale backend cache with the 3scale Istio adapter, you must also enable Mixer policy and Mixer telemetry. See Deploying the Red Hat OpenShift Service Mesh control plane.

Integrate the 3scale adapter with Red Hat OpenShift Service Mesh

You can use these examples to configure requests to your services using the 3scale Istio Adapter.

  • Red Hat OpenShift Service Mesh version 2.x

  • A working 3scale account (SaaS or 3scale 2.9 On-Premises)

  • Enabling backend cache requires 3scale 2.9 or greater

  • Red Hat OpenShift Service Mesh prerequisites

  • Ensure Mixer policy enforcement is enabled. Update Mixer policy enforcement section provides instructions to check the current Mixer policy enforcement status and enable policy enforcement.

  • Mixer policy and telemetry must be enabled if you are using a mixer plugin.

    • You will need to properly configure the Service Mesh Control Plane (SMCP) when upgrading.

To configure the 3scale Istio Adapter, refer to Red Hat OpenShift Service Mesh custom resources for instructions on adding adapter parameters to the custom resource file.

Pay particular attention to the kind: handler resource. You must update this with your 3scale account credentials. You can optionally add a service_id to a handler, but this is kept for backwards compatibility only, since it would render the handler only useful for one service in your 3scale account. If you add service_id to a handler, enabling 3scale for other services requires you to create more handlers with different service_ids.

Use a single handler per 3scale account by following the steps below:

  1. Create a handler for your 3scale account and specify your account credentials. Omit any service identifier.

      apiVersion: "config.istio.io/v1alpha2"
      kind: handler
       name: threescale
       adapter: threescale
         system_url: "https://<organization>-admin.3scale.net/"
         access_token: "<ACCESS_TOKEN>"
         address: "threescale-istio-adapter:3333"

    Optionally, you can provide a backend_url field within the params section to override the URL provided by the 3scale configuration. This may be useful if the adapter runs on the same cluster as the 3scale on-premise instance, and you wish to leverage the internal cluster DNS.

  2. Edit or patch the Deployment resource of any services belonging to your 3scale account as follows:

    1. Add the "service-mesh.3scale.net/service-id" label with a value corresponding to a valid service_id.

    2. Add the "service-mesh.3scale.net/credentials" label with its value being the name of the handler resource from step 1.

  3. Do step 2 to link it to your 3scale account credentials and to its service identifier, whenever you intend to add more services.

  4. Modify the rule configuration with your 3scale configuration to dispatch the rule to the threescale handler.

    Rule configuration example
      apiVersion: "config.istio.io/v1alpha2"
      kind: rule
        name: threescale
        match: destination.labels["service-mesh.3scale.net"] == "true"
          - handler: threescale.handler
              - threescale-authorization.instance

Generating 3scale custom resources

The adapter includes a tool that allows you to generate the handler, instance, and rule custom resources.

Table 1. Usage
Option Description Required Default value

-h, --help

Produces help output for available options



Unique name for this URL, token pair


-n, --namespace

Namespace to generate templates



-t, --token

3scale access token


-u, --url

3scale Admin Portal URL



3scale backend URL. If set, it overrides the value that is read from system configuration


-s, --service

3scale API/Service ID



3scale authentication pattern to specify (1=API Key, 2=App Id/App Key, 3=OIDC)



-o, --output

File to save produced manifests to


Standard output


Outputs the CLI version and exits immediately


Generate templates from URL examples

  • Run the following commands via oc exec from the 3scale adapter container image in Generating manifests from a deployed adapter.

  • Use the 3scale-config-gen command to help avoid YAML syntax and indentation errors.

  • You can omit the --service if you use the annotations.

  • This command must be invoked from within the container image via oc exec.

  • Use the 3scale-config-gen command to autogenerate templates files allowing the token, URL pair to be shared by multiple services as a single handler:

    $ 3scale-config-gen --name=admin-credentials --url="https://<organization>-admin.3scale.net:443" --token="[redacted]"
  • The following example generates the templates with the service ID embedded in the handler:

    $ 3scale-config-gen --url="https://<organization>-admin.3scale.net" --name="my-unique-id" --service="123456789" --token="[redacted]"
Additional resources

Generating manifests from a deployed adapter

  • NAME is an identifier you use to identify with the service you are managing with 3scale.

  • The CREDENTIALS_NAME reference is an identifier that corresponds to the match section in the rule configuration. This is automatically set to the NAME identifier if you are using the CLI tool.

  • Its value does not need to be anything specific: the label value should just match the contents of the rule. See Routing service traffic through the adapter for more information.

  1. Run this command to generate manifests from a deployed adapter in the istio-system namespace:

    $ export NS="istio-system" URL="https://replaceme-admin.3scale.net:443" NAME="name" TOKEN="token"
    oc exec -n ${NS} $(oc get po -n ${NS} -o jsonpath='{.items[?(@.metadata.labels.app=="3scale-istio-adapter")].metadata.name}') \
    -it -- ./3scale-config-gen \
    --url ${URL} --name ${NAME} --token ${TOKEN} -n ${NS}
  2. This will produce sample output to the terminal. Edit these samples if required and create the objects using the oc create command.

  3. When the request reaches the adapter, the adapter needs to know how the service maps to an API on 3scale. You can provide this information in two ways:

    1. Label the workload (recommended)

    2. Hard code the handler as service_id

  4. Update the workload with the required annotations:

    You only need to update the service ID provided in this example if it is not already embedded in the handler. The setting in the handler takes precedence.

    $ export CREDENTIALS_NAME="replace-me"
    export SERVICE_ID="replace-me"
    export DEPLOYMENT="replace-me"
    patch="$(oc get deployment "${DEPLOYMENT}"
    patch="$(oc get deployment "${DEPLOYMENT}" --template='{"spec":{"template":{"metadata":{"labels":{ {{ range $k,$v := .spec.template.metadata.labels }}"{{ $k }}":"{{ $v }}",{{ end }}"service-mesh.3scale.net/service-id":"'"${SERVICE_ID}"'","service-mesh.3scale.net/credentials":"'"${CREDENTIALS_NAME}"'"}}}}}' )"
    oc patch deployment "${DEPLOYMENT}" --patch ''"${patch}"''

Routing service traffic through the adapter

Follow these steps to drive traffic for your service through the 3scale adapter.

  • Credentials and service ID from your 3scale administrator.

  1. Match the rule destination.labels["service-mesh.3scale.net/credentials"] == "threescale" that you previously created in the configuration, in the kind: rule resource.

  2. Add the above label to PodTemplateSpec on the Deployment of the target workload to integrate a service. the value, threescale, refers to the name of the generated handler. This handler stores the access token required to call 3scale.

  3. Add the destination.labels["service-mesh.3scale.net/service-id"] == "replace-me" label to the workload to pass the service ID to the adapter via the instance at request time.

Configure the integration settings in 3scale

Follow this procedure to configure the 3scale integration settings.

For 3scale SaaS customers, Red Hat OpenShift Service Mesh is enabled as part of the Early Access program.

  1. Navigate to [your_API_name]Integration

  2. Click Settings.

  3. Select the Istio option under Deployment.

    • The API Key (user_key) option under Authentication is selected by default.

  4. Click Update Product to save your selection.

  5. Click Configuration.

  6. Click Update Configuration.

Caching behavior

Responses from 3scale System APIs are cached by default within the adapter. Entries will be purged from the cache when they become older than the cacheTTLSeconds value. Also by default, automatic refreshing of cached entries will be attempted seconds before they expire, based on the cacheRefreshSeconds value. You can disable automatic refreshing by setting this value higher than the cacheTTLSeconds value.

Caching can be disabled entirely by setting cacheEntriesMax to a non-positive value.

By using the refreshing process, cached values whose hosts become unreachable will be retried before eventually being purged when past their expiry.

Authenticating requests

This release supports the following authentication methods:

  • Standard API Keys: single randomized strings or hashes acting as an identifier and a secret token.

  • Application identifier and key pairs: immutable identifier and mutable secret key strings.

  • OpenID authentication method: client ID string parsed from the JSON Web Token.

Applying authentication patterns

Modify the instance custom resource, as illustrated in the following authentication method examples, to configure authentication behavior. You can accept the authentication credentials from:

  • Request headers

  • Request parameters

  • Both request headers and query parameters

When specifying values from headers, they must be lower case. For example, if you want to send a header as User-Key, this must be referenced in the configuration as request.headers["user-key"].

API key authentication method

Service Mesh looks for the API key in query parameters and request headers as specified in the user option in the subject custom resource parameter. It checks the values in the order given in the custom resource file. You can restrict the search for the API key to either query parameters or request headers by omitting the unwanted option.

In this example, Service Mesh looks for the API key in the user_key query parameter. If the API key is not in the query parameter, Service Mesh then checks the user-key header.

API key authentication method example
apiVersion: "config.istio.io/v1alpha2"
kind: instance