procedures: Add readiness init container docs (#2139)

Add readiness init container docs

Co-authored-by: Anatolii Bazko <abazko@redhat.com>
Co-authored-by: Mickey Maler <mmaler@redhat.com>
Co-authored-by: Max Leonov <mleonov@redhat.com>
Co-authored-by: tstastna <78429689+tstastna@users.noreply.github.com>
Co-authored-by: Fabrice Flore-Thébault <ffloreth@redhat.com>
Co-authored-by: Robert Krátký <rkratky@redhat.com>
Co-authored-by: Nick Boldt <nboldt@redhat.com>
Co-authored-by: che-bot <39771996+che-bot@users.noreply.github.com>
Co-authored-by: Mykhailo Kuznietsov <mkuznets@redhat.com>

modules/administration-guide/nav.adoc

@@ -34,6 +34,14 @@
 
 * xref:migration-from-postgresql-9-to-postgresql-13.adoc[]
 
+* xref:readiness-init-containers.adoc[]
+** xref:enabling-and-disabling-readiness-init-containers-for-the-operator-installer.adoc[]
+*** xref:enabling-readiness-init-containers-for-the-operator-installer.adoc[]
+*** xref:disabling-readiness-init-containers-for-the-operator-installer.adoc[]
+** xref:enabling-and-disabling-readiness-init-containers-for-the-olm-installer.adoc[]
+*** xref:enabling-readiness-init-containers-for-the-olm-installer.adoc[]
+*** xref:disabling-readiness-init-containers-for-the-olm-installer.adoc[]
+
 * xref:caching-images-for-faster-workspace-start.adoc[]
 ** xref:defining-the-list-of-images-to-pull.adoc[]
 ** xref:defining-the-memory-parameters-for-the-image-puller.adoc[]

modules/administration-guide/pages/disabling-readiness-init-containers-for-the-olm-installer.adoc

@@ -0,0 +1,6 @@
+[id="disabling-readiness-init-containers-for-the-olm-installer"]
+:navtitle: Disabling the readiness init containers for the OLM installer
+:keywords: disable-readiness-init-containers, disabling-readiness-init-containers, init-container, readiness-init-container, startup, olm
+:page-aliases: .:disabling-readiness-init-containers-for-the-olm-installer
+
+include::partial$proc_disabling-readiness-init-containers-for-the-olm-installer.adoc[]

modules/administration-guide/pages/disabling-readiness-init-containers-for-the-operator-installer.adoc

@@ -0,0 +1,6 @@
+[id="disabling-readiness-init-containers-for-the-operator-installer"]
+:navtitle: Disabling the readiness init containers for the Operator installer
+:keywords: disable-readiness-init-containers, disabling-readiness-init-containers, init-container, readiness-init-container, startup, operator
+:page-aliases: .:disabling-readiness-init-containers-for-the-operator-installer
+
+include::partial$proc_disabling-readiness-init-containers-for-the-operator-installer.adoc[]

modules/administration-guide/pages/enabling-and-disabling-readiness-init-containers-for-the-olm-installer.adoc

@@ -0,0 +1,6 @@
+[id="enabling-and-disabling-readiness-init-containers-for-the-olm-installer"]
+:navtitle: Enabling and disabling the readiness init containers for the OLM installer
+:keywords: enable-readiness-init-containers, disable-readiness-init-containers, enabling-readiness-init-containers, disabling-readiness-init-containers, init-container, readiness-init-container, startup, olm
+:page-aliases: .:enabling-and-disabling-readiness-init-containers-for-the-olm-installer
+
+include::partial$assembly_enabling-and-disabling-readiness-init-containers-for-the-olm-installer.adoc[]

modules/administration-guide/pages/enabling-and-disabling-readiness-init-containers-for-the-operator-installer.adoc

@@ -0,0 +1,6 @@
+[id="enabling-and-disabling-readiness-init-containers-for-the-operator-installer"]
+:navtitle: Enabling and disabling the readiness init containers for the Operator installer
+:keywords: enable-readiness-init-containers, disable-readiness-init-containers, enabling-readiness-init-containers, disabling-readiness-init-containers, init-container, readiness-init-container, startup, operator
+:page-aliases: .:enabling-and-disabling-readiness-init-containers-for-the-operator-installer
+
+include::partial$assembly_enabling-and-disabling-readiness-init-containers-for-the-operator-installer.adoc[]

modules/administration-guide/pages/enabling-readiness-init-containers-for-the-olm-installer.adoc

@@ -0,0 +1,6 @@
+[id="enabling-readiness-init-containers-for-the-olm-installer"]
+:navtitle: Enabling the readiness init containers for the OLM installer
+:keywords: enable-readiness-init-containers, enabling-readiness-init-containers, init-container, readiness-init-container, startup, olm
+:page-aliases: .:enabling-readiness-init-containers-for-the-olm-installer
+
+include::partial$proc_enabling-readiness-init-containers-for-the-olm-installer.adoc[]

modules/administration-guide/pages/enabling-readiness-init-containers-for-the-operator-installer.adoc

@@ -0,0 +1,6 @@
+[id="enabling-readiness-init-containers-for-the-operator-installer"]
+:navtitle: Enabling the readiness init containers for the Operator installer
+:keywords: enable-readiness-init-containers, enabling-readiness-init-containers, init-container, readiness-init-container, startup, operator
+:page-aliases: .:enabling-readiness-init-containers-for-the-operator-installer
+
+include::partial$proc_enabling-readiness-init-containers-for-the-operator-installer.adoc[]

modules/administration-guide/pages/readiness-init-containers.adoc

@@ -0,0 +1,6 @@
+[id="readiness-init-containers"]
+:navtitle: Readiness init containers
+:keywords: init-container, readiness-init-container, startup
+:page-aliases: .:readiness-init-containers
+
+include::partial$assembly_readiness-init-containers.adoc[]

modules/administration-guide/partials/assembly_enabling-and-disabling-readiness-init-containers-for-the-olm-installer.adoc

@@ -0,0 +1,13 @@
+:parent-context-of-enabling-and-disabling-readiness-init-containers-for-the-olm-installer: {context}
+
+[id="enabling-and-disabling-readiness-init-containers-for-the-olm-installer_{context}"]
+= Enabling and disabling the readiness init containers for the OLM installer
+
+:context: enabling-and-disabling-readiness-init-containers-for-the-olm-installer
+
+You can enable and disable the readiness init containers for the {prod-short} installed by the OLM installer. (Available through `{prod-cli}`, the OLM installer uses the Operator Lifecycle Manager to install {prod-short}.)
+
+* xref:enabling-readiness-init-containers-for-the-olm-installer.adoc[Enabling the readiness init containers for the OLM installer]
+* xref:disabling-readiness-init-containers-for-the-olm-installer.adoc[Disabling the readiness init containers for the OLM installer]
+
+:context: {parent-context-of-enabling-and-disabling-readiness-init-containers-for-the-olm-installer}

modules/administration-guide/partials/assembly_enabling-and-disabling-readiness-init-containers-for-the-operator-installer.adoc

@@ -0,0 +1,13 @@
+:parent-context-of-enabling-and-disabling-readiness-init-containers-for-the-operator-installer: {context}
+
+[id="enabling-and-disabling-readiness-init-containers-for-the-operator-installer_{context}"]
+= Enabling and disabling the readiness init containers for the Operator installer
+
+:context: enabling-and-disabling-readiness-init-containers-for-the-operator-installer
+
+You can enable and disable the readiness init containers for the {prod-short} installed by the Operator installer:
+
+* xref:enabling-readiness-init-containers-for-the-operator-installer.adoc[Enabling the readiness init containers for the Operator installer]
+* xref:disabling-readiness-init-containers-for-the-operator-installer.adoc[Disabling the readiness init containers for the Operator installer]
+
+:context: {parent-context-of-enabling-and-disabling-readiness-init-containers-for-the-operator-installer}

modules/administration-guide/partials/assembly_readiness-init-containers.adoc

@@ -0,0 +1,16 @@
+:parent-context-of-readiness-init-containers: {context}
+
+[id="readiness-init-containers_{context}"]
+= Readiness init containers
+
+:context: readiness-init-containers
+
+{prod-short} Operator installs {prod-short} and starts its containers in the correct order. If a node with {prod-short} is restarted and all {prod-short} containers start simultaneously, some containers may fail because some other component they depend on is not ready. To avoid such failures, the readiness init containers queue the containers for {prod-short} components to start in the correct order.
+
+The readiness init containers are disabled by default. If you choose to enable them, proceed according to the installation method used to install {prod-short}:
+
+* xref:enabling-and-disabling-readiness-init-containers-for-the-operator-installer.adoc[]
+
+* xref:enabling-and-disabling-readiness-init-containers-for-the-olm-installer.adoc[]
+
+:context: {parent-context-of-readiness-init-containers}

modules/administration-guide/partials/proc_disabling-readiness-init-containers-for-the-olm-installer.adoc

@@ -0,0 +1,42 @@
+:_module-type: PROCEDURE
+
+[id="disabling-readiness-init-containers-for-the-olm-installer_{context}"]
+= Disabling the readiness init containers for the OLM installer
+
+To disable the previously enabled readiness init containers for the {prod-short} installed by the OLM installer:
+
+.Prerequisites
+
+* {prod-short} is installed by the OLM installer.
+
+.Procedure
+
+. Find the {prod-short} Operator subscription name:
++
+[source,shell,subs="+quotes,+attributes"]
+----
+$ {orch-cli} get subscriptions -n {prod-namespace}
+----
+
+. Get the CSV (Cluster Service Version) name from the {prod-short} Operator subscription:
++
+[source,shell,subs="+quotes,+attributes"]
+----
+$ {orch-cli} get subscription <subscription-name> -n {prod-namespace} -o yaml | grep installedCSV
+----
+
+. Edit the `ClusterServiceVersion` YAML manifest:
++
+[source,shell,subs="+quotes,+attributes"]
+----
+$ {orch-cli} edit csv _<csv-name>_ -n {prod-namespace}
+----
+. Remove the following environment variable from the Operator Deployment spec:
++
+[source,yaml,subs="+quotes,+attributes"]
+----
+ - name: ADD_COMPONENT_READINESS_INIT_CONTAINERS
+   value: "true"
+----
+
+. Wait for the {prod-short} Operator restart to finish. The restarted Operator will then continue with restarting some of its components.

modules/administration-guide/partials/proc_disabling-readiness-init-containers-for-the-operator-installer.adoc

@@ -0,0 +1,28 @@
+[id="disabling-readiness-init-containers-for-the-operator-installer_{context}"]
+= Disabling the readiness init containers for the Operator installer
+
+To disable the previously enabled readiness init containers for the {prod-short} installed by the Operator installer:
+
+.Prerequisites
+
+* {prod} installed by the Operator installer.
+
+.Procedure
+
+. Find the name of the {prod-short} Operator Deployment. Usually it is `{prod-id-short}-operator`:
++
+[source,yaml,subs="+quotes,+attributes"]
+----
+$ {orch-cli} get deployments -n {prod-namespace}
+----
+
+. Edit the Deployment as follows: Under `spec.template.spec.containers[0].env` of the Operator Deployment, remove the following lines:
++
+[source,yaml,subs="+quotes,+attributes"]
+----
+ - name: ADD_COMPONENT_READINESS_INIT_CONTAINERS <1>
+   value: "true"
+----
+<1> `ADD_COMPONENT_READINESS_INIT_CONTAINERS` is an environment variable.
+
+. Wait while {prod-short} Operator restarts some components.

modules/administration-guide/partials/proc_enabling-readiness-init-containers-for-the-olm-installer.adoc

@@ -0,0 +1,44 @@
+:_module-type: PROCEDURE
+
+[id="enabling-readiness-init-containers-for-the-olm-installer_{context}"]
+= Enabling the readiness init containers for the OLM installer
+
+The readiness init containers are not enabled by default, so to use them you first have to enable them. To enable the readiness init containers for the {prod-short} installed by the OLM installer:
+
+.Prerequisites
+
+* {prod-short} is installed by the OLM installer.
+
+.Procedure
+
+. Find the {prod-short} Operator subscription name:
++
+[source,shell,subs="+quotes,+attributes"]
+----
+$ {orch-cli} get subscriptions -n {prod-namespace}
+----
+
+. Get the CSV (Cluster Service Version) name from the {prod-short} Operator subscription:
++
+[source,shell,subs="+quotes,+attributes"]
+----
+$ {orch-cli} get subscription <subscription-name> -n {prod-namespace} -o yaml | grep installedCSV
+----
+
+. Edit the `ClusterServiceVersion` YAML manifest:
++
+[source,shell,subs="+quotes,+attributes"]
+----
+$ {orch-cli} edit csv _<csv-name>_ -n {prod-namespace}
+----
+. Add the following environment variable to the Operator Deployment spec:
++
+[source,yaml,subs="+quotes,+attributes"]
+----
+ - name: ADD_COMPONENT_READINESS_INIT_CONTAINERS
+   value: "true"
+----
+
+. Wait for the {prod-short} Operator restart to finish. The restarted Operator will then continue with restarting some of its components.
+
+NOTE: Repeat these steps after each {prod-short} upgrade when a new CSV is created by OLM.

modules/administration-guide/partials/proc_enabling-readiness-init-containers-for-the-operator-installer.adoc

@@ -0,0 +1,30 @@
+[id="enabling-readiness-init-containers-for-the-operator-installer_{context}"]
+= Enabling the readiness init containers for the Operator installer
+
+The readiness init containers are not enabled by default, so to use them you first have to enable them. To enable the readiness init containers for the {prod-short} installed by the Operator installer:
+
+.Prerequisites
+
+* {prod} installed by the Operator installer.
+
+.Procedure
+
+. Find the name of the {prod-short} Operator Deployment. Usually it is `{prod-id-short}-operator`:
++
+[source,yaml,subs="+quotes,+attributes"]
+----
+$ {orch-cli} get deployments -n {prod-namespace}
+----
+
+. Edit the Deployment as follows: Under `spec.template.spec.containers[0].env` of the Operator Deployment, insert the following lines:
++
+[source,yaml,subs="+quotes,+attributes"]
+----
+ - name: ADD_COMPONENT_READINESS_INIT_CONTAINERS <1>
+   value: "true"
+----
+<1> `ADD_COMPONENT_READINESS_INIT_CONTAINERS` is an environment variable.
+
+. Wait while {prod-short} Operator restarts some components.
+
+NOTE: Repeat these steps after each {prod-short} upgrade when a new Operator Deployment is created.