Add in serviceability, release doc & re-arrange README and doc md fil…

…es (#282) * Add in serviceability documentation Signed-off-by: Maysun J Faisal <[email protected]> * Apply serviceability feedback, arrange readme and md files Signed-off-by: Maysun J Faisal <[email protected]> * Update link on serviceability doc Signed-off-by: Maysun J Faisal <[email protected]> * Add in Release documentation Signed-off-by: Maysun J Faisal <[email protected]> * Address PR Feedback for MD files Signed-off-by: Maysun J Faisal <[email protected]> * Amend Release Notes.. Signed-off-by: Maysun J Faisal <[email protected]> --------- Signed-off-by: Maysun J Faisal <[email protected]>
redhat-appstudio · Oct 17, 2023 · ba47cab · ba47cab
1 parent 0efb196
commit ba47cab
Show file tree

Hide file tree

Showing 12 changed files with 238 additions and 149 deletions.
diff --git a/README.md b/README.md
@@ -2,139 +2,33 @@
 
 [![codecov](https://codecov.io/gh/redhat-appstudio/application-service/branch/main/graph/badge.svg)](https://codecov.io/gh/redhat-appstudio/application-service)
 
+## Overview
 
-A Kubernetes operator to create and manage applications and control the lifecycle of applications.
+A Kubernetes operator to create, manage and control the lifecycle of applications and components.
 
-## 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 Kubernetes CRD definitions for the application-service specific resources - `Application`, `Component` and `ComponentDetectionQuery`.
 
-To build the operator binary run:
+## Documentation
 
-```
-make build
-```
+### ⚡ Project Info
+* [HAS/application-service project information page](https://docs.google.com/document/d/1axzNOhRBSkly3M2Y32Pxr1MBpBif2ljb-ufj0_aEt74/edit?usp=sharing) - document detailing the project
+* [Google Drive](https://drive.google.com/drive/u/0/folders/1pqESr0oc2ldtfj9RDx65vD_KdkgY_G9h) - information for people new to the project
 
-To test the code:
+### 🔥 Developers
 
-```
-make test
-```
+* [Build, Test and Deploy](./docs/build-test-and-deploy.md) - build, test and deploy the application-service
+* [Serviceability](./docs/serviceability.md) - serviceability information like accessing and understanding logs, debugging, common problems and FAQs
 
-**Note:** In order for the controller tests to run, follow the instructions for [installing the Pact tools](#installing-pact-tools)
+### ⭐ Other Info
 
-To build the docker image of the operator one can run:
+* [Gitops-generation](./docs/gitops-generation.md) - information on the GitOps resource generation from application-service
+* [Pact tests](./docs/pact-tests.md) - contract tests using a Pact framework (part of the unit tests)
+* [OpenShift CI job artifacts](https://docs.ci.openshift.org/docs/how-tos/artifacts/) - Prow job executed by the CI system generates an artifacts directory, this document describes the contents of this directory and how they can be used to investigate the job steps
 
-```
-make docker-build
-```
+## Release
 
-This will make a docker image called `controller:latest` which might or might not be what you want. To override the name of the image build, specify it in the `IMG` environment variable, e.g.:
-
-```
-IMG=quay.io/user/hasoperator:next make docker-build
-```
-
-To push the image to an image repository one can use:
-
-```
-make docker-push
-```
-
-The image being pushed can again be modified using the environment variable:
-```
-IMG=quay.io/user/hasoperator:next make docker-push
-```
-
-## Installing Pact Tools
-
-The Pact tests in the controller package require pact tooling to be installed and on your path. Follow these instructions to do so:
-
-1. Change directory to an appropriate folder (e.g. `/usr/local`)
-2. Run `curl -fsSL https://raw.githubusercontent.com/pact-foundation/pact-ruby-standalone/master/install.sh | bash`
-3. Add the pact tools' bin folder (e.g. `/usr/local/pact/bin`) to your path to your shell PATH. Ensure all binary files within the `bin/` folder has executable permissions
-4. Run `go install github.com/pact-foundation/pact-go@v1` to install the `pact-go` tool
-5. Run `pact-go install` to validate that all of the necessary Pact tools are installed
-
-## Deploying the Operator
-
-The following section outlines the steps to deploy HAS on a physical Kubernetes cluster.
-
-### Setting up the AppStudio Build Service environment
-
-* Install `OpenShift GitOps` from the in-cluster Operator Marketplace.
-* `oc -n openshift-gitops apply -f https://raw.githubusercontent.com/redhat-appstudio/infra-deployments/main/argo-cd-apps/base/build.yaml`
-
-As a user, upon creation of Component, Tekton resources would be created by the controller.
-
-To use auto generated image repository for the Component's image add `image.redhat.com/generate: "true"` annotation to the Component.
-
-If you wish to get 'working' PipelineRuns with user provided image repository, create an image pull secret and link it to the `pipeline` Service Account in the Component's namespace (in both `secrets` and `imagePullSecrets` sections).
-See [Kubernetes docs](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#registry-secret-existing-credentials) for more information on how to create `Secrets` containing registry credentials.
-
-
-
-### Creating a GitHub Secret for HAS
-
-Before deploying the operator, you must ensure that a secret, `has-github-token`, exists in the namespace where HAS will be deployed. This secret must contain a key, `tokens`, whose value points to a comma separated list, without spaces, of key-value pairs of token names and tokens, delimited by a colon. 
-
-For example, on OpenShift:
-
-<img width="801" alt="Screenshot 2023-03-22 at 3 53 11 PM" src="https://user-images.githubusercontent.com/6880023/227020767-30b3db08-e191-4ec1-81df-81ae2df55d79.png">
-
-Or via command-line:
-
-```bash
-application-service % kubectl create secret generic has-github-token --from-literal=tokens=token1:ghp_faketoken,token2:ghp_anothertoken,token3:ghp_thirdtoken
-```
-
-Any token that is used here must have the following permissions set:
-- `repo`
-- `delete_repo`
-
-In addition to this, each GitHub token must be associated with an account that has write access to the GitHub organization you plan on using with HAS (see next section).
-
-
-### Using Private Git Repos
-
-HAS requires SPI to be set up in order to work with private git repositories.
-
-See [private-git-repos.md](docs/private-git-repos.md) for information on setting up HAS and SPI for use with private git repositories.
-
-### Deploying HAS
-
-
-Once a secret has been created, simply run the following commands to deploy HAS:
-```
-make install
-make deploy
-```
-
-### Specifying Alternate GitHub org
-
-By default, HAS will use the `redhat-appstudio-appdata` org for the creation of GitOps repositories. If you wish to use your own account, or a different GitHub org, setting `GITHUB_ORG=<org>` before deploying will ensure that an alternate location is used.
-
-For example:
-
-`GITHUB_ORG=fake-organization make deploy` would deploy HAS configured to use github.com/fake-organization.
-
-### Specifying Alternate Devfile Registry URL
-
-By default, the production devfile registry URL will be used for `ComponentDetectionQuery`. If you wish to use a different devfile registry, setting `DEVFILE_REGISTRY_URL=<devfile registry url>`  before deploying will ensure that an alternate devfile registry is used.
-
-For example:
-
-`DEVFILE_REGISTRY_URL=https://myregistry make deploy` would deploy HAS configured to use https://myregistry.
-
-### Disabling Webhooks for Local Dev
-
-Webhooks require self-signed certificates to validate the resources. To disable webhooks during local dev and testing, export `ENABLE_WEBHOOKS=false`
-
-### Useful links:
-* [HAS Project information page](https://docs.google.com/document/d/1axzNOhRBSkly3M2Y32Pxr1MBpBif2ljb-ufj0_aEt74/edit?usp=sharing)
-* Every Prow job executed by the CI system generates an artifacts directory containing information about that execution and its results. This [document](https://docs.ci.openshift.org/docs/how-tos/artifacts/) describes the contents of this directory and how they can be used to investigate the steps by the job.
-* For more information on the GitOps resource generation, please refer to the [gitops-generation](./docs/gitops-generation.md) documentation
-* Contract testing using a Pact framework is part of unit tests. Follow [this documentation](pactTests.md) to learn more.
+For more information on the application-service release policy, please read the release [guideline](./docs/release.md).
 
 ## Contributions
 
-Please see our [CONTRIBUTING](./docs/CONTRIBUTING.md) for more information.
+If you would like to contribute to application-service, please be so kind to read our [CONTRIBUTING](./docs/CONTRIBUTING.md) guide for more information.
diff --git a/config/samples/binding/binding.yaml b/config/samples/binding/binding.yaml
@@ -1,4 +1,4 @@
-# API type definition is in github.com/redhat-appstudio/managed-gitops
+# API type definition is in https://github.com/redhat-appstudio/application-api/tree/main/api/v1alpha1
 apiVersion: appstudio.redhat.com/v1alpha1
 kind: SnapshotEnvironmentBinding
 metadata:

diff --git a/config/samples/environment/environment.yaml b/config/samples/environment/environment.yaml
@@ -1,4 +1,4 @@
-# API type definition is in github.com/redhat-appstudio/managed-gitops
+# API type definition is in https://github.com/redhat-appstudio/application-api/tree/main/api/v1alpha1
 apiVersion: appstudio.redhat.com/v1alpha1
 kind: Environment
 metadata:

diff --git a/config/samples/snapshot/snapshot.yaml b/config/samples/snapshot/snapshot.yaml
@@ -1,4 +1,4 @@
-# API type definition is in github.com/redhat-appstudio/managed-gitops
+# API type definition is in https://github.com/redhat-appstudio/application-api/tree/main/api/v1alpha1
 apiVersion: appstudio.redhat.com/v1alpha1
 kind: Snapshot
 metadata:

diff --git a/docs/build-test-and-deploy.md b/docs/build-test-and-deploy.md
@@ -0,0 +1,124 @@
+# Build, Test and Deploy
+
+## Build
+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".
+
+To build the operator binary run:
+
+```
+make build
+```
+
+To build the docker image of the operator one can run:
+
+```
+make docker-build
+```
+
+This will make a docker image called `controller:latest` which might or might not be what you want. To override the name of the image build, specify it in the `IMG` environment variable, e.g.:
+
+```
+IMG=quay.io/user/hasoperator:next make docker-build
+```
+
+To push the image to an image repository one can use:
+
+```
+make docker-push
+```
+
+The image being pushed can again be modified using the environment variable:
+```
+IMG=quay.io/user/hasoperator:next make docker-push
+```
+
+## Test
+
+To test the code:
+
+```
+make test
+```
+
+**Note:** In order for the controller tests to run, follow the instructions for [installing the Pact tools](./installing-pact-tools.md)
+
+## Deploy
+
+The following section outlines the steps to deploy application-service on a physical Kubernetes cluster.
+
+### Deploying on a Local Cluster
+
+#### Creating a GitHub Secret for application-service
+
+Before deploying the operator, you must ensure that a secret `has-github-token`, exists in the namespace where application-service will be deployed. This secret must contain a key `tokens`, whose value points to a comma separated list without spaces of key-value pairs of token names and tokens, delimited by a colon. 
+
+For example, on OpenShift:
+
+<img width="801" alt="Screenshot 2023-03-22 at 3 53 11 PM" src="https://user-images.githubusercontent.com/6880023/227020767-30b3db08-e191-4ec1-81df-81ae2df55d79.png">
+
+Or via command-line:
+
+```bash
+application-service % kubectl create secret generic has-github-token --from-literal=tokens=token1:ghp_faketoken,token2:ghp_anothertoken,token3:ghp_thirdtoken
+```
+
+Any token that is used here must have the following permissions set:
+- `repo`
+- `delete_repo`
+
+In addition to this, each GitHub token must be associated with an account that has write access to the GitHub organization you plan on using with application-service.
+
+#### Using Private Git Repos
+
+The application-service component requires SPI to be set up in order to work with private git repositories.
+
+Please refer to the [instructions](./private-git-repos.md) for information on setting up application-service and SPI for use with private git repositories.
+
+#### Deploy application-service
+
+
+Once a secret has been created, simply run the following commands to deploy application-service:
+```
+make install
+make deploy
+```
+
+The application-service deployment can be further configured. Please refer to the sections below for your needs.
+
+#### Specifying Alternate GitHub org
+
+By default, application-service will use the `redhat-appstudio-appdata` org for the creation of GitOps repositories. If you wish to use your own account, or a different GitHub org, setting `GITHUB_ORG=<org>` before deploying will ensure that an alternate location is used.
+
+For example:
+
+`GITHUB_ORG=fake-organization make deploy` would deploy application-service configured to use github.com/fake-organization.
+
+#### Specifying Alternate Devfile Registry URL
+
+By default, the production devfile registry URL will be used for `ComponentDetectionQuery`. If you wish to use a different devfile registry, setting `DEVFILE_REGISTRY_URL=<devfile registry url>`  before deploying will ensure that an alternate devfile registry is used.
+
+For example:
+
+`DEVFILE_REGISTRY_URL=https://myregistry make deploy` would deploy application-service configured to use https://myregistry.
+
+### Deploying Locally
+
+#### Disabling Webhooks for Local Development
+
+Webhooks require self-signed certificates to validate the Kubernetes resources. To disable webhooks during local development and testing, export `ENABLE_WEBHOOKS=false`
+
+#### Setting the GitHub Token Environment variable
+
+Either of the Environment variable `GITHUB_AUTH_TOKEN` or `GITHUB_TOKEN_LIST` needs to be set.
+
+The `GITHUB_AUTH_TOKEN` variable is the legacy format and requires one token, example `GITHUB_AUTH_TOKEN=ghp_faketoken`. The `GITHUB_TOKEN_LIST` can take a list of tokens, example `GITHUB_TOKEN_LIST=token1:ghp_faketoken,token2:ghp_anothertoken`.
+
+#### Executing the application-service binary
+
+The application-service controller manager can be run locally on your development environment (example, laptop). For example, to build and run the executable manager:
+
+```
+make install
+make build
+./bin/manager
+```
diff --git a/docs/installing-pact-tools.md b/docs/installing-pact-tools.md
@@ -0,0 +1,9 @@
+# Installing Pact Tools
+
+The Pact tests in the controller package require pact tooling to be installed and on your path. Follow these instructions to do so:
+
+1. Change directory to an appropriate folder (e.g. `/usr/local`)
+2. Run `curl -fsSL https://raw.githubusercontent.com/pact-foundation/pact-ruby-standalone/master/install.sh | bash`
+3. Add the pact tools' bin folder (e.g. `/usr/local/pact/bin`) to your path to your shell PATH. Ensure all binary files within the `bin/` folder has executable permissions
+4. Run `go install github.com/pact-foundation/pact-go@v1` to install the `pact-go` tool
+5. Run `pact-go install` to validate that all of the necessary Pact tools are installed
diff --git a/pactTests.md → docs/pact-tests.md b/pactTests.md → docs/pact-tests.md
diff --git a/docs/private-git-repos.md b/docs/private-git-repos.md
@@ -1,8 +1,11 @@
 # Using Private Git Repositories with HAS
 
+Please follow the following instructions to install SPI and use with application-service.
+
+Note: SPI _cannot_ be used on a Red Hat OpenShift Local (formerly, CRC) cluster.
 ## Configuring SPI
 
-In order to use HAS resources (e.g. `Applications`, `Components`, `ComponentDetectionQuery`) with private git repositories, SPI must be installed on the same cluster as HAS (TODO review HAS install instructions):
+In order to use HAS resources (e.g. `Application`, `Component`, `ComponentDetectionQuery`) with private git repositories, SPI must be installed on the same cluster as HAS (TODO review HAS install instructions):
 
 1) Clone the [SPI operator repo](https://github.com/redhat-appstudio/service-provider-integration-operator) and run the [make command](https://github.com/redhat-appstudio/service-provider-integration-operator/blob/main/docs/DEVELOP.md#running-in-cluster) corresponding to your target cluster type e.g. `make deploy_openshift`
 

diff --git a/docs/release.md b/docs/release.md
@@ -0,0 +1,7 @@
+# Release
+
+The application-service repository does not do GitHub releases at the moment. Consumers of the application-service Go module are expected to update to the latest commit on a frequent basis. 
+
+Any depreceation or breaking changes are documented as part of the code change in the PR or the function description.
+
+Since application-service is part of the AppStudio project, code commits to the application-service repository are automatically added to the [infra-deployments](https://github.com/redhat-appstudio/infra-deployments/tree/main/components/has) repository.