STONEBLD-1455: Populate image-controller.md (#115)

* STONEBLD-1455: Populate image-controller.md Signed-off-by: Chenxiong Qi <[email protected]> * Update according to comments Signed-off-by: Chenxiong Qi <[email protected]> * Update Signed-off-by: Chenxiong Qi <[email protected]> * Rewrite according to comment Signed-off-by: Chenxiong Qi <[email protected]> * Update suggested updates Signed-off-by: Chenxiong Qi <[email protected]> --------- Signed-off-by: Chenxiong Qi <[email protected]>
konflux-ci · Jul 14, 2023 · 17520d8 · 17520d8
1 parent c901db3
commit 17520d8
Showing 1 changed file with 34 additions and 0 deletions.
diff --git a/book/image-controller.md b/book/image-controller.md
@@ -1,2 +1,36 @@
 # Image Controller
 
+# Overview
+Image controller sets up and manages container image repositories for an application's components. This enables greater component isolation within AppStudio where each component has its own image repository and secret for pushing images built via AppStudio.
+
+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/book/ref/application-environment-api.html#component):
+
+- **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.
+
+- **Modify visibility**: Image controller is able to switch an image repository's visibility between public and private.
+
+- **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 AppStudio services, but a remote image registry. AppStudio 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
+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.
+
+  Here is an example that requests a private image repository:
+
+  ```yaml
+  image.redhat.com/generate: '{"visibility": "private"}'
+  ```
+
+- `image.redhat.com/image`: image controller provides information of prepared resources to external services via this annotation, which includes the image repository URL, the visibility of that repository, and a secret name pointing to the created Kubernetes Secret.
+
+  If something went wrong during the requested operation, this annotation will include a field `Message` with a corresponding error message.
+
+  Here is an example that shows a public image repository is ready on Quay.io and a Secret named `secret-name` contains a robot account token and is available for image push.
+
+  ```yaml
+  image.redhat.com/image: "{\"image\":\"quay.io/redhat-user-workloads/image-controller-system/city-transit/billing\",\"visibility\":\"public\",\"secret\":\"secret-name\"}"
+  ```