= 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`.
Reconcile loop can be adjusted in `watches.yaml` file.

----
# 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.


== Contributors
Simple guide to troubleshooting in codeready containers.

* Make the change
* Tag and create new image and push to registry
+
Open Makefile and bump up the version
`make`
`podman push quay.io/fedora/fas2discourse-operator:<VERSION>`
+
In case you don't have the permissions to push to the repositories in the fedora namespace,
push to your own namespace in quay.io and pull the image into crc from there.
+
* Start crc and login
+
`crc start`
`oc login -u kubeadmin https://api.crc.testing:6443`
+
* Deploy controller to the k8s cluster
`make deploy`
+
* Remove the deployment and deploy again
+
`oc get deployments`
`oc delete <deployment NAME>`
`make deploy`
+
* Check if in correct project
+
`oc project fas2discourse-operator`
+
* Apply Fas2DiscourseConfig custom resource
+
`oc apply -f config/samples/_v1alpha1_fas2discourseconfig.yaml`
+
* Check t/he logs:
+
`oc get pods`
`oc logs -f <pod NAME>`


== Local testing or developing
The guide above will work only when running in the cluster.
For local testing, it is necessary to create a secret.
For that you have to create a [Discourse API key]
(https://meta.discourse.org/t/create-and-configure-an-api-key/230124)
(probably in staging Discourse instance)
and a [keytab file]
(https://pagure.io/fedora-infra/howtos/blob/main/f/create_keytab.md)
for kinit.

=== Create a secret
With command `oc create secret generic`. Let's name it `fas2discourse-operator-discourse-apikey-secret`.

`FAS2DISCOURSE_API_KEY=<insert your Discourse API key>`
`DISCOURSE_HOST=https://askfedora.staged-by-discourse.com/`
`KEYTAB_NAME=<insert name on the keytab file>`
`KEYTAB_PATH=<insert path to the keytab file>`

For example:
`oc create secret generic fas2discourse-operator-discourse-apikey-secret -n fas2discourse-operator --from-literal fas2discourse-discourse-apikey=$FAS2DISCOURSE_API_KEY --from-literal discourse-host="$DISCOURSE_HOST"`

`oc create secret generic fas2discourse-operator-keytab-secret --from-file=$KEYTAB_NAME="$KEYTAB_PATH"`

To confirm the secret was created, run:
`oc get secrets`

Continue with applying the Fas2DiscourseConfig custom resource.