support for OSSMC in the Kiali Operator

DEVELOPING.adoc

@@ -44,9 +44,9 @@ If, however, a developer needs to make changes to the operator, because the Kial
 
 The link:https://github.com/kiali/kiali[Kiali git repo] has a link:https://github.com/kiali/kiali/blob/master/Makefile[Makefile] and a set of link:https://github.com/kiali/kiali/blob/master/make[Makefile targets] that are used in conjunction with the Kiali Operator so you can install and run the operator built from your local git clones. They use the Kiali Operator helm chart to install the operator, so you must link:https://github.com/kiali/kiali#building[clone the helm-chart git repo in the proper place as well].
 
-To install the operator that contains your local changes, run `make operator-create`. If you are using minikube, you will need to set the environment variable `CLUSTER_TYPE=minikube` and you need to also set `MINIKUBE_PROFILE` if your minikube profile name is not `minikube`. At this point you can create your own Kiali CR to trigger the operator to install Kiali, or use `make kiali-create` to install a sample Kiali CR for you.
+To install the operator that contains your local changes, run `make operator-create`. If you are using minikube, you will need to set the environment variable `CLUSTER_TYPE=minikube` and you need to also set `MINIKUBE_PROFILE` if your minikube profile name is not `minikube`. At this point you can create your own Kiali CR to trigger the operator to install Kiali, or use `make kiali-create` to install a sample Kiali CR for you. Similarly, `make ossmconsole-create` will create an OSSMConsole CR to install the OSSMC OpenShift Console plugin.
 
-To remove the operator (and the Kiali CR that may have also been created), run `make operator-delete`.
+To remove the operator (and any CRs that may have also been created), run `make operator-delete`.
 
 ### Installing the Operator in a Cluster Using OLM
 
@@ -56,17 +56,17 @@ If you do not have OLM installed, you can easily install it. First determine wha
 
 Once OLM is installed, you can install the Kiali Operator (and all the required resources such as the OLM catalog source and subscription) via `make olm-operator-create`.
 
-Once the operator is running, you can install a Kiali CR normally. One way to do this is to first create a kiali-operator namespace and run the `kiali-create` make target: `kubectl create ns kiali-operator && make kiali-create`.
+Once the operator is running, you can install a Kiali CR normally. One way to do this is to first create a kiali-operator namespace and run the `kiali-create` make target: `kubectl create ns kiali-operator && make kiali-create`. Similarly with the `ossmconsole-create` target for installing OSSMC.
 
-To remove the Kiali operator and all the other OLM resources that came with it (including the Kiali CR if you created one via the `kiali-create` target), run `make olm-operator-delete`.
+To remove the Kiali operator and all the other OLM resources that came with it (including the CRs if you created some via the `kiali-create` target or the `ossmconsole-create` target), run `make olm-operator-delete`.
 
-NOTE: By default, you will test with the latest version of the metadata. You can specify a different version by setting the `BUNDLE_VERSION` env var on the make command line. If the OC env var points to an `oc` binary, the metadata from the kiali-community will be used; otherwise, the metadata from the kiali-upstream will be used. If you instead want to test with the OSSM metadata, set the env var `OLM_BUNDLE_PACKAGE` to `kiali-ossm` on the make command line.
+NOTE: By default, you will test with the latest version of the "kiali-ossm" metadata. You can specify a different version by setting the `BUNDLE_VERSION` env var on the make command line. If the OC env var points to an `oc` binary, the metadata from the kiali-community will be used; otherwise, the metadata from the kiali-upstream will be used. If you want to do this, you also must set the env var `OLM_BUNDLE_PACKAGE` to `kiali` on the make command line.
 
 ### Running the Operator Playbook Without Installing in a Cluster
 
-Sometimes you made simple changes to the operator playbook and roles that can be quickly tested by running the Ansible playbook on your local machine. This saves time because it doesn't require you to install the operator directly in your cluster. To do this, you must have Ansible installed (e.g. `ansible-playbook` must be in your $PATH). You can run the operator playbook via `make run-operator-playbook`. This will run both the kiali-deploy and kiali-remove playbooks so the operator will install and then immediately uninstall a Kiali Server. The operator playbook is configured via the files found in the link:dev-playbook-config[dev-playbook-config directory].
+Sometimes you made simple changes to the operator playbook and roles that can be quickly tested by running the Ansible playbook on your local machine. This saves time because it doesn't require you to install the operator directly in your cluster. To do this, you must have Ansible installed (e.g. `ansible-playbook` must be in your $PATH). You can run the operator playbook via `make run-operator-playbook-kiali` (to test the Kiali playbooks) or `make run-operator-playbook-ossmconsole` (to test the OSSMC playbooks). `run-operator-playbook-kiali` will run both the kiali-deploy and kiali-remove playbooks so the operator will install and then immediately uninstall a Kiali Server. `run-operator-playbook-ossmconsole` will run both the ossmconsole-deploy and ossmconsole-remove playbooks so the operator will install and then immediately uninstall a OSSMC plugin. The operator playbooks are configured via the files found in the link:dev-playbook-config[dev-playbook-config directory].
 
-In order to use this `run-operator-playbook` target, you must have Python3 in your PATH (having an alias is not enough).
+In order to use these "run-operator-playbook" targets, you must have Python3 in your PATH (having an alias is not enough).
 
 You also must make sure your local Python and Ansible environment matches as closely as possible to the environment of the Kiali operator. To find out the different versions of software within the Kiali operator image, run the following:
 
@@ -84,7 +84,7 @@ To install these, run `ansible-galaxy collection install -r operator/requirement
 
 ### Running the Operator Without Installing in a Cluster
 
-The previous section tells you how to run the Ansible playbook directly on your local machine. If you want to run the actual operator on your local machine in the same manner in which it runs inside the cluster (that is, within the `ansible-operator` shell process) then use the `make run-operator` make target. This will run the ansible-operator executable and point it to the operator's Ansible playbooks and roles. This operator will watch for Kiali CRs in the cluster - when it sees one, it will process it just as if it was running in the cluster. This will allow you to test the Ansible operator infrastructure as well as the operator's Ansible playbooks themselves.
+The previous section tells you how to run the Ansible playbook directly on your local machine. If you want to run the actual operator on your local machine in the same manner in which it runs inside the cluster (that is, within the `ansible-operator` shell process) then use the `make run-operator` make target. This will run the ansible-operator executable and point it to the operator's Ansible playbooks and roles. This operator will watch for Kiali CRs and OSSMConsole CRs in the cluster - when it sees one, it will process it just as if it was running in the cluster. This will allow you to test the Ansible operator infrastructure as well as the operator's Ansible playbooks themselves.
 
 ### Running the Operator With the Ansible Profiler
 

Makefile

@@ -95,12 +95,21 @@ validate: .ensure-operator-sdk-exists
 
 ## validate-cr: Ensures the example CR is valid according to the CRD schema
 validate-cr:
+	@printf "\n========== Validating the Kiali CR ==========\n"
 	${ROOTDIR}/crd-docs/bin/validate-kiali-cr.sh --kiali-cr-file ${ROOTDIR}/crd-docs/cr/kiali.io_v1alpha1_kiali.yaml
+	@printf "\n========== Validating the OSSMConsole CR ==========\n"
+	${ROOTDIR}/crd-docs/bin/validate-ossmconsole-cr.sh --cr-file ${ROOTDIR}/crd-docs/cr/kiali.io_v1alpha1_ossmconsole.yaml
 
-## gen-crd-doc: Generates documentation for the Kiali CR configuration
-gen-crd-doc:
+.gen-crd-doc-kiali:
 	mkdir -p ${OUTDIR}/crd-docs
-	${DORP} run -v ${OUTDIR}/crd-docs:/opt/crd-docs-generator/output -v ${ROOTDIR}/crd-docs/config:/opt/crd-docs-generator/config quay.io/giantswarm/crd-docs-generator:0.9.0 --config /opt/crd-docs-generator/config/apigen-config.yaml
+	${DORP} run -v ${OUTDIR}/crd-docs:/opt/crd-docs-generator/output:z -v ${ROOTDIR}/crd-docs/config/kiali:/opt/crd-docs-generator/config:z quay.io/giantswarm/crd-docs-generator:0.9.0 --config /opt/crd-docs-generator/config/apigen-config.yaml
+
+.gen-crd-doc-ossmconsole:
+	mkdir -p ${OUTDIR}/crd-docs
+	${DORP} run -v ${OUTDIR}/crd-docs:/opt/crd-docs-generator/output:z -v ${ROOTDIR}/crd-docs/config/ossmconsole:/opt/crd-docs-generator/config:z quay.io/giantswarm/crd-docs-generator:0.9.0 --config /opt/crd-docs-generator/config/apigen-config.yaml
+
+## gen-crd-doc: Generates documentation for the Kiali CR and OSSMConsole CR configuration
+gen-crd-doc: .gen-crd-doc-kiali .gen-crd-doc-ossmconsole
 
 # Ensure "docker buildx" is available and enabled. For more details, see: https://github.com/docker/buildx/blob/master/README.md
 # This does a few things:

crd-docs/bin/validate-ossmconsole-cr.sh

@@ -0,0 +1,182 @@
+#!/bin/bash
+
+##############################################################################
+# validate-ossmconsole-cr.sh
+#
+# This script can be used to validate an OSSMConsole CR.
+#
+# To use this script, you must:
+# * Have "oc" or "kubectl"
+# * Be connected to a cluster
+# * Have cluster-admin rights
+#
+##############################################################################
+
+set -u
+
+crd() {
+  local crd_file=""
+
+  # if not specified, use the default location; otherwise, it is either a file or a URL
+  if [ -z "${OSSMCONSOLE_CRD_LOCATION:-}" ]; then
+    local script_root="$(cd "$(dirname "$0")" ; pwd -P)"
+    crd_file="${script_root}/../crd/kiali.io_ossmconsoles.yaml"
+  elif [ -f "${OSSMCONSOLE_CRD_LOCATION}" ]; then
+    crd_file="${OSSMCONSOLE_CRD_LOCATION}"
+  fi
+  ([ -n "${crd_file}" ] && cat "${crd_file}" || curl -sL "${OSSMCONSOLE_CRD_LOCATION}") | sed 's/ name: ossmconsoles.kiali.io/ name: testossmconsoles.kiali.io/g' | sed 's/ kind: OSSMConsole/ kind: TestOSSMConsole/g' | sed 's/ listKind: OSSMConsoleList/ listKind: TestOSSMConsoleList/g' | sed 's/ plural: ossmconsoles/ plural: testossmconsoles/g' | sed 's/ singular: ossmconsole/ singular: testossmconsole/g'
+}
+
+# process command line args to override environment
+_CMD=""
+while [[ $# -gt 0 ]]; do
+  key="$1"
+  case $key in
+    -ce|--client-exe)    CLIENT_EXE="$2"               ; shift;shift ;;
+    -crd|--crd-location) OSSMCONSOLE_CRD_LOCATION="$2" ; shift;shift ;;
+    -cf|--cr-file)       OSSMCONSOLE_CR_FILE="$2"      ; shift;shift ;;
+    -cn|--cr-name)       OSSMCONSOLE_CR_NAME="$2"      ; shift;shift ;;
+    -n|--namespace)      NAMESPACE="$2"                ; shift;shift ;;
+    -pc|--print-crd)     PRINT_CRD="$2"                ; shift;shift ;;
+    -h|--help)
+      cat <<HELPMSG
+
+$0 [option...]
+
+  -ce|--client-exe
+      The path to the client executable. Should be a path to either a "oc" or "kubectl" executable.
+  -crd|--crd-location
+      The file or URL location where the OSSMConsole CRD is. This CRD must include the schema.
+      If not specified, the internally defined CRD is used.
+  -cf|--cr-file
+      The file of the OSSMConsole CR to test.
+  -cn|--cr-name
+      The name of an existing OSSMConsole CR to test.
+  -n|--namespace
+      The namespace where the existing CR is or where the test CR will be created.
+      Default: "default"
+  -pc|--print-crd
+      If true, then this script will just print the CRD used to validate. It will not validate anything.
+      Default "false"
+HELPMSG
+      exit 1
+      ;;
+    *)
+      echo "Unknown argument [$key]. Aborting."
+      exit 1
+      ;;
+  esac
+done
+
+# Set up some defaults
+
+: ${NAMESPACE:=default}
+: ${PRINT_CRD:=false}
+
+# If we are to print the CRD, do it now immediately and then exit. Nothing else to do.
+if [ "${PRINT_CRD}" == "true" ]; then
+  echo "$(crd)"
+  exit $?
+fi
+
+echo "=== SETTINGS ==="
+echo OSSMCONSOLE_CRD_LOCATION=${OSSMCONSOLE_CRD_LOCATION:-}
+echo OSSMCONSOLE_CR_FILE=${OSSMCONSOLE_CR_FILE:-}
+echo OSSMCONSOLE_CR_NAME=${OSSMCONSOLE_CR_NAME:-}
+echo NAMESPACE=${NAMESPACE}
+echo PRINT_CRD=${PRINT_CRD}
+echo "=== SETTINGS ==="
+
+# Determine what cluster client tool we are using.
+if [ -z "${CLIENT_EXE:-}" ]; then
+  if which oc &>/dev/null; then
+    CLIENT_EXE="$(which oc)"
+    echo "Using 'oc' located here: ${CLIENT_EXE}"
+  else
+    if which kubectl &>/dev/null; then
+      CLIENT_EXE="$(which kubectl)"
+      echo "Using 'kubectl' located here: ${CLIENT_EXE}"
+    else
+      echo "ERROR! You do not have 'oc' or 'kubectl' in your PATH. Please install it and retry."
+      exit 1
+    fi
+  fi
+else
+  echo "Client executable: ${CLIENT_EXE}"
+fi
+
+if [ -z "${OSSMCONSOLE_CR_FILE:-}" -a -z "${OSSMCONSOLE_CR_NAME:-}" ]; then
+  echo "ERROR! You must specify one of either --cr-file or --cr-name"
+  exit 1
+fi
+
+if [ -n "${OSSMCONSOLE_CR_FILE:-}" -a -n "${OSSMCONSOLE_CR_NAME:-}" ]; then
+  echo "ERROR! You must specify only one of either --cr-file or --cr-name"
+  exit 1
+fi
+
+if [ -n "${OSSMCONSOLE_CR_FILE:-}" -a ! -f "${OSSMCONSOLE_CR_FILE:-}" ]; then
+  echo "ERROR! OSSMConsole CR file is not found: [${OSSMCONSOLE_CR_FILE:-}]"
+  exit 1
+fi
+
+if [ -n "${OSSMCONSOLE_CR_NAME:-}" ]; then
+  if ! ${CLIENT_EXE} get -n "${NAMESPACE}" ossmconsole "${OSSMCONSOLE_CR_NAME}" &> /dev/null; then
+    echo "ERROR! OSSMConsole CR [${OSSMCONSOLE_CR_NAME}] does not exist in namespace [${NAMESPACE}]"
+    exit 1
+  fi
+fi
+
+# Make sure we have admin rights to some cluster
+if ! ${CLIENT_EXE} get namespaces &> /dev/null ; then
+  echo "ERROR! You must be connected to/logged into a cluster"
+  exit 1
+fi
+if [ "$(${CLIENT_EXE} auth can-i create crd --all-namespaces)" != "yes" ]; then
+  echo "ERROR! You must have cluster-admin permissions"
+  exit 1
+fi
+
+# install the test CRD with the schema
+if ! echo "$(crd)" | ${CLIENT_EXE} apply --validate=true --wait=true -f - &> /dev/null ; then
+  echo "ERROR! Failed to install the test CRD"
+  exit 1
+fi
+
+# wait for the test CRD to be established and then give k8s a few more seconds.
+# if we don't do this, the validation test may report a false negative.
+if ! ${CLIENT_EXE} wait --for condition=established --timeout=60s crd/testossmconsoles.kiali.io &> /dev/null ; then
+  echo "WARNING! Test CRD is not established yet. The validation test may not produce accurate results."
+else
+  for s in 3 2 1; do echo -n "." ; sleep 1 ; done
+  echo
+fi
+
+# validate the CR by creating a test version of it
+echo "Validating the CR:"
+echo "----------"
+if [ -n "${OSSMCONSOLE_CR_FILE:-}" ]; then
+  if ! cat "${OSSMCONSOLE_CR_FILE}" | sed 's/kind: OSSMConsole/kind: TestOSSMConsole/g' | sed 's/- kiali.io\/finalizer//g' | kubectl apply -n ${NAMESPACE} -f - ; then
+    echo "----------"
+    echo "ERROR! Validation failed for OSSMConsole CR [${OSSMCONSOLE_CR_FILE}]"
+    exit 1
+  else
+    echo "----------"
+    echo "OSSMConsole CR [${OSSMCONSOLE_CR_FILE}] is valid."
+  fi
+else
+  if ! ${CLIENT_EXE} get -n "${NAMESPACE}" ossmconsole "${OSSMCONSOLE_CR_NAME}" -o yaml | sed 's/kind: OSSMConsole/kind: TestOSSMConsole/g' | sed 's/- kiali.io\/finalizer//g' | kubectl apply -n "${NAMESPACE}" -f - ; then
+    echo "----------"
+    echo "ERROR! Validation failed for OSSMConsole CR [${OSSMCONSOLE_CR_NAME}] in namespace [${NAMESPACE}]"
+    exit 1
+  else
+    echo "----------"
+    echo "OSSMConsole CR [${OSSMCONSOLE_CR_NAME}] in namespace [${NAMESPACE}] is valid."
+  fi
+fi
+
+# delete the test CRD (which deletes the test CR along with it)
+if ! echo "$(crd)" | ${CLIENT_EXE} delete --wait=true -f - &> /dev/null ; then
+  echo "ERROR! Failed to delete the test CRD. You should remove it manually."
+  exit 1
+fi

crd-docs/config/ossmconsole/apigen-config.yaml

@@ -0,0 +1,15 @@
+template_path: ./apigen-crd.template
+
+source_repositories:
+- url: https://github.com/kiali/kiali-operator
+  organization: kiali
+  short_name: kiali-operator
+  commit_reference: master
+  crd_paths:
+  - crd-docs/crd
+  cr_paths:
+  - crd-docs/cr
+  metadata:
+    ossmconsoles.kiali.io:
+      owner:
+      - https://github.com/orgs/kiali/teams/maintainers

crd-docs/config/ossmconsole/apigen-crd.template

@@ -0,0 +1,99 @@
+---
+title: {{ .Title }} CR Reference
+linkTitle: {{ .Title }} CR Reference
+description: |
+{{- if .Description }}
+{{ .Description | indent 2 }}
+{{- else }}
+  Reference page for the {{ .Title }} CR.
+  The Kiali Operator will watch for a resource of this type and install the OSSM Console plugin according to that resource's configuration. Only one resource of this type should exist at any one time.
+{{- end }}
+technical_name: {{ .NamePlural }}.{{ .Group }}
+source_repository: {{ .SourceRepository }}
+source_repository_ref: {{ .SourceRepositoryRef }}
+---
+
+{{ if .VersionSchemas }}
+{{ range $versionName, $versionSchema := .VersionSchemas }}
+<div class="crd-schema-version">
+
+{{with .ExampleCR}}
+<h3 id="example-cr">Example CR</h3>
+<em>(all values shown here are the defaults unless otherwise noted)</em>
+
+```yaml
+{{ .|raw -}}
+```
+{{end}}
+
+### Validating your OSSMConsole CR
+
+A tool is available to allow you to check your own OSSMConsole CR to ensure it is valid. Simply download [the validation script](https://raw.githubusercontent.com/kiali/kiali-operator/master/crd-docs/bin/validate-ossmconsole-cr.sh) and run it, passing in the location of the OSSMConsole CRD you wish to validate with (e.g. the latest version is found [here](https://raw.githubusercontent.com/kiali/kiali-operator/master/crd-docs/crd/kiali.io_ossmconsoles.yaml)) and the location of your OSSMConsole CR. You must be connected to/logged into a cluster for this validation tool to work.
+
+For example, to validate an OSSMConsole CR named `ossmconsole` in the namespace `istio-system` using the latest version of the OSSMConsole CRD, run the following:
+<pre>
+bash <(curl -sL https://raw.githubusercontent.com/kiali/kiali-operator/master/crd-docs/bin/validate-ossmconsole-cr.sh) \
+  -crd https://raw.githubusercontent.com/kiali/kiali-operator/master/crd-docs/crd/kiali.io_ossmconsoles.yaml \
+  --cr-name ossmconsole \
+  -n istio-system
+</pre>
+
+For additional help in using this validation tool, pass it the `--help` option.
+
+<h3 id="property-details">Properties</h3>
+
+{{ range $versionSchema.Properties }}
+<div class="property depth-{{.Depth}}">
+<div class="property-header">
+<hr/>
+<h3 class="property-path" id="{{.Path}}">{{.Path}}</h3>
+</div>
+<div class="property-body">
+<div class="property-meta">
+{{with .Type}}<span class="property-type">({{.}})</span>{{end}}
+{{ if not .Required }}
+{{ else -}}
+<span class="property-required">*Required*</span>
+{{ end -}}
+</div>
+{{with .Description}}
+<div class="property-description">
+{{.|markdown}}
+</div>
+{{end}}
+</div>
+</div>
+{{ end }}
+
+
+{{ if .Annotations }}
+<h3 id="annotation-details">Annotations</h3>
+
+{{ range $versionSchema.Annotations }}
+<div class="annotation">
+<div class="annotation-header">
+<h3 class="annotation-path" id="{{.CRDVersion}}-{{.Annotation}}">{{.Annotation}}</h3>
+</div>
+<div class="annotation-body">
+<div class="annotation-meta">
+{{with .Release}}<span class="annotation-release">{{.}}</span>{{end}}
+</div>
+{{with .Documentation}}
+<div class="annotation-description">
+{{.|markdown}}
+</div>
+{{end}}
+</div>
+</div>
+{{ end }}
+{{ end }}
+
+</div>
+{{end}}
+
+{{ else }}
+<div class="crd-noversions">
+<p>We currently cannot show any schema information on this <abbr title="custom resource definition">CRD</abbr>. Sorry for the inconvenience!</p>
+<p>Please refer to <a href="https://kiali.io">Kiali Documentation</a>.</p>
+</div>
+{{ end }}