From 244bf310ae80c4c243a5935b19ff720d46f8d9fb Mon Sep 17 00:00:00 2001 From: David Kirwan Date: Tue, 25 Apr 2023 13:57:18 +0100 Subject: [PATCH] fas2discourse: SOPs fas2discourse: Update index to link to the fas2discourse operator SOPs fas2discourse: Add SOP for interacting with the operator fas2discourse: add SOP for debugging issues with operator Signed-off-by: David Kirwan --- .../pages/sop_fas2discourse_operator.adoc | 13 +++++ .../sop_fas2discourse_operator_build.adoc | 23 +++++++++ .../sop_fas2discourse_operator_debugging.adoc | 37 ++++++++++++++ ...p_fas2discourse_operator_installation.adoc | 34 +++++++++++++ ...op_fas2discourse_operator_interacting.adoc | 48 +++++++++++++++++++ .../sop_fas2discourse_operator_testing.adoc | 14 ++++++ modules/ocp4/pages/sops.adoc | 1 + 7 files changed, 170 insertions(+) create mode 100644 modules/ocp4/pages/sop_fas2discourse_operator.adoc create mode 100644 modules/ocp4/pages/sop_fas2discourse_operator_build.adoc create mode 100644 modules/ocp4/pages/sop_fas2discourse_operator_debugging.adoc create mode 100644 modules/ocp4/pages/sop_fas2discourse_operator_installation.adoc create mode 100644 modules/ocp4/pages/sop_fas2discourse_operator_interacting.adoc create mode 100644 modules/ocp4/pages/sop_fas2discourse_operator_testing.adoc diff --git a/modules/ocp4/pages/sop_fas2discourse_operator.adoc b/modules/ocp4/pages/sop_fas2discourse_operator.adoc new file mode 100644 index 0000000..371bde3 --- /dev/null +++ b/modules/ocp4/pages/sop_fas2discourse_operator.adoc @@ -0,0 +1,13 @@ += fas2discourse Operator +The following SOPs are related to the administration of the fas2discourse operator. + +== Resources +- https://pagure.io/cpe/fas2discourse/[Code] +- https://quay.io/repository/fedora/fas2discourse-operator[Image] +- https://pagure.io/fedora-infrastructure/issue/10952[Initial ticket] +- xref:sop_fas2discourse_operator_installation.adoc[Install the fas2discourse operator] +- xref:sop_fas2idscourse_operator_testing.adoc[Testing the fas2discourse operator] +- xref:sop_fas2discourse_operator_build.adoc[Building/releasing the fas2discourse operator] +- xref:sop_fas2discourse_operator_interacting.adoc[Interacting with the the fas2discourse operator] +- xref:sop_fas2discourse_operator_debugging.adoc[Debugging issues with the the fas2discourse operator] + diff --git a/modules/ocp4/pages/sop_fas2discourse_operator_build.adoc b/modules/ocp4/pages/sop_fas2discourse_operator_build.adoc new file mode 100644 index 0000000..c75ca16 --- /dev/null +++ b/modules/ocp4/pages/sop_fas2discourse_operator_build.adoc @@ -0,0 +1,23 @@ += Build/release the fas2discourse Operator + +== Resources +- [1] Code: https://pagure.io/cpe/fas2discourse +- [2] Quay: https://quay.io/repository/fedora/fas2discourse-operator + +== Installation +To build the operator and tag it with version `0.0.63` as an example: + +- First ensure that you are logged into quay.io and have access to the repository at [2]. +- Check out the code at [1]. +- Make the change to the version of the operator being built by editing the `Makefile` and change the variable at the top `VERSION ?= 0.0.63` + +---- +make build +---- + +Push the operator to the quay.io catalog then with the following: + +---- +podman push quay.io/repository/fedora/fas2discourse-operator:0.0.63 +---- + diff --git a/modules/ocp4/pages/sop_fas2discourse_operator_debugging.adoc b/modules/ocp4/pages/sop_fas2discourse_operator_debugging.adoc new file mode 100644 index 0000000..9245d84 --- /dev/null +++ b/modules/ocp4/pages/sop_fas2discourse_operator_debugging.adoc @@ -0,0 +1,37 @@ += Debugging issues with the fas2discourse Operator + +== Resources +- [1] Code: https://pagure.io/cpe/fas2discourse/ +- [2] Playbook: https://pagure.io/fedora-infra/ansible/blob/main/f/playbooks/manual/fas2discourse.yml +- [3] Role: https://pagure.io/fedora-infra/ansible/blob/main/f/roles/fas2discourse + +== Workload +The operator runs in the namespace: `fas2discourse-operator` on both the staging and production openshift clusters. + +There is a single pod running. First port of call should be to examine the logs of this pod. + +By default, the verbocity of logs are set low. To increase them to debug level add the following annotation to the `Fas2DiscourseConfig` object in the `fas2discourse-operator` namespace: + +---- +apiVersion: fas2discourse.apps.fedoraproject.org/v1alpha1 +kind: Fas2discourseConfig +metadata: + annotations: + ansible.sdk.operatorframework.io/verbosity: '5' +---- + +This will enable full output from logging, which may aid in debugging. + +The following task list is contained inside the operator. This list is repeated in the reconcile loop which is currently set to run every `20 minutes`. + +---- +# tasks file for Fas2discourseConfig + +- include_tasks: retrieve_openshift_secrets.yml # Retrieves the secrets such as discourse api key etc and populates variable which feeds into the later tasks +- include_tasks: kerberos_auth.yml # Authenticate to fasjson via keytab +- include_tasks: retrieve_discourse_groups.yml # Contact Discourse API, retrieve the list of groups, and retrieve the list of users in each group +- include_tasks: retrieve_ipa_groups.yml # Contact fasjson, using the Discourse group list, retrieve the membership of each group in IPA +- include_tasks: sync_group_membership.yml # Using set functions, discover who is not in Discourse group but is in IPA group: add them. Who is in Discourse group but not in IPA group: remove them. +---- + +The results of each call in the workflow is outputted in the log. If any task fails the entire loop stops and retries. diff --git a/modules/ocp4/pages/sop_fas2discourse_operator_installation.adoc b/modules/ocp4/pages/sop_fas2discourse_operator_installation.adoc new file mode 100644 index 0000000..93a3820 --- /dev/null +++ b/modules/ocp4/pages/sop_fas2discourse_operator_installation.adoc @@ -0,0 +1,34 @@ += Installation of the fas2discourse Operator + +== Resources +- [1] Code: https://pagure.io/cpe/fas2discourse/ +- [2] Playbook: https://pagure.io/fedora-infra/ansible/blob/main/f/playbooks/manual/fas2discourse.yml +- [3] Role: https://pagure.io/fedora-infra/ansible/blob/main/f/roles/fas2discourse + +== Installation on Fedora Infra + +There is a playbook [2] and role [3]. To install the operator in staging and production, run the playbook [2]. Users in the `sysadmin-openshift` group have permissions to run this playbook. + + +== Installation on a CRC cluster +There is a Makefile bundled with the code [1] of this operator. + +To install the operator the basic steps are followed: + +- From a terminal, be logged into the cluster with cluster-admin privileges. +- Run `make deploy` + +To activate the operator we need to create a `fas2discourseconfig` custom resource. An example of one exists in `config/samples/_v1alpha1_fas2discourseconfig.yaml` + +Create it with the following: + +---- +oc apply -f config/samples/_v1alpha1_fas2discourseconfig.yaml +---- + + + + +== Configuration + +- No other configuration is required for this operator. diff --git a/modules/ocp4/pages/sop_fas2discourse_operator_interacting.adoc b/modules/ocp4/pages/sop_fas2discourse_operator_interacting.adoc new file mode 100644 index 0000000..c30d4ce --- /dev/null +++ b/modules/ocp4/pages/sop_fas2discourse_operator_interacting.adoc @@ -0,0 +1,48 @@ += Interacting with the fas2discourse Operator + +== Resources +- [1] Code: https://pagure.io/cpe/fas2discourse/ +- [2] Playbook: https://pagure.io/fedora-infra/ansible/blob/main/f/playbooks/manual/fas2discourse.yml +- [3] Role: https://pagure.io/fedora-infra/ansible/blob/main/f/roles/fas2discourse + +== Overview of the fas2discourse Operator +The role of this operator is to synchronise group membership between IPA and Discourse. It does not synchronise all groups and all members, but only groups which exist in Discourse. + +To start the synchronisation of a group, you must first request that a Discourse admin create it in Discourse. The fas2discourse operator will then begin to synchronise users to that group based on their membership in this group in IPA. + +== Configuration of the fas2discourse operator +All configuration for the fas2idscourse operator is contained in the Fedora Infra private ansible repo. + +Default vars contains the list which are used in the playbook which deploys the operator: + +---- +fas2discourse_hostname: "fas2discourse.hostna.me" +fas2discourse_namespace: "fas2discourse-operator" +fas2discourse_project_description: "The fas2discourse-operator is responsible for synchronising group membership for users between Discourse and IPA." +fas2discourse_keytab_file: "OVERRIDEME WITH A FILE LOOKUP" +fas2discourse_discourse_apikey: "OVERRIDEME WITH A DISCOURSE APIKEY" +---- + +The Operator has the following vars which it uses internally. These vars are populated by querying secrets in Openshift: + +---- +# defaults file for Fas2discourseConfig +fas2discourse_keytab_path: "/etc/fas2discourse" +fas2discourse_principal: "fas2discourse/fas2discourse.hostna.me@FEDORAPROJECT.ORG" +f2d_namespace: "fas2discourse-operator" +f2d_secret: "fas2discourse-operator-k8s-secret" +f2d_discourse_secret: "fas2discourse-operator-discourse-apikey-secret" +fasjson_host: "OVERRIDEME" +discourse_host: "OVERRIDEME" +discourse_api: "OVERRIDEME" +discourse_ignored_groups: + - "admins" + - "staff" + - "moderators" + - "trust_level_0" + - "trust_level_1" + - "trust_level_2" + - "trust_level_3" + - "trust_level_4" +---- + diff --git a/modules/ocp4/pages/sop_fas2discourse_operator_testing.adoc b/modules/ocp4/pages/sop_fas2discourse_operator_testing.adoc new file mode 100644 index 0000000..f977be2 --- /dev/null +++ b/modules/ocp4/pages/sop_fas2discourse_operator_testing.adoc @@ -0,0 +1,14 @@ += Test the fas2discourse Operator + +== Resources +- [1] Code: https://pagure.io/cpe/fas2discourse/ +- [2] Molecule: https://molecule.readthedocs.io/en/latest/ + +== Installation +There is a molecule directory bundled with the code [1] of this operator. They currently are designed to only run against a code ready container cluster. + +To run the operator molecule tests: + +- Ensure that the molecule utility is installed `dnf install python3-molecule` +- From a terminal, be logged into the crc cluster with cluster-admin privileges. +- Run `molecule test` diff --git a/modules/ocp4/pages/sops.adoc b/modules/ocp4/pages/sops.adoc index 96f04d7..d1cd49a 100644 --- a/modules/ocp4/pages/sops.adoc +++ b/modules/ocp4/pages/sops.adoc @@ -21,3 +21,4 @@ - xref:sop_velero.adoc[SOP Velero] - xref:sop_aws_efs_operator.adoc[SOP AWS EFS Operator] - xref:sop_communishift.adoc[SOP Communishift Cluster Administration] +- xref:sop_fas2discourse_operator.adoc[SOP fas2discourse operator]