In order to configure the 3scale Istio Adapter the user needs to refer to the OpenShift Service Mesh documentation and understand the requirements through the documentation for the 3scale Istio Adapter, which are spread in several chapters.

Also there is no explanation on how 3scale Istio Adapter works and what is the flow between the Service Mesh and 3scale API Management through the adapter.

The requests are:

• A quick fix of the existing documentation according to the comments added to this issue.
• To add a complete example, step by step, on how to configure 3scale-istio-adapter with Service Mesh, currently there is none.
• To add an overview of how 3scale Adapter works with 3scale, what is the purpose of the adapter and how is the flow (communication between components).
• To add a complete example, step by step, how to test this integration.

Comments on the existing documentation:

1. 3scale Adapter can be installed very easily via the cluster console for the Service Mesh Control Plane instance (e.g. basic ) by clicking on "Install 3Scale Adapter" button. This is not mentioned in the docs and should be added to the docs and called out. This is a very simple way to install the adapter.

2. Updating Mixer Policy:

Procedure Step 2, the following command

   $ oc get cm -n istio-system istio -o jsonpath='{.data.mesh}' | grep disablePolicyChecks

and Procedure, Step 3, the following commands

  $ oc edit cm -n istio-system istio

the config map name "istio" is hardcoded and needs to be modified. It seems to be derived from the name of Service Mesh Control Plane (SMCP) name. If installed following the docs, the SMCP name would be "basic". And the config map name is "istio-basic". There is a note elsewhere in the document which points out istio-system is used in the docs but any other project can be used. In other places in the documentation, I see <smcp-name> being used for SMCP name. So one suggestion would be to use istio-<smcp-name> instead of "istio" for the config map in the above commands.

3. Red Hat OpenShift Service Mesh custom resources has an example that shows the following fragment

   policy:
    type: Istiod # or Mixer
    mixer: # only applies if policy.type: Mixer
      enableChecks: false
      failOpen: false

3scale Adapter is a Mixer Plugin. So the .spec.policy.type would be set to "Mixer". However, it is not clear if "enableChecks" must be set to true in ServiceMeshControlPlane resource spec if disablePolicyChecks is already set to true globally.

In section 2.11.3. ServiceMeshControlPlane parameters > 2.11.3.1. Istio global example there is this note and example of global parameters:

NOTE
In order for the 3scale Istio Adapter to work, disablePolicyChecks must be false.

  istio:
    global:
      tag: 1.1.0
      hub: registry.redhat.io/openshift-service-mesh/
      proxy:
        resources:
          requests:
            cpu: 10m
            memory: 128Mi
          limits:
      mtls:
        enabled: false
      disablePolicyChecks: true
      policyCheckFailOpen: false
      imagePullSecrets:
        - MyPullSecret

What is the procedure to set “disablePolicyChecks” to false, through the configmaps or globally? If disablePolicyChecks is set globally should enableChecks=false be enabled under policy? Or which one takes precedence if both are set?

4. Integrate the 3scale adapter with Red Hat OpenShift Service Mesh Prerequisites Section

The Note

   NOTE
   Pay particular attention to the kind: handler resource. You must update this with your 3scale credentials and the service ID of the API you want to manage.

The above note contradicts the following Note in section 1.14.1.2. "Generating manifests from a deployed adapter".

  Update the workload with the required annotations:

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

The second note implies that the service ID need not be embedded in the handler as shown in the following fragment:

    params:
     service_id: "<SERVICE_ID>"
     system_url: "https://<organization>-admin.3scale.net/"
     access_token: "<ACCESS_TOKEN>"
   connection:

5. Integrate the 3scale adapter with Red Hat OpenShift Service Mesh, Section "2.12.1.1.1. Generate templates from URL examples"

The following snippets

  $ 3scale-gen-config --name=admin-credentials --url="https://<organization>-admin.3scale.net:443" --token="[redacted]"

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

3scale-gen-config should be "3scale-config-gen". Also, to execute 3scale-config-gen, you have to rsh into the 3scale-istio-adapter pod. The way it is written leads one to believe it is a stand alone cmd and it won't work. So oc rsh should be shown (for e.g.) as shown in the following section and reproduced below

  $ 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}

6. Integrate the 3scale adapter with Red Hat OpenShift Service Mesh, Section "2.12.1.2. Generating manifests from a deployed adapter"

This has the following section.

  $ 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}"''

It is not clear what "DEPLOYMENT" should be set to. There are 5 deployments for bookinfo

  $ oc project bookinfo
  $ oc get deployments
  NAME             READY   UP-TO-DATE   AVAILABLE   AGE
  details-v1       1/1     1            1           9d
  productpage-v1   1/1     1            1           9d
  ratings-v1       1/1     1            1           9d
  reviews-v1       1/1     1            1           9d
  reviews-v2       1/1     1            1           9d
  reviews-v3       1/1     1            1           9d

Need more details here.

Also, the above snippet "oc get deployment" assumes that it is being run in the project for app e.g. "bookinfo" project. To make it more general, we can change it to pass the project name so it can be run from any project/namespace. e.g.

  patch="$(oc get deployment -n "${BOOKINFO_NS}" "${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}"'"}}}}}' )"

Instead of ${BOOKINFO_NS}, using another convention for e.g. <bookinfo-ns> .

7. The list items shown below do not match the latest Service ( or Product ) configuration UI in 3scale and do not reflect the API as a Product

   2. At the top of the Integration page click on edit integration settings in the top right corner.
   3. Under the Service Mesh heading, click the Istio option.
   4. Scroll to the bottom of the page and click Update Service.

One way to rewrite this would be:

   2. In the Configuration, click on the Settings.
   3. Select Istio option in the right hand pane.
   4. Scroll to the bottom of the page and click Update Product.

8. In the chapter 1.15.1.2. Generating manifests from a deployed adapter the command:

export NS="istio-system" URL="https://replaceme-admin.3scale.net:443" NAME="name" TOKEN="token"

a NAME needs to be set.

Then in step 4. Update the workload with the required annotations:
it is not clear what CREDENTIALS_NAME is:

export CREDENTIALS_NAME="replace-me"

The CREDENTIALS_NAME should be the name of the handler and rule “threescale”.
Also is "threescale" a mandatory name or can be anything? This is not clear.

9. The same information is also in the chapter 2.12. Using the 3scale Istio adapter.