Update image-controller doc (#203)

This update includes brief information about functionalities with
ImageRepository.

ImageController API is added as well.

Signed-off-by: Chenxiong Qi <[email protected]>

.github/workflows/generate-api-docs.yml

@@ -80,6 +80,12 @@ jobs:
           path: crd-temp/internal-services
           repository: redhat-appstudio/internal-services
 
+      - name: Checkout Image Controller API
+        uses: actions/checkout@v3
+        with:
+          path: crd-temp/image-controller
+          repository: konflux-ci/image-controller
+
       - name: Install crd-ref-docs
         uses: supplypike/setup-bin@v1
         with:
@@ -117,6 +123,9 @@ jobs:
       - name: Generate Internal Services API docs
         run: crd-ref-docs --log-level=ERROR --config=ref/config.yaml --output-path=ref/internal-services.md --renderer=markdown --source-path=crd-temp/internal-services/api/v1alpha1/
 
+      - name: Generate Image Controller API docs
+        run: crd-ref-docs --log-level=ERROR --config=ref/config.yaml --output-path=ref/image-controller.md --renderer=markdown --source-path=crd-temp/image-controller/api/v1alpha1/
+
       - name: Upload generated docs
         uses: actions/upload-artifact@v3
         with:

architecture/image-controller.md

@@ -3,7 +3,7 @@
 # Overview
 Image controller sets up and manages container image repositories for an application's components. This enables greater component isolation within Konflux where each component has its own image repository and secret for pushing images built via Konflux.
 
-The image controller can perform three actions on image repositories by watching for either specific annotation changes or deletion events of a [Component CR](https://redhat-appstudio.github.io/architecture/ref/application-environment-api.html#component):
+The image controller can perform three actions on image repositories by working together with [Component](https://konflux-ci.dev/architecture/ref/application-environment-api.html#component)-specific ImageRepository custom resource.
 
 - **Setup image repository**: Image controller creates an image repository for the Component CR in a remote image registry as well as a robot account which is specific to that repository for image push. A Kubernetes Secret object is also created with that robot account token in order to make it available for build PipelineRun.
 
@@ -12,9 +12,46 @@ The image controller can perform three actions on image repositories by watching
 - **Cleanup**: When a Component CR is requested to be deleted, image controller will remove component's image repository and robot account from the remote registry. The Kubernetes Secret will be removed along with the Component CR eventually due to the ownership established between them.
 
 # Dependencies
+
 Image controller does not depend on other Konflux services, but a remote image registry. Konflux services are able to use the resources prepared by image controller, e.g. Build Service makes the Secret available to every build PipelineRun of a component for image push.
 
 # Interface
+
+## ImageRepository CR
+
+The ImageRepository CR is the interface to interact with image controller to create and manage image repositories in a registry.
+
+To create an image repository for a Component, apply this YAML code:
+
+```yaml
+apiVersion: appstudio.redhat.com/v1alpha1
+kind: ImageRepository
+metadata:
+    name: imagerepository-for-component-sample
+    namespace: test-ns
+    labels:
+        appstudio.redhat.com/component: my-component
+        appstudio.redhat.com/application: my-app
+```
+
+By default, a public image repository is created, and two robot accounts and corresponding Kubernetes Secret objects are created for pull and push individually. All these artifacts information are recorded in the `.status` field.
+
+To change the image repository visibility, set `public` or `private` to `.spec.image.visibility`.
+
+To regenerate pull and push token, set `true` to `.spec.credentials.regenerate-token`
+
+To verify if secrets are linked to the ServiceAccount correctly and have a fix if necessary, set `true` to `.spec.credentials.verify-linking`.
+
+`.status` field includes various information about an image repository:
+
+- `.status.credentials` includes pull and push Secrets names.
+- `.status.image` includes the repository URL and current visiblity.
+- `.status.state` shows whether image controller responded last operation request successfully or not.
+
+For more detailed information of the functionalities, please refer to konflux-ci/image-controller [project document](https://github.com/konflux-ci/image-controller/?tab=readme-ov-file#readme).
+
+## Legacy interaction via Component annotations
+
 Image controller uses annotations to interact with external services.
 
 - `image.redhat.com/generate`: An external service is able to request an image repository for an application component by setting this annotation on the corresponding Component CR. For initial request, the value should include field `visibility` to indicate the visibility of the created image repository in the remote registry, and it can be set again subsequently to change the visibility on demand. Note that, this annotation will be removed once requested operation finishes.