From 7657327abf9486eea35518afaac39f3beb47d44d Mon Sep 17 00:00:00 2001 From: John Mazzitelli Date: Tue, 24 Oct 2023 11:33:58 -0400 Subject: [PATCH] update DEVELOPING and IMPLEMENTATION docs with new ossmc info (#700) --- DEVELOPING.adoc | 6 ++-- IMPLEMENTATION.adoc | 67 ++++++++++++++++++++++++--------------------- 2 files changed, 40 insertions(+), 33 deletions(-) diff --git a/DEVELOPING.adoc b/DEVELOPING.adoc index 6134cb17..1a733c7d 100644 --- a/DEVELOPING.adoc +++ b/DEVELOPING.adoc @@ -225,10 +225,12 @@ NOTE: If you have never run the Molecule tests before, the Molecule container im - [ ] Add the new role directory by copying the link:./roles[default] role and naming the new role with the form `vX.Y`. - [ ] Add the new RELATED_IMAGE reference for the version being added to the link:./manifests/kiali-ossm/manifests/kiali.clusterserviceversion.yaml/[the CSV] -- [ ] Add the new version to link:./playbooks/default-supported-images.yml[default-supported-images.yml] +- [ ] Add the new version to link:./playbooks/kiali-default-supported-images.yml[kiali-default-supported-images.yml] +- [ ] Add the new version to link:./playbooks/ossmconsole-default-supported-images.yml[ossmconsole-default-supported-images.yml] ### Are You Removing Support For an Old Ansible Role Version? - [ ] Delete the role directory (link:./roles/[one of these]) - [ ] Remove the RELATED_IMAGE reference for the version being removed from link:./manifests/kiali-ossm/manifests/kiali.clusterserviceversion.yaml/[the CSV] -- [ ] Remove the version from link:./playbooks/default-supported-images.yml[default-supported-images.yml] +- [ ] Remove the version from link:./playbooks/kiali-default-supported-images.yml[kiali-default-supported-images.yml] +- [ ] Remove the version from link:./playbooks/ossmconsole-default-supported-images.yml[ossmconsole-default-supported-images.yml] diff --git a/IMPLEMENTATION.adoc b/IMPLEMENTATION.adoc index cfe015f2..95113062 100644 --- a/IMPLEMENTATION.adoc +++ b/IMPLEMENTATION.adoc @@ -2,65 +2,70 @@ This document describes the current state of the implementation of the Kiali Operator (henceforce, "KO"). The purpose for this document is to provide an introduction to the internals of the KO to those who have a need to modify or enhance the KO. -NOTE: This document reflects the current implementation as of release link:https://github.com/kiali/kiali-operator/tree/v1.69.0[v1.69.0] +NOTE: This document reflects the current implementation as of release link:https://github.com/kiali/kiali-operator/tree/v1.76.0[v1.76.0] NOTE: To learn how to set up and run the KO within your own development environment, see link:./DEVELOPING.adoc[DEVELOPING.adoc]. == Ansible -The core of the KO is Ansible. The KO utilizes the link:https://sdk.operatorframework.io/docs/building-operators/ansible/[Ansible Operator SDK] to provide the base Kubernetes operator functionality. The Kiali-specific code is implemented inside Ansible link:https://github.com/kiali/kiali-operator/tree/v1.69.0/playbooks[playbooks] and link:https://github.com/kiali/kiali-operator/tree/v1.69.0/roles[roles]. +The core of the KO is Ansible. The KO utilizes the link:https://sdk.operatorframework.io/docs/building-operators/ansible/[Ansible Operator SDK] to provide the base Kubernetes operator functionality. The Kiali-specific code is implemented inside Ansible link:https://github.com/kiali/kiali-operator/tree/master/playbooks[playbooks] and link:https://github.com/kiali/kiali-operator/tree/master/roles[roles]. NOTE: The KO needs to periodically update its Ansible Operator SDK base image. To see how this is done, just do the same things done previously (see link:https://github.com/kiali/kiali/issues/6220[this issue] and link:https://github.com/kiali/kiali-operator/pull/657/files[this PR] as good examples of what needs to be done). == Multiple Version Support -The KO can support installing multiple versions of the Kiali server by invoking different versions of the Ansible roles. The versions the KO supports are defined in link:https://github.com/kiali/kiali-operator/blob/v1.69.0/playbooks/default-supported-images.yml[default-supported-images.yml]. For each version supported, there is an link:https://github.com/kiali/kiali-operator/tree/v1.69.0/roles[Ansible role] that the KO executes when it needs to install or remove that Kiali version. +The KO can support installing multiple versions of the Kiali server and OSSMC by invoking different versions of the Ansible roles. The versions the KO supports are defined in link:https://github.com/kiali/kiali-operator/blob/master/playbooks/kiali-default-supported-images.yml[kiali-default-supported-images.yml] and (for OSSMC) in link:https://github.com/kiali/kiali-operator/blob/master/playbooks/ossmconsole-default-supported-images.yml[ossmconsole-default-supported-images.yml]. For each version supported, there is an link:https://github.com/kiali/kiali-operator/tree/master/roles[Ansible role] that the KO executes when it needs to install or remove that Kiali or OSSMC version. NOTE: If you need to add support for a new version or remove support for an obsolete version, see link:./DEVELOPING.adoc[DEVELOPING.adoc] for those instructions. -To tell the KO which version of Kiali to install, you set the `spec.version` field in the Kiali CR. If no `spec.version` is defined in the Kiali CR, the default Ansible role that is executed is defined in link:https://github.com/kiali/kiali-operator/blob/v1.69.0/playbooks/default-playbook.yml[default-playbook.yml] (side note: the file, and the field inside it, are technically named incorrectly. This isn't the default _playbook_, instead it is the default _role_. But ignore that.) Today, the default version of the Ansible role that is invoked is called, literally, link:https://github.com/kiali/kiali-operator/tree/v1.69.0/roles/default[default]. This `default` version is the only one that the upstream Kiali project officially supports. This version support is provided for use by other products that want to retain support for earlier Kiali versions (such as Red Hat OpenShift Service Mesh). +To tell the KO which version of Kiali or OSSMC to install, you set the `spec.version` field in the Kiali CR or OSSMConsole CR. If no `spec.version` is defined in the CR, the default Ansible role that is executed is defined in link:https://github.com/kiali/kiali-operator/blob/master/playbooks/default-playbook.yml[default-playbook.yml] (side note: the file, and the field inside it, are technically named incorrectly. This isn't the default _playbook_, instead it is the default _role_. But ignore that.) Today, the default version of the Ansible role that is invoked is called, literally, link:https://github.com/kiali/kiali-operator/tree/master/roles/default[default]. This `default` version is the only one that the upstream Kiali project officially supports. This version support is provided for use by other products that want to retain support for earlier Kiali versions (such as Red Hat OpenShift Service Mesh). == Main Ansible Playbooks -There are three main link:https://github.com/kiali/kiali-operator/tree/v1.69.0/playbooks[playbooks] that can be invoked by the Ansible Operator SDK when it determines a reconciliation needs to take place. The Ansible Operator SDK knows to do this via the configuration defined in link:https://github.com/kiali/kiali-operator/blob/v1.69.0/watches.yaml[watches.yaml]. +There are several main link:https://github.com/kiali/kiali-operator/tree/master/playbooks[playbooks] that can be invoked by the Ansible Operator SDK when it determines a reconciliation needs to take place. The Ansible Operator SDK knows to do this via the configuration defined in link:https://github.com/kiali/kiali-operator/blob/master/watches.yaml[watches.yaml]. -- link:https://github.com/kiali/kiali-operator/tree/v1.69.0/playbooks/kiali-deploy.yml[kiali-deploy.yml] - this is invoked when a new Kiali CR is created or an existing one is modified. This playbook determines which version is to be installed/updated and runs that version's corresponding `kiali-deploy` link:https://github.com/kiali/kiali-operator/tree/v1.69.0/roles[Ansible role]. If Kiali is to be upgraded (that is, if the Kiali CR's `spec.version` has been changed), this playbook will first invoke the `kiali-remove` Ansible role of the version specified in the `spec.version` previously declared in the Kiali CR (as found in the Kiali CR's `status` field); once the old Kiali is removed, the new version is installed by the execution of the `kiali-deploy` Ansible role of the new version to be installed (as found in the Kiali CR `spec.version`). Therefore, an "upgrade" is really just an "uninstall" followed by an "install". -- link:https://github.com/kiali/kiali-operator/tree/v1.69.0/playbooks/kiali-remove.yml[kiali-remove.yml] - this is invoked when a Kiali CR has been removed. This playbook determines which version of Kiali is being uninstalled (as found in the now-deleted Kiali CR's `spec.version` field) and runs that version's corresponding `kiali-remove` link:https://github.com/kiali/kiali-operator/tree/v1.69.0/roles[Ansible role]. -- link:https://github.com/kiali/kiali-operator/tree/v1.69.0/playbooks/kiali-new-namespace-detected.yml[kiali-new-namespace-detected.yml] - this is invoked when a new namespace is created in the cluster. This playbook is simple and small. It's only job is to simply "touch" any and all existing Kiali CRs ("touching" in this context means adding/modifying an link:https://github.com/kiali/kiali-operator/blob/v1.69.0/playbooks/kiali-new-namespace-detected.yml#L30-L31[annotation to the Kiali CR] such that the modification will cause the KO to trigger a reconcilation). The playbook will only touch those Kiali CRs link:https://github.com/kiali/kiali-operator/blob/v1.69.0/playbooks/kiali-new-namespace-detected.yml#L34[if the namespace was created after the Kiali CR was created] and if the link:https://github.com/kiali/kiali-operator/blob/v1.69.0/playbooks/kiali-new-namespace-detected.yml#L21[Kiali CR was not modified or touched within the current minute]. This playbook enables a useful feature for those Kiali installations that are not given cluster-wide access but are given access to a set of namespaces defined by regular expressions (see `spec.deployment.accessible_namespaces`) or by Istio Discovery Selectors. In that case, when the KO reconciles the touched Kiali CRs, it will create the necessary Role/RoleBinding resources to give the Kiali installation access to the newly detected namespace. +- link:https://github.com/kiali/kiali-operator/tree/master/playbooks/kiali-deploy.yml[kiali-deploy.yml] - this is invoked when a new Kiali CR is created or an existing one is modified. This playbook determines which version is to be installed/updated and runs that version's corresponding `kiali-deploy` link:https://github.com/kiali/kiali-operator/tree/master/roles[Ansible role]. If Kiali is to be upgraded (that is, if the Kiali CR's `spec.version` has been changed), this playbook will first invoke the `kiali-remove` Ansible role of the version specified in the `spec.version` previously declared in the Kiali CR (as found in the Kiali CR's `status` field); once the old Kiali is removed, the new version is installed by the execution of the `kiali-deploy` Ansible role of the new version to be installed (as found in the Kiali CR `spec.version`). Therefore, an "upgrade" is really just an "uninstall" followed by an "install". +- link:https://github.com/kiali/kiali-operator/tree/master/playbooks/kiali-remove.yml[kiali-remove.yml] - this is invoked when a Kiali CR has been removed. This playbook determines which version of Kiali is being uninstalled (as found in the now-deleted Kiali CR's `spec.version` field) and runs that version's corresponding `kiali-remove` link:https://github.com/kiali/kiali-operator/tree/master/roles[Ansible role]. +- link:https://github.com/kiali/kiali-operator/tree/v1.75.0/playbooks/kiali-new-namespace-detected.yml[kiali-new-namespace-detected.yml] - this is invoked when a new namespace is created in the cluster. This playbook is simple and small. It's only job is to simply "touch" any and all existing Kiali CRs ("touching" in this context means adding/modifying an link:https://github.com/kiali/kiali-operator/blob/v1.75.0/playbooks/kiali-new-namespace-detected.yml#L30-L31[annotation to the Kiali CR] such that the modification will cause the KO to trigger a reconcilation). The playbook will only touch those Kiali CRs link:https://github.com/kiali/kiali-operator/blob/v1.75.0/playbooks/kiali-new-namespace-detected.yml#L34[if the namespace was created after the Kiali CR was created] and if the link:https://github.com/kiali/kiali-operator/blob/v1.75.0/playbooks/kiali-new-namespace-detected.yml#L21[Kiali CR was not modified or touched within the current minute]. This playbook enables a useful feature for those Kiali installations that are not given cluster-wide access but are given access to a set of namespaces defined by regular expressions (see `spec.deployment.accessible_namespaces`) or by Istio Discovery Selectors. In that case, when the KO reconciles the touched Kiali CRs, it will create the necessary Role/RoleBinding resources to give the Kiali installation access to the newly detected namespace. +- KO v1.76.0 added support for OSSMC. There are additional `ossmconsole-deploy.yml` and `ossmconsole-remove.yml` playbooks that install and uninstall OSSMC. These are triggered by OSSMConsole CRs, but work analogously as the `kiali-deploy.yml` and `kiali-remove.yml` playbooks as described above. == Ansible Deploy Role -The link:https://github.com/kiali/kiali-operator/tree/v1.69.0/roles/default/kiali-deploy[kiali-deploy] role is responsible for installing and updating a Kiai server. It is a standard Ansible role that follows the normal Ansible format. The different directories in this role are described below. +The link:https://github.com/kiali/kiali-operator/tree/master/roles/default/kiali-deploy[kiali-deploy] role is responsible for installing and updating a Kiai server. It is a standard Ansible role that follows the normal Ansible format. The different directories in this role are described below. -* link:https://github.com/kiali/kiali-operator/tree/v1.69.0/roles/default/kiali-deploy/defaults[defaults] - defines defaults for virtually every setting possible in the Kiali CR. Note that a top-level dict is defined (`kiali_defaults`) with everything under it. This is because the `vars` (see below) need to do a trick in order to support the use-case where the user doesn't define every setting in the Kiali CR (which is the typical use-case). Read link:https://github.com/kiali/kiali-operator/blob/v1.69.0/roles/default/kiali-deploy/vars/main.yml#L1-L9[the comment here] to understand the purpose of the trick. Any new setting added to the Kiali CR schema should (almost always) have a default set here. There are a few cases where having an undefined default is necessary, but most times it is not. When in doubt, set the default here. -* link:https://github.com/kiali/kiali-operator/tree/v1.69.0/roles/default/kiali-deploy/filter_plugins[filter_plugins] - filter plugins are a way to jump from Ansible into a Python context when things are easier or more efficient to do with Python code rather than directly within Ansible tasks. There are two custom filters the KO uses in the deploy role: -** link:https://github.com/kiali/kiali-operator/blob/v1.69.0/roles/default/kiali-deploy/filter_plugins/only_accessible_namespaces.py[only_accessible_namespaces.py] - given a list of all known namespaces and a list of accessible namespace regular expressions, this filters out all non-accessible namespaces (i.e. returns a list of only the namespaces that match an accessible namespace regex). Example usage link:https://github.com/kiali/kiali-operator/blob/v1.69.0/roles/default/kiali-deploy/tasks/main.yml#L556[here]. -** link:https://github.com/kiali/kiali-operator/blob/v1.69.0/roles/default/kiali-deploy/filter_plugins/stripnone.py[stripnone] - Recursively processes a given dict value and removes all keys that have a 'None' value. This is needed when setting up the startup variable values. Example usage link:https://github.com/kiali/kiali-operator/blob/v1.69.0/roles/default/kiali-deploy/vars/main.yml#L36[here]. -* link:https://github.com/kiali/kiali-operator/tree/v1.69.0/roles/default/kiali-deploy/meta[meta] - The KO only uses this to declare the collections it wants to use. Today, the KO only needs to link:https://github.com/kiali/kiali-operator/blob/v1.69.0/roles/default/kiali-deploy/meta/main.yml[declare the kubernetes.core collection]. -* link:https://github.com/kiali/kiali-operator/tree/v1.69.0/roles/default/kiali-deploy/tasks[tasks] - The tasks that are executed when a Kiali CR has been created or modified. The KO does not care if this is a new Kiali that needs to be installed or an existing Kiali that needs to be updated. The KO will invoke the same tasks and process the same templates. Any existing resources will simply be updated to match that of the templates (this is what it means when it is said the operator "reconciles" the existing resources with the desired state of the templates). The link:https://github.com/kiali/kiali-operator/blob/v1.69.0/roles/default/kiali-deploy/tasks/main.yml[main.yml] file is the main starting point of execution for the deploy role. This performs some initialization (getting version information of the operator itself and the cluster, initializing variables and setting defaults, etc) and then handles creation and updates of the various resources that make up a Kiali installation. There is a lot of work done here (and included tasks such as link:https://github.com/kiali/kiali-operator/blob/v1.69.0/roles/default/kiali-deploy/tasks/remove-roles.yml[remove-roles.yml] and others) that handle reconciling the Roles and Role Bindings (as accessible namespaces come and go, the Kiali Service Account must have its Roles/RoleBindings updated appropriately). -* link:https://github.com/kiali/kiali-operator/tree/v1.69.0/roles/default/kiali-deploy/templates[templates] - YAML files which are used to create new resources (or update existing ones). Ansible expressions can be placed in the templates; these expressions will be evaluated when they are processed by the `kubernetes.core.k8s` task (an example where they are processed is link:https://github.com/kiali/kiali-operator/blob/v1.69.0/roles/default/kiali-deploy/tasks/process-resource.yml#L4-L7[here]). There are two sets of YAML templates - one for OpenShift clusters (link:https://github.com/kiali/kiali-operator/tree/v1.69.0/roles/default/kiali-deploy/templates/openshift[`openshift`]) and one for non-OpenShift clusters (link:https://github.com/kiali/kiali-operator/tree/v1.69.0/roles/default/kiali-deploy/templates/kubernetes[`kubernetes`]). -* link:https://github.com/kiali/kiali-operator/tree/v1.69.0/roles/default/kiali-deploy/vars[vars] - defines the actual variables used by the Ansible deploy tasks. All variables are stored under the main top level dict called `kiali_vars`. Read link:https://github.com/kiali/kiali-operator/blob/v1.69.0/roles/default/kiali-deploy/vars/main.yml#L1-L9[the comment here] to understand the trick being used to define the variables. Notice that only the top group of variables (directly under `kiali_vars`) has a section defined here (e.g. link:https://github.com/kiali/kiali-operator/blob/v1.69.0/roles/default/kiali-deploy/vars/main.yml#L34-L39[`auth`] is a top group of variables). When adding a new top group, just copy-and-paste an existing group and rename variables in the new top group as appropriate. +* link:https://github.com/kiali/kiali-operator/tree/master/roles/default/kiali-deploy/defaults[defaults] - defines defaults for virtually every setting possible in the Kiali CR. Note that a top-level dict is defined (`kiali_defaults`) with everything under it. This is because the `vars` (see below) need to do a trick in order to support the use-case where the user doesn't define every setting in the Kiali CR (which is the typical use-case). Read link:https://github.com/kiali/kiali-operator/blob/master/roles/default/kiali-deploy/vars/main.yml#L1-L9[the comment here] to understand the purpose of the trick. Any new setting added to the Kiali CR schema should (almost always) have a default set here. There are a few cases where having an undefined default is necessary, but most times it is not. When in doubt, set the default here. +* link:https://github.com/kiali/kiali-operator/tree/master/roles/default/kiali-deploy/filter_plugins[filter_plugins] - filter plugins are a way to jump from Ansible into a Python context when things are easier or more efficient to do with Python code rather than directly within Ansible tasks. There are two custom filters the KO uses in the deploy role: +** link:https://github.com/kiali/kiali-operator/blob/master/roles/default/kiali-deploy/filter_plugins/only_accessible_namespaces.py[only_accessible_namespaces.py] - given a list of all known namespaces and a list of accessible namespace regular expressions, this filters out all non-accessible namespaces (i.e. returns a list of only the namespaces that match an accessible namespace regex). Example usage link:https://github.com/kiali/kiali-operator/blob/v1.75.0/roles/default/kiali-deploy/tasks/main.yml#L532[here]. +** link:https://github.com/kiali/kiali-operator/blob/master/roles/default/kiali-deploy/filter_plugins/stripnone.py[stripnone] - Recursively processes a given dict value and removes all keys that have a 'None' value. This is needed when setting up the startup variable values. Example usage link:https://github.com/kiali/kiali-operator/blob/v1.75.0/roles/default/kiali-deploy/vars/main.yml#L36[here]. +* link:https://github.com/kiali/kiali-operator/tree/master/roles/default/kiali-deploy/meta[meta] - The KO only uses this to declare the collections it wants to use. Today, the KO only needs to link:https://github.com/kiali/kiali-operator/blob/master/roles/default/kiali-deploy/meta/main.yml[declare the kubernetes.core collection]. +* link:https://github.com/kiali/kiali-operator/tree/master/roles/default/kiali-deploy/tasks[tasks] - The tasks that are executed when a Kiali CR has been created or modified. The KO does not care if this is a new Kiali that needs to be installed or an existing Kiali that needs to be updated. The KO will invoke the same tasks and process the same templates. Any existing resources will simply be updated to match that of the templates (this is what it means when it is said the operator "reconciles" the existing resources with the desired state of the templates). The link:https://github.com/kiali/kiali-operator/blob/master/roles/default/kiali-deploy/tasks/main.yml[main.yml] file is the main starting point of execution for the deploy role. This performs some initialization (getting version information of the operator itself and the cluster, initializing variables and setting defaults, etc) and then handles creation and updates of the various resources that make up a Kiali installation. There is a lot of work done here (and included tasks such as link:https://github.com/kiali/kiali-operator/blob/master/roles/default/kiali-deploy/tasks/remove-roles.yml[remove-roles.yml] and others) that handle reconciling the Roles and Role Bindings (as accessible namespaces come and go, the Kiali Service Account must have its Roles/RoleBindings updated appropriately). +* link:https://github.com/kiali/kiali-operator/tree/master/roles/default/kiali-deploy/templates[templates] - YAML files which are used to create new resources (or update existing ones). Ansible expressions can be placed in the templates; these expressions will be evaluated when they are processed by the `kubernetes.core.k8s` task (an example where they are processed is link:https://github.com/kiali/kiali-operator/blob/v1.75.0/roles/default/kiali-deploy/tasks/process-resource.yml#L4-L7[here]). There are two sets of YAML templates - one for OpenShift clusters (link:https://github.com/kiali/kiali-operator/tree/master/roles/default/kiali-deploy/templates/openshift[`openshift`]) and one for non-OpenShift clusters (link:https://github.com/kiali/kiali-operator/tree/master/roles/default/kiali-deploy/templates/kubernetes[`kubernetes`]). +* link:https://github.com/kiali/kiali-operator/tree/master/roles/default/kiali-deploy/vars[vars] - defines the actual variables used by the Ansible deploy tasks. All variables are stored under the main top level dict called `kiali_vars`. Read link:https://github.com/kiali/kiali-operator/blob/v1.75.0/roles/default/kiali-deploy/vars/main.yml#L1-L9[the comment here] to understand the trick being used to define the variables. Notice that only the top group of variables (directly under `kiali_vars`) has a section defined here (e.g. link:https://github.com/kiali/kiali-operator/blob/v1.75.0/roles/default/kiali-deploy/vars/main.yml#L34-L39[`auth`] is a top group of variables). When adding a new top group, just copy-and-paste an existing group and rename variables in the new top group as appropriate. + +The link:https://github.com/kiali/kiali-operator/tree/master/roles/default/ossmconsole-deploy[ossmconsole-deploy] role is responsible for installing and updating OSSMC. It is an Ansible role that follows the normal Ansible format and follows the same design as the `kiali-deploy` role described above. == Ansible Remove Role -The link:https://github.com/kiali/kiali-operator/tree/v1.69.0/roles/default/kiali-remove[kiali-remove] role is responsible for uninstalling a Kiai server. It is a standard Ansible role that follows the normal Ansible format. The different directories in this role are described below. +The link:https://github.com/kiali/kiali-operator/tree/master/roles/default/kiali-remove[kiali-remove] role is responsible for uninstalling a Kiai server. It is a standard Ansible role that follows the normal Ansible format. The different directories in this role are described below. + +* link:https://github.com/kiali/kiali-operator/tree/master/roles/default/kiali-remove/defaults[defaults] - defines defaults for only those Kiali CR settings the remove tasks need in order to perform the uninstall. Note that a top-level dict is defined (`kiali_defaults_remove`) with everything under it. This is because the `vars` (see below) need to do a trick in order to support the use-case where the user doesn't define all the settings in the Kiali CR (which is the typical use-case). Read link:https://github.com/kiali/kiali-operator/blob/v1.75.0/roles/default/kiali-deploy/vars/main.yml#L1-L9[the comment here] to understand the purpose of the trick. +* link:https://github.com/kiali/kiali-operator/tree/master/roles/default/kiali-remove/filter_plugins[filter_plugins] - filter plugins are a way to jump from Ansible into a Python context when things are easier or more efficient to do with Python code rather than directly within Ansible tasks. There is one custom filter the KO uses in the remove role: +** link:https://github.com/kiali/kiali-operator/blob/master/roles/default/kiali-remove/filter_plugins/stripnone.py[stripnone.py] - Recursively processes a given dict value and removes all keys that have a None value. This is needed when setting up the startup variable values. Example usage link:https://github.com/kiali/kiali-operator/blob/v1.75.0/roles/default/kiali-remove/vars/main.yml#L6[here]. +* link:https://github.com/kiali/kiali-operator/tree/master/roles/default/kiali-remove/meta[meta] - The KO only uses this to declare the collections it wants to use. Today, the KO only needs to link:https://github.com/kiali/kiali-operator/blob/master/roles/default/kiali-remove/meta/main.yml[declare the kubernetes.core collection]. +* link:https://github.com/kiali/kiali-operator/tree/master/roles/default/kiali-remove/tasks[tasks] - The tasks that are executed when a Kiali CR has been removed and Kiali needs to be uninstalled. These tasks will also run if an existing Kial CR had its `spec.version` changed, in which case the old version installation will be removed via these tasks (this is described link:#main-ansible-playbooks[above]). +* link:https://github.com/kiali/kiali-operator/tree/master/roles/default/kiali-remove/vars[vars] - defines the actual variables used by the Ansible remove tasks. All variables are stored under the main top level dict called `kiali_vars_remove`. Read link:https://github.com/kiali/kiali-operator/blob/v1.75.0/roles/default/kiali-deploy/vars/main.yml#L1-L9[the comment here] to understand the trick being used to define the variables. Notice that only the top group of variables (directly under `kiali_vars_remove`) has a section defined here (e.g. link:https://github.com/kiali/kiali-operator/blob/v1.75.0/roles/default/kiali-remove/vars/main.yml#L4-L9[`deployment`] is a top group of variables). When adding a new top group, just copy-and-paste an existing group and rename variables in the new top group as appropriate. -* link:https://github.com/kiali/kiali-operator/tree/v1.69.0/roles/default/kiali-remove/defaults[defaults] - defines defaults for only those Kiali CR settings the remove tasks need in order to perform the uninstall. Note that a top-level dict is defined (`kiali_defaults_remove`) with everything under it. This is because the `vars` (see below) need to do a trick in order to support the use-case where the user doesn't define all the settings in the Kiali CR (which is the typical use-case). Read link:https://github.com/kiali/kiali-operator/blob/v1.69.0/roles/default/kiali-deploy/vars/main.yml#L1-L9[the comment here] to understand the purpose of the trick. -* link:https://github.com/kiali/kiali-operator/tree/v1.69.0/roles/default/kiali-remove/filter_plugins[filter_plugins] - filter plugins are a way to jump from Ansible into a Python context when things are easier or more efficient to do with Python code rather than directly within Ansible tasks. There is one custom filter the KO uses in the remove role: -** link:https://github.com/kiali/kiali-operator/blob/v1.69.0/roles/default/kiali-remove/filter_plugins/stripnone.py[stripnone.py] - Recursively processes a given dict value and removes all keys that have a None value. This is needed when setting up the startup variable values. Example usage link:https://github.com/kiali/kiali-operator/blob/v1.69.0/roles/default/kiali-remove/vars/main.yml#L6[here]. -* link:https://github.com/kiali/kiali-operator/tree/v1.69.0/roles/default/kiali-remove/meta[meta] - The KO only uses this to declare the collections it wants to use. Today, the KO only needs to link:https://github.com/kiali/kiali-operator/blob/v1.69.0/roles/default/kiali-remove/meta/main.yml[declare the kubernetes.core collection]. -* link:https://github.com/kiali/kiali-operator/tree/v1.69.0/roles/default/kiali-remove/tasks[tasks] - The tasks that are executed when a Kiali CR has been removed and Kiali needs to be uninstalled. These tasks will also run if an existing Kial CR had its `spec.version` changed, in which case the old version installation will be removed via these tasks (this is described link:#main-ansible-playbooks[above]). -* link:https://github.com/kiali/kiali-operator/tree/v1.69.0/roles/default/kiali-remove/vars[vars] - defines the actual variables used by the Ansible remove tasks. All variables are stored under the main top level dict called `kiali_vars_remove`. Read link:https://github.com/kiali/kiali-operator/blob/v1.69.0/roles/default/kiali-deploy/vars/main.yml#L1-L9[the comment here] to understand the trick being used to define the variables. Notice that only the top group of variables (directly under `kiali_vars_remove`) has a section defined here (e.g. link:https://github.com/kiali/kiali-operator/blob/v1.69.0/roles/default/kiali-remove/vars/main.yml#L4-L9[`deployment`] is a top group of variables). When adding a new top group, just copy-and-paste an existing group and rename variables in the new top group as appropriate. +The link:https://github.com/kiali/kiali-operator/tree/master/roles/default/ossmconsole-remove[ossmconsole-remove] role is responsible for uninstalling OSSMC. It is an Ansible role that follows the normal Ansible format and follows the same design as the `kiali-remove` role described above. == OLM Metadata Publishing link:https://github.com/operator-framework/operator-lifecycle-manager[OLM] is an alternative method of installing the KO, as opposed to using the link:https://github.com/kiali/helm-charts/tree/master/kiali-operator[Kiali Operator Helm Chart]. When a new release of the Kiali link:https://quay.io/repository/kiali/kiali?tab=tags[server] and link:https://quay.io/repository/kiali/kiali-operator?tab=tags[operator] container images are published on Quay.io, OLM metadata needs to published so users of OLM can subscribe to (aka install) the new KO. -There are three sets of link:https://github.com/kiali/kiali-operator/tree/v1.69.0/manifests[OLM metadata maintained in the github project], each for a different operator catalog that a user might want to use. +There are three sets of link:https://github.com/kiali/kiali-operator/tree/master/manifests[OLM metadata maintained in the github project], each for a different operator catalog that a user might want to use. -. The link:https://github.com/kiali/kiali-operator/tree/v1.69.0/manifests/kiali-upstream[kiali-upstream] metadata is published to the link:https://github.com/k8s-operatorhub/community-operators[Kubernetes Community Operators repo]. These operators then become available on link:https://operatorhub.io/operator/kiali[OperatorHub.io] -. The link:https://github.com/kiali/kiali-operator/tree/v1.69.0/manifests/kiali-community[kiali-community] metadata is published to the link:https://github.com/redhat-openshift-ecosystem/community-operators-prod[OpenShift Community Operators repo]. These operators then become available to OpenShift users as "community" operators. -. The link:https://github.com/kiali/kiali-operator/tree/v1.69.0/manifests/kiali-ossm[kiali-ossm] metadata is published as part of the productized OpenShift Service Mesh (OSSM) offering. These operators then become available to OpenShift customers as Red Hat-provided operators. +. The link:https://github.com/kiali/kiali-operator/tree/master/manifests/kiali-upstream[kiali-upstream] metadata is published to the link:https://github.com/k8s-operatorhub/community-operators[Kubernetes Community Operators repo]. These operators then become available on link:https://operatorhub.io/operator/kiali[OperatorHub.io] +. The link:https://github.com/kiali/kiali-operator/tree/master/manifests/kiali-community[kiali-community] metadata is published to the link:https://github.com/redhat-openshift-ecosystem/community-operators-prod[OpenShift Community Operators repo]. These operators then become available to OpenShift users as "community" operators. +. The link:https://github.com/kiali/kiali-operator/tree/master/manifests/kiali-ossm[kiali-ossm] metadata is published as part of the productized OpenShift Service Mesh (OSSM) offering. These operators then become available to OpenShift customers as Red Hat-provided operators. The publishing of the Kubernetes Community ("kiali-upstream") and OpenShift Community ("kiali-community") Operator metadata is performed manually after a release of Kiali has been published and the Quay.io containers have been verified. Here are the steps necessary. @@ -78,19 +83,19 @@ NOTE: In order for the PRs that you will create to be automatically processed, y git fetch origin git checkout -b v1.70 origin/v1.70 ``` -. Change to the link:https://github.com/kiali/kiali-operator/tree/v1.69.0/manifests[manifests] directory: +. Change to the link:https://github.com/kiali/kiali-operator/tree/master/manifests[manifests] directory: + ``` cd ./manifests ``` -. Run the link:https://github.com/kiali/kiali-operator/blob/v1.69.0/manifests/prepare-community-prs.sh[prepare-community-prs.sh] script. +. Run the link:https://github.com/kiali/kiali-operator/blob/master/manifests/prepare-community-prs.sh[prepare-community-prs.sh] script. + ``` ./prepare-community-prs.sh \ --gitrepo-operatorhub \ --gitrepo-redhat ``` -. Read the link:https://github.com/kiali/kiali-operator/blob/v1.69.0/manifests/prepare-community-prs.sh#L103-L106[output of the script] and follow its directions. Basically, you want to push a PR to those two github repos for the Kubernetes Community Operators and OpenShift Community Operators +. Read the link:https://github.com/kiali/kiali-operator/blob/v1.75.0/manifests/prepare-community-prs.sh#L103-L106[output of the script] and follow its directions. Basically, you want to push a PR to those two github repos for the Kubernetes Community Operators and OpenShift Community Operators + ``` New Kiali metadata has been added to new branches in the community git repo.