Merge pull request #13668 from geekspertise/servicemesh

TP8 Documentation and Release Notes Updates

servicemesh-install/servicemesh-install.adoc

@@ -14,6 +14,9 @@ include::servicemesh-install/topics/servicemesh-architecture.adoc[leveloffset=+2
 // Include supported configurations
 include::servicemesh-install/topics/install-supported-config.adoc[leveloffset=+2]
 
+//Include Service Mesh vs Istio comparison
+include::servicemesh-install/topics/servicemesh-istio-comparison.adoc[leveloffset=+2]
+
 // Include installation overview
 include::servicemesh-install/topics/install-overview.adoc[leveloffset=+2]
 

servicemesh-install/topics/appendix-threescale-adapter.adoc

@@ -1,20 +1,19 @@
 [[threescale-adapter]]
-3scale Istio Adapter
-The 3scale Istio Adapter allows you to label a service running within the {ProductName} and integrate that service with the 3Scale API Management solution.
+The 3scale Istio Adapter allows you to label a service running within the {ProductName} and integrate that service with the 3scale API Management solution.
 
 Prerequisites:
 
 * {ProductName} 0.7.0+
 * A working 3scale account (https://www.3scale.net/signup/[SaaS] or https://access.redhat.com/documentation/en-us/red_hat_3scale_api_management/2.4/html/infrastructure/onpremises-installation[On-Premises])
-* https://docs.openshift.com/container-platform/3.11/servicemesh-install/servicemesh-install.html#service-mesh-install_prerequisites[{ProductName} prerequisistes]
+* https://docs.openshift.com/container-platform/3.11/servicemesh-install/servicemesh-install.html#service-mesh-install_prerequisites[{ProductName} prerequisites]
 
 [NOTE]
 ====
 To configure the 3scale Istio Adapter, refer to https://docs.openshift.com/container-platform/3.11/servicemesh-install/servicemesh-install.html#install_chapter_3[Installing Service Mesh] for instructions on adding adapter parameters to the custom resource file.
 ====
 
 == Integrate the adapter with {ProductName}
-You can use these samples to configure request to your services using the 3scale Istio Adapter.
+You can use these examples to configure requests to your services using the 3scale Istio Adapter.
 
 [NOTE]
 ====
@@ -71,7 +70,7 @@ spec:
 ----
 
 === Routing service traffic through the adapter
-In order to drive traffic for your service through the adapter and be managed by 3scale, need to match the rule `destination.labels["service-mesh.3scale.net"] == "true"` that you previously created in the configuration, in the kind: rule resource.
+To drive traffic for your service through the 3scale adapter, you need to match the rule `destination.labels["service-mesh.3scale.net"] == "true"` that you previously created in the configuration, in the kind: rule resource.
 
 You must add a label to the PodTemplateSpec on the Deployment of the target workload. For example, in a `productpage` service, whose Pod is managed by the `productpage-v1` deployment, add the above label under `spec.template.labels` in `productpage-v1` to have the adapter authorize requests to this service.
 
@@ -135,12 +134,92 @@ Responses from 3scale System API's will be cached by default within the adapter.
 
 Caching can be disabled entirely by setting `cacheEntriesMax` to a non-positive value.
 
-Through the refreshing process, cached values whose hosts become unreachable will be retried before eventually being purged when past their expiry.
+By using the refreshing process, cached values whose hosts become unreachable will be retried before eventually being purged when past their expiry.
 
 = Authenticating requests
-For this Technology Preview release, the only supported authentication mechanism will be providing credentials as a query parameter using the API key method. The key should use the default “user_key” query value.
+This Technology Preview 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.
 
-See https://access.redhat.com/documentation/en-us/red_hat_3scale_api_management/2.4/html/api_authentication/authentication-patterns#authentication_patterns[authentication patterns] for more information.
+== 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
+
+=== API key authentication method
+{ProductShortName} 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 {ProductShortName} looks for the API key in the `user_key` query parameter. If the API key is not in the query parameter, {ProductShortName} then checks the `x-user-key` header.
+
+.API key authentication method example
+----
+apiVersion: "config.istio.io/v1alpha2"
+kind: instance
+metadata:
+  name: threescale-authorization
+  namespace: istio-system
+spec:
+  template: authorization
+  params:
+    subject:
+      user: request.query_params["user_key"] | request.headers["x-user-key"] | ""
+    action:
+      path: request.url_path
+      method: request.method | "get"
+----
+
+If you want the adapter to examine a different query parameter or request header, change the name as appropriate. For example, to check for the API key in a query parameter named “key”, change `request.query_params["user_key"]` to `request.query_params["key"]`.
+
+=== Application ID and application key pair authentication method
+{ProductShortName} looks for the application ID and application key in query parameters and request headers, as specified in the `properties` option in the `subject` custom resource parameter. The application key is optional. It checks the values in the order given in the custom resource file. You can restrict the search for the credentials to either query parameters or request headers by not including the unwanted option.
+
+In this example, {ProductShortName} looks for the application ID and application key in the query parameters first, moving on to the request headers if needed.
+
+.Application ID and application key pair authenticaiton method example
+----
+apiVersion: "config.istio.io/v1alpha2"
+kind: instance
+metadata:
+  name: threescale-authorization
+  namespace: istio-system
+spec:
+  template: authorization
+  params:
+    subject:
+        app_id: request.query_params["app_id"] | request.headers["x-app-id"] | ""
+        app_key: request.query_params["app_key"] | request.headers["x-app-key"] | ""
+    action:
+      path: request.url_path
+      method: request.method | "get"
+----
+
+If you want the adapter to examine a different query parameter or request header, change the name as appropriate. For example, to check for the application ID in a query parameter named “identification”, change `request.query_params["app_id"]` to `request.query_params["identification"]`.
+
+=== Hybrid authentication method
+You can choose to not enforce a particular authentication method and accept any valid credentials for either method. If both an API key and an application ID/application key pair are provided, {ProductShortName} uses the API key.
+
+In this example, {ProductShortName} checks for an API key in the query parameters, then the request headers. If there is no API key, it then checks for an application ID and key in the query parameters, then the request headers.
+
+.Hybrid authentication method example
+----
+apiVersion: "config.istio.io/v1alpha2"
+kind: instance
+metadata:
+  name: threescale-authorization
+  namespace: istio-system
+spec:
+  template: authorization
+  params:
+    subject:
+      user: request.query_params["user_key"] | request.headers["x-user-key"] | request.api_key | ""
+      properties:
+        app_id: request.query_params["app_id"] | request.headers["x-app-id"] | ""
+        app_key: request.query_params["app_key"] | request.headers["x-app-key"] | ""
+    action:
+      path: request.url_path
+      method: request.method | "get"
+----
 
 = Adapter metrics
-The adapter, by default reports various Prometheus metrics which are exposed on port `8080` at the `/metrics` endpoint. These allow some insight into how the interactions between the adapter and 3scale are performing. The service is labelled to be automatically discovered and scraped by Prometheus.
+The adapter, by default reports various Prometheus metrics that are exposed on port `8080` at the `/metrics` endpoint. These metrics allow some insight into how the interactions between the adapter and 3scale are performing. The service is labeled to be automatically discovered and scraped by Prometheus.

servicemesh-install/topics/application-requirements.adoc

@@ -20,17 +20,18 @@ oc adm policy add-scc-to-user privileged -z <service account> -n <namespace>
 
 [NOTE]
 ====
-The relaxing of security constraints is only necessary during the {ProductName} Tech Preview.
+The relaxing of security constraints is only necessary during the {ProductName} Technology Preview.
 ====
 
 [[updating-master-configuration]]
 == Updating the master configuration
 
 {ProductShortName} relies on the existence of a proxy sidecar within the application's pod to provide service mesh capabilities to the application. You can enable automatic sidecar injection or manage it manually. We recommend automatic injection by using the annotation, with no need to label namespaces, to ensure your application contains the appropriate configuration for your service mesh upon deployment. This method requires fewer privileges and does not conflict with other OpenShift capabilities such as builder pods.
 
+
 [NOTE]
 ====
- The upstream community version of Istio injects the sidecar by default if you have labeled the namespace. You are not required to label the namespace with {ProductName}. However, {ProductName} requires you to opt in to having the sidecar automatically injected to a deployment. This avoids injecting a sidecar where it is not wanted (for example, build or deploy pods). The webhook checks the configuration of pods deploying into all namespaces to see if they are opting in to injection with the appropriate annotation.
+The upstream version of Istio injects the sidecar by default if you have labeled the namespace. You are not required to label the namespace with {ProductName}. However, {ProductName} requires you to opt in to having the sidecar automatically injected to a deployment. This avoids injecting a sidecar where it is not wanted (for example, build or deploy pods). The webhook checks the configuration of pods deploying into all namespaces to see if they are opting in to injection with the appropriate annotation.
 ====
 
 To enable the automatic injection of the {ProductShortName} sidecar you must first modify the master configuration on each master to include support for webhooks and signing of Certificate Signing Requests (CSRs).

servicemesh-install/topics/document-attributes.adoc

@@ -13,7 +13,7 @@
 :ProductName: Red Hat OpenShift Service Mesh
 :ProductShortName: Service Mesh
 :ProductRelease:
-:ProductVersion: 0.7.TechPreview
+:ProductVersion: 0.8.TechPreview
 :product-build:
 :DownloadURL: registry.access.redhat.com
 //
@@ -33,4 +33,4 @@
 //
 :Install_BookName: Installing Red Hat OpenShift Service Mesh
 :Using_BookName: Using Red Hat OpenShift Service Mesh
-:RN_BookName: Red Hat OpenShift Service Mesh  Release Notes
+:RN_BookName: Red Hat OpenShift Service Mesh Release Notes

servicemesh-install/topics/install-overview.adoc

@@ -12,8 +12,8 @@ Depending on how you define the custom resource file, you can install one or mor
 
 * *Istio* - based on the  open source https://istio.io/[Istio] project, lets you connect, secure, control, and observe the microservices that make up your applications.
 * *Jaeger* - based on the opensource https://www.jaegertracing.io/[Jaeger] project, lets you perform tracing to monitor and troubleshoot transactions in complex distributed systems.
-* *Kiali* - based on the opensource https://www.kiali.io/[Kiali] project, Kiali provides observability for your service mesh.  Using Kiali lets you view configurations, monitor traffic, and view and analyze traces in a single console.
-* *Launcher* - based on the opensource  http://fabric8.io/[fabric8] community, this integrated development platform helps you build cloud native applications and microservices.  {ProductName} includes several boosters that let you explore features of the {ProductShortName}.
+* *Kiali* - based on the opensource https://www.kiali.io/[Kiali] project, Kiali provides observability for your service mesh. Using Kiali lets you view configurations, monitor traffic, and view and analyze traces in a single console.
+* *Launcher* - based on the opensource  http://fabric8.io/[fabric8] community, this integrated development platform helps you build cloud native applications and microservices. {ProductName} includes several boosters that let you explore features of the {ProductShortName}.
 
 During the installation the operator creates an Ansible job that runs an Ansible playbook that performs the following installation and configuration tasks automatically:
 

servicemesh-install/topics/install-post.adoc

@@ -28,7 +28,7 @@ openshift-ansible-istio-installer-job-fbtfj   0/1       Completed   0          2
 prometheus-5f9fd67f8-r6b86                    1/1       Running     0          1m
 ```
 
-If you also chose to install the Fabric8 launcher, monitor the containers within the `devex` project until the following state is reached:
+If you also installed the Fabric8 launcher, monitor the containers within the `devex` project until the following state is reached:
 
 ```
 NAME                          READY     STATUS    RESTARTS   AGE

servicemesh-install/topics/install-prerequisites.adoc

@@ -4,7 +4,7 @@
 Before you can install {ProductName}, you must meet the following prerequisites:
 
 * Possess an active {product-title} subscription on your Red Hat account. If you do not have a subscription, contact your sales representative for more information.
-* Install {product-title} version 3.11, or higher.   For more information about the system and environment requirements, see the https://access.redhat.com/documentation/en-us/openshift_container_platform/3.11/html/installing_clusters/install-config-install-prerequisites#system-requirements[OpenShift Container Platform documentation].
+* Install {product-title} version 3.11, or higher. For more information about the system and environment requirements, see the https://access.redhat.com/documentation/en-us/openshift_container_platform/3.11/html/installing_clusters/install-config-install-prerequisites#system-requirements[OpenShift Container Platform documentation].
 * Install the version of the {product-title} command line utility (the `oc` client tool) that matches your {product-title} version and add it to your path. For example, if you have {product-title} 3.11 you must have the matching `oc` client version 3.11. For installation instructions, see the {product-title} https://access.redhat.com/documentation/en-us/openshift_container_platform/3.11/html-single/cli_reference/#installing-the-cli[Command Line Reference] document.
 
 
@@ -17,7 +17,7 @@ Before you can install the {ProductShortName} into an {product-title} installati
 [[updating-node-configuration]]
 == Updating the node configuration
 
-To run the Elasticsearch application, you must make a change to the kernel configuration on each node.  This change is handled through the `sysctl` service.
+To run the Elasticsearch application, you must make a change to the kernel configuration on each node. This change is handled through the `sysctl` service.
 
 Make the following changes on each node within your {product-title} installation:
 

servicemesh-install/topics/install-remove.adoc

@@ -1,7 +1,7 @@
 [[removing_service-mesh]]
 = Removing {ProductName}
 
-The following command removes the {ProductShortName} from an existing installation.  You can run these commands from any host with access to the cluster.  Ensure you are logged in as a cluster admin before running the following commands.
+The following command removes the {ProductShortName} from an existing installation. Log in as a cluster admin and run these commands from any host with access to the cluster.
 
 . Remove the custom resource by running the following command:
 +

servicemesh-install/topics/install-supported-config.adoc

@@ -15,12 +15,11 @@ The following are the only supported configurations for the {ProductName} {Produ
 ====
 OpenShift Online and OpenShift Dedicated are not supported for {ProductName} {ProductVersion}.
 ====
-+
 
 * The deployment must be contained to a single {product-title} cluster (no federation).
-*  This release of {ProductName} is only available on {product-title} x86_64.
-*  {ProductName} is only suited {product-title} Software Defined Networking (SDN) configured as a flat network with no external providers.
-* This release supports only configurations where all service mesh components are contained in the OpenShift cluster in which it operates.  It does not support management of microservices that reside outside of the cluster, or in a multi-cluster scenario.
+* This release of {ProductName} is only available on {product-title} x86_64.
+* {ProductName} is only suited for {product-title} Software Defined Networking (SDN) configured as a flat network with no external providers.
+* This release supports only configurations where all service mesh components are contained in the OpenShift cluster in which it operates. It does not support management of microservices that reside outside of the cluster, or in a multi-cluster scenario.
 * The Kiali observability console is only supported on the two most recent releases of the Chrome, Edge, Firefox, or Safari browsers.
 
-For more information about support for this technology preview, see this https://access.redhat.com/articles/3580021[Red Hat Knowledge Base article]
+For more information about support for this technology preview, see this https://access.redhat.com/articles/3580021[Red Hat Knowledge Base article].

servicemesh-install/topics/install-upgrade.adoc

@@ -1,4 +1,4 @@
 [[upgrading-service-mesh]]
 = Upgrading {ProductName}
 
-While {ProductName} is a Technology Preview, there is no upgrade.  If you have an existing {ProductShortName} installation (for example if you have installed the developer preview) then that installation *must* be removed prior to installing a new version of {ProductName}.
+While {ProductName} is a Technology Preview, there is no upgrade. If you have an existing {ProductShortName} installation (for example if you have installed the developer preview) then that installation *must* be removed prior to installing a new version of {ProductName}.