doc: add init task doc

docs/src/main/asciidoc/init-tasks.adoc

@@ -0,0 +1,83 @@
+////
+This guide is maintained in the main Quarkus repository
+and pull requests should be submitted there:
+https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
+////
+= Initialization tasks
+:categories: initialization
+:summary: This guide explains how to configure initialization tasks
+
+There are often initialization tasks performed by Quarkus extensions that are meant to be run once.
+For example Flyway or Liquibase initialization fall into that category. But what happens when the scaling
+needs of an application requires more instances of the application to run? Or what happens when the application
+restarts ?
+
+A common environment where both of these cases are pretty common is Kubernetes. To address these challenges,
+Quarkus allows externalization of such tasks as Kubernetes Jobs and uses init containers to ensure that an 
+application instance only starts once the initialization jobs have finished. With this approach even if an 
+application has multiple replicas, the initialization logic will only run once.
+
+This approach is reflected in the manifests generated by xref:kubernetes.adoc[Kubernetes extension].
+
+== Disabling the feature
+
+The feature can be explictily disabled per task (enabled by default).
+The default behavior can change setting the following property to `false`:
+
+[source,properties]
+----
+quarkus.openshift.init-task-defaults.enabled=false
+----
+
+In the case where we need to disable a particular task, we can use the following property:
+
+[source,properties]
+----
+quarkus.openshift.init-tasks."<task name>".enabled=false
+----
+
+The task name is the name of the Kubernetes Job resource that follows the convention `${quarkus.appliction.name}-${extension}-init`.
+If the convention is hard to remember you can always peek at the generated manifests.
+
+== Controlling the generated Job
+
+The Job container is pretty similar to the application container and the only thing that changes is the configured environment variables.
+More specifically, the following environment variable is added, to tell the Job to exit right after initialization.
+
+[source,properties]
+----
+QUARKUS_INIT_AND_EXIT=true
+----
+
+The image, image pull policy, service account, volumes, mounts and additional environment variables are inherited from the deployment resource.
+Any customization that happens to the original deployment resource (via configuration or extension) will be reflected in the Job too.
+
+== Coordination between Job and deployment
+
+The deploymnet resource should not start until the Job has succesfully completed. The common pattern that is used among Kubernetes users is the
+use of init containers to achieve this. An init container that `wait for` the Job to complete is enough to enforce that requirement.
+
+=== Using a custom wait for image
+
+To change the `wait-for` image which by default is `groundnuty/k8s-wait-for:no-root-v1.7` you can use:
+
+[source,properties]
+----
+quarkus.openshift.init-task-defaults.wait-for-image=my/wait-for-image:1.0
+----
+
+=== Configuring permissions
+
+For an init container to be able to to perform the `wait for job` it needs to be able to perform `get` operations on the `Job` resource.
+This is done automatically and the generated manifests include the required `Role` and `RoleBinding` resources. 
+
+If for any reason additiona permissions are required either by the init container or the `Job`, they can be configured with through the xref:deploying-to-kuberentes.adoc#generating-rbac-resources[Kubernetes RBAC configuration].
+
+**Note**: Both the application, the init container and the `Job` use the same `ServiceAccount` and therefore share the same permissions. 
+
+== Extension providing Initialization Tasks
+
+Currently this feature is used by the following extensions:
+- xref:flyway.adoc[Flyway]
+- xref:liquibase.adoc[Liquibase]
+- xref:liquibase-mongodb.adoc[Liquibase MongoDB]