docs: import CloudNativePG main

Author: cnpg-bot

website/docs/instance_manager.md

@@ -25,7 +25,7 @@ of the Pod, the instance manager acts as a backend to handle the
 ## Startup Probe
 
 The startup probe ensures that a PostgreSQL instance, whether a primary or
-standby, has fully started.
+standby, has started up.
 
 :::info
     By default, the startup probe uses
@@ -34,6 +34,14 @@ standby, has fully started.
     strategy.
 :::
 
+With the default `pg_isready` strategy, an instance is considered started as
+soon as PostgreSQL is alive, even if it is still rejecting connections while
+it completes its startup sequence (for example, a standby performing crash
+recovery or replaying WAL). This prevents the kubelet from repeatedly
+restarting an instance that is legitimately recovering. The instance remains
+unready, and therefore excluded from the ready endpoints of the services,
+until the readiness probe reports that it accepts connections.
+
 While the startup probe is running, the liveness and readiness probes remain
 disabled. Following Kubernetes standards, if the startup probe fails, the
 kubelet will terminate the container, which will then be restarted.
@@ -42,13 +50,15 @@ The `.spec.startDelay` parameter specifies the maximum time, in seconds,
 allowed for the startup probe to succeed.
 
 By default, the `startDelay` is set to `3600` seconds. It is recommended to
-adjust this setting based on the time PostgreSQL needs to fully initialize in
-your specific environment.
+adjust this setting based on the time PostgreSQL needs to start in your
+specific environment. With the default `pg_isready` strategy, this only
+needs to cover the time required for the postmaster to come alive, while
+with the `query` and `streaming` strategies it must also account for the
+time needed to complete recovery and accept connections.
 
 :::warning
-    Setting `.spec.startDelay` too low can cause the liveness probe to activate
-    prematurely, potentially resulting in unnecessary Pod restarts if PostgreSQL
-    hasn’t fully initialized.
+    Setting `.spec.startDelay` too low can cause the startup probe to fail
+    before PostgreSQL has started up, resulting in unnecessary Pod restarts.
 :::
 
 CloudNativePG configures the startup probe with the following default parameters:
@@ -105,8 +115,11 @@ To accommodate these requirements, CloudNativePG extends the
 - `type`: specifies the criteria for considering the probe successful. Accepted
   values, in increasing order of complexity/depth, include:
 
-    - `pg_isready`: marks the probe as successful when the `pg_isready` command
-      exits with `0`. This is the default for primary instances and replicas.
+    - `pg_isready`: relies on the exit code of the `pg_isready` command. The
+      startup probe is successful when the server is either accepting
+      connections or alive but rejecting them, as described above. The
+      readiness probe is successful only when the server is accepting
+      connections. This is the default for primary instances and replicas.
     - `query`: marks the probe as successful when a basic query is executed on
       the `postgres` database locally.
     - `streaming`: marks the probe as successful when the replica begins
@@ -143,6 +156,14 @@ probes:
     maximumLag: 16Mi
 ```
 
+:::info
+    The `query` and `streaming` strategies require PostgreSQL to accept
+    connections, so a startup probe using them keeps failing while an
+    instance replays WAL after a crash. When using these strategies, make
+    sure that `startDelay` (or your custom `failureThreshold`) allows enough
+    time for recovery to complete.
+:::
+
 ## Liveness Probe
 
 The liveness probe begins after the startup probe successfully completes. Its