Add in serviceability, release doc & re-arrange README and doc md files #282

maysunfaisal · 2023-03-14T19:39:25Z

What does this PR do?:

Adds in documentation for serviceability
Rearrange README and doc md files
Adds in release policy

Which issue(s)/story(ies) does this PR fixes:

https://issues.redhat.com/browse/DEVHAS-294

PR acceptance criteria:

Unit/Functional tests
Documentation
Client Impact

How to test changes / Special notes to the reviewer:

Adds in information about logging, debugging, common problems, FAQs. Rearranges md files.

Inspired from the https://github.com/redhat-appstudio/managed-gitops repo

codecov · 2023-03-14T19:45:09Z

Codecov Report

Patch coverage: 83.46% and project coverage change: -0.71% ⚠️

Comparison is base (1afd7ae) 84.61% compared to head (2593b4b) 83.91%.
Report is 94 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #282      +/-   ##
==========================================
- Coverage   84.61%   83.91%   -0.71%     
==========================================
  Files          27       31       +4     
  Lines        3530     4259     +729     
==========================================
+ Hits         2987     3574     +587     
- Misses        402      516     +114     
- Partials      141      169      +28

Files Changed	Coverage Δ
pkg/devfile/errors.go	`100.00% <ø> (ø)`
controllers/component_controller_finalizer.go	`63.46% <41.66%> (-11.54%)`	⬇️
pkg/util/ioutils/ioutils.go	`86.95% <50.00%> (-13.05%)`	⬇️
controllers/component_controller.go	`73.15% <60.56%> (-4.45%)`	⬇️
cdq-analysis/pkg/devfile.go	`68.30% <68.30%> (ø)`
cdq-analysis/pkg/componentdetectionquery.go	`69.28% <69.28%> (ø)`
controllers/componentdetectionquery_controller.go	`74.51% <71.42%> (+3.97%)`	⬆️
pkg/github/token_mock.go	`75.67% <75.67%> (-24.33%)`	⬇️
cdq-analysis/pkg/detect.go	`73.78% <83.92%> (ø)`
pkg/github/token.go	`87.74% <84.95%> (-7.65%)`	⬇️
... and 17 more

... and 2 files with indirect coverage changes

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

kim-tsao · 2023-03-14T20:43:40Z

docs/serviceability.md

@@ -0,0 +1,58 @@
+# Serviceability


Correct me if I'm wrong but I assume the target audience is 1) the HAS developer writing code that needs to emit serviceable logs and 2) the SRE that needs to know where to look for logs and troubleshoot. If this is the case, let's update the doc with this info

What kind of info are we looking for on 1 and 2 in your suggestion..

Just an overview blurb describing the purpose and intent of this doc. When I read this doc without any context, I see it can serve two purposes 1. From a developer perspective for someone who is unfamiliar with instrumenting logs and what is supposed to go into them, the Understanding the Logs topic can be useful. 2) from the troubleshooting perspective for a developer/SRE. Understanding where to look for the logs and what to do with them is also useful.

@kim-tsao I can update this PR now that we have more info on getting access doc

kim-tsao · 2023-03-14T20:51:18Z

docs/serviceability.md

+View the application-service controller logs by tailing the manager container log of the controller manager pod. Example,
+
+```
+oc logs -f application-service-application-service-controller-manager -c manager


Depending on where this cluster is i.e. local cluster, staging or prod, we will need to understand how we can get access in order to run this command but I think the preferred approach for a managed service is to pull the logs from a centralized log store like Cloudwatch or Splunk since the retention period is longer. Since the details are unknown for now, we can clarify and say Deploy on a Local Cluster with another section or sub-section for Deployed on Managed Clusters as TBD

kim-tsao · 2023-03-14T20:54:06Z

docs/serviceability.md

+```
+
+### Understanding the Logs
+Each application-service controller logs their reconcile logic to the manager. The log message format is generally of format 


We should also link to this ADR once it's been merged. It explains the expected log conventions. Maybe add a placeholder to link to the AppStudio log conventions ADR so it serves as a reminder

The ADR has been mentioned in the doc

kim-tsao · 2023-03-14T21:06:18Z

docs/serviceability.md

+
+## Debugging
+
+- Insert break points at the controller functions to debug unit tests


This only explains debugging unit tests which is pretty narrow if there is a real problem. For managed services, we would typically get a copy of the logs, scan it for errors and then search the code repo with the error message snippets to see where the problem may be coming from but we need to be careful since some messages may be concatenated so searching on a unique word may be better.

I put in more info on how to debug from the code.

kim-tsao · 2023-03-14T21:17:48Z

docs/serviceability.md

+- When debugging unit and integration tests, remember that the mock clients used are hosting dummy data and mocking the api call and returns 
+
+## Common Problems
+- A Github Personal Access token is required as the application-service controller requires the token for pushing the resources to the GitOps repository


Are you suggesting users use their own github PAT to create gitops repos under their own user org? if so, link to these instructions https://github.com/redhat-appstudio/application-service#creating-a-github-secret-for-has. We should also follow github's suggestion to use a fine grained token instead of the classic one: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#fine-grained-personal-access-tokens

johnmcollier

Left some comments, but overall liked the changes.

johnmcollier · 2023-09-01T21:01:10Z

README.md


 A Kubernetes operator to create and manage applications and control the lifecycle of applications.

-## Building & Testing
-This operator provides a `Makefile` to run all the usual development tasks. If you simply run `make` without any arguments, you'll get a list of available "targets".
+This repository is closely associated with the [application-api](https://github.com/redhat-appstudio/application-api/) repository, which contains the public APIs.


Nit: public APIs for what?

johnmcollier · 2023-09-01T21:02:38Z

docs/build-service.md

@@ -0,0 +1,11 @@
+# Setting up the AppStudio Build Service environment


This is no longer necessary for HAS

johnmcollier · 2023-09-01T21:03:14Z

docs/build-and-test.md

@@ -0,0 +1,43 @@
+# Build and Test


TBH, I like having build and deploy together in the same file.

johnmcollier · 2023-09-01T21:03:49Z

docs/deploy.md

+
+The following section outlines the steps to deploy application-service on a physical Kubernetes cluster.
+
+## Setting up the AppStudio Build Service environment


See my other comment, I think this can be removed. It hasn’t been needed for HAS since mid last year.

johnmcollier · 2023-09-01T21:05:38Z

docs/serviceability.md

+- When creating a `Component` from the `ComponentDetectionQuery`, remember to replace the generic application name `insert-application-name`, if the information is being used from a `ComponentDetectionQuery` status
+
+## FAQs
+Q. Where can I view the application-service api types?


I would also suggest linking to the book of appstudio.

johnmcollier · 2023-09-01T21:17:37Z

docs/serviceability.md

+  - the log message. For example, `"msg":"Finished reconcile loop for user-tenant/devfile-sample-go-basic-development-binding-hr9nm"`. You may search for the string `Finished reconcile loop for` in the application-service repository to track down the code logic that is emitting the log. Remember to look out for resource name concatenation and/or error wrapping that may not turn up in your code search. It is advised to exclude such strings from the code search for debugging purposes
+
+## Common Problems
+- When deploying HAS locally or on a local cluster, a Github Personal Access Token is required as the application-service controller requires the token for pushing the resources to the GitOps repository. Please refer to the [instructions](../docs/deploy.md#creating-a-github-secret-for-application-service) in the deploy section for more information


I don’t think I saw steps for deploying HAS locally (I.e. outside of a container)?

johnmcollier · 2023-09-01T21:19:04Z

docs/serviceability.md

+
+## Debugging
+
+- Insert break points at the controller functions to debug unit tests


How to setup HAS with debugger (e.g. dlv in vscode) would be good in this section

johnmcollier · 2023-09-01T21:20:15Z

docs/serviceability.md

+oc logs -f application-service-application-service-controller-manager -c manager -n application-service
+```
+
+### Deployed on a Managed Cluster


Perhaps just leave this section out since it’s RHTAP specific

I will probably keep it in for now, because Kim suggested we put it here in her PR review. I think we can iterate over it and move it in the future if we dont want it.

johnmcollier · 2023-09-01T21:21:22Z

docs/serviceability.md

+```
+make install
+make build
+./bin/manager


This feels like it should go in the deploy doc? Plus I believe some environment variables (disabling webhooks and git token) need to be set before running the binary.

then just say here that the logs are available in the terminal window

johnmcollier · 2023-09-01T21:23:19Z

docs/serviceability.md

@@ -0,0 +1,76 @@
+# Serviceability
+
+The serviceability document aims to help local application-service developers and SRE engineers to access and service the application-service component. This document will help you understand how to access and understand the application-service logs, how to debug an application-service problem and provides a quick summary on the various questions that you might have regarding application-service. 


NIT: SRE (Site Reliability Engineer) Engineer? 😛

Signed-off-by: Maysun J Faisal <[email protected]>

maysunfaisal · 2023-10-16T23:38:09Z

@johnmcollier I have addressed your PR review, PTAL! Thanks.

Signed-off-by: Maysun J Faisal <[email protected]>

openshift-ci · 2023-10-17T14:13:34Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: johnmcollier, maysunfaisal

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~OWNERS~~ [johnmcollier,maysunfaisal]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

maysunfaisal requested review from johnmcollier and kim-tsao March 14, 2023 19:39

kim-tsao reviewed Mar 14, 2023

View reviewed changes

maysunfaisal force-pushed the update-serviceability-1 branch from 8386a98 to 655f366 Compare September 1, 2023 20:23

openshift-ci bot added the approved label Sep 1, 2023

maysunfaisal changed the title ~~Add in serviceability documentation~~ Add in serviceability doc & re-arrange README and doc md files Sep 1, 2023

maysunfaisal requested a review from kim-tsao September 1, 2023 20:25

johnmcollier reviewed Sep 1, 2023

View reviewed changes

maysunfaisal changed the title ~~Add in serviceability doc & re-arrange README and doc md files~~ Add in serviceability, release doc & re-arrange README and doc md files Sep 11, 2023

maysunfaisal added 4 commits October 16, 2023 17:15

Add in serviceability documentation

d3846c0

Signed-off-by: Maysun J Faisal <[email protected]>

Apply serviceability feedback, arrange readme and md files

f0e45b5

Signed-off-by: Maysun J Faisal <[email protected]>

Update link on serviceability doc

ce9de86

Signed-off-by: Maysun J Faisal <[email protected]>

Add in Release documentation

f1d3ce9

Signed-off-by: Maysun J Faisal <[email protected]>

maysunfaisal force-pushed the update-serviceability-1 branch from 2593b4b to f1d3ce9 Compare October 16, 2023 21:16

Address PR Feedback for MD files

6f05b91

Signed-off-by: Maysun J Faisal <[email protected]>

maysunfaisal requested a review from johnmcollier October 16, 2023 23:37

Amend Release Notes..

1976ab1

Signed-off-by: Maysun J Faisal <[email protected]>

johnmcollier approved these changes Oct 17, 2023

View reviewed changes

openshift-ci bot assigned johnmcollier Oct 17, 2023

openshift-ci bot added the lgtm label Oct 17, 2023

maysunfaisal merged commit ba47cab into redhat-appstudio:main Oct 17, 2023
9 checks passed

rh-tap-build-team bot mentioned this pull request Oct 17, 2023

application-service update redhat-appstudio/infra-deployments#2566

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add in serviceability, release doc & re-arrange README and doc md files #282

Add in serviceability, release doc & re-arrange README and doc md files #282

maysunfaisal commented Mar 14, 2023 •

edited

Loading

codecov bot commented Mar 14, 2023 •

edited

Loading

kim-tsao Mar 14, 2023 •

edited

Loading

maysunfaisal Mar 14, 2023

kim-tsao Mar 14, 2023

maysunfaisal Jun 5, 2023

maysunfaisal Sep 1, 2023

kim-tsao Mar 14, 2023

kim-tsao Mar 14, 2023

maysunfaisal Sep 1, 2023

kim-tsao Mar 14, 2023

maysunfaisal Sep 1, 2023

kim-tsao Mar 14, 2023

maysunfaisal Sep 1, 2023

johnmcollier left a comment

johnmcollier Sep 1, 2023 •

edited

Loading

johnmcollier Sep 1, 2023

johnmcollier Sep 1, 2023

johnmcollier Sep 1, 2023

johnmcollier Sep 1, 2023

johnmcollier Sep 1, 2023

johnmcollier Sep 1, 2023

johnmcollier Sep 1, 2023

maysunfaisal Oct 16, 2023

johnmcollier Sep 1, 2023

johnmcollier Sep 1, 2023

maysunfaisal commented Oct 16, 2023

openshift-ci bot commented Oct 17, 2023


		## Debugging

		- Insert break points at the controller functions to debug unit tests

		@@ -0,0 +1,11 @@
		# Setting up the AppStudio Build Service environment


		The following section outlines the steps to deploy application-service on a physical Kubernetes cluster.

		## Setting up the AppStudio Build Service environment

		@@ -0,0 +1,76 @@
		# Serviceability

		The serviceability document aims to help local application-service developers and SRE engineers to access and service the application-service component. This document will help you understand how to access and understand the application-service logs, how to debug an application-service problem and provides a quick summary on the various questions that you might have regarding application-service.

Add in serviceability, release doc & re-arrange README and doc md files #282

Add in serviceability, release doc & re-arrange README and doc md files #282

Conversation

maysunfaisal commented Mar 14, 2023 • edited Loading

What does this PR do?:

Which issue(s)/story(ies) does this PR fixes:

PR acceptance criteria:

How to test changes / Special notes to the reviewer:

codecov bot commented Mar 14, 2023 • edited Loading

Codecov Report

kim-tsao Mar 14, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

johnmcollier left a comment

Choose a reason for hiding this comment

johnmcollier Sep 1, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

maysunfaisal commented Oct 16, 2023

openshift-ci bot commented Oct 17, 2023

maysunfaisal commented Mar 14, 2023 •

edited

Loading

codecov bot commented Mar 14, 2023 •

edited

Loading

kim-tsao Mar 14, 2023 •

edited

Loading

johnmcollier Sep 1, 2023 •

edited

Loading