6894-3scaleIstioAdapterUpdates: Added updates for the procedure to configure the integration setting in 3scale

dfennessy · dfennessy · commit 98e99fc03f1e · 2021-07-01T11:41:56.000+01:00
diff --git a/modules/ossm-cr-example.adoc b/modules/ossm-cr-example.adoc
@@ -3,7 +3,7 @@
 // * service_mesh/v2x/customizing-installation-ossm.adoc
 
 [id="ossm-cr-example_{context}"]
-= Control plane parameters 
+= Control plane parameters
 
 The following table lists the top-level parameters for the `ServiceMeshControlPlane` resource.
 
@@ -187,9 +187,9 @@ spec:
       some-other-egress-gateway: {}
 
   policy:
-    type: Istiod # or Mixer
+    type: Mixer
     mixer: # only applies if policy.type: Mixer
-      enableChecks: false
+      enableChecks: true
       failOpen: false
 
   telemetry:
diff --git a/modules/ossm-mixer-policy-1x.adoc b/modules/ossm-mixer-policy-1x.adoc
@@ -10,6 +10,7 @@ In previous versions of {ProductName}, Mixer’s policy enforcement was enabled
 .Prerequisites
 * Access to the {product-title} Command-line Interface (CLI) also known as `oc`.
 
+NOTE: The examples use <istio-system> as the control plane namespace. Replace this value with the namespace where you deployed the Service Mesh Control Plane (SMCP).
 
 .Procedure
 
@@ -19,14 +20,14 @@ In previous versions of {ProductName}, Mixer’s policy enforcement was enabled
 +
 [source,terminal]
 ----
-$ oc get cm -n istio-system istio -o jsonpath='{.data.mesh}' | grep disablePolicyChecks
+$ oc get cm -n <istio-system> istio -o jsonpath='{.data.mesh}' | grep disablePolicyChecks
 ----
 
 . If `disablePolicyChecks: true`, edit the {ProductShortName} ConfigMap:
 +
 [source,terminal]
 ----
-$ oc edit cm -n istio-system istio
+$ oc edit cm -n <istio-system> istio
 ----
 
 . Locate `disablePolicyChecks: true` within the ConfigMap and change the value to `false`.
diff --git a/modules/ossm-mixer-policy.adoc b/modules/ossm-mixer-policy.adoc
@@ -10,6 +10,7 @@ In previous versions of {ProductName}, Mixer’s policy enforcement was enabled
 .Prerequisites
 * Access to the {product-title} Command-line Interface (CLI) also known as `oc`.
 
+NOTE: The examples use <istio-system> as the control plane namespace. Replace this value with the namespace where you deployed the Service Mesh Control Plane (SMCP).
 
 .Procedure
 
@@ -19,14 +20,14 @@ In previous versions of {ProductName}, Mixer’s policy enforcement was enabled
 +
 [source,terminal]
 ----
-$ oc get cm -n istio-system istio -o jsonpath='{.data.mesh}' | grep disablePolicyChecks
+$ oc get cm -n <istio-system> istio -o jsonpath='{.data.mesh}' | grep disablePolicyChecks
 ----
 
 . If `disablePolicyChecks: true`, edit the {ProductShortName} ConfigMap:
 +
 [source,terminal]
 ----
-$ oc edit cm -n istio-system istio
+$ oc edit cm -n <istio-system> istio
 ----
 
 . Locate `disablePolicyChecks: true` within the ConfigMap and change the value to `false`.
diff --git a/modules/ossm-threescale-integrate-1x.adoc b/modules/ossm-threescale-integrate-1x.adoc
@@ -24,12 +24,15 @@ To configure the 3scale Istio Adapter, refer to {ProductName} custom resources f
 
 [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.
+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`.
 ====
 
-. Modify the handler configuration with your 3scale configuration.
+Use a single handler per 3scale account by following the steps below:
+
+.Procedure
+
+. Create a handler for your 3scale account and specify your account credentials. Omit any service identifier.
 +
-.Handler configuration example
 [source,yaml]
 ----
   apiVersion: "config.istio.io/v1alpha2"
@@ -39,15 +42,18 @@ Pay particular attention to the `kind: handler` resource. You must update this w
   spec:
    adapter: threescale
    params:
-     service_id: "<SERVICE_ID>"
      system_url: "https://<organization>-admin.3scale.net/"
      access_token: "<ACCESS_TOKEN>"
    connection:
      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.
-
++
+. Edit or patch the Deployment resource of any services belonging to your 3scale account as follows:
+.. Add the `"service-mesh.3scale.net/service-id"` label with a value corresponding to a valid `service_id`.
+.. Add the `"service-mesh.3scale.net/credentials"` label with its value being the _name of the handler resource_ from step 1.
+. Do step 2 to link it to your 3scale account credentials and to its service identifier, whenever you intend to add more services.
 . Modify the rule configuration with your 3scale configuration to dispatch the rule to the threescale handler.
 +
 .Rule configuration example
diff --git a/modules/ossm-threescale-integrate.adoc b/modules/ossm-threescale-integrate.adoc
@@ -27,12 +27,15 @@ To configure the 3scale Istio Adapter, refer to {ProductName} custom resources f
 
 [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.
+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`.
 ====
 
-. Modify the handler configuration with your 3scale configuration.
+Use a single handler per 3scale account by following the steps below:
+
+.Procedure
+
+. Create a handler for your 3scale account and specify your account credentials. Omit any service identifier.
 +
-.Handler configuration example
 [source,yaml]
 ----
   apiVersion: "config.istio.io/v1alpha2"
@@ -42,15 +45,18 @@ Pay particular attention to the `kind: handler` resource. You must update this w
   spec:
    adapter: threescale
    params:
-     service_id: "<SERVICE_ID>"
      system_url: "https://<organization>-admin.3scale.net/"
      access_token: "<ACCESS_TOKEN>"
    connection:
      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.
-
++
+. Edit or patch the Deployment resource of any services belonging to your 3scale account as follows:
+.. Add the `"service-mesh.3scale.net/service-id"` label with a value corresponding to a valid `service_id`.
+.. Add the `"service-mesh.3scale.net/credentials"` label with its value being the _name of the handler resource_ from step 1.
+. Do step 2 to link it to your 3scale account credentials and to its service identifier, whenever you intend to add more services.
 . Modify the rule configuration with your 3scale configuration to dispatch the rule to the threescale handler.
 +
 .Rule configuration example
diff --git a/modules/ossm-threescale-integration-settings.adoc b/modules/ossm-threescale-integration-settings.adoc
@@ -15,10 +15,16 @@ For 3scale SaaS customers, {ProductName} is enabled as part of the Early Access
 
 .Procedure
 
-. Navigate to *[your_API_name]* -> *Integration* -> *Configuration*.
+. Navigate to *[your_API_name]* -> *Integration*
 
-. At the top of the *Integration* page click on *edit integration settings* in the top right corner.
+. Click *Settings*.
 
-. Under the *Service Mesh* heading, click the *Istio* option.
+. Select the *Istio* option under _Deployment_.
++
+* The *API Key (user_key)* option under _Authentication_ is selected by default.
 
-. Scroll to the bottom of the page and click *Update Service*.
+. Click *Update Product* to save your selection.
+
+. Click *Configuration*.
+
+. Click *Update Configuration*.
diff --git a/modules/ossm-threescale-manifests.adoc b/modules/ossm-threescale-manifests.adoc
@@ -6,6 +6,12 @@
 [id="ossm-threescale-manifests_{context}"]
 = Generating manifests from a deployed adapter
 
+[NOTE]
+====
+* `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 link:https://github.com/3scale/3scale-istio-adapter/blob/v2.X/README.md#routing-service-traffic-through-the-adapter[Routing service traffic through the adapter] for more information.
+====
 
 . Run this command to generate manifests from a deployed adapter in the `istio-system` namespace:
 +
diff --git a/modules/ossm-threescale-templates.adoc b/modules/ossm-threescale-templates.adoc
@@ -6,14 +6,27 @@
 [id="ossm-threescale-templates_{context}"]
 = Generate templates from URL examples
 
-* This example generates templates allowing the token, URL pair to be shared by multiple services as a single handler:
+[NOTE]
+====
+* Run the following commands via `oc exec` from the 3scale adapter container image in xref:ossm-threescale-manifests_{context}[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`.
+====
+
+.Procedure
+
+* 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-gen-config --name=admin-credentials --url="https://<organization>-admin.3scale.net:443" --token="[redacted]"
+$ 3scale-config-gen --name=admin-credentials --url="https://<organization>-admin.3scale.net:443" --token="[redacted]"
 ----
-
-* This example generates the templates with the service ID embedded in the handler:
++
+* The following example generates the templates with the service ID embedded in the handler:
 +
 ----
-$ 3scale-gen-config --url="https://<organization>-admin.3scale.net" --name="my-unique-id" --service="123456789" --token="[redacted]"
+$ 3scale-config-gen --url="https://<organization>-admin.3scale.net" --name="my-unique-id" --service="123456789" --token="[redacted]"
 ----
+
+.Additional resources
+* link:https://access.redhat.com/documentation/en-us/red_hat_3scale_api_management/2.10/html-single/admin_portal_guide/index#tokens[Tokens].
