diff --git a/_topic_map.yml b/_topic_map.yml index e63d305b959c..0cce92f3cf4a 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -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 diff --git a/cnv/cnv_install/cnv-about-cnv.adoc b/cnv/cnv_install/cnv-about-cnv.adoc index af95d82c4912..9155b656e672 100644 --- a/cnv/cnv_install/cnv-about-cnv.adoc +++ b/cnv/cnv_install/cnv-about-cnv.adoc @@ -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::[] diff --git a/modules/ossm-architecture.adoc b/modules/ossm-architecture.adoc new file mode 100644 index 000000000000..0ddc4dc77cfe --- /dev/null +++ b/modules/ossm-architecture.adoc @@ -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. diff --git a/modules/ossm-automatic-sidecar-injection.adoc b/modules/ossm-automatic-sidecar-injection.adoc new file mode 100644 index 000000000000..c7f66c984f02 --- /dev/null +++ b/modules/ossm-automatic-sidecar-injection.adoc @@ -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. diff --git a/modules/ossm-configure-security-constraints.adoc b/modules/ossm-configure-security-constraints.adoc new file mode 100644 index 000000000000..63af44e8262b --- /dev/null +++ b/modules/ossm-configure-security-constraints.adoc @@ -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 `` and `` 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 -n +---- + +. 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 -n +---- diff --git a/modules/ossm-control-plane-deploy.adoc b/modules/ossm-control-plane-deploy.adoc new file mode 100644 index 000000000000..e6c3462a0f02 --- /dev/null +++ b/modules/ossm-control-plane-deploy.adoc @@ -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 +---- diff --git a/modules/ossm-control-plane-verify.adoc b/modules/ossm-control-plane-verify.adoc new file mode 100644 index 000000000000..835882ffa366 --- /dev/null +++ b/modules/ossm-control-plane-verify.adoc @@ -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 +---- diff --git a/modules/ossm-cr-cni.adoc b/modules/ossm-cr-cni.adoc new file mode 100644 index 000000000000..c7fc5341ef5d --- /dev/null +++ b/modules/ossm-cr-cni.adoc @@ -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` +|=== diff --git a/modules/ossm-cr-example.adoc b/modules/ossm-cr-example.adoc new file mode 100644 index 000000000000..930bcf896dbe --- /dev/null +++ b/modules/ossm-cr-example.adoc @@ -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 +---- diff --git a/modules/ossm-cr-gateway.adoc b/modules/ossm-cr-gateway.adoc new file mode 100644 index 000000000000..93c1a6dfd5bd --- /dev/null +++ b/modules/ossm-cr-gateway.adoc @@ -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` +|=== diff --git a/modules/ossm-cr-istio-global.adoc b/modules/ossm-cr-istio-global.adoc new file mode 100644 index 000000000000..6fa246ac8b9d --- /dev/null +++ b/modules/ossm-cr-istio-global.adoc @@ -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` +|=== diff --git a/modules/ossm-cr-kiali.adoc b/modules/ossm-cr-kiali.adoc new file mode 100644 index 000000000000..83ec498bc161 --- /dev/null +++ b/modules/ossm-cr-kiali.adoc @@ -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 +|=== diff --git a/modules/ossm-cr-mixer.adoc b/modules/ossm-cr-mixer.adoc new file mode 100644 index 000000000000..f19fbfc45c4c --- /dev/null +++ b/modules/ossm-cr-mixer.adoc @@ -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` +|=== diff --git a/modules/ossm-cr-parameters.adoc b/modules/ossm-cr-parameters.adoc new file mode 100644 index 000000000000..39ee718fde37 --- /dev/null +++ b/modules/ossm-cr-parameters.adoc @@ -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. +==== diff --git a/modules/ossm-cr-pilot.adoc b/modules/ossm-cr-pilot.adoc new file mode 100644 index 000000000000..c6b5eec05ec9 --- /dev/null +++ b/modules/ossm-cr-pilot.adoc @@ -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` +|=== diff --git a/modules/ossm-cr-threescale.adoc b/modules/ossm-cr-threescale.adoc new file mode 100644 index 000000000000..a2053d76886d --- /dev/null +++ b/modules/ossm-cr-threescale.adoc @@ -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` +|=== diff --git a/modules/ossm-cr-tracing-jaeger.adoc b/modules/ossm-cr-tracing-jaeger.adoc new file mode 100644 index 000000000000..895dcd7cd649 --- /dev/null +++ b/modules/ossm-cr-tracing-jaeger.adoc @@ -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 +|=== + diff --git a/modules/ossm-document-attributes.adoc b/modules/ossm-document-attributes.adoc new file mode 100644 index 000000000000..27e32dab94c8 --- /dev/null +++ b/modules/ossm-document-attributes.adoc @@ -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 diff --git a/modules/ossm-installation-activities.adoc b/modules/ossm-installation-activities.adoc new file mode 100644 index 000000000000..3045dfbcf589 --- /dev/null +++ b/modules/ossm-installation-activities.adoc @@ -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. diff --git a/modules/ossm-manual-sidecar-injection.adoc b/modules/ossm-manual-sidecar-injection.adoc new file mode 100644 index 000000000000..76295a0594d0 --- /dev/null +++ b/modules/ossm-manual-sidecar-injection.adoc @@ -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 - +---- diff --git a/modules/ossm-master-configuration.adoc b/modules/ossm-master-configuration.adoc new file mode 100644 index 000000000000..5e79457d61f7 --- /dev/null +++ b/modules/ossm-master-configuration.adoc @@ -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. +==== diff --git a/modules/ossm-mixer-policy.adoc b/modules/ossm-mixer-policy.adoc new file mode 100644 index 000000000000..ccc32744ea21 --- /dev/null +++ b/modules/ossm-mixer-policy.adoc @@ -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`. diff --git a/modules/ossm-mt-installation.adoc b/modules/ossm-mt-installation.adoc new file mode 100644 index 000000000000..accf751ad66a --- /dev/null +++ b/modules/ossm-mt-installation.adoc @@ -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 +---- diff --git a/modules/ossm-mt-known-issues.adoc b/modules/ossm-mt-known-issues.adoc new file mode 100644 index 000000000000..403487172b5a --- /dev/null +++ b/modules/ossm-mt-known-issues.adoc @@ -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. diff --git a/modules/ossm-mt-namespaces.adoc b/modules/ossm-mt-namespaces.adoc new file mode 100644 index 000000000000..19a9a012b369 --- /dev/null +++ b/modules/ossm-mt-namespaces.adoc @@ -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 +---- + diff --git a/modules/ossm-mt-vs-clusterwide.adoc b/modules/ossm-mt-vs-clusterwide.adoc new file mode 100644 index 000000000000..672ec49cd4da --- /dev/null +++ b/modules/ossm-mt-vs-clusterwide.adoc @@ -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. diff --git a/modules/ossm-operator-install.adoc b/modules/ossm-operator-install.adoc new file mode 100644 index 000000000000..9e39c73521d6 --- /dev/null +++ b/modules/ossm-operator-install.adoc @@ -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 +---- + diff --git a/modules/ossm-operator-verify.adoc b/modules/ossm-operator-verify.adoc new file mode 100644 index 000000000000..a19653b7f276 --- /dev/null +++ b/modules/ossm-operator-verify.adoc @@ -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 +---- diff --git a/modules/ossm-remove-control-plane.adoc b/modules/ossm-remove-control-plane.adoc new file mode 100644 index 000000000000..48c7e9ae714c --- /dev/null +++ b/modules/ossm-remove-control-plane.adoc @@ -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 `` with the output from the previous command, and run this command to remove the custom resource: ++ +---- +$ oc delete servicemeshcontrolplanes -n istio-system +---- + diff --git a/modules/ossm-remove-operator.adoc b/modules/ossm-remove-operator.adoc new file mode 100644 index 000000000000..8b93e547132c --- /dev/null +++ b/modules/ossm-remove-operator.adoc @@ -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 '**' +---- diff --git a/modules/ossm-remove-projects.adoc b/modules/ossm-remove-projects.adoc new file mode 100644 index 000000000000..bbab5ecac223 --- /dev/null +++ b/modules/ossm-remove-projects.adoc @@ -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 +---- diff --git a/modules/ossm-rn-fixed-issues.adoc b/modules/ossm-rn-fixed-issues.adoc new file mode 100644 index 000000000000..64ae04e3f74a --- /dev/null +++ b/modules/ossm-rn-fixed-issues.adoc @@ -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. diff --git a/modules/ossm-rn-known-issues.adoc b/modules/ossm-rn-known-issues.adoc new file mode 100644 index 000000000000..c726df58347a --- /dev/null +++ b/modules/ossm-rn-known-issues.adoc @@ -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. diff --git a/modules/ossm-rn-new-features.adoc b/modules/ossm-rn-new-features.adoc new file mode 100644 index 000000000000..722035346e7d --- /dev/null +++ b/modules/ossm-rn-new-features.adoc @@ -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. diff --git a/modules/ossm-security-constraints.adoc b/modules/ossm-security-constraints.adoc new file mode 100644 index 000000000000..e4f0ee4915a1 --- /dev/null +++ b/modules/ossm-security-constraints.adoc @@ -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. diff --git a/modules/ossm-servicemesh-overview.adoc b/modules/ossm-servicemesh-overview.adoc new file mode 100644 index 000000000000..d3069592e597 --- /dev/null +++ b/modules/ossm-servicemesh-overview.adoc @@ -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. diff --git a/modules/ossm-support.adoc b/modules/ossm-support.adoc new file mode 100644 index 000000000000..c90b0eb9eeb9 --- /dev/null +++ b/modules/ossm-support.adoc @@ -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. diff --git a/modules/ossm-supported-configurations.adoc b/modules/ossm-supported-configurations.adoc new file mode 100644 index 000000000000..1140aae9c964 --- /dev/null +++ b/modules/ossm-supported-configurations.adoc @@ -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. diff --git a/modules/ossm-tech-preview.adoc b/modules/ossm-tech-preview.adoc new file mode 100644 index 000000000000..ec99d4d966fb --- /dev/null +++ b/modules/ossm-tech-preview.adoc @@ -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]. diff --git a/modules/ossm-threescale-authentication.adoc b/modules/ossm-threescale-authentication.adoc new file mode 100644 index 000000000000..17c7012588c8 --- /dev/null +++ b/modules/ossm-threescale-authentication.adoc @@ -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"] | "" +---- diff --git a/modules/ossm-threescale-caching.adoc b/modules/ossm-threescale-caching.adoc new file mode 100644 index 000000000000..45b521a0bb38 --- /dev/null +++ b/modules/ossm-threescale-caching.adoc @@ -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. diff --git a/modules/ossm-threescale-cr.adoc b/modules/ossm-threescale-cr.adoc new file mode 100644 index 000000000000..a4f8c9a0c961 --- /dev/null +++ b/modules/ossm-threescale-cr.adoc @@ -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 +| +|=== diff --git a/modules/ossm-threescale-integrate.adoc b/modules/ossm-threescale-integrate.adoc new file mode 100644 index 000000000000..48a3bf648b6c --- /dev/null +++ b/modules/ossm-threescale-integrate.adoc @@ -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: "" + system_url: "https://-admin.3scale.net/" + 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 +---- diff --git a/modules/ossm-threescale-integration-settings.adoc b/modules/ossm-threescale-integration-settings.adoc new file mode 100644 index 000000000000..2da54d730ccb --- /dev/null +++ b/modules/ossm-threescale-integration-settings.adoc @@ -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*. diff --git a/modules/ossm-threescale-manifests.adoc b/modules/ossm-threescale-manifests.adoc new file mode 100644 index 000000000000..d31b73ee92c9 --- /dev/null +++ b/modules/ossm-threescale-manifests.adoc @@ -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}"'' + +---- diff --git a/modules/ossm-threescale-metrics.adoc b/modules/ossm-threescale-metrics.adoc new file mode 100644 index 000000000000..04c8a43d5601 --- /dev/null +++ b/modules/ossm-threescale-metrics.adoc @@ -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. diff --git a/modules/ossm-threescale-routing.adoc b/modules/ossm-threescale-routing.adoc new file mode 100644 index 000000000000..9c889f04bf19 --- /dev/null +++ b/modules/ossm-threescale-routing.adoc @@ -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. + diff --git a/modules/ossm-threescale-templates.adoc b/modules/ossm-threescale-templates.adoc new file mode 100644 index 000000000000..f9ac2d26b00f --- /dev/null +++ b/modules/ossm-threescale-templates.adoc @@ -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://-admin.3scale.net:443" --token="[redacted]" +---- + +* This example generates the templates with the service ID embedded in the handler: ++ +---- +$ 3scale-gen-config --url="https://-admin.3scale.net" --name="my-unique-id" --service="123456789" --token="[redacted]" +---- diff --git a/modules/ossm-tutorial-bookinfo-adding-destination-rules.adoc b/modules/ossm-tutorial-bookinfo-adding-destination-rules.adoc new file mode 100644 index 000000000000..4f62026a2564 --- /dev/null +++ b/modules/ossm-tutorial-bookinfo-adding-destination-rules.adoc @@ -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 +---- diff --git a/modules/ossm-tutorial-bookinfo-install.adoc b/modules/ossm-tutorial-bookinfo-install.adoc new file mode 100644 index 000000000000..a189e72923ad --- /dev/null +++ b/modules/ossm-tutorial-bookinfo-install.adoc @@ -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}') +---- diff --git a/modules/ossm-tutorial-bookinfo-overview.adoc b/modules/ossm-tutorial-bookinfo-overview.adoc new file mode 100644 index 000000000000..8981c2b47362 --- /dev/null +++ b/modules/ossm-tutorial-bookinfo-overview.adoc @@ -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. diff --git a/modules/ossm-tutorial-bookinfo-removing.adoc b/modules/ossm-tutorial-bookinfo-removing.adoc new file mode 100644 index 000000000000..9926e1ed76ba --- /dev/null +++ b/modules/ossm-tutorial-bookinfo-removing.adoc @@ -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. +---- diff --git a/modules/ossm-tutorial-bookinfo-verify-install.adoc b/modules/ossm-tutorial-bookinfo-verify-install.adoc new file mode 100644 index 000000000000..5814aa4b5806 --- /dev/null +++ b/modules/ossm-tutorial-bookinfo-verify-install.adoc @@ -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:///productpage +---- ++ +** Alternatively, you can open `http:///productpage` in your browser. + +//// +TO DO +Add screen shot of bookinfo. +//// diff --git a/modules/ossm-tutorial-grafana-accessing.adoc b/modules/ossm-tutorial-grafana-accessing.adoc new file mode 100644 index 000000000000..cd0736857cae --- /dev/null +++ b/modules/ossm-tutorial-grafana-accessing.adoc @@ -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://`. 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:///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. diff --git a/modules/ossm-tutorial-jaeger-generating-traces.adoc b/modules/ossm-tutorial-jaeger-generating-traces.adoc new file mode 100644 index 000000000000..295eab479e39 --- /dev/null +++ b/modules/ossm-tutorial-jaeger-generating-traces.adoc @@ -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:///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://`. + +. 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. diff --git a/modules/ossm-tutorial-kiali-accessing-console.adoc b/modules/ossm-tutorial-kiali-accessing-console.adoc new file mode 100644 index 000000000000..d492a520d594 --- /dev/null +++ b/modules/ossm-tutorial-kiali-accessing-console.adoc @@ -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 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:// (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. diff --git a/modules/ossm-tutorial-kiali-applications-page.adoc b/modules/ossm-tutorial-kiali-applications-page.adoc new file mode 100644 index 000000000000..b5d4c4ebc012 --- /dev/null +++ b/modules/ossm-tutorial-kiali-applications-page.adoc @@ -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. diff --git a/modules/ossm-tutorial-kiali-graph.adoc b/modules/ossm-tutorial-kiali-graph.adoc new file mode 100644 index 000000000000..83a8a7ef7835 --- /dev/null +++ b/modules/ossm-tutorial-kiali-graph.adoc @@ -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. diff --git a/modules/ossm-tutorial-kiali-istio-config.adoc b/modules/ossm-tutorial-kiali-istio-config.adoc new file mode 100644 index 000000000000..45edf3a6f360 --- /dev/null +++ b/modules/ossm-tutorial-kiali-istio-config.adoc @@ -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] diff --git a/modules/ossm-tutorial-kiali-services-page.adoc b/modules/ossm-tutorial-kiali-services-page.adoc new file mode 100644 index 000000000000..a6189db82041 --- /dev/null +++ b/modules/ossm-tutorial-kiali-services-page.adoc @@ -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. diff --git a/modules/ossm-tutorial-kiali-workloads-page.adoc b/modules/ossm-tutorial-kiali-workloads-page.adoc new file mode 100644 index 000000000000..9244e81c40a7 --- /dev/null +++ b/modules/ossm-tutorial-kiali-workloads-page.adoc @@ -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. diff --git a/modules/ossm-tutorial-prometheus-querying-metrics.adoc b/modules/ossm-tutorial-prometheus-querying-metrics.adoc new file mode 100644 index 000000000000..a5ef3d3eb9db --- /dev/null +++ b/modules/ossm-tutorial-prometheus-querying-metrics.adoc @@ -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 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://`. 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`. diff --git a/modules/ossm-understanding-service-mesh.adoc b/modules/ossm-understanding-service-mesh.adoc new file mode 100644 index 000000000000..99188f4a08d1 --- /dev/null +++ b/modules/ossm-understanding-service-mesh.adoc @@ -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 diff --git a/modules/ossm-updating-master-configuration.adoc b/modules/ossm-updating-master-configuration.adoc new file mode 100644 index 000000000000..56de518b521e --- /dev/null +++ b/modules/ossm-updating-master-configuration.adoc @@ -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 +---- + diff --git a/modules/ossm-updating-node-configuration.adoc b/modules/ossm-updating-node-configuration.adoc new file mode 100644 index 000000000000..74ad1f420a1b --- /dev/null +++ b/modules/ossm-updating-node-configuration.adoc @@ -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 +---- + + diff --git a/modules/ossm-vs-istio.adoc b/modules/ossm-vs-istio.adoc new file mode 100644 index 000000000000..f1a5c85cd101 --- /dev/null +++ b/modules/ossm-vs-istio.adoc @@ -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[
]: "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[
]: "" +---- + +[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 None +gateway1-scqhv www.bookinfo.com istio-ingressgateway 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 `[-].` 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). \ No newline at end of file diff --git a/service_mesh/service_mesh_install/images b/service_mesh/service_mesh_install/images index 847b03ed0541..5fa6987088da 120000 --- a/service_mesh/service_mesh_install/images +++ b/service_mesh/service_mesh_install/images @@ -1 +1 @@ -../../images/ \ No newline at end of file +../../images \ No newline at end of file diff --git a/service_mesh/service_mesh_install/installing-mt-ossm.adoc b/service_mesh/service_mesh_install/installing-mt-ossm.adoc new file mode 100644 index 000000000000..f777392a8292 --- /dev/null +++ b/service_mesh/service_mesh_install/installing-mt-ossm.adoc @@ -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}. \ No newline at end of file diff --git a/service_mesh/service_mesh_install/installing-ossm.adoc b/service_mesh/service_mesh_install/installing-ossm.adoc new file mode 100644 index 000000000000..c858672822c4 --- /dev/null +++ b/service_mesh/service_mesh_install/installing-ossm.adoc @@ -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}. \ No newline at end of file diff --git a/service_mesh/service_mesh_install/modules b/service_mesh/service_mesh_install/modules index 36719b9de743..8b0e8540076d 120000 --- a/service_mesh/service_mesh_install/modules +++ b/service_mesh/service_mesh_install/modules @@ -1 +1 @@ -../../modules/ \ No newline at end of file +../../modules \ No newline at end of file diff --git a/service_mesh/service_mesh_install/ossm-example-bookinfo.adoc b/service_mesh/service_mesh_install/ossm-example-bookinfo.adoc new file mode 100644 index 000000000000..ac1fd7886fd4 --- /dev/null +++ b/service_mesh/service_mesh_install/ossm-example-bookinfo.adoc @@ -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] diff --git a/service_mesh/service_mesh_install/ossm-tutorial-grafana.adoc b/service_mesh/service_mesh_install/ossm-tutorial-grafana.adoc new file mode 100644 index 000000000000..a439fb4a7575 --- /dev/null +++ b/service_mesh/service_mesh_install/ossm-tutorial-grafana.adoc @@ -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] diff --git a/service_mesh/service_mesh_install/ossm-tutorial-jaeger-tracing.adoc b/service_mesh/service_mesh_install/ossm-tutorial-jaeger-tracing.adoc new file mode 100644 index 000000000000..6067341890a6 --- /dev/null +++ b/service_mesh/service_mesh_install/ossm-tutorial-jaeger-tracing.adoc @@ -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] diff --git a/service_mesh/service_mesh_install/ossm-tutorial-kiali.adoc b/service_mesh/service_mesh_install/ossm-tutorial-kiali.adoc new file mode 100644 index 000000000000..df7ae576252f --- /dev/null +++ b/service_mesh/service_mesh_install/ossm-tutorial-kiali.adoc @@ -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] diff --git a/service_mesh/service_mesh_install/ossm-tutorial-prometheus.adoc b/service_mesh/service_mesh_install/ossm-tutorial-prometheus.adoc new file mode 100644 index 000000000000..78ecfa19df5c --- /dev/null +++ b/service_mesh/service_mesh_install/ossm-tutorial-prometheus.adoc @@ -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] diff --git a/service_mesh/service_mesh_install/prepare-to-deploy-applications-ossm.adoc b/service_mesh/service_mesh_install/prepare-to-deploy-applications-ossm.adoc new file mode 100644 index 000000000000..533ddfc670ae --- /dev/null +++ b/service_mesh/service_mesh_install/prepare-to-deploy-applications-ossm.adoc @@ -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}. \ No newline at end of file diff --git a/service_mesh/service_mesh_install/preparing-ossm-installation.adoc b/service_mesh/service_mesh_install/preparing-ossm-installation.adoc new file mode 100644 index 000000000000..981ef88cf171 --- /dev/null +++ b/service_mesh/service_mesh_install/preparing-ossm-installation.adoc @@ -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. diff --git a/service_mesh/service_mesh_install/removing-ossm.adoc b/service_mesh/service_mesh_install/removing-ossm.adoc new file mode 100644 index 000000000000..8a33d77c69e2 --- /dev/null +++ b/service_mesh/service_mesh_install/removing-ossm.adoc @@ -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] diff --git a/service_mesh/service_mesh_install/understanding-ossm.adoc b/service_mesh/service_mesh_install/understanding-ossm.adoc new file mode 100644 index 000000000000..f833c7256973 --- /dev/null +++ b/service_mesh/service_mesh_install/understanding-ossm.adoc @@ -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. diff --git a/service_mesh/servicemesh-release-notes.adoc b/service_mesh/servicemesh-release-notes.adoc new file mode 100644 index 000000000000..5e05e9d29ef1 --- /dev/null +++ b/service_mesh/servicemesh-release-notes.adoc @@ -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] \ No newline at end of file diff --git a/service_mesh/threescale_adapter/images b/service_mesh/threescale_adapter/images new file mode 120000 index 000000000000..5fa6987088da --- /dev/null +++ b/service_mesh/threescale_adapter/images @@ -0,0 +1 @@ +../../images \ No newline at end of file diff --git a/service_mesh/threescale_adapter/modules b/service_mesh/threescale_adapter/modules new file mode 120000 index 000000000000..8b0e8540076d --- /dev/null +++ b/service_mesh/threescale_adapter/modules @@ -0,0 +1 @@ +../../modules \ No newline at end of file diff --git a/service_mesh/threescale_adapter/threescale-adapter.adoc b/service_mesh/threescale_adapter/threescale-adapter.adoc new file mode 100644 index 000000000000..5310d935e579 --- /dev/null +++ b/service_mesh/threescale_adapter/threescale-adapter.adoc @@ -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]