From 0b3db566efe3c6f5b287560f825ed644a6b97953 Mon Sep 17 00:00:00 2001 From: Elise Hines Date: Mon, 1 Jul 2019 11:09:06 -0400 Subject: [PATCH] TP12 Modularization Work --- _topic_map.yml | 35 ++-- modules/ossm-architecture.adoc | 21 +++ modules/ossm-automatic-sidecar-injection.adoc | 43 +++++ .../ossm-configure-security-constraints.adoc | 41 +++++ modules/ossm-control-plane-deploy.adoc | 48 ++++++ modules/ossm-control-plane-verify.adoc | 66 +++++++ modules/ossm-cr-cni.adoc | 40 +++++ modules/ossm-cr-example.adoc | 75 ++++++++ modules/ossm-cr-gateway.adoc | 76 +++++++++ modules/ossm-cr-istio-global.adoc | 104 +++++++++++ modules/ossm-cr-kiali.adoc | 55 ++++++ modules/ossm-cr-mixer.adoc | 82 +++++++++ modules/ossm-cr-parameters.adoc | 13 ++ modules/ossm-cr-pilot.adoc | 38 +++++ modules/ossm-cr-threescale.adoc | 93 ++++++++++ modules/ossm-cr-tracing-jaeger.adoc | 50 ++++++ modules/ossm-document-attributes.adoc | 36 ++++ modules/ossm-installation-activities.adoc | 21 +++ modules/ossm-manual-sidecar-injection.adoc | 29 ++++ modules/ossm-master-configuration.adoc | 13 ++ modules/ossm-mixer-policy.adoc | 30 ++++ modules/ossm-mt-installation.adoc | 31 ++++ modules/ossm-mt-known-issues.adoc | 19 +++ modules/ossm-mt-namespaces.adoc | 58 +++++++ modules/ossm-mt-vs-clusterwide.adoc | 10 ++ modules/ossm-operator-install.adoc | 85 +++++++++ modules/ossm-operator-verify.adoc | 29 ++++ modules/ossm-remove-control-plane.adoc | 35 ++++ modules/ossm-remove-operator.adoc | 63 +++++++ modules/ossm-remove-projects.adoc | 24 +++ modules/ossm-security-constraints.adoc | 20 +++ modules/ossm-supported-configurations.adoc | 21 +++ modules/ossm-tech-preview.adoc | 15 ++ modules/ossm-threescale-authentication.adoc | 161 ++++++++++++++++++ modules/ossm-threescale-caching.adoc | 11 ++ modules/ossm-threescale-cr.adoc | 58 +++++++ modules/ossm-threescale-integrate.adoc | 64 +++++++ .../ossm-threescale-integration-settings.adoc | 23 +++ modules/ossm-threescale-manifests.adoc | 41 +++++ modules/ossm-threescale-metrics.adoc | 7 + modules/ossm-threescale-routing.adoc | 20 +++ modules/ossm-threescale-templates.adoc | 18 ++ modules/ossm-understanding-service-mesh.adoc | 27 +++ .../ossm-updating-master-configuration.adoc | 49 ++++++ modules/ossm-updating-node-configuration.adoc | 40 +++++ modules/ossm-vs-istio.adoc | 139 +++++++++++++++ .../installing-mt-ossm.adoc | 30 ++++ .../service_mesh_install/installing-ossm.adoc | 55 ++++++ .../prepare-to-deploy-applications-ossm.adoc | 30 ++++ .../preparing-ossm-installation.adoc | 25 +++ .../service_mesh_install/removing-ossm.adoc | 13 ++ .../understanding-ossm.adoc | 19 +++ .../threescale-adapter.adoc | 26 +++ 53 files changed, 2265 insertions(+), 10 deletions(-) create mode 100644 modules/ossm-architecture.adoc create mode 100644 modules/ossm-automatic-sidecar-injection.adoc create mode 100644 modules/ossm-configure-security-constraints.adoc create mode 100644 modules/ossm-control-plane-deploy.adoc create mode 100644 modules/ossm-control-plane-verify.adoc create mode 100644 modules/ossm-cr-cni.adoc create mode 100644 modules/ossm-cr-example.adoc create mode 100644 modules/ossm-cr-gateway.adoc create mode 100644 modules/ossm-cr-istio-global.adoc create mode 100644 modules/ossm-cr-kiali.adoc create mode 100644 modules/ossm-cr-mixer.adoc create mode 100644 modules/ossm-cr-parameters.adoc create mode 100644 modules/ossm-cr-pilot.adoc create mode 100644 modules/ossm-cr-threescale.adoc create mode 100644 modules/ossm-cr-tracing-jaeger.adoc create mode 100644 modules/ossm-document-attributes.adoc create mode 100644 modules/ossm-installation-activities.adoc create mode 100644 modules/ossm-manual-sidecar-injection.adoc create mode 100644 modules/ossm-master-configuration.adoc create mode 100644 modules/ossm-mixer-policy.adoc create mode 100644 modules/ossm-mt-installation.adoc create mode 100644 modules/ossm-mt-known-issues.adoc create mode 100644 modules/ossm-mt-namespaces.adoc create mode 100644 modules/ossm-mt-vs-clusterwide.adoc create mode 100644 modules/ossm-operator-install.adoc create mode 100644 modules/ossm-operator-verify.adoc create mode 100644 modules/ossm-remove-control-plane.adoc create mode 100644 modules/ossm-remove-operator.adoc create mode 100644 modules/ossm-remove-projects.adoc create mode 100644 modules/ossm-security-constraints.adoc create mode 100644 modules/ossm-supported-configurations.adoc create mode 100644 modules/ossm-tech-preview.adoc create mode 100644 modules/ossm-threescale-authentication.adoc create mode 100644 modules/ossm-threescale-caching.adoc create mode 100644 modules/ossm-threescale-cr.adoc create mode 100644 modules/ossm-threescale-integrate.adoc create mode 100644 modules/ossm-threescale-integration-settings.adoc create mode 100644 modules/ossm-threescale-manifests.adoc create mode 100644 modules/ossm-threescale-metrics.adoc create mode 100644 modules/ossm-threescale-routing.adoc create mode 100644 modules/ossm-threescale-templates.adoc create mode 100644 modules/ossm-understanding-service-mesh.adoc create mode 100644 modules/ossm-updating-master-configuration.adoc create mode 100644 modules/ossm-updating-node-configuration.adoc create mode 100644 modules/ossm-vs-istio.adoc create mode 100644 service_mesh/service_mesh_install/installing-mt-ossm.adoc create mode 100644 service_mesh/service_mesh_install/installing-ossm.adoc create mode 100644 service_mesh/service_mesh_install/prepare-to-deploy-applications-ossm.adoc create mode 100644 service_mesh/service_mesh_install/preparing-ossm-installation.adoc create mode 100644 service_mesh/service_mesh_install/removing-ossm.adoc create mode 100644 service_mesh/service_mesh_install/understanding-ossm.adoc create mode 100644 service_mesh/threescale_adapter/threescale-adapter.adoc diff --git a/_topic_map.yml b/_topic_map.yml index d759318135bc..d8d0c496a071 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -773,16 +773,31 @@ Topics: # 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 +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: 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 # Dir: service_mesh_release_notes # Topics: 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..e1ebc1497c4a --- /dev/null +++ b/modules/ossm-cr-tracing-jaeger.adoc @@ -0,0 +1,50 @@ +// 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: + 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..69aedb5035fb --- /dev/null +++ b/modules/ossm-document-attributes.adoc @@ -0,0 +1,36 @@ +// Standard document attributes to be used in the documentation +// +// The following are shared by all documents: +:toc: +:toclevels: 4 +//NOTE: Actual directory is content/img, but the symlink uses the names the ccutil expects +// :imagesdir: servicemesh-install/images +: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-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-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..5344edb833f1 --- /dev/null +++ b/modules/ossm-threescale-integrate.adoc @@ -0,0 +1,64 @@ +// 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.html#preparing-ossm-installation[{ProductName} prerequisites] +* Ensure Mixer policy enforcement is enabled. xref:../service_mesh_install/installing-ossm.html#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-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/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/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..c9c42369b67c --- /dev/null +++ b/service_mesh/service_mesh_install/understanding-ossm.adoc @@ -0,0 +1,19 @@ +[id="understanding-ossm"] += Understanding {ProductName} +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. \ 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]