From a5ed0dfa40817f7648c4325cd771bc3d02922059 Mon Sep 17 00:00:00 2001 From: Julie Stickler Date: Fri, 29 Apr 2022 14:09:39 -0400 Subject: [PATCH] OSSMDOC-168: part 1 of Kiali config reference. --- _topic_maps/_topic_map.yml | 4 +- modules/jaeger-config-default.adoc | 10 +- ...eger.adoc => ossm-config-smcp-jaeger.adoc} | 2 +- modules/ossm-config-smcp-kiali.adoc | 204 ++++++++++++++++++ modules/ossm-configuring-external-kiali.adoc | 15 ++ ...i.adoc => ossm-configuring-kiali-v1x.adoc} | 2 +- modules/ossm-kiali-service-mesh.adoc | 7 +- modules/ossm-vs-istio.adoc | 2 +- service_mesh/v1x/ossm-custom-resources.adoc | 2 +- service_mesh/v2x/ossm-reference-jaeger.adoc | 2 +- service_mesh/v2x/ossm-reference-kiali.adoc | 14 ++ 11 files changed, 248 insertions(+), 16 deletions(-) rename modules/{ossm-configuring-jaeger.adoc => ossm-config-smcp-jaeger.adoc} (95%) create mode 100644 modules/ossm-config-smcp-kiali.adoc create mode 100644 modules/ossm-configuring-external-kiali.adoc rename modules/{ossm-configuring-kiali.adoc => ossm-configuring-kiali-v1x.adoc} (99%) create mode 100644 service_mesh/v2x/ossm-reference-kiali.adoc diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 66fd027e75df..b3a93c8b5dad 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -2414,8 +2414,10 @@ Topics: File: threescale-adapter - Name: Troubleshooting Service Mesh File: ossm-troubleshooting-istio - - Name: Service Mesh configuration reference + - Name: Control plane configuration reference File: ossm-reference-smcp + - Name: Kiali configuration reference + File: ossm-reference-kiali - Name: Jaeger configuration reference File: ossm-reference-jaeger - Name: Uninstalling Service Mesh diff --git a/modules/jaeger-config-default.adoc b/modules/jaeger-config-default.adoc index 8387100c6fb4..ed465ac68bdc 100644 --- a/modules/jaeger-config-default.adoc +++ b/modules/jaeger-config-default.adoc @@ -2,12 +2,11 @@ This REFERENCE module included in the following assemblies: - rhbjaeger-deploying.adoc //// - +:_content-type: REFERENCE [id="jaeger-config-default_{context}"] = Jaeger default configuration options -:pantheon-module-type: REFERENCE -The Jaeger custom resource (CR) defines the architecture and settings to be used when creating the Jaeger resources. You can modify these parameters to customize your Jaeger implementation to your business needs. +The Jaeger custom resource (CR) defines the architecture and settings to use when creating the Jaeger resources. You can modify these parameters to customize your Jaeger implementation to your business needs. .Jaeger generic YAML example [source,yaml] @@ -62,13 +61,13 @@ spec: |OpenShift automatically generates the `UID` and completes the `namespace` with the name of the project where the object is created. |`name:` -|Name for the object. +|Name of Jaeger custom resource. If a Jaeger CR matching the value of `name` exists, the {SMProductShortname} Operator will use that CR for the installation. If no Jaeger CR exists, the Operator will create one using this `name` and the configuration options specified in the SMCP. |The name of your Jaeger instance. |`jaeger-all-in-one-inmemory` |`spec:` |Specification for the object to be created. -|Contains all of the configuration parameters for your Jaeger instance. When a common definition (for all Jaeger components) is required, it is defined under the spec node. When the definition relates to an individual component, it is placed under the spec/ node. +|Contains all of the configuration parameters for your Jaeger instance. When a common definition (for all Jaeger components) is required, it is defined under the spec node. When the definition relates to an individual component, it is placed under the spec/ node. |N/A |`strategy:` @@ -110,7 +109,6 @@ spec: |Configuration options that define the Ingester service. | | - |=== diff --git a/modules/ossm-configuring-jaeger.adoc b/modules/ossm-config-smcp-jaeger.adoc similarity index 95% rename from modules/ossm-configuring-jaeger.adoc rename to modules/ossm-config-smcp-jaeger.adoc index 85eebbe62a26..aee7bfbd30e0 100644 --- a/modules/ossm-configuring-jaeger.adoc +++ b/modules/ossm-config-smcp-jaeger.adoc @@ -2,7 +2,7 @@ // // * service_mesh/v2x/customizing-installation-ossm.adoc - +:_content-type: CONCEPT [id="ossm-specifying-jaeger-configuration_{context}"] = Specifying Jaeger configuration in the SMCP diff --git a/modules/ossm-config-smcp-kiali.adoc b/modules/ossm-config-smcp-kiali.adoc new file mode 100644 index 000000000000..4835e923f609 --- /dev/null +++ b/modules/ossm-config-smcp-kiali.adoc @@ -0,0 +1,204 @@ +// Module included in the following assemblies: +//* service_mesh/v2x/ossm-reference-kiali.adoc +:_content-type: REFERENCE +[id="ossm-smcp-kiali_{context}"] += Specifying Kiali configuration in the SMCP + +You can configure Kiali under the `addons` section of the `ServiceMeshControlPlane` resource. Kiali is enabled by default. To disable Kiali, set `spec.addons.kiali.enabled` to `false`. + +You can specify your Kiali configuration in either of two ways: + +* Specify the Kiali configuration in the `ServiceMeshControlPlane` resource under `spec.addons.kiali.install`. This approach has some limitations, because the complete list of Kiali configurations is not available in the SMCP. + +* Configure and deploy a Kiali instance and specify the name of the Kiali resource as the value for `spec.addons.kiali.name` in the `ServiceMeshControlPlane` resource. You must create the CR in the same namespace as the Service Mesh control plane, for example, `istio-system`. If a Kiali resource matching the value of `name` exists, the control plane will configure that Kiali resource for use with the control plane. This approach lets you fully customize your Kiali configuration in the Kiali resource. Note that with this approach, various fields in the Kiali resource are overwritten by the {SMProductShortName} Operator, specifically, the `accessible_namespaces` list, as well as the endpoints for Grafana, Prometheus, and tracing. + +.Example SMCP parameters for Kiali +[source,yaml] +---- +apiVersion: maistra.io/v2 +kind: ServiceMeshControlPlane +metadata: + name: basic +spec: + addons: + kiali: + name: kiali + enabled: true + install: + dashboard: + viewOnly: false + enableGrafana: true + enableTracing: true + enablePrometheus: true + service: + ingress: + contextPath: /kiali +---- + +.`ServiceMeshControlPlane` Kiali parameters +[options="header"] +[cols="l, a, a, a"] +|=== +|Parameter |Description |Values |Default value +|spec: + addons: + kiali: + name: +|Name of Kiali custom resource. If a Kiali CR matching the value of `name` exists, the {SMProductShortname} Operator will use that CR for the installation. If no Kiali CR exists, the Operator will create one using this `name` and the configuration options specified in the SMCP. +|string +|`kiali` + +|kiali: + enabled: +|This parameter enables or disables Kiali. Kiali is enabled by default. +|`true`/`false` +|`true` + +|kiali: + install: +|Install a Kiali resource if the named Kiali resource is not present. The `install` section is ignored if `addons.kiali.enabled` is set to `false`. +| +| + +|kiali: + install: + dashboard: +|Configuration parameters for the dashboards shipped with Kiali. +| +| + +|kiali: + install: + dashboard: + viewOnly: +|This parameter enables or disables view-only mode for the Kiali console. When view-only mode is enabled, users cannot use the Kiali console to make changes to the {SMProductShortname}. +|`true`/`false` +|`false` + +|kiali: + install: + dashboard: + enableGrafana: +|Grafana endpoint configured based on `spec.addons.grafana` configuration. +|`true`/`false` +|`true` + +|kiali: + install: + dashboard: + enablePrometheus: +|Prometheus endpoint configured based on `spec.addons.prometheus` configuration. +|`true`/`false` +|`true` + +|kiali: + install: + dashboard: + enableTracing: +|Tracing endpoint configured based on Jaeger custom resource configuration. +|`true`/`false` +|`true` + +|kiali: + install: + service: +|Configuration parameters for the Kubernetes service associated with the Kiali installation. +| +| + +|kiali: + install: + service: + metadata: +|Use to specify additional metadata to apply to resources. +|N/A +|N/A + +|kiali: + install: + service: + metadata: + annotations: +|Use to specify additional annotations to apply to the component's service. +|string +|N/A + +|kiali: + install: + service: + metadata: + labels: +|Use to specify additional labels to apply to the component's service. +|string +|N/A + +|kiali: + install: + service: + ingress: +|Use to specify details for accessing the component’s service through an OpenShift Route. +|N/A +|N/A + +|kiali: + install: + service: + ingress: + metadata: + annotations: +|Use to specify additional annotations to apply to the component's service ingress. +|string +|N/A + +|kiali: + install: + service: + ingress: + metadata: + labels: +|Use to specify additional labels to apply to the component's service ingress. +|string +|N/A + +|kiali: + install: + service: + ingress: + enabled: +|Use to customize an OpenShift Route for the service associated with a component. +|`true`/`false` +|`true` + +|kiali: + install: + service: + ingress: + contextPath: +|Use to specify the context path to the service. +|string +|N/A + +|install: + service: + ingress: + hosts: +|Use to specify a single hostname per OpenShift route. An empty hostname implies a default hostname for the Route. +|string +|N/A + +|install: + service: + ingress: + tls: +|Use to configure the TLS for the OpenShift route. +| +|N/A + +|kiali: + install: + service: + nodePort: +|Use to specify the `nodePort` for the component's service `Values..service.nodePort.port` +|integer +|N/A +|=== diff --git a/modules/ossm-configuring-external-kiali.adoc b/modules/ossm-configuring-external-kiali.adoc new file mode 100644 index 000000000000..f04be0c1dcd5 --- /dev/null +++ b/modules/ossm-configuring-external-kiali.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * service_mesh/v2x/customizing-installation-ossm.adoc +:_content-type: CONCEPT +[id="ossm-specifying-external-kiali_{context}"] += Specifying Kiali configuration in a Kiali custom resource + +You can fully customize your Kiali deployment by configuring Kiali in the Kiali custom resource (CR) rather than in the `ServiceMeshControlPlane` (SMCP) resource. This configuration is sometimes called an "external Kiali" since the configuration is specified outside of the SMCP. + +[NOTE] +==== +You must deploy the `ServiceMeshControlPlane` and Kiali custom resources in the same namespace. For example, `istio-system`. +==== + +You can configure and deploy a Kiali instance and then specify the `name` of the Kiali resource as the value for `spec.addons.kiali.name` in the SMCP resource. If a Kiali CR matching the value of `name` exists, the control plane will use the existing installation. This approach lets you fully customize your Kiali configuration. diff --git a/modules/ossm-configuring-kiali.adoc b/modules/ossm-configuring-kiali-v1x.adoc similarity index 99% rename from modules/ossm-configuring-kiali.adoc rename to modules/ossm-configuring-kiali-v1x.adoc index 0b7cd4b9ac26..e853fa2d9d8b 100644 --- a/modules/ossm-configuring-kiali.adoc +++ b/modules/ossm-configuring-kiali-v1x.adoc @@ -2,7 +2,7 @@ // // * service_mesh/v1x/customizing-installation-ossm.adoc // * service_mesh/v2x/customizing-installation-ossm.adoc - +:_content-type: REFERENCE [id="configuring-kiali_{context}"] = Configuring Kiali diff --git a/modules/ossm-kiali-service-mesh.adoc b/modules/ossm-kiali-service-mesh.adoc index d3fa1268731b..869fe75d7f4b 100644 --- a/modules/ossm-kiali-service-mesh.adoc +++ b/modules/ossm-kiali-service-mesh.adoc @@ -2,16 +2,15 @@ This CONCEPT module included in the following assemblies: -service_mesh/v1x/ossm-vs-community.adoc -service_mesh/v2x/ossm-vs-community.adoc - //// - +:_content-type: CONCEPT [id="ossm-kiali-service-mesh_{context}"] = Kiali and service mesh -Installing Kiali via the Service Mesh on {product-title} differs from community Kiali installations in multiple ways. These modifications are sometimes necessary to resolve issues, provide additional features, or to handle differences when deploying on {product-title}. +Installing Kiali via the Service Mesh on {product-title} differs from community Kiali installations in multiple ways. These modifications are sometimes necessary to resolve issues, provide additional features, or to handle differences when deploying on {product-title}. * Kiali has been enabled by default. * Ingress has been enabled by default. * Updates have been made to the Kiali ConfigMap. * Updates have been made to the ClusterRole settings for Kiali. -* Do not edit the ConfigMap or the Kiali custom resource files as those changes might be overwritten by the {SMProductShortName} or Kiali Operators. All configuration for Kiali running on {SMProductName} is done in the `ServiceMeshControlPlane` custom resource file and there are limited configuration options. Updating the Operator files should be restricted to those users with `cluster-admin` privileges. If you use {product-dedicated}, updating the operator files should be restricted to those users with `dedicated-admin` privileges. +* Do not edit the ConfigMap, because your changes might be overwritten by the {SMProductShortName} or Kiali Operators. Files that the Kiali Operator manages have a `kiali.io/`` label or annotation. Updating the Operator files should be restricted to those users with `cluster-admin` privileges. If you use {product-dedicated}, updating the Operator files should be restricted to those users with `dedicated-admin` privileges. diff --git a/modules/ossm-vs-istio.adoc b/modules/ossm-vs-istio.adoc index f8f8c4b3b928..a98162c73515 100644 --- a/modules/ossm-vs-istio.adoc +++ b/modules/ossm-vs-istio.adoc @@ -37,7 +37,7 @@ Hold for OSSMDOC-547 as to what we support |=== | |Upstream Istio -|{ProductName} +|{SMProductName} |Namespace Label |supports "enabled" and "disabled" diff --git a/service_mesh/v1x/ossm-custom-resources.adoc b/service_mesh/v1x/ossm-custom-resources.adoc index 23dd29cdadc6..04bfe49ea81a 100644 --- a/service_mesh/v1x/ossm-custom-resources.adoc +++ b/service_mesh/v1x/ossm-custom-resources.adoc @@ -27,7 +27,7 @@ include::modules/ossm-cr-mixer.adoc[leveloffset=+2] include::modules/ossm-cr-pilot.adoc[leveloffset=+2] -include::modules/ossm-configuring-kiali.adoc[leveloffset=+1] +include::modules/ossm-configuring-kiali-v1x.adoc[leveloffset=+1] include::modules/ossm-configuring-jaeger-v1x.adoc[leveloffset=+1] diff --git a/service_mesh/v2x/ossm-reference-jaeger.adoc b/service_mesh/v2x/ossm-reference-jaeger.adoc index 6921b3057667..c76f229f4d1c 100644 --- a/service_mesh/v2x/ossm-reference-jaeger.adoc +++ b/service_mesh/v2x/ossm-reference-jaeger.adoc @@ -10,7 +10,7 @@ When the {SMProductShortName} Operator deploys the `ServiceMeshControlPlane` res include::modules/ossm-enabling-jaeger.adoc[leveloffset=+1] -include::modules/ossm-configuring-jaeger.adoc[leveloffset=+1] +include::modules/ossm-config-smcp-jaeger.adoc[leveloffset=+1] include::modules/ossm-deploying-jaeger.adoc[leveloffset=+1] diff --git a/service_mesh/v2x/ossm-reference-kiali.adoc b/service_mesh/v2x/ossm-reference-kiali.adoc new file mode 100644 index 000000000000..26ff7bc5353c --- /dev/null +++ b/service_mesh/v2x/ossm-reference-kiali.adoc @@ -0,0 +1,14 @@ +:_content-type: ASSEMBLY +[id="kiali-config-ref"] += Kiali configuration reference +include::_attributes/common-attributes.adoc[] +:context: kiali-config-ref + +toc::[] + +When the {SMProductShortName} Operator creates the `ServiceMeshControlPlane` it also processes the Kiali resource. The Kiali Operator then uses this object when creating Kiali instances. + +// The following include statements pull in the module files for the assembly. +include::modules/ossm-config-smcp-kiali.adoc[leveloffset=+1] + +include::modules/ossm-configuring-external-kiali.adoc[leveloffset=+1]