openshift/openshift-docs
1
0
Fork 0
mirror of https://github.com/openshift/openshift-docs.git synced 2026-02-05 21:46:22 +01:00
Code Issues Releases Activity

Merge pull request #16030 from vikram-redhat/enterprise-4.2

Browse Source 
Making CNV and SM same as master/4.1
This commit is contained in:
Vikram Goyal
2019-07-26 17:05:22 +10:00
committed by GitHub
parent 345cd0ffad 4009ca15c2
commit 56d36d1dd1
83 changed files with 3334 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files

195
_topic_map.yml
View File

@@ -662,9 +662,6 @@ Topics:
- Name: Enabling features using FeatureGates
File: nodes-cluster-enabling-features
Distros: openshift-enterprise,openshift-origin
- Name: Disabling features using FeatureGates
File: nodes-cluster-disabling-features
Distros: openshift-enterprise,openshift-origin
---
Name: Logging
Dir: logging
@@ -791,50 +788,148 @@ Topics:
- Name: Administrator CLI commands
File: administrator-cli-commands
Distros: openshift-enterprise,openshift-origin
#---
#Name: Serverless applications
#Dir: serverless
#Distros: openshift-enterprise
#Topics:
# - Name:
# File:
#---
#Name: Container-native Virtualization
#Dir: cnv
#Distros: openshift-enterprise
#Topics:
#- Name: Container-native Virtualization Installation
# Dir: cnv_install
# Topics:
# - Name: CNV Install Assemblies Placeholder
# File: cnv-install-placeholder
#- Name: Container-native Virtualization User's Guide
# Dir: cnv_users_guide
# Topics:
# - Name: CNV User's Guide Assemblies Placeholder
# File: cnv-users-guide-placeholder
# - Name: Controlling virtual machines states
# File: cnv-controlling-vm-states
# - Name: Accessing virtual machine consoles
# File: cnv-accessing-vm-consoles
#- Name: Container-native Virtualization Release Notes
# Dir: cnv_release_notes
# Topics:
# - Name: CNV Release Notes Placeholder
# File: cnv-release-notes-placeholder
#---
#Name: Service Mesh
#Dir: service_mesh
#Distros: openshift-enterprise
#Topics:
#- Name: Service Mesh Installation
# Dir: service_mesh_install
# Topics:
# - Name: Service Mesh Insatll Assemblies Placeholder
# File: service-mesh-install-placeholder
#- Name: Service Mesh Release Notes
# Dir: service_mesh_release_notes
# Topics:
# - Name: Service Mesh Release Notes Placeholder
# File: service-mesh-release-notes-placeholder
#---
---
Name: Service Mesh
Dir: service_mesh
Distros: openshift-enterprise
Topics:
- Name: Service Mesh Installation
Dir: service_mesh_install
Topics:
- Name: Understanding service mesh
File: understanding-ossm
- Name: Preparing to install service mesh
File: preparing-ossm-installation
- Name: Installing service mesh
File: installing-ossm
- Name: Installing a multi-tenant service mesh
File: installing-mt-ossm
- Name: Deploying applications on service mesh
File: prepare-to-deploy-applications-ossm
- Name: Example application
File: ossm-example-bookinfo
- Name: Kiali tutorial
File: ossm-tutorial-kiali
- Name: Distributed tracing tutorial
File: ossm-tutorial-jaeger-tracing
- Name: Grafana tutorial
File: ossm-tutorial-grafana
- Name: Prometheus tutorial
File: ossm-tutorial-prometheus
- Name: Removing service mesh
File: removing-ossm
- Name: 3scale adapter
Dir: threescale_adapter
Topics:
- Name: Using the 3scale Istio adapter
File: threescale-adapter
- Name: Service Mesh Release Notes
File: servicemesh-release-notes
---
Name: Container-native Virtualization
Dir: cnv
Distros: openshift-enterprise
Topics:
- Name: Container-native Virtualization installation
Dir: cnv_install
Topics:
- Name: About Container-native Virtualization
File: cnv-about-cnv
- Name: Preparing your OpenShift cluster for Container-native Virtualization
File: preparing-cluster-for-cnv
- Name: Installing Container-native Virtualization
File: installing-container-native-virtualization
- Name: Installing the `virtctl` client
File: cnv-installing-virtctl
- Name: Uninstalling Container-native Virtualization
File: uninstalling-container-native-virtualization
- Name: Container-native Virtualization user's guide
Dir: cnv_users_guide
Topics:
### VIRTUAL MACHINE CHESS SALAD (silly name to highlight that the commented out assemblies need to be checked against merged filenams)
- Name: Creating virtual machines
File: cnv-create-vms
### Importing virtual machines
- Name: Importing a VMware virtual machine or template with the virtual machine wizard
File: cnv-importing-vmware-vm
- Name: Importing virtual machine images with DataVolumes
File: cnv-importing-virtual-machine-images-datavolumes
### VM CHESS SALAD cont'd
- Name: Editing virtual machines
File: cnv-edit-vms
- Name: Deleting virtual machines
File: cnv-delete-vms
- Name: Controlling virtual machines states
File: cnv-controlling-vm-states
- Name: Accessing virtual machine consoles
File: cnv-accessing-vm-consoles
- Name: Using the CLI tools
File: cnv-using-the-cli-tools
### Virtual machine networking
- Name: Using the default Pod network with Container-native Virtualization
File: cnv-using-the-default-pod-network-with-cnv
- Name: Attaching a virtual machine to multiple networks
File: cnv-attaching-vm-multiple-networks
- Name: Installing the QEMU guest agent on virtual machines
File: cnv-installing-qemu-guest-agent
- Name: Viewing the IP address of vNICs on a virtual machine
File: cnv-viewing-ip-of-vm-vnic
### Advanced virtual machine configuration
- Name: Configuring PXE booting for virtual machines
File: cnv-configuring-pxe-booting
- Name: Managing guest memory
File: cnv-managing-guest-memory
### Templates
- Name: Creating virtual machine templates
File: cnv-creating-vm-template
- Name: Editing a virtual machine template
File: cnv-editing-vm-template
- Name: Deleting a virtual machine template
File: cnv-deleting-vm-template
### Cloning virtual machines
- Name: Cloning a virtual machine disk into a new DataVolume
File: cnv-cloning-vm-disk-into-new-datavolume
- Name: Cloning a virtual machine by using a DataVolumeTemplate
File: cnv-cloning-vm-using-datavolumetemplate
### A BETTER NAME THAN 'STORAGE 4 U'
- Name: Uploading local disk images by using the virtctl tool
File: cnv-uploading-local-disk-images-virtctl
- Name: Expanding virtual storage by adding blank disk images
File: cnv-expanding-virtual-storage-with-blank-disk-images
### Virtual machine live migration
- Name: Virtual machine live migration
File: cnv-live-migration
- Name: Live migration limits and timeouts
File: cnv-live-migration-limits
- Name: Migrating a virtual machine instance to another node
File: cnv-migrate-vmi
- Name: Monitoring live migration of a virtual machine instance
File: cnv-monitor-vmi-migration
- Name: Cancelling the live migration of a virtual machine instance
File: cnv-cancel-vmi-migration
### Node maintenance mode
- Name: Node maintenance mode
File: cnv-node-maintenance
- Name: Configuring virtual machine eviction strategy
File: cnv-configuring-vmi-eviction-strategy
- Name: Setting a node to maintenance mode
File: cnv-setting-node-maintenance
- Name: Resuming a node from maintenance mode
File: cnv-resuming-node
### Installing VirtIO drivers on Windows virtual machines
- Name: Installing VirtIO driver on an existing Windows virtual machine
File: cnv-installing-virtio-drivers-on-existing-windows-vm
- Name: Installing VirtIO driver on a new Windows virtual machine
File: cnv-installing-virtio-drivers-on-new-windows-vm
### Logging, events, and monitoring
- Name: Viewing logs
File: cnv-logs
- Name: Viewing events
File: cnv-events
- Name: OpenShift cluster monitoring
File: cnv-openshift-cluster-monitoring
- Name: Container-native Virtualization 2.0 release notes
Dir: cnv_release_notes
Topics:
- Name: Container-native Virtualization 2.0 release notes
File: cnv-release-notes

2
cnv/cnv_install/cnv-about-cnv.adoc
View File

@@ -1,5 +1,5 @@
[id="cnv-about-cnv"]
= About {ProductName}
= About Container-native Virtualization
include::modules/cnv-document-attributes.adoc[]
:context: cnv-about-cnv
toc::[]

21
modules/ossm-architecture.adoc Normal file
View File

@@ -0,0 +1,21 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/understanding-ossm.adoc
[id="ossm-architecture_{context}"]
= {ProductName} Architecture
{ProductName} is logically split into a data plane and a control plane:
The *data plane* is a set of intelligent proxies deployed as sidecars. These proxies intercept and control all inbound and outbound network communication between microservices in the service mesh. Sidecar proxies also communicate with Mixer, the general-purpose policy and telemetry hub.
* *Envoy proxy* intercepts all inbound and outbound traffic for all services in the service mesh. Envoy is deployed as a sidecar to the relevant service in the same pod.
The *control plane* manages and configures proxies to route traffic, and configures Mixers to enforce policies and collect telemetry.
* *Mixer* enforces access control and usage policies (such as authorization, rate limits, quotas, authentication, request tracing) and collects telemetry data from the Envoy proxy and other services.
* *Pilot* configures the proxies at runtime. Pilot provides service discovery for the Envoy sidecars, traffic management capabilities for intelligent routing (for example, A/B tests or canary deployments), and resiliency (timeouts, retries, and circuit breakers).
* *Citadel* issues and rotates certificates. Citadel provides strong service-to-service and end-user authentication with built-in identity and credential management. You can use Citadel to upgrade unencrypted traffic in the service mesh. Operators can enforce policies based on service identity rather than on network controls using Citadel.
* *Galley* ingests the service mesh configuration, then validates, processes, and distributes the configuration. Galley protects the other service mesh components from obtaining user configuration details from {product-title}.
{ProductName} also uses the *istio-operator* to manage the installation of the control plane. An _Operator_ is a piece of software that enables you to implement and automate common activities in your OpenShift cluster. It acts as a controller, allowing you to set or change the desired state of objects in your cluster.

43
modules/ossm-automatic-sidecar-injection.adoc Normal file
View File

@@ -0,0 +1,43 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/prepare-to-deploy-applications-ossm.adoc
[id="ossm-automatic-sidecar-injection_{context}"]
= Enabling automatic sidecar injection
When deploying an application into the {ProductName} you must opt in to injection by specifying the `sidecar.istio.io/inject` annotation with a value of `true`. Opting in ensures that the sidecar injection does not interfere with other OpenShift features such as builder pods used by numerous frameworks within the OpenShift ecosystem.
.Prerequisites
* Identify the deployments for which you want to enable automatic sidecar injection.
* Locate the application's yaml configuration file.
.Procedure
. Open the application's configuration yaml file in an editor.
. Add `sidecar.istio.io/inject` to the configuration yaml with a value of `true` as illustrated here:
+
.Sleep test application example
[source,yaml]
----
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
name: sleep
spec:
replicas: 1
template:
metadata:
annotations:
sidecar.istio.io/inject: "true"
labels:
app: sleep
spec:
containers:
- name: sleep
image: tutum/curl
command: ["/bin/sleep","infinity"]
imagePullPolicy: IfNotPresent
----
. Save the configuration file.

41
modules/ossm-configure-security-constraints.adoc Normal file
View File

@@ -0,0 +1,41 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/prepare-to-deploy-applications-ossm.adoc
[id="ossm-configure-security-constraints_{context}"]
= Configuring {ProductName} security constraints
Configure service accounts that require additional permissions to run in the {ProductShortName} with `anyuid` or `privileged` Security Context Constraints (SCCs).
[NOTE]
====
You do not need to follow this procedure if you are using {product-title} 4.1.
====
.Prerequisites
* Identify the service accounts that require SCC changes.
* Identify the namespaces associated with the service accounts that require SCC changes.
.Procedure
. Identify the service account(s) that require relaxed privileges.
+
[NOTE]
====
Replace `<service account>` and `<namespace>` with values specific to your application in the commands in this procedure.
====
. Run this command for each service account that requires the `anyuid` SCC for its associated sidecar container.
+
----
$ oc adm policy add-scc-to-user anyuid -z <service account> -n <namespace>
----
. Run this command for each service account that requires the `privileged` SCC to allow successful updates to its pod's networking configuration:
+
----
$ oc adm policy add-scc-to-user privileged -z <service account> -n <namespace>
----

48
modules/ossm-control-plane-deploy.adoc Normal file
View File

@@ -0,0 +1,48 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/installing-ossm.adoc
[id="ossm-control-plane-deploy_{context}"]
= Deploying the control plane
With the introduction of {product-title} 4.1, the network capabilities of the host are now based on nftables rather than iptables. This change impacts the initialization of the {ProductName} application components. {ProductShortName} needs to know what host operating system OpenShift is running on to correctly initialize {ProductShortName} networking components.
[NOTE]
====
You do not need to follow this procedure if you are using {product-title} 4.1.
====
If the OpenShift installation is deployed on a Red Hat Enterprise Linux (RHEL) 7 host, then the custom resource must explicitly request the RHEL 7 `proxy-init` container image by including the following:
.Enabling the proxy-init container for RHEL 7 hosts
[subs=+macros]
----
apiVersion: maistra.io/v1
kind: ServiceMeshControlPlane
spec:
istio:
global:
pass:quotes[*proxy_init:*]
pass:quotes[*image: proxy-init*]
----
Use the custom resource definition file you created to deploy the {ProductShortName} control plane.
.Procedure
. Create a custom resource definition file named `istio-installation.yaml`.
. Run this command to deploy the control plane:
+
----
$ oc create -n istio-system -f istio-installation.yaml
----
. Run this command to watch the progress of the pods during the installation process:
+
----
$ oc get pods -n istio-system -w
----

66
modules/ossm-control-plane-verify.adoc Normal file
View File

@@ -0,0 +1,66 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/installing-ossm.adoc
[id="ossm-control-plane-verify_{context}"]
= Verifying the control plane installation
Verify that the control plane installation completed successfully.
.Procedure
[NOTE]
====
The name of the resource is `istio-installation`.
====
. Run this command to determine if the Operator finished deploying the control plane:
+
----
$ oc get servicemeshcontrolplane/basic-install -n istio-system --template='{{range .status.conditions}}{{printf "%s=%s, reason=%s, message=%s\n\n" .type .status .reason .message}}{{end}}'
----
+
When the control plane installation is finished, the output is similar to the following:
+
----
Installed=True, reason=InstallSuccessful, message=%!s()
Reconciled=True, reason=InstallSuccessful, message=%!s()
----
. After the control plane is deployed, run this command to check the status of the pods:
+
----
$ oc get pods -n istio-system
----
. Verify that the pods are in a state similar to this:
+
[NOTE]
====
The results returned when you run this verification step vary depending on your configuration including the number of nodes in the cluster, and whether you are using 3scale, Jaeger, Kiali, or Prometheus.
====
+
----
NAME READY STATUS RESTARTS AGE
3scale-istio-adapter-67b96f97b5-cwvgt 1/1 Running 0 99s
grafana-75f4cbbc6-xw99s 1/1 Running 0 54m
istio-citadel-8489b8bb96-ttqfd 1/1 Running 0 54m
stio-egressgateway-5ccd4d5ddd-wtp2h 1/1 Running 0 52m
istio-galley-58ff8db57c-jrpkz 1/1 Running 0 54m
istio-ingressgateway-698674848f-bk57s 1/1 Running 0 52m
istio-node-2d764 1/1 Running 0 54m
istio-node-4h926 1/1 Running 0 54m
istio-node-6qxcj 1/1 Running 0 54m
istio-node-8fxqz 1/1 Running 0 54m
istio-node-gzg5v 1/1 Running 0 54m
istio-node-vxx5p 1/1 Running 0 54m
istio-pilot-764966cf69-9nlhp 2/2 Running 0 19m
istio-policy-7c856f7d5f-4fjk4 2/2 Running 2 53m
istio-sidecar-injector-757b8ccdbf-znggc 1/1 Running 0 49m
istio-telemetry-65d8b47c98-jrp9h 2/2 Running 2 53m
jaeger-f775b79f8-cmbb2 2/2 Running 0 54m
kiali-7646d796cd-kfx29 1/1 Running 0 20m
prometheus-56cb9c859b-dlqmn 2/2 Running 0 54m
----

40
modules/ossm-cr-cni.adoc Normal file
View File

@@ -0,0 +1,40 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/installing-ossm.adoc
[id="ossm-cr-cni_{context}"]
= Container Network Interface (CNI) example
This example illustrates the CNI parameter and its values for {ProductName}.
[WARNING]
====
If Container Network Interface (CNI) is enabled, manual sidecar injection will work, but pods will not be able to communicate with the control plane unless they are a part of the `ServiceMeshMemberRoll` resource.
====
.CNI example
[source,yaml]
----
apiVersion: maistra.io/v1
kind: ServiceMeshControlPlane
metadata:
name: basic-install
spec:
istio:
istio_cni:
enabled: true
----
.CNI parameter
|===
|Type |Parameter |Description |Values |Default value
|`istio_cni`
|`enabled`
|This parameter enables the Container Network Interface (CNI).
|`true`/`false`
|`false`
|===

75
modules/ossm-cr-example.adoc Normal file
View File

@@ -0,0 +1,75 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/installing-ossm.adoc
[id="ossm-cr-example_{context}"]
= {ProductName} custom resource
[NOTE]
====
The `istio-system` namespace is used an example throughout the {ProductShortName} documentation, but you can use other namespaces as necessary.
====
To deploy the {ProductShortName} control plane, you must create a custom resource. A _custom resource_ allows you to introduce your own API into a Kubernetes project or cluster. You create a custom resource yaml file that defines the project parameters and creates the object. This example custom resource yaml file contains all of the supported parameters and deploys {ProductName} {ProductVersion} images based on Red Hat Enterprise Linux (RHEL).
[IMPORTANT]
====
The 3scale Istio Adapter is deployed and configured in the custom resource file. It also requires a working 3scale account (link:https://www.3scale.net/signup/[SaaS] or link:https://access.redhat.com/documentation/en-us/red_hat_3scale_api_management/2.4/html/infrastructure/onpremises-installation[On-Premises]).
====
.Full example istio-installation.yaml
[source,yaml]
----
apiVersion: maistra.io/v1
kind: ServiceMeshControlPlane
metadata:
name: basic-install
threeScale:
enabled: false
istio:
global:
proxy:
resources:
requests:
cpu: 100m
memory: 128Mi
limits:
cpu: 500m
memory: 128Mi
multitenant: true
gateways:
istio-egressgateway:
autoscaleEnabled: false
istio-ingressgateway:
autoscaleEnabled: false
ior_enabled: false
mixer:
policy:
autoscaleEnabled: false
telemetry:
autoscaleEnabled: false
resources:
requests:
cpu: 100m
memory: 1G
limits:
cpu: 500m
memory: 4G
pilot:
autoscaleEnabled: false
traceSampling: 100.0
kiali:
dashboard:
user: admin
passphrase: admin
tracing:
enabled: true
----

76
modules/ossm-cr-gateway.adoc Normal file
View File

@@ -0,0 +1,76 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/installing-ossm.adoc
[id="ossm-cr-gateway_{context}"]
= Istio gateway example
Here is an example that illustrates the Istio gateway parameters for the {ProductName} custom resource and a description of the available parameters with appropriate values.
[WARNING]
====
Automatic route creation does not currently work with multi-tenancy. Set `ior_enabled` to `false` for multi-tenant installations.
====
[source,yaml]
----
gateways:
istio-egressgateway:
autoscaleEnabled: false
autoscaleMin: 1
autoscaleMax: 5
istio-ingressgateway:
autoscaleEnabled: false
autoscaleMin: 1
autoscaleMax: 5
ior_enabled: false
----
.Istio Gateway parameters
|===
|Type |Parameter |Description |Values |Default value
|`istio-egressgateway`
|`autoscaleEnabled`
|This parameter enables autoscaling.
|`true`/`false`
|`true`
|
|`autoscaleMin`
|The minimum number of pods to deploy for the egress gateway based on the autoscaleEnabled setting
|A valid number of allocatable pods based on your environment's configuration
|`1`
|
|`autoscaleMax`
|The maximum number of pods to deploy for the egress gateway based on the autoscaleEnabled setting
|A valid number of allocatable pods based on your environment's configuration
|`5`
|`istio-ingressgateway`
|`autoscaleEnabled`
|This parameter enables autoscaling.
|`true`/`false`
|`true`
|
|`autoscaleMin`
|The minimum number of pods to deploy for the ingress gateway based on the autoscaleEnabled setting
|A valid number of allocatable pods based on your environment's configuration
|`1`
|
|`autoscaleMax`
|The maximum number of pods to deploy for the ingress gateway based on the autoscaleEnabled setting
|A valid number of allocatable pods based on your environment's configuration
|`5`
|
|`ior_enabled`
|This parameter controls whether Istio routes are automatically configured in OpenShift
|`true`/`false`
|`true`
|===

104
modules/ossm-cr-istio-global.adoc Normal file
View File

@@ -0,0 +1,104 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/installing-ossm.adoc
[id="ossm-cr-istio-global_{context}"]
= Istio global example
Here is an example that illustrates the Istio global parameters for the {ProductName} custom resource and a description of the available parameters with appropriate values.
[NOTE]
====
In order for the 3scale Istio Adapter to work, `disablePolicyChecks` must be `false`.
====
[source,yaml]
----
istio:
global:
hub: `maistra/` or `registry.redhat.io/openshift-istio-tech-preview/`
tag: 0.12.0
proxy:
resources:
requests:
cpu: 100m
memory: 128Mi
limits:
cpu: 500m
memory: 128Mi
mtls:
enabled: false
disablePolicyChecks: true
policyCheckFailOpen: false
imagePullSecrets:
- MyPullSecret
----
[NOTE]
====
See the OpenShift documentation on xref:../../scalability_and_performance/recommended-host-practices.html#recommended-node-host-practices_[Scalability and performance] for additional details on CPU and memory resources for the containers in your pod.
====
.Global parameters
|===
|Parameter |Description |Values |Default value
|`disablePolicyChecks`
|This boolean indicates whether to enable policy checks
|`true`/`false`
|`true`
|`policyCheckFailOpen`
|This boolean indicates whether traffic is allowed to pass through to the Envoy sidecar when the Mixer policy service cannot be reached
|`true`/`false`
|`false`
|`tag`
|The tag that the Operator uses to pull the Istio images
|A valid container image tag
|`0.12.0`
|`hub`
|The hub that the Operator uses to pull Istio images
|A valid image repo
|`maistra/` or `registry.redhat.io/openshift-istio-tech-preview/`
|`mtls`
|This controls whether to enable Mutual Transport Layer Security (mTLS) between services by default
|`true`/`false`
|`false`
|`imagePullSecret`
|If access to the registry providing the Istio images is secure, list an link:https://kubernetes.io/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod[imagePullSecret] here
|redhat-registry-pullsecret OR quay-pullsecret
|None
|===
.Proxy parameters
|===
|Type |Parameter |Description |Values |Default value
|Resources
|`cpu`
|The percentage of CPU resources requested for Envoy proxy
|CPU resources in millicores based on your environment's configuration
|`100m`
|
|`memory`
|The amount of memory requested for Envoy proxy
|Available memory in bytes based on your environment's configuration
|`128Mi`
|Limits
|`cpu`
|The maximum percentage of CPU resources requested for Envoy proxy
|CPU resources in millicores based on your environment's configuration
|`2000m`
|
|`memory`
|The maximum amount of memory Envoy proxy is permitted to use
|Available memory in bytes based on your environment's configuration
|`128Mi`
|===

55
modules/ossm-cr-kiali.adoc Normal file
View File

@@ -0,0 +1,55 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/installing-ossm.adoc
[id="ossm-cr-kiali_{context}"]
= Kiali example
Here is an example that illustrates the Kiali parameters for the {ProductName} custom resource and a description of the available parameters with appropriate values.
[NOTE]
====
Kiali supports OAuth authentication and hard-coded user credentials. By default, Kiali uses OpenShift OAuth, but you can add a user and passphrase.
====
[source,yaml]
----
kiali:
enabled: true
hub: kiali/
tag: v01.0.0
dashboard:
user: admin
passphrase: admin
----
.Kiali parameters
|===
|Parameter |Description |Values |Default value
|`enabled`
|This enables or disables Kiali in {ProductShortName}. Kiali is installed by default. If you do not want to install Kiali, change the `enabled` value to `false`.
|`true`/`false`
|`true`
|`hub`
|The hub that the operator uses to pull Kiali images
|A valid image repo
|`kiali/` or `registry.redhat.io/openshift-istio-tech-preview/`
|`tag`
|The tag that the operator uses to pull the Istio images
|A valid container image tag
|`1.0.0`
|`user`
|The username to access the Kiali console. Note: This is not related to any OpenShift account.
|A valid Kiali dashboard username
|None
|`passphrase`
|The password used to access the Kiali console. Note: This is not related to any OpenShift account.
|A valid Kiali dashboard passphrase
|None
|===

82
modules/ossm-cr-mixer.adoc Normal file
View File

@@ -0,0 +1,82 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/installing-ossm.adoc
[id="ossm-cr-mixer_{context}"]
= Istio Mixer example
Here is an example that illustrates the Mixer parameters for the {ProductName} custom resource and a description of the available parameters with appropriate values.
[source,yaml]
----
mixer:
enabled: true
policy:
autoscaleEnabled: false
telemetry:
autoscaleEnabled: false
resources:
requests:
cpu: 100m
memory: 1G
limits:
cpu: 500m
memory: 4G
----
.Istio Mixer policy parameters
|===
|Parameter |Description |Values |Default value
|`enabled`
|This enables Mixer
|`true`/`false`
|`true`
|`autoscaleEnabled`
|This controls whether to enable autoscaling. Disable this for small environments.
|`true`/`false`
|`true`
|`autoscaleMin`
|The minimum number of pods to deploy based on the autoscaleEnabled setting
|A valid number of allocatable pods based on your environment's configuration
|`1`
|`autoscaleMax`
|The maximum number of pods to deploy based on the autoscaleEnabled setting
|A valid number of allocatable pods based on your environment's configuration
|`5`
|===
.Istio Mixer telemetry parameters
|===
|Type |Parameter |Description |Values |Default
|Resources
|`cpu`
|The percentage of CPU resources requested for Mixer telemetry
|CPU resources in millicores based on your environment's configuration
|`1000m`
|
|`memory`
|The amount of memory requested for Mixer telemetry
|Available memory in bytes based on your environment's configuration
|`1G`
|Limits
|`cpu`
|The maximum percentage of CPU resources Mixer telemetry is permitted to use
|CPU resources in millicores based on your environment's configuration
|`4800m`
|
|`memory`
|The maximum amount of memory Mixer telemetry is permitted to use
|Available memory in bytes based on your environment's configuration
|`4G`
|===

13
modules/ossm-cr-parameters.adoc Normal file
View File

@@ -0,0 +1,13 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/installing-ossm.adoc
[id="ossm-cr-parameters_{context}"]
= Custom resource parameters
The following examples illustrate use of the supported custom resource parameters for {ProductName} and the tables provide additional information about supported parameters.
[IMPORTANT]
====
The resources you configure for {ProductName} with these custom resource parameters, including CPUs, memory, and the number of pods, are based on the configuration of your OpenShift cluster. Configure these parameters based on the available resources in your current cluster configuration.
====

38
modules/ossm-cr-pilot.adoc Normal file
View File

@@ -0,0 +1,38 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/installing-ossm.adoc
[id="ossm-cr-pilot_{context}"]
= Istio Pilot example
Here is an example that illustrates the Istio Pilot parameters for the {ProductName} custom resource and a description of the available parameters with appropriate values.
[source,yaml]
----
pilot:
resources:
requests:
cpu: 100m
autoscaleEnabled: false
traceSampling: 100.0
----
.Istio Pilot parameters
|===
|Parameter |Description |Values |Default value
|`cpu`
|The percentage of CPU resources requested for Pilot
|CPU resources in millicores based on your environment's configuration
|`500m`
|`memory`
|The amount of memory requested for Pilot
|Available memory in bytes based on your environment's configuration
|`2048Mi`
|`traceSampling`
|This value controls how often random sampling occurs. Note: increase for development or testing.
|A valid percentage
|`1.0`
|===

93
modules/ossm-cr-threescale.adoc Normal file
View File

@@ -0,0 +1,93 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/installing-ossm.adoc
[id="ossm-cr-threescale_{context}"]
= 3scale example
Here is an example that illustrates the 3scale Istio Adapter parameters for the {ProductName} custom resource and a description of the available parameters with appropriate values.
[source,yaml]
----
threeScale:
enabled: false
PARAM_THREESCALE_LISTEN_ADDR: 3333
PARAM_THREESCALE_LOG_LEVEL: info
PARAM_THREESCALE_LOG_JSON: true
PARAM_THREESCALE_LOG_GRPC: false
PARAM_THREESCALE_REPORT_METRICS: true
PARAM_THREESCALE_METRICS_PORT: 8080
PARAM_THREESCALE_CACHE_TTL_SECONDS: 300
PARAM_THREESCALE_CACHE_REFRESH_SECONDS: 180
PARAM_THREESCALE_CACHE_ENTRIES_MAX: 1000
PARAM_THREESCALE_CACHE_REFRESH_RETRIES: 1
PARAM_THREESCALE_ALLOW_INSECURE_CONN: false
PARAM_THREESCALE_CLIENT_TIMEOUT_SECONDS: 10
PARAM_THREESCALE_GRPC_CONN_MAX_SECONDS: 60
----
.3scale parameters
|===
|Parameter |Description |Values |Default value
|`enabled`
|Whether to use the 3scale adapter
|`true`/`false`
|`false`
|`PARAM_THREESCALE_LISTEN_ADDR`
|Sets the listen address for the gRPC server
|Valid port number
|`3333`
|`PARAM_THREESCALE_LOG_LEVEL`
|Sets the minimum log output level.
|`debug`, `info`, `warn`, `error`, or `none`
|`info`
|`PARAM_THREESCALE_LOG_JSON`
|Controls whether the log is formatted as JSON
|`true`/`false`
|`true`
|`PARAM_THREESCALE_REPORT_METRICS`
|Controls whether 3scale system and backend metrics are collected and reported to Prometheus
|`true`/`false`
|`true`
|`PARAM_THREESCALE_METRICS_PORT`
|Sets the port that the 3scale `/metrics` endpoint can be scrapped from
|Valid port number
|`8080`
|`PARAM_THREESCALE_CACHE_TTL_SECONDS`
|Time period, in seconds, to wait before purging expired items from the cache
|Time period in seconds
|`300`
|`PARAM_THREESCALE_CACHE_REFRESH_SECONDS`
|Time period before expiry when cache elements are attempted to be refreshed
|Time period in seconds
|`180`
|`PARAM_THREESCALE_CACHE_ENTRIES_MAX`
|Max number of items that can be stored in the cache at any time. Set to `0` to disable caching
|Valid number
|`1000`
|`PARAM_THREESCALE_CACHE_REFRESH_RETRIES`
|The number of times unreachable hosts are retried during a cache update loop
|Valid number
|`1`
|`PARAM_THREESCALE_ALLOW_INSECURE_CONN`
|Allow to skip certificate verification when calling `3scale` APIs. Enabling this is not recommended.
|`true`/`false`
|`false`
|`PARAM_THREESCALE_CLIENT_TIMEOUT_SECONDS`
|Sets the number of seconds to wait before terminating requests to 3scale System and Backend
|Time period in seconds
|`10`
|===

51
modules/ossm-cr-tracing-jaeger.adoc Normal file
View File

@@ -0,0 +1,51 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/installing-ossm.adoc
[id="ossm-cr-tracing-jaeger_{context}"]
= Tracing and Jaeger example
This example illustrates tracing parameters for the {ProductName} custom resource and a description of the available parameters with appropriate values.
[source,yaml]
----
tracing:
enabled: false
jaeger:
tag: 1.13.1
template: all-in-one
agentStrategy: DaemonSet
----
.Tracing and Jaeger parameters
|===
|Parameter |Description |Value |Default value
|`enabled`
| This enables tracing in the environment
|`true`/`false`
|`true`
|`hub`
| The hub that the Operator uses to pull Jaeger images
| A valid image repo
| `jaegertracing/` or `registry.redhat.io/openshift-istio-tech-preview/`
| `tag`
| The tag that the Operator uses to pull the Jaeger images
| A valid container image tag.
| `1.13.1`
| `template`
| The deployment template to use for Jaeger
| The name of a template type
| `all-in-one`/`production-elasticsearch`
|`agentStrategy`
| Deploy the Jaeger Agent to each compute node
| `DaemonSet` if required
| None
|===

34
modules/ossm-document-attributes.adoc Normal file
View File

@@ -0,0 +1,34 @@
// Standard document attributes to be used in the Service Mesh documentation
//
// The following are shared by all RHOSSM documents:
:toc:
:toclevels: 4
:experimental:
//
// Product content attributes, that is, substitution variables in the files.
//
:product-title: OpenShift Container Platform
:ProductName: Red Hat OpenShift Service Mesh
:ProductShortName: Service Mesh
:ProductRelease:
:ProductVersion: 0.12.TechPreview
:product-build:
:DownloadURL: registry.redhat.io
//
// Documentation publishing attributes used in the master-docinfo.xml file
// Note that the DocInfoProductName generates the URL for the product page.
// Changing the value changes the generated URL.
//
:DocInfoProductName: OpenShift Service Mesh
:DocInfoProductNumber: 1.0.TechPreview
//
// Book Names:
// Defining the book names in document attributes instead of hard-coding them in
// the master.adoc files and in link references. This makes it easy to change the
// book name if necessary.
// Using the pattern ending in 'BookName' makes it easy to grep for occurrences
// throughout the topics
//
: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

21
modules/ossm-installation-activities.adoc Normal file
View File

@@ -0,0 +1,21 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/preparing-ossm-installation.adoc
[id="ossm-installation-activities_{context}"]
= {ProductName} installation activities
The {ProductName} installation process creates two different projects (namespaces):
* istio-operator project (1 pod)
* istio-system project (17 pods)
* kiali-operator project (1 pod)
* observability project (1 pod)
You first create a Kubernetes _Operator_. This Operator defines and monitors a _custom resource_ that manages the deployment, updating, and deletion of the {ProductShortName} components.
Depending on how you define the custom resource file, you can install one or more of the following components when you install the {ProductShortName}:
* *Istio* - based on the open source link:https://istio.io/[Istio] project, lets you connect, secure, control, and observe the microservices that make up your applications.
* *Jaeger* - based on the open source link:https://www.jaegertracing.io/[Jaeger] project, lets you perform tracing to monitor and troubleshoot transactions in complex distributed systems.
* *Kiali* - based on the open source link: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.

29
modules/ossm-manual-sidecar-injection.adoc Normal file
View File

@@ -0,0 +1,29 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/prepare-to-deploy-applications-ossm.adoc
[id="ossm-manual-sidecar-injection_{context}"]
= Using manual sidecar injection
Manual injection of the sidecar is supported using the upstream Istio community `istioctl` command.
[NOTE]
====
When you use manual sidecar injection, ensure you have access to a running cluster so the correct configuration can be obtained from the istio-sidecar-injector configmap within the istio-system namespace.
====
.Prerequisites
* Download the appropriate link:https://github.com/istio/istio/releases/tag/1.1.8[installation] for your OS.
.Procedure
. Unpack the `istioctl` installation into a directory
. Add the `istioctl` binary to the the bin directory in your PATH.
. Run this command to inject the sidecar into your application and pipe the configuration to the `oc` command to create deployments:
+
----
$ istioctl kube-inject -f app.yaml | oc create -f -
----

13
modules/ossm-master-configuration.adoc Normal file
View File

@@ -0,0 +1,13 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/prepare-to-deploy-applications-ossm.adoc
[id="ossm-master-configuration_{context}"]
= {ProductName}'s master configuration
{ProductName} relies on a proxy sidecar within the application's pod to provide {ProductShortName} capabilities to the application. You can enable automatic sidecar injection or manage it manually. Red Hat recommends automatic injection using the annotation with no need to label namespaces. This ensures that your application contains the appropriate configuration for the {ProductShortName} upon deployment. This method requires fewer privileges and does not conflict with other OpenShift capabilities such as builder pods.
[NOTE]
====
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.
====

30
modules/ossm-mixer-policy.adoc Normal file
View File

@@ -0,0 +1,30 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/installing-ossm.adoc
[id="ossm-mixer-policy_{context}"]
= Updating Mixer policy enforcement
In previous versions of {ProductName}, Mixer’s policy enforcement was enabled by default. Mixer policy enforcement is now disabled by default. You must enable it before running policy tasks.
.Procedure
. Run this command to check the current Mixer policy enforcement status:
+
----
$ oc get cm -n istio-system istio -o jsonpath='{.data.mesh}' | grep disablePolicyChecks
----
. If `disablePolicyChecks: true`, edit the {ProductShortName} ConfigMap:
+
----
$ oc edit cm -n istio-system istio
----
. Locate `disablePolicyChecks: true` within the ConfigMap and change the value to `false`.
. Save the configuration and exit the editor.
. Re-check the Mixer policy enforcement status to ensure it is set to `false`.

31
modules/ossm-mt-installation.adoc Normal file
View File

@@ -0,0 +1,31 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/installing-mt-ossm.adoc
[id="ossm-mt-installation_{context}"]
= Installing {ProductName} with multi-tenancy
This procedure describes the how to enable multi-tenancy.
.Prerequisites
* An installed, verified {ProductShortName} Operator.
* A custom resource file that defines the parameters of your {ProductName} control plane.
.Procedure
* Set the `multitenant` option to `true` in the istio section of the `ServiceMeshControlPlane` resource. For example:
+
.Multi-tenant custom resource example
[source,yaml]
----
apiVersion: maistra.io/v1
kind: ServiceMeshControlPlane
spec:
istio:
global:
# enable multitenant
multitenant: true
# additional control plane configuration details
----

19
modules/ossm-mt-known-issues.adoc Normal file
View File

@@ -0,0 +1,19 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/installing-mt-ossm.adoc
[id="ossm-mt-known-issues_{context}"]
= Known issues with multi-tenant {ProductName} installations
Here is a summary of the known issues with multi-tenant {ProductShortName} installations.
[WARNING]
====
Automatic route creation is currently incompatible with multi-tenant {ProductShortName} installations. Ensure that it is disabled, by setting `ior_enabled` to `false` in your `ServiceMeshControlPlane` if you plan to attempt a multi-tenant installation.
====
* `MeshPolicy` is still a cluster-scoped resource and applies to all control planes installed in OpenShift. This can prevent the installation of multiple control planes or cause unknown behavior if one control plane is deleted.
* The Jaeger agent runs as a `DaemonSet`, therefore `tracing` may only be enabled for a single `ServiceMeshControlPlane` instance.
* If you delete the project that contains the control plane before you delete the `ServiceMeshControlPlane` resource, some parts of the installation may not be removed:
** Service accounts added to the `SecurityContextConstraints` may not be removed.
** `OAuthClient` resources associated with Kiali may not be removed, or its list of redirectURIs may not be accurate.

58
modules/ossm-mt-namespaces.adoc Normal file
View File

@@ -0,0 +1,58 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/installing-mt-ossm.adoc
[id="ossm-mt-namespaces_{context}"]
= Configuring namespaces in multi-tenant installations
A multi-tenant control plane installation only affects namespaces configured as part of the {ProductShortName}. You must specify the namespaces associated with the {ProductShortName} in a `ServiceMeshMemberRoll` resource located in the same namespace as the `ServiceMeshControlPlane` resource and name it `default`.
[WARNING]
====
If Container Network Interface (CNI) is enabled, manual sidecar injection will work, but pods will not be able to communicate with the control plane unless they are a part of the `ServiceMeshMemberRoll` resource.
====
[NOTE]
====
The member namespaces are only updated if the {ProductShortName} control plane installation succeeds.
====
* You can add any number of namespaces, but a namespace can only belong to *one* `ServiceMeshMemberRoll`.
* `ServiceMeshMemberRoll` resources are reconciled in response to the following events:
** The `ServiceMeshMemberRoll` is created, updated, or deleted
** The `ServiceMeshControlPlane` resource in the namespace containing the `ServiceMeshMemberRoll` is created or updated
** A namespace listed in the `ServiceMeshMemberRoll` is created or deleted
The `ServiceMeshMemberRoll` is deleted when its corresponding `ServiceMeshControlPlane` resource is deleted.
Here is an example that joins the bookinfo namespace into the {ProductShortName}:
.Prerequisites
* An installed, verified {ProductShortName} Operator.
* Location of the namespace where the custom resource installed the control plane.
.Procedure
. Create a custom resource file named `ServiceMeshMemberRoll` in the same namespace as the `ServiceMeshControlPlane` custom resource.
. Name the resource `default`.
. Add the namespaces to the member list in the `ServiceMeshMemberRoll`. The `bookinfo` namespace is joined to the {ProductShortName} in this example.
+
.Namespace configuration example
[source,yaml]
----
apiVersion: maistra.io/v1
kind: ServiceMeshMemberRoll
metadata:
name: default
spec:
members:
# a list of namespaces joined into the service mesh
- bookinfo
----

10
modules/ossm-mt-vs-clusterwide.adoc Normal file
View File

@@ -0,0 +1,10 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/installing-mt-ossm.adoc
[id="ossm-mt-vs-clusterwide_{context}"]
= Differences between multi-tenant and cluster-wide installations
The main difference between a multi-tenant installation and a cluster-wide installation is the scope of privileges used by the control plane deployments, for example, Galley and Pilot. The components no longer use cluster-scoped Role Based Access Control (RBAC) `ClusterRoleBinding`, but rely on namespace-scoped RBAC `RoleBinding`.
Every namespace in the `members` list will have a `RoleBinding` for each service account associated with a control plane deployment and each control plane deployment will only watch those member namespaces. Each member namespace has a `maistra.io/member-of` label added to it, where the `member-of` value is the namespace containing the control plane installation.

85
modules/ossm-operator-install.adoc Normal file
View File

@@ -0,0 +1,85 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/installing-ossm.adoc
[id="ossm-operator-installation_{context}"]
= Installing the Operators
The {ProductShortName} installation process introduces an Operator to manage the installation of the control plane within the `istio-operator` namespace. This Operator defines and monitors a custom resource related to the deployment, update, and deletion of the control plane.
Starting with {ProductName} {ProductVersion}, you must install the Jaeger Operator and the Kiali Operator before the {ProductName} Operator can install the control plane.
[id="ossm-operator-install-jaeger_{context}"]
== Installing the Jaeger Operator
You must install the Jaeger Operator for the {ProductName} Operator to install the control plane.
.Prerequisites
* An account with cluster administrator access.
.Procedure
. Log into your {product-title} installation as a cluster administrator.
. Run the following commands to install the Jaeger Operator:
+
----
$ oc new-project observability # create the project for the jaeger operator
$ oc create -n observability -f https://raw.githubusercontent.com/jaegertracing/jaeger-operator/v1.13.1/deploy/crds/jaegertracing_v1_jaeger_crd.yaml
$ oc create -n observability -f https://raw.githubusercontent.com/jaegertracing/jaeger-operator/v1.13.1/deploy/service_account.yaml
$ oc create -n observability -f https://raw.githubusercontent.com/jaegertracing/jaeger-operator/v1.13.1/deploy/role.yaml
$ oc create -n observability -f https://raw.githubusercontent.com/jaegertracing/jaeger-operator/v1.13.1/deploy/role_binding.yaml
$ oc create -n observability -f https://raw.githubusercontent.com/jaegertracing/jaeger-operator/v1.13.1/deploy/operator.yaml
----
[id="ossm-operator-install-kiali_{context}"]
== Installing the Kiali Operator
You must install the Kiali Operator for the {ProductName} Operator to install the control plane.
.Prerequisites
* Review the link:https://www.kiali.io/documentation/getting-started[Kiali] documentation.
* An account with cluster administrator access.
.Procedure
. Log into your {product-title} installation as a cluster administrator.
. Run the following command to install the Kiali Operator:
+
----
$ bash <(curl -L https://git.io/getLatestKialiOperator) --operator-image-version v1.0.0 --operator-watch-namespace '**' --accessible-namespaces '**' --operator-install-kiali false
----
[id="ossm-operator-install-istio_{context}"]
== Installing the {ProductName} Operator
.Prerequisites
* Review the link:https://github.com/Maistra/istio-operator/tree/maistra-0.12/deploy[Operator templates on GitHub].
* An account with cluster administrator access.
* The Jaeger Operator must be installed.
* The Kiali Operator must be installed.
.Procedure
. Log into your {product-title} installation as a cluster administrator.
. If the `istio-operator` and `istio-system` namespaces do not exist, run these commands to create the namespaces:
+
----
$ oc new-project istio-operator
$ oc new-project istio-system
----
. Run this command to install the {ProductShortName} Operator. You can run them from any host with access to the cluster.
+
----
$ oc apply -n istio-operator -f https://raw.githubusercontent.com/Maistra/istio-operator/maistra-0.12/deploy/servicemesh-operator.yaml
----

29
modules/ossm-operator-verify.adoc Normal file
View File

@@ -0,0 +1,29 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/installing-ossm.adoc
[id="ossm-operator-verify_{context}"]
= Verifying the Operator installation
Before proceeding with the install process, verify that the Operator is installed correctly.
.Prerequisites
* An account with cluster administrator access.
.Procedure
. Log into your {product-title} installation as a cluster administrator.
. Run this command to verify that the Operator is installed correctly.
+
----
$ oc get pods -n istio-operator
----
. When the Operator reaches a running state, it is installed correctly.
+
----
NAME READY STATUS RESTARTS AGE
istio-operator-5cd6bcf645-fvb57 1/1 Running 0 1h
----

35
modules/ossm-remove-control-plane.adoc Normal file
View File

@@ -0,0 +1,35 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/removing-ossm.adoc
[id="ossm-remove-control-plane_{context}"]
= Removing the control plane
Follow this procedure to remove the {ProductName} control plane.
.Procedure
[NOTE]
====
When you remove the custom resource, {ProductShortName} tells the Operator to begin uninstalling everything it installed.
====
[TIP]
====
You can use the shortened `smcp` command in place of `servicemeshcontrolplanes`.
====
. Run this command to retrieve the name of the installed custom resource:
+
----
$ oc get servicemeshcontrolplanes -n istio-system
----
+
. Replace `<name_of_custom_resource>` with the output from the previous command, and run this command to remove the custom resource:
+
----
$ oc delete servicemeshcontrolplanes -n istio-system <name_of_custom_resource>
----

63
modules/ossm-remove-operator.adoc Normal file
View File

@@ -0,0 +1,63 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/removing-ossm.adoc
[id="ossm-remove-operator_{context}"]
= Removing the Operators
You must remove the Operators to successfully remove {ProductName}. Once you remove the {ProductName} Operator, you must remove the Jaeger Operator and the Kiali Operator.
[id="ossm-remove-operator-istio_{context}"]
== Removing the {ProductName} Operator
Follow this procedure to remove the {ProductName} Operator.
.Prerequisites
* An account with cluster administrator access.
* The {ProductName} Operator must be installed.
.Procedure
* Run the following command to remove the {ProductName} Operator:
+
----
$ oc delete -n istio-operator -f https://raw.githubusercontent.com/Maistra/istio-operator/maistra-0.12/deploy/servicemesh-operator.yaml
----
[id="ossm-remove-operator-jaeger_{context}"]
== Removing the Jaeger Operator
This procedure removes the Jaeger Operator.
.Prerequisites
* An account with cluster administrator access.
* The Jaeger Operator must be installed.
.Procedure
* Run the following commands to remove the Jaeger Operator:
+
----
$ oc delete -n observability -f https://raw.githubusercontent.com/jaegertracing/jaeger-operator/v1.13.1/deploy/operator.yaml
$ oc delete -n observability -f https://raw.githubusercontent.com/jaegertracing/jaeger-operator/v1.13.1/deploy/role_binding.yaml
$ oc delete -n observability -f https://raw.githubusercontent.com/jaegertracing/jaeger-operator/v1.13.1/deploy/role.yaml
$ oc delete -n observability -f https://raw.githubusercontent.com/jaegertracing/jaeger-operator/v1.13.1/deploy/service_account.yaml
$ oc delete -n observability -f https://raw.githubusercontent.com/jaegertracing/jaeger-operator/v1.13.1/deploy/crds/jaegertracing_v1_jaeger_crd.yaml
----
[id="ossm-remove-operator-kiali_{context}"]
== Removing the Kiali Operator
.Prerequisites
* An account with cluster administrator access.
* The Kiali Operator must be installed.
.Procedure
* Run the following command to remove the Kiali Operator:
+
----
$ bash <(curl -L https://git.io/getLatestKialiOperator) --uninstall-mode true --operator-watch-namespace '**'
----

24
modules/ossm-remove-projects.adoc Normal file
View File

@@ -0,0 +1,24 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/removing-ossm.adoc
[id="ossm-remove-projects_{context}"]
= Removing the projects
Follow this procedure to remove the {ProductName} projects.
.Procedure
. Run this command to remove the `istio-system` project:
+
----
$ oc delete project istio-system
----
+
. Run this command to remove the `istio-operator` project:
+
----
$ oc delete project istio-operator
----

77
modules/ossm-rn-fixed-issues.adoc Normal file
View File

@@ -0,0 +1,77 @@
////
Module included in the following assemblies:
- servicemesh-release-notes.adoc
////
[id="ossm-rn-fixed-issues_{context}"]
= Fixed issues
////
Provide the following info for each issue if possible:
Consequence - What user action or situation would make this problem appear (If you have the foo option enabled and did x)? What did the customer experience as a result of the issue? What was the symptom?
Cause - Why did this happen?
Fix - What did we change to fix the problem?
Result - How has the behavior changed as a result? Try to avoid “It is fixed” or “The issue is resolved” or “The error no longer presents”.
////
The following issues been resolved in the current release:
* https://issues.jboss.org/browse/MAISTRA-4[MAISTRA-4] - The uninstall does not remove all the files, and as a result, when you re-install the istio-operator installation fails because `customresourcedefinitions.apiextensions.k8s.io "installations.istio.openshift.com"` already exists.
* https://issues.jboss.org/browse/MAISTRA-5[MAISTRA-5] - `openshift-ansible-istio-installer-job` pod tries to start but with errors.
* https://issues.jboss.org/browse/MAISTRA-13[MAISTRA-13] - Installer should determine release version from installed components. At present, the installer queries the yaml file, however if the yaml has been modified, the installer is not able to remove an older version.
* https://github.com/Maistra/openshift-ansible/pull/19/[MAISTRA-21] - The default in the installer of 512Mi was too low for tracing. Increased default Elasticsearch memory from 512 MB to 1 GB.
* https://issues.jboss.org/browse/MAISTRA-61[MAISTRA-61] After all applicable resources are deployed to OpenShift, Istio sidecars may lose information about their routes and can no longer communicate with services until the next update is received.
* https://issues.jboss.org/browse/MAISTRA-79[MAISTRA-79] - Running the `istiooc cluster up` command results in the istio-operator namespace deploying a pod responsible for continually ensuring the Elasticsearch sysctl requirements are met. This loop runs constantly causing a significant load on the system running the cluster.
* https://issues.jboss.org/browse/MAISTRA-110[MAISTRA-110] In large clusters, citadel can take a significant amount of time to create secrets. This may cause the installation to fail.
* https://issues.jboss.org/browse/MAISTRA-157[MAISTRA-157] The conditional rate limiting feature does not restrict access as expected.
* https://issues.jboss.org/browse/MAISTRA-196[MAISTRA-196] If you edit the installation to modify a parameter, for example to enable authentication, the new installation will fail due to the existence of the new 1.1 CRD configmaps.
* https://issues.jboss.org/browse/MAISTRA-420[MAISTRA-420] [Multi-tenant implementation] The Jaeger agent pods are unscheduled as a result of port collision in multi-tenancy deployment on OpenShift 4.1.rc.5.
* https://issues.jboss.org/browse/MAISTRA-245[MAISTRA-245] The sidecar injector pod fails to start if you are running the upstream community version.
* https://issues.jboss.org/browse/MAISTRA-462[MAISTRA-462] [Multi-tenant implementation] After adding a namespace member to a second control plane, Kiali does not display the namespace member in the namespace list because the namespace for the second control plane is missing the `maistra.io/member-of` and `istio.openshift.io/member-of` labels. This is a result of the installation of the second control plane failing due to https://issues.jboss.org/browse/MAISTRA-464[MAISTRA-464](the operator can't create the `istio-ingressgateway` service in the second control plane, because the NodePort already being used by the first control plane). The workaround is to manually change the node ports of the `istio-ingressgateway` service in the first control plane's namespace (using `oc edit svc`). The operator will then be able to finish deploying the second control plane.
* https://issues.jboss.org/browse/MAISTRA-466[MAISTRA-466] [Multi-tenant implementation] When you install more than one control plane, the operator overwrites the Kiali oauthclient yaml on any existing Kiali installations so that only the most recent installation functions. The Kiali oauthclient (`oc get oauthclients kiali`) contains a list of the authorized URLs that OpenShift OAuth will redirect to. If your URL is not part of this list, then the oauth login will fail and return the following message:
+
----
`{"error":"invalid_request","error_description":"The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed."}
----
+
* https://issues.jboss.org/browse/MAISTRA-469[MAISTRA-469] If you delete a project before deleting the ServiceMeshControlPlane, the cleanup process does not execute for resources in the deleted project. Service accounts added to the SecurityContextConstraints are not removed and the Kiali OAuthClient resource is not updated properly.
* https://issues.jboss.org/browse/MAISTRA-470[MAISTRA-470] If you include the control plane namespace in the member roll, the reconciliation process produces an error that spams the logs and prevents the status of the configuredMembers list from updating even for members that were successfully configured.
* https://issues.jboss.org/browse/KIALI-1284[KIALI-1284] In Istio, a Workload can be any pod or group of pods, regardless where they originate from. They may come from Kubernetes Deployments, Replica Sets or even as a single "orphan" pod. In Kiali the current assumption is that a Workload comes from a Deployment. This should represent the vast majority of the cases.
* https://issues.jboss.org/browse/KIALI-1570[KIALI-1570]
When a graph is loading in the Kiali console, a message that the graph is empty is displayed instead of a message that the graph is loading.
* https://issues.jboss.org/browse/KIALI-1572[KIALI-1572]
If you see this ERROR message when you view the Kiali logs, you can ignore it:
+
----
Failed to determine console version from file [/opt/kiali/console/version.txt]. error=open /opt/kiali/console/version.txt: no such file or directory Kiali: Console version: unknown
----
+
* https://issues.jboss.org/browse/KIALI-1609[KIALI-1609]
When dealing with very small values (for example, less than 0.0.1 rps) you might encounter some inconsistencies in the graph. We are working on making changes to have this function better when dealing with very small values.
* https://issues.jboss.org/browse/KIALI-2261[KIALI-2261] In the Kiali graph, unused links (that is, edges with no traffic) are being labeled as having 100% of the request traffic, even though there is currently no request traffic. See also https://issues.jboss.org/browse/KIALI-2296[KIALI-2296].
* https://issues.jboss.org/browse/KIALI-2403[KIALI-2403] The Istio version is no longer listed on the Kiali About page after moving to Istio 1.1.0-snapshot.6, because the latest Istio Pilot now listens on a different port. Istio Pilot listens on port 8080, and you can visit Pilot to determine the Istio version (http://istio-pilot:8080/version).
* https://issues.jboss.org/browse/KIALI-2430[KIALI-2430] When you click on a TCP edge, and then click on an HTTP edge the graph crashes in Kiali.
* https://issues.jboss.org/browse/KIALI-2671[KIALI-2671] If you *do not* specify a dashboard user/password in the control plane custom resource the operator will use Oauth for the installation. The OpenShift strategy for using Oauth does not work in {ProductName} {ProductVersion} Technology Preview 10. As a workaround, ensure that you provide a user and password in the custom resource.
* https://issues.jboss.org/browse/KIALI-2942[KIALI-2942] When using OpenShift OAuth, when you click the logout link, you are still logged into the Kiali console. When you go to the login URL it will check your cookies and then automatically log you back in. The workaround is to delete the Kiali cookie.

158
modules/ossm-rn-known-issues.adoc Normal file
View File

@@ -0,0 +1,158 @@
////
Module included in the following assemblies:
- servicemesh-release-notes.adoc
////
[id="ossm-rn-known-issues_{context}"]
= Known issues
////
Consequence - What user action or situation would make this problem appear (Selecting the Foo option with the Bar version 1.3 plugin enabled results in an error message)? What did the customer experience as a result of the issue? What was the symptom?
Cause (if it has been identified) - Why did this happen?
Workaround (If there is one)- What can you do to avoid or negate the effects of this issue in the meantime? Sometimes if there is no workaround it is worthwhile telling readers to contact support for advice. Never promise future fixes.
Result - If the workaround does not completely address the problem.
////
These limitations exist in {ProductName} at this time:
* {ProductName} does not support IPv6, as it it not supported by the upstream Istio project, nor fully supported by OpenShift.
////
https://github.com/istio/old_issues_repo/issues/115
////
* The istio-init container requires a privileged security context or at least to run as root and to have the NET_ADMIN capability. The istio-init container needs to be privileged because it needs to properly configure the iptables rules in the pod to intercept network connections. The team is currently investigating ideas for ways to reduce the privileges required by Istio.
+
[NOTE]
====
The Istio CNI plugin allows a pod to join the service mesh without requiring additional privileges to be granted for each pod. To enable the plugin, edit the control plane custom resource file
to set the *enabled* field in the *istio_cni* section to `true`.
====
+
* Graph layout - The layout for the Kiali graph can render differently, depending on your application architecture and the data to display (number of graph nodes and their interactions). Because it is difficult if not impossible to create a single layout that renders nicely for every situation, Kiali offers a choice of several different layouts. To choose a different layout, you can choose a different *Layout Schema* from the *Graph Settings* menu.
[NOTE]
====
While Kafka publisher is included in the release as part of Jaeger, it is not supported.
====
[id="ossm-rn-known-issues-sm_{context}"]
== {ProductName} Issues
These are the known issues in {ProductName} at this time:
* https://issues.jboss.org/browse/MAISTRA-684[MAISTRA-684] The default Jaeger version in the `istio-operator` is 1.12.0, which does not match Jaeger version 1.13.1 that shipped in {ProductName} {ProductVersion}.
+
If you install {ProductName} {ProductVersion} without changing the Jaeger version to 1.13.1, this is what you see when you check the pods in `istio-system`:
+
----
$ oc get pods -n istio-system
NAME READY STATUS RESTARTS AGE
elasticsearch-0 1/1 Running 0 16m
grafana-694d54c786-m6dfc 2/2 Running 0 18m
istio-citadel-7658c96954-r8p46 1/1 Running 0 18m
istio-egressgateway-d759556b8-hwc7n 1/1 Running 0 18m
istio-galley-7cf565999f-b729t 1/1 Running 0 18m
istio-ingressgateway-bc97545d5-5mpw4 1/1 Running 0 18m
istio-pilot-dd7c67fb5-r8nbt 2/2 Running 0 29m
istio-policy-b5df8c557-5xbbl 2/2 Running 0 18m
istio-sidecar-injector-5bccb75987-xl6t6 1/1 Running 0 18m
istio-telemetry-7f86b4f6d9-kgl5p 2/2 Running 0 30m
jaeger-collector-85c597698c-54b2c 0/1 ImagePullBackOff 0 18m
jaeger-query-59b877c9d9-92vmj 1/3 ImagePullBackOff 0 18m
kiali-54ff784b57-8clh2 1/1 Running 0 18m
prometheus-7b89468cf6-pbnqh 2/2 Running 0 18m
----
+
Run this command to see `istio-system` events:
+
----
$ oc get events -n istio-system
----
+
You will see this error:
+
----
...
8m50s Warning Failed pod/jaeger-query-59b877c9d9-92vmj Failed to pull image "registry.redhat.io/distributed-tracing-tech-preview/jaeger-agent:1.12.0": rpc error: code = Unknown desc = Error reading manifest 1.12.0 in registry.redhat.io/distributed-tracing-tech-preview/jaeger-agent: error parsing HTTP 404 response body: invalid character 'F' looking for beginning of value: "File not found.\""
...
----
+
The workaround is to make the following change to your custom resource to ensure you install Jaeger 1.13.1:
+
[source,yaml]
----
tracing:
enabled: true
jaeger:
tag: 1.13.1
----
* https://issues.jboss.org/browse/MAISTRA-622[MAISTRA-622] In Maistra 0.12.0/TP12, permissive mode does not work. The user has the option to use Plain text mode or Mutual TLS mode, but not permissive.
* https://issues.jboss.org/browse/MAISTRA-572[MAISTRA-572] Jaeger cannot be used with Kiali. In this release Jaeger is configured to use the OAuth proxy, but is also only configured to work through a browser and doesn't allow service access. Kiali cannot properly communicate with the Jaeger endpoint and it considers Jaeger to be disabled. See also https://issues.jboss.org/browse/TRACING-591[TRACING-591].
* https://issues.jboss.org/browse/MAISTRA-465[MAISTRA-465] The Maistra operator fails to create a service for operator metrics.
* https://issues.jboss.org/browse/MAISTRA-453[MAISTRA-453] If you create a new project and deploy pods immediately, sidecar injection does not occur. The operator fails to add the `maistra.io/member-of` before the pods are created, therefore the pods must be deleted and recreated for sidecar injection to occur.
* https://issues.jboss.org/browse/MAISTRA-357[MAISTRA-357] In OpenShift 4 Beta on AWS, it is not possible, out of the box, to access a TCP or HTTPS service through the ingress gateway on a port other than port 80. The AWS load balancer has a health check that verifies if port 80 on the service endpoint is active.
+
The load balancer health check only checks the first port defined in the Istio ingress gateway ports list. This port is configured as 80/HTTP:31380/TCP. Without a service running on this port, the load balancer health check fails.
+
To check HTTPS or TCP traffic by using an ingress gateway, you must have an existing HTTP service, for example, the Bookinfo sample application product page running on the ingress gateway port 80. Alternatively, using the AWS EC2 console, you can change the port that the load balancer uses to perform the health check, and replace 80 with the port your service actually uses.
* https://issues.jboss.org/browse/MAISTRA-348[MAISTRA-348] To access a TCP service by using the ingress gateway on a port other than 80 or 443, use the service hostname provided by the AWS load balancer rather than the OpenShift router.
+
The istio-ingressgateway route hostname (for example, `istio-ingressgateway-istio-system.apps.[cluster name].openshift.com`) works with port 80 or port 443 traffic. However, that route hostname does not support other port traffic.
+
To access service(s) running on the ingress gateway TCP port(s), you can retrieve the istio-ingressgateway external hostname (for example,
`[uuid].[aws region].elb.amazonaws.com`) and then check traffic by using that external hostname value.
+
To retrieve the external IP hostname value, issue this command:
+
----
$ oc -n istio-system get service istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].hostname}'
----
* https://issues.jboss.org/browse/MAISTRA-193[MAISTRA-193] Unexpected console info messages are visible when health checking is enabled for citadel.
* https://issues.jboss.org/browse/MAISTRA-158[MAISTRA-158] Applying multiple gateways referencing the same hostname will cause all gateways to stop functioning.
* https://issues.jboss.org/browse/MAISTRA-108[MAISTRA-108] Part of the process to install Operator Lifecycle Manager (OLM) in an {product-title} cluster is to run the https://docs.openshift.com/container-platform/3.11/install_config/installing-operator-framework.html#installing-olm-using-ansible_installing-operator-framework[registry authorization playbook], but an error prevents the process from completing successfully.
+
The task "openshift_control_plane : Check for file paths outside of /etc/origin/master in master's config" fails because if finds "/dev/null" string within the master-config.yaml file. This string is added when we patch the configuration when preparing the cluster to install Istio.
+
Here are the two webhooks:
+
[subs=+macros]
----
MutatingAdmissionWebhook:
configuration:
apiVersion: apiserver.config.k8s.io/v1alpha1
kind: WebhookAdmission
pass:quotes[*kubeConfigFile: /dev/null*]
----
+
[subs=+macros]
----
ValidatingAdmissionWebhook:
configuration:
apiVersion: apiserver.config.k8s.io/v1alpha1s
kind: WebhookAdmission
pass:quotes[*kubeConfigFile: /dev/null*]
----
+
Create a soft link from `/var/lib/origin/null` to `/dev/null` and replace the two kubeConfigFile variables to `/var/lib/origin/null`. This makes the task think /var/lib/origin/null is an asset in the origin "perimeter" and continue running.
* https://issues.jboss.org/browse/MAISTRA-62[MAISTRA-62] After a successful Istio installation, when upgrading an OCP cluster from 3.10 to 3.11, the storage upgrade task fails causing the entire upgrade process to fail.
[id="ossm-rn-known-issues-kiali_{context}"]
== Kiali Issues
* https://issues.jboss.org/browse/KIALI-3118[KIALI-3118] After changes to the ServiceMeshMemberRoll, for example adding or removing namespaces, the Kiali pod restarts and then displays errors on the Graph page while the Kiali pod is restarting.
* https://issues.jboss.org/browse/KIALI-3096[KIALI-3096] Runtime metrics fail in {ProductShortName}. There is an oauth filter between the {ProductShortname} and Prometheus, requiring a bearer token to be passed to Prometheus before access will be granted. Kiali has been updated to use this token when communicating to the Prometheus server, but the application metrics are currently failing with 403 errors.
* https://issues.jboss.org/browse/KIALI-2206[KIALI-2206] When you are accessing the Kiali console for the first time, and there is no cached browser data for Kiali, the “View in Grafana” link on the Metrics tab of the Kiali Service Details page redirects to the wrong location. The only way you would encounter this issue is if you are accessing Kiali for the first time.
* https://github.com/kiali/kiali/issues/507[KIALI-507] Kiali does not support Internet Explorer 11. This is because the underlying frameworks do not support Internet Explorer. To access the Kiali console, use one of the two most recent versions of the Chrome, Edge, Firefox or Safari browser.

82
modules/ossm-rn-new-features.adoc Normal file
View File

@@ -0,0 +1,82 @@
////
Module included in the following assemblies:
- servicemesh-release-notes.adoc
////
[id="ossm-rn-new-features_{context}"]
////
Feature – Describe the new functionality available to the customer. For enhancements, try to describe as specifically as possible where the customer will see changes.
Reason – If known, include why has the enhancement been implemented (use case, performance, technology, etc.). For example, showcases integration of X with Y, demonstrates Z API feature, includes latest framework bug fixes. There may not have been a 'problem' previously, but system behaviour may have changed.
Result – If changed, describe the current user experience
////
== New features Technology Preview 12
This release of {ProductName} adds support for Istio 1.1.8, Jaeger 1.13.1, Kiali 1.0.0, and the 3scale Istio Adapter 0.7.1.
Other notable changes in this release include the following:
* Integrates the Kiali and Jaeger operators into the installation.
* Adds support for Kubernetes Container Network Interface (CNI).
* Adds support for Operator Lifecycle Management (OLM).
* Updates the Istio OpenShift Router for multitenancy.
* Defaults to configuring the control planes for multitenancy. You can still configure a single tenant control plane in {ProductName} {ProductVersion}.
[NOTE]
====
To simplify installation and support, future releases will only support the a multi-tenant control plane for one or more tenants.
====
== New features Technology Preview 11
The release of {ProductName} adds support for multi-tenant installations, Red Hat Enterprise Linux (RHEL) Universal Base Images (UBI8), OpenSSL 1.1.1, Kiali 0.20.x, the 3scale Istio Adapter 0.6.0, and Istio 1.1.5.
== New features Technology Preview 10
The release of {ProductName} adds support for Kiali 0.16.x, the 3scale Istio Adapter 0.5.0, and Istio 1.1.
== New features Technology Preview 9
The release of {ProductName} adds support for Kiali 0.15.x, Jaeger 1.11, the 3scale Istio Adapter 0.4.1, and Istio 1.1.0-rc.2.
[NOTE]
====
Starting with {ProductName} 0.9.TechPreview, Mixer’s policy enforcement is disabled by default, but you must enable it to run policy tasks. See https://docs.openshift.com/container-platform/3.11/servicemesh-install/servicemesh-install.html#update-mixer-policy-enforcement[Update Mixer policy enforcement] for instructions on enabling Mixer policy enforcement.
====
== New features Technology Preview 8
The release of {ProductName} adds support for Kiali 0.14.x and the 3scale Istio Adapter 0.3.
== New features Technology Preview 7
The release of {ProductName} adds the 3scale Istio Adapter and support for Kiali 0.13.x, Jaeger 1.9.0, and Istio 1.1.
== New features Technology Preview 6
The release of {ProductName} adds support for Kiali 0.11.x and and Istio 1.0.5.
== New features Technology Preview 5
The release of {ProductName} adds support for Kiali 0.10.x, Jaeger 1.8.1, and Istio 1.0.4.
== New features Technology Preview 4
The release of {ProductName} adds support for Kiali 0.9.x and Istio 1.0.3.
== New features Technology Preview 3
The release of {ProductName} adds support for OpenShift 3.11, support for Kiali 0.8.x, and an updated base Ansible installer (3.11.16-3).
== New features Technology Preview 2
The release adds the Kiali observability console to {ProductName}. Kiali provides a number of graphs that you can use to view the topography and health of the microservices that make up your service mesh. You can view predefined dashboards that provide detailed request and response metrics (volume, duration, size, TCP traffic) per inbound and outbound traffic. You can also browse your service mesh by application, workloads, and services to view the health of each element.
== New features Technology Preview 1
{ProductName} provides a number of key capabilities uniformly across a network of services:
* *Traffic Management* - Control the flow of traffic and API calls between services, make calls more reliable, and make the network more robust in the face of adverse conditions.
* *Service Identity and Security* - Provide services in the mesh with a verifiable identity and provide the ability to protect service traffic as it flows over networks of varying degrees of trustworthiness.
* *Policy Enforcement* - Apply organizational policy to the interaction between services, ensure access policies are enforced and resources are fairly distributed among consumers. Policy changes are made by configuring the mesh, not by changing application code.
* *Telemetry* - Gain understanding of the dependencies between services and the nature and flow of traffic between them, providing the ability to quickly identify issues.

20
modules/ossm-security-constraints.adoc Normal file
View File

@@ -0,0 +1,20 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/prepare-to-deploy-applications-ossm.adoc
[id="ossm-security-constraints_{context}"]
= {ProductName} security constraints
[NOTE]
====
The relaxing of security constraints is only necessary during the {ProductName} Technology Preview.
====
When you deploy an application into a {ProductShortName} running in an OpenShift environment, it is necessary to relax the security constraints placed on the application by its service account to ensure the application can function correctly. Each service account must be granted permissions with the `anyuid` and `privileged` Security Context Constraints (SCC) to enable the sidecars to run correctly.
The `privileged` SCC is required to ensure changes to the pod's networking configuration is updated successfully with the `istio-init` initialization container and the `anyuid` SCC is required to enable the sidecar container to run with its required user id of `1337`.
To configure the correct permissions it is necessary to identify the service accounts being used by your application's pods. For most applications, this will be the `default` service account, however your Deployment/DeploymentConfig may override this within the pod specification by providing the `serviceAccountName`.
For each identified service account you must update the cluster configuration to ensure they are granted access to the `anyuid` and `privileged` SCCs by executing the following commands from an account with cluster admin privileges.

22
modules/ossm-servicemesh-overview.adoc Normal file
View File

@@ -0,0 +1,22 @@
////
Module included in the following assemblies:
- servicemesh-install.adoc
- servicemesh-release-notes.adoc
////
[id="ossm-servicemesh-overview_{context}"]
= {ProductName} overview
[IMPORTANT]
====
This release of {ProductName} is a Technology Preview release only. Technology Preview releases are not supported with Red Hat production service-level agreements (SLAs) and might not be functionally complete, and Red Hat does NOT recommend using them for production. Using {ProductName} on a cluster renders the whole OpenShift cluster as a technology preview, that is, in an unsupported state. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. For more information see link:https://access.redhat.com/support/offerings/techpreview/[Red Hat Technology Preview Features Support Scope].
====
{ProductName} is a platform that provides behavioral insight and operational control over the service mesh, providing a uniform way to connect, secure, and monitor microservice applications.
The term _service mesh_ describes the network of microservices that make up applications in a distributed microservice architecture and the interactions between those microservices. As a service mesh grows in size and complexity, it can become harder to understand and manage.
Based on the open source https://istio.io/[Istio] project, {ProductName} adds a transparent layer on existing distributed applications without requiring any changes to the service code. You add {ProductName} support to services by deploying a special sidecar proxy throughout your environment that intercepts all network communication between microservices. You configure and manage the service mesh using the control plane features.
{ProductName} provides an easy way to create a network of deployed services that provides discovery, load balancing, service-to-service authentication, failure recovery, metrics, and monitoring. A service mesh also provides more complex operational functionality, including A/B testing, canary releases, rate limiting, access control, and end-to-end authentication.

16
modules/ossm-support.adoc Normal file
View File

@@ -0,0 +1,16 @@
////
Module included in the following assemblies:
- servicemesh-release-notes.adoc
////
[id="ossm-support_{context}"]
= Getting support
If you experience difficulty with a procedure described in this documentation, visit the Red Hat Customer Portal at http://access.redhat.com. Through the customer portal, you can:
* Search or browse through the Red Hat Knowledgebase of technical support articles about Red Hat products
* Submit a support case to Red Hat Global Support Services (GSS)
* Access other product documentation
If you have a suggestion for improving this guide or have found an error, please submit a Bugzilla report at http://bugzilla.redhat.com against *Product* for the *Documentation* component. Please provide specific details, such as the section number, guide name, and {ProductShortName} version so we can easily locate the content.

21
modules/ossm-supported-configurations.adoc Normal file
View File

@@ -0,0 +1,21 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/preparing-ossm-install.adoc
[id="ossm-supported-configurations_{context}"]
= {ProductName} supported configurations
The following are the only supported configurations for the {ProductName} {ProductVersion}:
* Red Hat {product-title} version 4.1.
[NOTE]
====
OpenShift Online and OpenShift Dedicated are not supported for {ProductName} {ProductVersion}.
====
* The deployment must be contained to a single {product-title} cluster that is not federated.
* 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 only supports configurations where all {ProductShortName} 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.

15
modules/ossm-tech-preview.adoc Normal file
View File

@@ -0,0 +1,15 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/understanding-ossm.adoc
[id="ossm-tech-preview_{context}"]
= {ProductName} is a Technology Preview Release
[IMPORTANT]
====
This release of {ProductName} is a Technology Preview release only. Technology Preview releases are not supported with Red Hat production service-level agreements (SLAs) and might not be functionally complete, and Red Hat does NOT recommend using them for production. Using {ProductName} on a cluster renders the whole OpenShift cluster as a technology preview, that is, in an unsupported state. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. For more information see link:https://access.redhat.com/support/offerings/techpreview/[Red Hat Technology Preview Features Support Scope].
====
.Related information
* Additional information about support for this technology preview is available in this link:https://access.redhat.com/articles/3580021[Red Hat Knowledge Base article].

161
modules/ossm-threescale-authentication.adoc Normal file
View File

@@ -0,0 +1,161 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/threescale_adapter/threescale-adapter.adoc
[id="ossm-threescale-authentication_{context}"]
= Authenticating requests
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.
* *OpenID authentication method*: client ID string parsed from the JSON Web Token.
[id="ossm-threescale-authentication-patterns_{context}"]
== 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
[NOTE]
====
When specifying values from headers they must be lower case. For example, if you want to send a header as `X-User-Key`, this must be referenced in the configuration as `request.headers["x-user-key"]`.
====
[id="ossm-threescale-apikey-authentication_{context}"]
=== 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
[source,yaml]
----
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"]`.
[id="ossm-threescale-appidapikey-authentication_{context}"]
=== 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 authentication method example
[source,yaml]
----
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"]`.
[id="ossm-threescale-openid-authentication_{context}"]
=== OpenID authentication method
To use the _OpenID Connect (OIDC) authentication method_, use the `properties` value on the `subject` field to set `client_id`, and optionally `app_key`.
You can manipulate this object using the methods described previously. In the example configuration shown below, the client identifier (application ID) is parsed from the JSON Web Token (JWT) under the label _azp_. You can modify this as needed.
.OpenID authentication method example
[source,yaml]
----
apiVersion: "config.istio.io/v1alpha2"
kind: instance
metadata:
name: threescale-authorization
spec:
template: threescale-authorization
params:
Subject:
properties:
app_key: request.query_params["app_key"] | request.headers["x-app-key"] | ""
client_id: request.auth.claims["azp"] | ""
action:
path: request.url_path
method: request.method | "get"
service: destination.labels["service-mesh.3scale.net/service-id"] | ""
----
For this integration to work correctly, OIDC must still be done in 3scale for the client to be created in the identity provider (IdP). You should create link:https://istio.io/docs/ops/security/end-user-auth/[end-user authentication] for the service you want to protect in the same namespace as that service. The JWT is passed in the `Authorization` header of the request.
In the sample `Policy` defined below, replace `issuer` and `jwksUri` as appropriate.
.OpenID Policy example
[source,yaml]
----
apiVersion: authentication.istio.io/v1alpha1
kind: Policy
metadata:
name: jwt-example
namespace: bookinfo
spec:
origins:
- jwt:
issuer: >-
http://keycloak-keycloak.34.242.107.254.nip.io/auth/realms/3scale-keycloak
jwksUri: >-
http://keycloak-keycloak.34.242.107.254.nip.io/auth/realms/3scale-keycloak/protocol/openid-connect/certs
principalBinding: USE_ORIGIN
targets:
- name: productpage
----
[id="ossm-threescale-hybrid-authentication_{context}"]
=== 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
[source,yaml]
----
apiVersion: "config.istio.io/v1alpha2"
kind: instance
metadata:
name: threescale-authorization
spec:
template: authorization
params:
subject:
user: request.query_params["user_key"] | request.headers["x-user-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"] | ""
client_id: request.auth.claims["azp"] | ""
action:
path: request.url_path
method: request.method | "get"
service: destination.labels["service-mesh.3scale.net/service-id"] | ""
----

11
modules/ossm-threescale-caching.adoc Normal file
View File

@@ -0,0 +1,11 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/threescale_adapter/threescale-adapter.adoc
[id="ossm-threescale-caching_{context}"]
= 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.

58
modules/ossm-threescale-cr.adoc Normal file
View File

@@ -0,0 +1,58 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/threescale_adapter/threescale-adapter.adoc
[id="ossm-threescale-cr_{context}"]
= Generating 3scale custom resources
The adapter includes a tool that allows you to generate the `handler`, `instance`, and `rule` custom resources.
.Usage
|===
|Option |Description |Required | Default value
|`-h, --help`
|Produces help output for available options
|No
|
|`--name`
|Unique name for this URL, token pair
|Yes
|
|`-n, --namespace`
|Namespace to generate templates
|No
|istio-system
|`-t, --token`
|3scale access token
|Yes
|
|`-u, --url`
|3scale Admin Portal URL
|Yes
|
|`-s, --service`
|3scale API/Service ID
|No
|
|`--auth`
|3scale authentication pattern to specify (1=Api Key, 2=App Id/App Key, 3=OIDC)
|No
|Hybrid
|`-o, --output`
|File to save produced manifests to
|No
|Standard output
|`--version`
|Outputs the CLI version and exits immediately
|No
|
|===

63
modules/ossm-threescale-integrate.adoc Normal file
View File

@@ -0,0 +1,63 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/threescale_adapter/threescale-adapter.adoc
[id="ossm-threescale-integrate_{context}"]
= Integrate the 3Scale adapter with {ProductName}
You can use these examples to configure requests to your services using the 3scale Istio Adapter.
.Prerequisites:
* {ProductName} 0.12.0+
* A working 3scale account (link:https://www.3scale.net/signup/[SaaS] or link:https://access.redhat.com/documentation/en-us/red_hat_3scale_api_management/2.5/html/installing_3scale/onpremises-installation[3scale 2.5 On-Premises])
* xref:../service_mesh_install/preparing-ossm-installation.adoc#preparing-ossm-installation[{ProductName} prerequisites]
* Ensure Mixer policy enforcement is enabled. xref:../service_mesh_install/installing-ossm.adoc#ossm-mixer-policy_installing-ossm[Update Mixer policy enforcement] provides instructions to check the current Mixer policy enforcement status and enable policy enforcement.
[NOTE]
====
To configure the 3scale Istio Adapter, refer to xref:../service_mesh_install/installing-ossm.html#ossm-cr-parameters_installing-ossm[{ProductName} custom resources] for instructions on adding adapter parameters to the custom resource file.
====
[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.
====
. Modify the handler configuration with your 3scale configuration.
+
.Handler configuration example
[source,yaml]
----
apiVersion: "config.istio.io/v1alpha2"
kind: handler
metadata:
name: threescale
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"
----
. Modify the rule configuration with your 3scale configuration to dispatch the rule to the threescale handler.
+
.Rule configuration example
[source,yaml]
----
apiVersion: "config.istio.io/v1alpha2"
kind: rule
metadata:
name: threescale
spec:
match: destination.labels["service-mesh.3scale.net"] == "true"
actions:
- handler: threescale.handler
instances:
- threescale-authorization.instance
----

23
modules/ossm-threescale-integration-settings.adoc Normal file
View File

@@ -0,0 +1,23 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/threescale_adapter/threescale-adapter.adoc
[id="ossm-threescale-integration-settings_{context}"]
= Configure the integration settings in 3scale
Follow this procedure to configure the 3scale integration settings.
[NOTE]
====
For 3scale SaaS customers, {ProductName} is enabled as part of the Early Access program.
====
.Procedure
. Navigate to *[your_API_name]* -> *Integration* -> *Configuration*.
. At the top of the *Integration* page click on *edit integration settings* in the top right corner.
. Under the *Service Mesh* heading, click the *Istio* option.
. Scroll to the bottom of the page and click *Update Service*.

41
modules/ossm-threescale-manifests.adoc Normal file
View File

@@ -0,0 +1,41 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/threescale_adapter/threescale-adapter.adoc
[id="ossm-threescale-manifests_{context}"]
= Generating manifests from a deployed adapter
. 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}
----
. This will produce sample output to the terminal. Edit these samples if required and create the objects using the `oc create` command.
. 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:
.. Label the workload (recommended)
.. Hard code the handler as `service_id`
. xref:../threescale_adapter/threescale-adapter.html#ossm-threescale-routing_threescale-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*.
====
+
----
$ 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}"''
----

7
modules/ossm-threescale-metrics.adoc Normal file
View File

@@ -0,0 +1,7 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/threescale_adapter/threescale-adapter.adoc
[id="ossm-threescale-metrics_{context}"]
= 3scale Adapter metrics
The adapter, by default reports various Prometheus metrics that are exposed on port `8080` at the `/metrics` endpoint. These metrics provide insight into how the interactions between the adapter and 3scale are performing. The service is labeled to be automatically discovered and scraped by Prometheus.

20
modules/ossm-threescale-routing.adoc Normal file
View File

@@ -0,0 +1,20 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/threescale_adapter/threescale-adapter.adoc
[id="ossm-threescale-routing_{context}"]
= Routing service traffic through the adapter
Follow these steps to drive traffic for your service through the 3scale adapter.
.Prerequisites
* Credentials and service ID from your 3scale administrator.
.Procedure
. Match the rule `destination.labels["service-mesh.3scale.net/credentials"] == "threescale"` that you previously created in the configuration, in the `kind: rule` resource.
. 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.
. 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.

18
modules/ossm-threescale-templates.adoc Normal file
View File

@@ -0,0 +1,18 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/threescale_adapter/threescale-adapter.adoc
[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:
+
----
$ 3scale-gen-config --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:
+
----
$ 3scale-gen-config --url="https://<organization>-admin.3scale.net" --name="my-unique-id" --service="123456789" --token="[redacted]"
----

34
modules/ossm-tutorial-bookinfo-adding-destination-rules.adoc Normal file
View File

@@ -0,0 +1,34 @@
////
This TASK module included in the following assemblies:
- ossm-tutorial-bookinfo.adoc
////
[id="ossm-tutorial-bookinfo-adding-destination-rules_{context}"]
= Adding default destination rules
Before you can use the Bookinfo application, you have to add default destination rules. There are two preconfigured yaml files, depending on whether or not you enabled mutual transport layer security (TLS) authentication.
.Procedure
. To add destination rules, run one of the following commands:
** If you did not enable mutual TLS:
+
----
$ oc apply -n myproject -f https://raw.githubusercontent.com/istio/istio/release-1.1/samples/bookinfo/networking/destination-rule-all.yaml
----
** If you enabled mutual TLS:
+
----
$ oc apply -n myproject -f https://raw.githubusercontent.com/istio/istio/release-1.1/samples/bookinfo/networking/destination-rule-all-mtls.yaml
----
+
. To list all available destination rules:
+
----
$ oc get destinationrules -o yaml
----

60
modules/ossm-tutorial-bookinfo-install.adoc Normal file
View File

@@ -0,0 +1,60 @@
////
This TASK module included in the following assemblies:
- ossm-tutorial-bookinfo.adoc
////
[id="ossm-tutorial-bookinfo-install_{context}"]
= Installing the Bookinfo application
The following steps describe deploying and running the Bookinfo tutorial on OpenShift Container Platform with {ProductShortName} {ProductVersion}.
.Prerequisites:
* {product-title} 3.11 or higher installed.
* {ProductName} {ProductVersion} installed.
[NOTE]
====
{ProductName} implements auto-injection differently than the upstream Istio project, therefore this procedure uses a version of the `bookinfo.yaml` file annotated to enable automatic injection of the Istio sidecar.
====
.Procedure
. Create a project for the Bookinfo application.
+
----
$ oc new-project myproject
----
+
. Update the Security Context Constraints (SCC) by adding the service account used by Bookinfo to the `anyuid` and `privileged` SCCs in the _"myproject"_ Namespace:
+
----
$ oc adm policy add-scc-to-user anyuid -z default -n myproject
$ oc adm policy add-scc-to-user privileged -z default -n myproject
----
+
. Deploy the Bookinfo application in the _"myproject"_ Namespace by applying the `bookinfo.yaml` file:
+
----
$ oc apply -n myproject -f https://raw.githubusercontent.com/Maistra/bookinfo/master/bookinfo.yaml
----
+
. Create the ingress gateway for Bookinfo by applying the `bookinfo-gateway.yaml` file:
+
----
$ oc apply -n myproject -f https://raw.githubusercontent.com/Maistra/bookinfo/master/bookinfo-gateway.yaml
----
. Set the value for the `GATEWAY_URL` parameter:
+
----
$ export GATEWAY_URL=$(oc get route -n istio-system istio-ingressgateway -o jsonpath='{.spec.host}')
----

22
modules/ossm-tutorial-bookinfo-overview.adoc Normal file
View File

@@ -0,0 +1,22 @@
////
This CONCEPT module included in the following assemblies:
- ossm-tutorial-bookinfo.adoc
////
[id="ossm-tutorial-bookinfo-overview_{context}"]
= Bookinfo application
The upstream Istio project has an example tutorial called https://istio.io/docs/examples/bookinfo[bookinfo], which is composed of four separate microservices used to demonstrate various Istio features. The Bookinfo application displays information about a book, similar to a single catalog entry of an online book store. Displayed on the page is a description of the book, book details (ISBN, number of pages and other information), and book reviews.
The Bookinfo application consists of four separate microservices:
* The `productpage` microservice calls the `details` and `reviews` microservices to populate the page.
* The `details` microservice contains book information.
* The `reviews` microservice contains book reviews. It also calls the `ratings` microservice.
* The `ratings` microservice contains book ranking information that accompanies a book review.
There are three versions of the reviews microservice:
* Version v1 does not call the `ratings` Service.
* Version v2 calls the `ratings` Service and displays each rating as one to five black stars.
* Version v3 calls the `ratings` Service and displays each rating as one to five red stars.

42
modules/ossm-tutorial-bookinfo-removing.adoc Normal file
View File

@@ -0,0 +1,42 @@
////
This TASK module included in the following assemblies:
- ossm-tutorial-bookinfo.adoc
////
[id="ossm-tutorial-bookinfo-removing_{context}"]
= Removing the Bookinfo application
When you finish with the Bookinfo application, you can remove it by running the cleanup script.
[TIP]
====
Several of the other {ProductShortName} tutorials also use the Bookinfo application. Do not run the cleanup script if you plan to explore other {ProductShortName} tutorials.
====
.Procedure
. Download the cleanup script:
+
----
$ curl -o cleanup.sh https://raw.githubusercontent.com/Maistra/bookinfo/master/cleanup.sh && chmod +x ./cleanup.sh
----
. Delete the Bookinfo virtualservice, gateway, and terminate the Pods by running the cleanup script:
+
----
$ ./cleanup.sh
namespace ? [default] myproject
----
. Confirm shutdown by running these commands:
+
----
$ oc get virtualservices -n myproject
No resources found.
$ oc get gateway -n myproject
No resources found.
$ oc get pods -n myproject
No resources found.
----

26
modules/ossm-tutorial-bookinfo-verify-install.adoc Normal file
View File

@@ -0,0 +1,26 @@
////
This TASK module included in the following assemblies:
- ossm-tutorial-bookinfo.adoc
////
[id="ossm-tutorial-bookinfo-verify-install_{context}"]
= Verifying the Bookinfo installation
Before configuring your application, verify that it successfully deployed.
.Procedure
* To confirm that the application is deployed:
** Run this command:
+
----
$ curl -o /dev/null -s -w "%{http_code}\n" http://<GATEWAY_URL>/productpage
----
+
** Alternatively, you can open `http://<GATEWAY_URL>/productpage` in your browser.
////
TO DO
Add screen shot of bookinfo.
////

54
modules/ossm-tutorial-grafana-accessing.adoc Normal file
View File

@@ -0,0 +1,54 @@
////
This TASK module included in the following assemblies:
- ossm-tutorial-grafana.adoc
////
[id="ossm-tutorial-grafana-accessing_{context}"]
= Accessing the Grafana dashboard
The Grafana dashboard's web-based interface lets you visualize your metrics data.
.Prerequisites:
* {product-title} 3.11 or higher installed.
* {ProductName} {ProductVersion} installed.
* `Bookinfo` demonstration application installed.
.Procedure
. A route to access the Grafana dashboard already exists. Query for details of the route:
+
----
$ export GRAFANA_URL=$(oc get route -n istio-system grafana -o jsonpath='{.spec.host}')
----
+
. Launch a browser and navigate to navigate to `http://<GRAFANA_URL>`. You see Grafana's home screen, as shown in the following figure:
+
image::ossm-grafana-home-screen.png[]
+
. From the menu in the upper-left corner, select *Istio Mesh Dashboard* to see Istio mesh metrics.
+
image::ossm-grafana-mesh-no-traffic.png[]
+
. Generate some traffic by accessing the Bookinfo application:
+
----
$ curl -o /dev/null http://<GATEWAY_URL>/productpage
----
+
The dashboard reflects the traffic through the mesh, similar to the following figure:
+
image::ossm-grafana-mesh-with-traffic.png[]
+
. To see detailed metrics for a Service, click on a Service name in the *Service* column. The Service dashboard resembles the following figure:
+
image::ossm-grafana-services.png[]
+
Note that *TCP Bandwidth* metrics are empty, because Bookinfo only uses http-based Services. The dashboard also displays metrics for Workloads that call the *Client Workloads* Service and for Workloads that process requests from the *Service Workloads*. You can switch to a different Service or filter metrics by client and Service Workloads by using the menus at the top of the dashboard.
+
. To switch to the Workloads dashboard, click *Istio Workload Dashboard* on the menu in the upper-left corner. You will see a screen resembling the following figure:
+
image::ossm-grafana-workloads.png[]
+
This dashboard shows Workload metrics and metrics for client (inbound) and Service (outbound) Workloads. You can switch to a different Workload; to filter metrics by inbound or outbound Workloads, use the menus at the top of the dashboard.

36
modules/ossm-tutorial-jaeger-generating-traces.adoc Normal file
View File

@@ -0,0 +1,36 @@
////
This TASK module included in the following assemblies:
- ossm-tutorial-jaeger-tracing.adoc
////
[[generating-traces-analyzing-trace-data]]
= Generating traces and analyzing trace data
This tutorial uses {ProductShortName} and the `bookinfo` tutorial to demonstrate how you can perform a trace using the Jaeger component of {ProductName}.
.Prerequisites:
* {product-title} 3.11 or higher installed.
* {ProductName} {ProductVersion} installed.
* `Bookinfo` demonstration application installed.
.Procedure
. After you have deployed the Bookinfo application you will need to generate calls to the Bookinfo application so that you have some trace data to analyze. Access http://<GATEWAY_URL>/productpage and refresh the page a few times to generate some trace data.
. A route to access the Jaeger dashboard already exists. Query for details of the route:
+
----
$ export JAEGER_URL=$(oc get route -n istio-system jaeger-query -o jsonpath='{.spec.host}')
----
+
. Launch a browser and navigate to `https://<JAEGER_URL>`.
. In the left pane of the Jaeger dashboard, from the Service menu, select "productpage" and click the *Find Traces* button at the bottom of the pane. A list of traces is displayed, as shown in the following image:
+
image::ossm-jaeger-main-screen.png[]
+
. Click one of the traces in the list to open a detailed view of that trace. If you click on the top (most recent) trace, you see the details that correspond to the latest refresh of the ``/productpage`.
+
image::ossm-jaeger-spans.png[]
+
The trace in the previous figure consists of a few nested spans, each corresponding to a Bookinfo Service call, all performed in response to a ``/productpage` request. Overall processing time was 2.62s, with the *details* Service taking 3.56ms, the *reviews* Service taking 2.6s, and the *ratings* Service taking 5.32ms. Each of the calls to remote Services is represented by a client-side and server-side span. For example, the *details* client-side span is labeled `productpage details.myproject.svc.cluster.local:9080`. The span nested underneath it, labeled `details details.myproject.svc.cluster.local:9080`, corresponds to the server-side processing of the request. The trace also shows calls to *istio-policy*, which reflect authorization checks made by Istio.

48
modules/ossm-tutorial-kiali-accessing-console.adoc Normal file
View File

@@ -0,0 +1,48 @@
////
This TASK module included in the following assemblies:
- ossm-tutorial-kiali.adoc
////
[id="ossm-kiali-tutorial-accessing-console_{context}"]
= Accessing the Kiali console
The Kiali console provides visualization and observability for your Service mesh. The Kiali console has different views that provide insights into Service mesh components at different levels, from Applications to Services to Workloads. It also provides validation for Istio configurations.
.Prerequisites
* {product-title} 3.11 or higher installed.
* {ProductName} {ProductVersion} installed.
* Kiali parameters specified in the custom resource file.
* `Bookinfo` demonstration application installed.
.Procedure
. A route to access the Kiali console already exists. Run the following command to obtain the route and Kiali URL:
+
----
$ oc get routes
----
+
.Sample output showing routes
+
----
NAME HOST/PORT PATH SERVICES PORT TERMINATION WILDCARD
grafana grafana-istio-system.127.0.0.1.nip.io grafana http None
istio-ingress istio-ingress-istio-system.127.0.0.1.nip.io istio-ingress http None
istio-ingressgateway istio-ingressgateway-istio-system.127.0.0.1.nip.io istio-ingressgateway http None
jaeger-query jaeger-query-istio-system.127.0.0.1.nip.io jaeger-query jaeger-query edge None
kiali kiali-istio-system.127.0.0.1.nip.io kiali <all> None
prometheus prometheus-istio-system.127.0.0.1.nip.io prometheus http-prometheus None
tracing tracing-istio-system.127.0.0.1.nip.io tracing tracing edge None
----
+
. Launch a browser and navigate to https://<KIALI_URL> (in the output example, this is `kiali-istio-system.127.0.0.1.nip.io`). You should see the Kiali console login screen.
. Log in to the Kiali console using the user name and password that you specified in the custom resource file during installation.
+
When you first log in you see the Overview page, which provides a quick overview of the health of the various Namespaces that are part of your {ProductShortName}.
+
image:ossm-kiali-overview.png[Overview Page]
+
. Use the left navigation or click one of the Namespace icons to view your Applications, Workloads, or Services.

20
modules/ossm-tutorial-kiali-applications-page.adoc Normal file
View File

@@ -0,0 +1,20 @@
////
This TASK module included in the following assemblies:
- ossm-tutorial-kiali.adoc
////
[id="ossm-kiali-tutorial-applications-page_{context}"]
= Exploring the Applications page
The Applications page lets you search for and view applications, their health, and other details.
.Procedure
. Click *Applications* in the left navigation.
. If necessary, select `bookinfo` from the *Namespace* menu. The page displays the applications in the selected Namespace and their health.
. Hover over the Health icon to view additional health details.
. Click the `reviews` Service to view the details for that application.
+
image:ossm-kiali-applications-details.png[Kiali Applications details]
+
. On the Applications Details page you can view more detailed health information, and drill down for further details about the three versions of the `reviews` Service.
. From the Application Details page you can also click tabs to view Traffic and Inbound and Outbound Metrics for the application.

25
modules/ossm-tutorial-kiali-graph.adoc Normal file
View File

@@ -0,0 +1,25 @@
////
This TASK module included in the following assemblies:
- ossm-tutorial-kiali.adoc
////
[id="ossm-kiali-tutorial-graph_{context}"]
= Exploring the Graph page
The Graph page shows a graph of microservices, which are connected by the requests going through them. On this page, you can see how Applications, Workloads, or Services interact with each other.
.Procedure
. Click *Graph* in the left navigation.
+
image:ossm-kiali-graph.png[Kiali graph]
+
. If necessary, select `bookinfo` from the *Namespace* menu. The graph displays the applications in the Bookinfo application.
. Click the question mark (?) under the *Namespace* menu to take the Graph Help Tour.
. Click *Done* to close the Help Tour.
. Click *Legend* in the lower left corner. Kiali displays the graph legend.
+
image:ossm-kiali-legend.png[Kiali legend]
+
. Close the Graph Legend.
. Hover over the *productpage* Node. Note how the graph highlights only the incoming and outgoing traffic from the Node.
. Click the *productpage* Node. Note how the details on the right side of the page change to display the *productpage* details.

19
modules/ossm-tutorial-kiali-istio-config.adoc Normal file
View File

@@ -0,0 +1,19 @@
////
This TASK module included in the following assemblies:
- ossm-tutorial-kiali.adoc
////
[id="ossm-kiali-tutorial-istio-config_{context}"]
= Exploring the Istio Config page
The Istio Config page lets you view all of the currently running configurations to your {ProductShortName}, such as Circuit Breakers, Destination Rules, Fault Injection, Gateways, Routes, Route Rules, and Virtual Services.
.Procedure
. Click *Istio Config* in the left navigation.
. If necessary, select `bookinfo` from the *Namespace* menu. The page displays a listing of configurations running in the selected Namespace and validation status.
+
image:ossm-kiali-istio-config.png[Istio configuration]
+
. Click one of the configurations to view additional information about the configuration file.
+
image:ossm-kiali-istio-config2.png[Istio Configuration YAML]

28
modules/ossm-tutorial-kiali-services-page.adoc Normal file
View File

@@ -0,0 +1,28 @@
////
This TASK module included in the following assemblies:
- ossm-tutorial-kiali.adoc
////
[id="ossm-kiali-tutorial-services-page_{context}"]
= Exploring the Services page
The Services page lets you search for and view Services, their health, and other details.
.Procedure
. Click *Services* in the left navigation.
. If necessary, select `bookinfo` from the *Namespace* menu. The page displays a listing of all the Services that are running in the selected Namespace and additional information about them, such as health status.
. Hover over the health icon for any of the Services to view health information about the Service. A Service is considered healthy when it is online and responding to requests without errors.
. Click the *Reviews* Service to view its details. Note that there are three different versions of this Service.
+
image:ossm-kiali-services-details.png[Kiali Services details]
+
. On the Services Details page you can view an overview of Workloads, virtual Services, and destination rules associated with the Service.
. From the Services Details page you can also click tabs to view Traffic, Inbound Metrics, and Traces for the Service.
. Click the Actions menu. From here you can perform the following actions:
* Create Weighted Routing
* Create Matching Routing
* Suspend Traffic
* Delete ALL Traffic Routing
. Click the name of one of the Services to view additional details about that specific version of the Service.

19
modules/ossm-tutorial-kiali-workloads-page.adoc Normal file
View File

@@ -0,0 +1,19 @@
////
This TASK module included in the following assemblies:
- ossm-tutorial-kiali.adoc
////
[id="ossm-kiali-tutorial-workloads-page_{context}"]
= Exploring the Workloads page
The Workloads page lets you search for and view Workloads, their health, and other details.
.Procedure
. Click *Workloads* in the left navigation.
. If necessary, select `bookinfo` from the *Namespace* menu. The page displays the Workloads in the selected Namespace, their health, and labels.
. Click the `reviews-v1` Workload to view the details for that Workload.
. On the Workload Details page you can view an overview of Pods and Services associated with the Workload.
+
image:ossm-kiali-workloads-details.png[Kiali Workloads details]
+
. From the Workload Details page you can also click tabs to view Traffic, Logs, and Inbound and Outbound Metrics for the Workload.

62
modules/ossm-tutorial-prometheus-querying-metrics.adoc Normal file
View File

@@ -0,0 +1,62 @@
////
This TASK module included in the following assemblies:
- ossm-tutorial-prometheus.adoc
////
[id="ossm-tutorial-prometheus-querying-metrics_{context}"]
= Querying Prometheus metrics
This tutorial uses {ProductShortName} and the `bookinfo` tutorial to demonstrate how you can query for metrics using Prometheus.
.Prerequisites:
* {product-title} 3.11 or higher installed.
* {ProductName} {ProductVersion} installed.
* `Bookinfo` demonstration application installed.
After you have verified the Bookinfo application has deployed, you will need to generate calls to the application before you query for metrics.
.Procedure
. Verify that the `prometheus` Service is running in your cluster. In Kubernetes environments, execute the following command:
+
----
$ oc get svc prometheus -n istio-system
----
+
You will see something like the following:
+
----
NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE
prometheus 10.59.241.54 <none> 9090/TCP 2m
----
+
. Generate network traffic by accessing the Bookinfo application:
+
----
$ curl -o /dev/null http://$GATEWAY_URL/productpage
----
+
. A route to access the Prometheus user interface already exists. Query for details of the route:
+
----
$ export PROMETHEUS_URL=$(oc get route -n istio-system prometheus -o jsonpath='{.spec.host}')
----
+
. Launch a browser and navigate to `http://<PROMETHEUS_URL>`. You will see the Prometheus home screen, similar to the following figure:
+
image::ossm-prometheus-home-screen.png[]
+
. In the *Expression* field, enter `istio_request_duration_seconds_count`, and click the `Execute` button. You will see a screen similar to the following figure:
+
image::ossm-prometheus-metrics.png[]
+
. You can narrow down queries by using selectors. For example `istio_request_duration_seconds_count{destination_workload="reviews-v2"}` shows only counters with the matching *destination_workload* label. For more information about using queries, see the link:https://prometheus.io/docs/prometheus/latest/querying/basics/#instant-vector-selectors[Prometheus documentation].
+
. To list all available Prometheus metrics, run the following command:
+
----
$ oc get prometheus -n istio-system -o jsonpath='{.items[*].spec.metrics[*].name}' requests_total request_duration_seconds request_bytes response_bytes tcp_sent_bytes_total tcp_received_bytes_total
----
+
Note that returned metric names must be prepended with `istio_` when used in queries, for example, `requests_total` is `istio_requests_total`.

27
modules/ossm-understanding-service-mesh.adoc Normal file
View File

@@ -0,0 +1,27 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/understanding-ossm.adoc
[id="ossm-understanding-service-mesh_{context}"]
= Understanding service mesh
A _service mesh_ is the network of microservices that make up applications in a distributed microservice architecture and the interactions between those microservices. When a service mesh grows in size and complexity, it can become harder to understand and manage.
Based on the open source link:https://istio.io/[Istio] project, {ProductName} adds a transparent layer on existing distributed applications without requiring any changes to the service code. You add {ProductName} support to services by deploying a special sidecar proxy to relevant services in the mesh that intercepts all network communication between microservices. You configure and manage the service mesh using the control plane features.
{ProductName} gives you an easy way to create a network of deployed services that provide:
* Discovery
* Load balancing
* Service-to-service authentication
* Failure recovery
* Metrics
* Monitoring
{ProductShortName} also provides more complex operational functions including:
* A/B testing
* Canary releases
* Rate limiting
* Access control
* End-to-end authentication

49
modules/ossm-updating-master-configuration.adoc Normal file
View File

@@ -0,0 +1,49 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/prepare-to-deploy-applications-ossm.adoc
[id="ossm-updating-master-configuration_{context}"]
= Updating the master configuration
To enable the automatic injection of the {ProductShortName} sidecar, you must first modify the master configuration on each master node in your {product-title} installation to include support for webhooks and signing of Certificate Signing Requests (CSRs).
[NOTE]
====
Updating the master configuration is not necessary if you are running {product-title} 4.1.
====
//.Prerequisites
//* An account with cluster administrator access.
.Procedure
. Change to the directory containing the master configuration file (for example, `/etc/origin/master/master-config.yaml`).
. Create a file named `master-config.patch` with the following contents:
+
----
admissionConfig:
pluginConfig:
MutatingAdmissionWebhook:
configuration:
apiVersion: apiserver.config.k8s.io/v1alpha1
kubeConfigFile: /dev/null
kind: WebhookAdmission
ValidatingAdmissionWebhook:
configuration:
apiVersion: apiserver.config.k8s.io/v1alpha1
kubeConfigFile: /dev/null
kind: WebhookAdmission
----
+
. In the same directory, issue the following commands to apply the patch to the `master-config.yaml` file:
+
----
$ cp -p master-config.yaml master-config.yaml.prepatch
$ oc ex config patch master-config.yaml.prepatch -p "$(cat master-config.patch)" > master-config.yaml
$ /usr/local/bin/master-restart api && /usr/local/bin/master-restart controllers
----

40
modules/ossm-updating-node-configuration.adoc Normal file
View File

@@ -0,0 +1,40 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/preparing-ossm-install.adoc
[id="ossm-updating-node-configuration_{context}"]
= Updating the node configuration
Before you can install the {ProductShortName} into an {product-title} installation, you must modify the master configuration and each of the schedulable nodes. These changes enable the features that are required in the {ProductShortName} and also ensure that Elasticsearch features function correctly.
[NOTE]
====
Updating the node configuration is not necessary if you are running {product-title} 4.1.
====
//.Prerequisites
//* An account with cluster administrator access.
.Procedure
[NOTE]
====
To run the Elastisearch application, you must repeat the steps in this procedure for each node in your {product-title} installation.
====
. Create a file named `/etc/sysctl.d/99-elasticsearch.conf` with the following contents:
+
----
vm.max_map_count = 262144
----
+
. Execute the following command:
+
----
$ sysctl vm.max_map_count=262144
----

139
modules/ossm-vs-istio.adoc Normal file
View File

@@ -0,0 +1,139 @@
// Module included in the following assemblies:
//
// * service_mesh/service_mesh_install/understanding-ossm.adoc
[id="ossm-vs-istio_{context}"]
= Comparing {ProductName} and upstream Istio community installations
An installation of {ProductName} differs from upstream Istio community installations in multiple ways. The modifications to {ProductName} are sometimes necessary to resolve issues, provide additional features, or to handle differences when deploying on OpenShift.
The current release of {ProductName} differs from the current upstream Istio community release in the following ways:
[id="ossm-multi-tenant-install_{context}"]
== Multi-tenant installations
[NOTE]
====
Single-tenant control plane installations are known to cause issues with {product-title} restarts and upgrades. Multi-tenant control plane installations are the default configuration starting with {ProductName} {ProductVersion}.
====
{ProductName} allows you to configure multi-tenant control plane installations, specify the namespaces that can access its {ProductShortName}, and isolate the {ProductShortName} from other control plane instances.
[id="ossm-automatic-injection_{context}"]
== Automatic injection
The upstream Istio community installation automatically injects the sidecar to namespaces you have labeled.
{ProductName} does not automatically inject the sidecar to any namespaces, but requires you to specify the `sidecar.istio.io/inject` annotation as illustrated in the xref:../service_mesh_install/prepare-to-deploy-applications-ossm.html#ossm-automatic-sidecar-injection_deploying-applications-ossm[Automatic sidecar injection] section.
[id="ossm-rbac_{context}"]
== Role Based Access Control features
Role Based Access Control (RBAC) provides a mechanism you can use to control access to a service. You can identify subjects by username or by specifying a set of properties and apply access controls accordingly.
The upstream Istio community installation includes options to perform exact header matches, match wildcards in headers, or check for a header containing a specific prefix or suffix.
.Upstream Istio community matching request headers example
[source,yaml]
----
apiVersion: "rbac.istio.io/v1alpha1"
kind: ServiceRoleBinding
metadata:
name: httpbin-client-binding
namespace: httpbin
spec:
subjects:
- user: "cluster.local/ns/istio-system/sa/istio-ingressgateway-service-account"
properties:
request.headers[<header>]: "value"
----
{ProductName} extends the ability to match request headers by using a regular expression. Specify a property key of `request.regex.headers` with a regular expression.
.{ProductName} matching request headers by using regular expressions
[source,yaml]
----
apiVersion: "rbac.istio.io/v1alpha1"
kind: ServiceRoleBinding
metadata:
name: httpbin-client-binding
namespace: httpbin
spec:
subjects:
- user: "cluster.local/ns/istio-system/sa/istio-ingressgateway-service-account"
properties:
request.regex.headers[<header>]: "<regular expression>"
----
[id="ossm-automatic-route-creation_{context}"]
== Automatic route creation
[WARNING]
====
Automatic route creation is currently incompatible with multi-tenant {ProductShortName} installations. Ensure that it is disabled in your `ServiceMeshControlPlane` if you plan to attempt a multi-tenant installation.
====
{ProductName} automatically manages OpenShift routes for Istio gateways. When an Istio gateway is created, updated, or deleted in the {ProductShortName}, a matching OpenShift route is created, updated, or deleted.
If the following gateway is created:
[source,yaml]
----
apiVersion: networking.istio.io/v1alpha3
kind: Gateway
metadata:
name: gateway1
spec:
selector:
istio: ingressgateway
servers:
- port:
number: 80
name: http
protocol: HTTP
hosts:
- www.bookinfo.com
- bookinfo.example.com
----
The following OpenShift routes are automatically created:
----
$ oc -n istio-system get routes
NAME HOST/PORT PATH SERVICES PORT TERMINATION WILDCARD
gateway1-lvlfn bookinfo.example.com istio-ingressgateway <all> None
gateway1-scqhv www.bookinfo.com istio-ingressgateway <all> None
----
If this gateway is deleted, {ProductName} will delete the routes.
[NOTE]
====
Manually created routes are not managed by the {ProductShortName}.
====
[id="ossm-catch-all-domains_{context}"]
=== Catch-all domains
{ProductName} does not support catch-all or wildcard domains. If {ProductShortName} finds a catch-all domain in the gateway definition, {ProductName} will create the route but link:https://docs.okd.io/latest/architecture/networking/routes.html#route-hostnames[relies on OpenShift to create a default hostname]. The route that {ProductShortName} creates will *not* be a catch-all route and will have a hostname with a `<route-name>[-<namespace>].<suffix>` structure.
[id="ossm-subdomains_{context}"]
=== Subdomains
Subdomains are supported, but they are not enabled by default in OpenShift. {ProductName} will create the route with the subdomain, but it will only work after you enable subdomains in OpenShift. See the link:https://docs.okd.io/latest/install_config/router/default_haproxy_router.html#using-wildcard-routes[OpenShift documentation on Wildcard Routes] for more information.
[id="ossm-tls_{context}"]
=== TLS
OpenShift routes are configured to support TLS.
[NOTE]
====
All OpenShift routes created by {ProductName} are in the `istio-system` namespace.
====
[id="ossm-openssl_{context}"]
== OpenSSL
{ProductName} replaces BoringSSL with OpenSSL. OpenSSL is a software library that contains an open source implementation of the Secure Sockets Layer (SSL) and Transport Layer Security (TLS) protocols. The {ProductName} Proxy binary dynamically links the OpenSSL libraries (libssl and libcrypto) from the underlying Red Hat Enterprise Linux operating system.
[id="ossm-cni_{context}"]
== Container Network Interface (CNI)
{ProductName} includes CNI which provides you with an alternate way to configure application pod networking. When you enable CNI, it replaces the `init-container` network configuration eliminating the need to grant service accounts and namespaces additional privileges by modifying their Security Context Constraints (SCCs).

2
service_mesh/service_mesh_install/images
View File

@@ -1 +1 @@
../../images/
../../images

30
service_mesh/service_mesh_install/installing-mt-ossm.adoc Normal file
View File

@@ -0,0 +1,30 @@
[id="installing-mt-ossm"]
= Installing {ProductName} with multi-tenant control planes
include::modules/ossm-document-attributes.adoc[]
:context: installing-mt-ossm
toc::[]
The {ProductName} operator supports multi-tenant control plane installations.
[NOTE]
====
* You cannot use multi-tenant control plane installations in conjunction with a cluster-wide control plane installation. {ProductName} installations must either be multi-tenant or single, cluster-wide installations.
* Single-tenant control plane installations are known to cause issues with {product-title} restarts and upgrades. Multi-tenant control plane installations are the default configuration starting with {ProductName} {ProductVersion}.
====
.Prerequisites
* Follow the instructions in xref:../service_mesh_install/installing-ossm.html#installing-ossm[Installing {ProductName}].
include::modules/ossm-mt-known-issues.adoc[leveloffset=+1]
include::modules/ossm-mt-vs-clusterwide.adoc[leveloffset=+1]
include::modules/ossm-mt-installation.adoc[leveloffset=+1]
include::modules/ossm-mt-namespaces.adoc[leveloffset=+1]
.Next steps
* Prepare to deploy applications on {ProductName}.

55
service_mesh/service_mesh_install/installing-ossm.adoc Normal file
View File

@@ -0,0 +1,55 @@
[id="installing-ossm"]
= Installing {ProductName}
include::modules/ossm-document-attributes.adoc[]
:context: installing-ossm
toc::[]
Installing the {ProductShortName} involves installing the Operator, and then creating and managing a custom resource definition file to deploy the control plane.
[NOTE]
====
Starting with {ProductName} 0.9.TechPreview, Mixer’s policy enforcement is disabled by default. You must enable it to run policy tasks. See xref:../service_mesh_install/installing-ossm.html#ossm-mixer-policy_installing-ossm[Update Mixer policy enforcement] for instructions on enabling Mixer policy enforcement.
====
[NOTE]
====
Single-tenant control plane installations are known to cause issues with {product-title} restarts and upgrades. Multi-tenant control plane installations are the default configuration starting with {ProductName} {ProductVersion}.
====
.Prerequisites
* Follow the xref:../service_mesh_install/preparing-ossm-installation.html#preparing-ossm-installation[Preparing to install {ProductName}] process.
* An account with cluster administration access.
include::modules/ossm-operator-install.adoc[leveloffset=+1]
include::modules/ossm-operator-verify.adoc[leveloffset=+2]
include::modules/ossm-cr-example.adoc[leveloffset=+1]
include::modules/ossm-cr-parameters.adoc[leveloffset=+1]
include::modules/ossm-cr-istio-global.adoc[leveloffset=+2]
include::modules/ossm-cr-cni.adoc[leveloffset=+2]
include::modules/ossm-cr-gateway.adoc[leveloffset=+2]
include::modules/ossm-cr-mixer.adoc[leveloffset=+2]
include::modules/ossm-cr-pilot.adoc[leveloffset=+2]
include::modules/ossm-cr-tracing-jaeger.adoc[leveloffset=+2]
include::modules/ossm-cr-kiali.adoc[leveloffset=+2]
include::modules/ossm-cr-threescale.adoc[leveloffset=+2]
include::modules/ossm-mixer-policy.adoc[leveloffset=+1]
include::modules/ossm-control-plane-deploy.adoc[leveloffset=+1]
include::modules/ossm-control-plane-verify.adoc[leveloffset=+2]
.Next steps
* Prepare to deploy applications on {ProductName}.

2
service_mesh/service_mesh_install/modules
View File

@@ -1 +1 @@
../../modules/
../../modules

20
service_mesh/service_mesh_install/ossm-example-bookinfo.adoc Normal file
View File

@@ -0,0 +1,20 @@
[id="ossm-bookinfo-tutorial"]
= Example Application
include::modules/ossm-document-attributes.adoc[]
:context: ossm-bookinfo-tutorial
toc::[]
// The following include statements pull in the module files that comprise the assembly.
include::modules/ossm-tutorial-bookinfo-overview.adoc[leveloffset=+1]
include::modules/ossm-tutorial-bookinfo-install.adoc[leveloffset=+1]
include::modules/ossm-tutorial-bookinfo-verify-install.adoc[leveloffset=+1]
include::modules/ossm-tutorial-bookinfo-adding-destination-rules.adoc[leveloffset=+1]
Now that you have a sample application, you can use the other tutorials in this guide to examine your service mesh.
include::modules/ossm-tutorial-bookinfo-removing.adoc[leveloffset=+1]

12
service_mesh/service_mesh_install/ossm-tutorial-grafana.adoc Normal file
View File

@@ -0,0 +1,12 @@
[id="ossm-grafana-tutorial"]
= Grafana Tutorial
include::modules/ossm-document-attributes.adoc[]
:context: ossm-grafana-tutorial
Grafana is an open source a tool for creating monitoring and metric analytics and dashboards. You use Grafana to query, visualize, and alert on your metrics no matter where they are stored: Graphite, Elasticsearch, OpenTSDB, Prometheus, or InfluxDB. Istio includes monitoring via Prometheus and Grafana.
This tutorial uses {ProductShortName} and the `bookinfo` tutorial to demonstrate how to set up and use the Istio Dashboard to monitor mesh traffic. As part of this task, you install the Grafana Istio add-on to view service mesh traffic data.
// The following include statements pull in the module files that comprise the assembly.
include::modules/ossm-tutorial-grafana-accessing.adoc[leveloffset=+1]

10
service_mesh/service_mesh_install/ossm-tutorial-jaeger-tracing.adoc Normal file
View File

@@ -0,0 +1,10 @@
[id="ossm-tutorial-jaeger-tracing"]
= Distributed tracing tutorial
include::modules/ossm-document-attributes.adoc[]
:context: ossm-jaeger-tutorial
Jaeger is an open source distributed tracing system. You use Jaeger for monitoring and troubleshooting microservices-based distributed systems. Using Jaeger you can perform a trace, which follows the path of a request through various microservices that make up an application. Jaeger is installed by default as part of the Service Mesh.
// The following include statements pull in the module files that comprise the assembly.
include::modules/ossm-tutorial-jaeger-generating-traces.adoc[leveloffset=+1]

24
service_mesh/service_mesh_install/ossm-tutorial-kiali.adoc Normal file
View File

@@ -0,0 +1,24 @@
[id="ossm-kiali-tutorial"]
= Kiali tutorial
include::modules/ossm-document-attributes.adoc[]
:context: ossm-kiali-tutorial
toc::[]
Kiali works with Istio to visualize your service mesh topology to provide visibility into features like circuit breakers, request rates, and more. Kiali offers insights about the mesh components at different levels, from abstract Applications to Services and Workloads. Kiali provides an interactive graph view of your Namespace in real time. It can display the interactions at several levels (applications, versions, workloads) with contextual information and charts on the selected graph node or edge.
This tutorial uses {ProductShortName} and the `bookinfo` tutorial to demonstrate how you can use the Kiali console to view the topography and health of your service mesh.
// The following include statements pull in the module files that comprise the assembly.
include::modules/ossm-tutorial-kiali-accessing-console.adoc[leveloffset=+1]
include::modules/ossm-tutorial-kiali-graph.adoc[leveloffset=+1]
include::modules/ossm-tutorial-kiali-applications-page.adoc[leveloffset=+1]
include::modules/ossm-tutorial-kiali-workloads-page.adoc[leveloffset=+1]
include::modules/ossm-tutorial-kiali-services-page.adoc[leveloffset=+1]
include::modules/ossm-tutorial-kiali-istio-config.adoc[leveloffset=+1]

10
service_mesh/service_mesh_install/ossm-tutorial-prometheus.adoc Normal file
View File

@@ -0,0 +1,10 @@
[id="ossm-prometheus-tutorial"]
= Prometheus tutorial
include::modules/ossm-document-attributes.adoc[]
:context: ossm-prometheus-tutorial
Prometheus is an open source system and service monitoring toolkit. Prometheus collects metrics from configured targets at specified intervals, evaluates rule expressions, displays the results, and can trigger alerts if some condition is observed to be true. Grafana or other API consumers can be used to visualize the collected data.
// The following include statements pull in the module files that comprise the assembly.
include::modules/ossm-tutorial-prometheus-querying-metrics.adoc[leveloffset=+1]

30
service_mesh/service_mesh_install/prepare-to-deploy-applications-ossm.adoc Normal file
View File

@@ -0,0 +1,30 @@
[id="deploying-applications-ossm"]
= Deploying applications on {ProductName}
include::modules/ossm-document-attributes.adoc[]
:context: deploying-applications-ossm
toc::[]
When you deploy an application into the {ProductShortName}, there are several differences between the behavior of applications in the upstream community version of Istio and the behavior of applications within a {ProductName} installation.
.Prerequisites
* Review xref:../service_mesh_install/understanding-ossm.html#ossm-vs-istio_understanding-ossm[Comparing {ProductName} and upstream Istio community installations]
* Review xref:../service_mesh_install/installing-ossm.html#installing-ossm[Installing {ProductName}]
include::modules/ossm-security-constraints.adoc[leveloffset=+1]
include::modules/ossm-configure-security-constraints.adoc[leveloffset=+2]
include::modules/ossm-master-configuration.adoc[leveloffset=+1]
include::modules/ossm-updating-master-configuration.adoc[leveloffset=+2]
include::modules/ossm-automatic-sidecar-injection.adoc[leveloffset=+3]
include::modules/ossm-manual-sidecar-injection.adoc[leveloffset=+3]
.Next steps
* Deploy applications on {ProductName}.

25
service_mesh/service_mesh_install/preparing-ossm-installation.adoc Normal file
View File

@@ -0,0 +1,25 @@
[id="preparing-ossm-installation"]
= Preparing to install {ProductName}
include::modules/ossm-document-attributes.adoc[]
:context: preparing-ossm-installation
toc::[]
Before you can install {ProductName}, review the installation activities, ensure that you meet the prerequisites:
.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} 4.1.
** For more information about {product-title} 4.1, see the xref:../../architecture/architecture-installation.html#installation-overview_architecture-installation[OpenShift Container Platform installation overview].
* 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.
** If you are using {product-title} 4.1, see xref:../../cli_reference/getting-started-cli.html#cli-about-cli_cli-developer-commands[About the CLI].
include::modules/ossm-installation-activities.adoc[leveloffset=+1]
include::modules/ossm-supported-configurations.adoc[leveloffset=+1]
include::modules/ossm-updating-node-configuration.adoc[leveloffset=+1]
.Next steps
* Install {ProductName} in your {product-title} environment.

13
service_mesh/service_mesh_install/removing-ossm.adoc Normal file
View File

@@ -0,0 +1,13 @@
[id="removing-ossm"]
= Removing {ProductName}
include::modules/ossm-document-attributes.adoc[]
:context: removing-ossm
toc::[]
This process allows you to remove {ProductName} from an existing {product-title} instance.
include::modules/ossm-remove-control-plane.adoc[leveloffset=+1]
include::modules/ossm-remove-operator.adoc[leveloffset=+1]
include::modules/ossm-remove-projects.adoc[leveloffset=+1]

19
service_mesh/service_mesh_install/understanding-ossm.adoc Normal file
View File

@@ -0,0 +1,19 @@
[id="understanding-ossm"]
= Understanding Red Hat Service Mesh
include::modules/ossm-document-attributes.adoc[]
:context: understanding-ossm
toc::[]
{ProductName} is a platform that provides behavioral insight and operational control over the service mesh. It gives you a uniform way to connect, secure, and monitor microservices in your {product-title} environment.
include::modules/ossm-tech-preview.adoc[leveloffset=+1]
include::modules/ossm-understanding-service-mesh.adoc[leveloffset=+1]
include::modules/ossm-architecture.adoc[leveloffset=+1]
include::modules/ossm-vs-istio.adoc[leveloffset=+1]
.Next steps
* Prepare to install {ProductName} in your {product-title} environment.

20
service_mesh/servicemesh-release-notes.adoc Normal file
View File

@@ -0,0 +1,20 @@
[id="service-mesh-release-notes"]
= Service Mesh Release Notes
include::modules/ossm-document-attributes.adoc[]
:context: ossm-release-notes
toc::[]
= {RN_BookName}
// The following include statements pull in the module files that comprise the assembly.
include::modules/ossm-servicemesh-overview.adoc[leveloffset=+1]
include::modules/ossm-support.adoc[leveloffset=+1]
include::modules/ossm-rn-new-features.adoc[leveloffset=+1]
include::modules/ossm-rn-known-issues.adoc[leveloffset=+1]
include::modules/ossm-rn-fixed-issues.adoc[leveloffset=+1]

1
service_mesh/threescale_adapter/images Symbolic link
View File

@@ -0,0 +1 @@
../../images

1
service_mesh/threescale_adapter/modules Symbolic link
View File

@@ -0,0 +1 @@
../../modules

26
service_mesh/threescale_adapter/threescale-adapter.adoc Normal file
View File

@@ -0,0 +1,26 @@
[id="threescale-adapter"]
= Using the 3scale Istio adapter
include::modules/ossm-document-attributes.adoc[]
:context: threescale-adapter
toc::[]
The 3scale Istio Adapter allows you to label a service running within the {ProductName} and integrate that service with the 3scale API Management solution.
include::modules/ossm-threescale-integrate.adoc[leveloffset=+1]
include::modules/ossm-threescale-cr.adoc[leveloffset=+2]
include::modules/ossm-threescale-templates.adoc[leveloffset=+3]
include::modules/ossm-threescale-manifests.adoc[leveloffset=+2]
include::modules/ossm-threescale-routing.adoc[leveloffset=+2]
include::modules/ossm-threescale-integration-settings.adoc[leveloffset=+1]
include::modules/ossm-threescale-caching.adoc[leveloffset=+1]
include::modules/ossm-threescale-authentication.adoc[leveloffset=+1]
include::modules/ossm-threescale-metrics.adoc[leveloffset=+1]