docs: import CloudNativePG main

Author: gbartolini

website/docs/appendixes/object_stores.md

@@ -27,6 +27,16 @@ You can also use any compatible implementation of the supported services.
 The required setup depends on the chosen storage provider and is
 discussed in the following sections.
 
+:::note Authentication Methods
+CloudNativePG does not independently test all authentication methods
+supported by `barman-cloud`. CloudNativePG's responsibility is limited to passing
+the provided credentials to `barman-cloud`, which then handles authentication
+according to its own implementation. Users should refer to the
+[Barman Cloud documentation](https://docs.pgbarman.org/release/latest/) to
+verify that their chosen authentication method is supported and properly
+configured.
+:::
+
 ## AWS S3
 
 [AWS Simple Storage Service (S3)](https://aws.amazon.com/s3/) is
@@ -195,17 +205,15 @@ spec:
 [Azure Blob Storage](https://azure.microsoft.com/en-us/services/storage/blobs/) is the
 object storage service provided by Microsoft.
 
-In order to access your storage account for backup and recovery of
-CloudNativePG managed databases, you will need one of the following
-combinations of credentials:
+CloudNativePG supports the following authentication methods for Azure Blob Storage:
 
 - [Connection String](https://docs.microsoft.com/en-us/azure/storage/common/storage-configure-connection-string#configure-a-connection-string-for-an-azure-storage-account)
-- Storage account name and [Storage account access key](https://docs.microsoft.com/en-us/azure/storage/common/storage-account-keys-manage)
-- Storage account name and [Storage account SAS Token](https://docs.microsoft.com/en-us/azure/storage/blobs/sas-service-create)
-- Storage account name and [Azure AD Workload Identity](https://azure.github.io/azure-workload-identity/docs/introduction.html)
-properly configured.
+- Storage Account Name + [Storage Account Access Key](https://docs.microsoft.com/en-us/azure/storage/common/storage-account-keys-manage)
+- Storage Account Name + [Storage Account SAS Token](https://docs.microsoft.com/en-us/azure/storage/blobs/sas-service-create)
+- [Azure AD Managed Identity](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/overview)
+- [Default Azure Credentials](https://learn.microsoft.com/en-us/python/api/azure-identity/azure.identity.defaultazurecredential?view=azure-python)
 
-Using **Azure AD Workload Identity**, you can avoid saving the credentials into a Kubernetes Secret,
+Using **Azure AD Managed Identity**, you can avoid saving the credentials into a Kubernetes Secret,
 and have a Cluster configuration adding the `inheritFromAzureAD` as follows:
 
 ```yaml
@@ -220,6 +228,23 @@ spec:
         inheritFromAzureAD: true
 ```
 
+Alternatively, you can use the **Default Azure Credentials** authentication mechanism, which provides
+a seamless authentication experience by supporting multiple authentication methods including environment
+variables, managed identities, and Azure CLI credentials. Add the `useDefaultAzureCredentials` flag
+as follows:
+
+```yaml
+apiVersion: postgresql.cnpg.io/v1
+kind: Cluster
+[...]
+spec:
+  backup:
+    barmanObjectStore:
+      destinationPath: "<destination path here>"
+      azureCredentials:
+        useDefaultAzureCredentials: true
+```
+
 On the other side, using both **Storage account access key** or **Storage account SAS Token**,
 the credentials need to be stored inside a Kubernetes Secret, adding data entries only when
 needed. The following command performs that:

website/docs/cloudnative-pg.v1.md

@@ -1239,6 +1239,7 @@ _Appears in:_
 | --- | --- | --- | --- | --- |
 | `podName` _string_ | The pod name |  |  |  |
 | `ContainerID` _string_ | The container ID |  |  |  |
+| `sessionID` _string_ | The instance manager session ID. This is a unique identifier generated at instance manager<br />startup and changes on every restart (including container reboots). Used to detect if<br />the instance manager was restarted during long-running operations like backups, which<br />would terminate any running backup process. |  |  |  |
 
 
 #### InstanceReportedState

website/docs/cnpg_i.md

@@ -200,7 +200,7 @@ must include this DNS name in its Subject Alternative Names (SAN).
 
 To enable a plugin, configure the `.spec.plugins` section in your `Cluster`
 resource. Refer to the CloudNativePG API Reference for the full
-[PluginConfiguration](https://cloudnative-pg.io/documentation/current/cloudnative-pg.v1/#postgresql-cnpg-io-v1-PluginConfiguration)
+[PluginConfiguration](https://cloudnative-pg.io/docs/devel/cloudnative-pg.v1/#pluginconfiguration)
 specification.
 
 Example:

website/docs/connection_pooling.md

@@ -666,9 +666,10 @@ spec:
 
 ### Deprecation of Automatic `PodMonitor` Creation
 
-!!!warning "Feature Deprecation Notice"
+:::warning[Feature Deprecation Notice]
     The `.spec.monitoring.enablePodMonitor` field in the `Pooler` resource is
     now deprecated and will be removed in a future version of the operator.
+:::
 
 If you are currently using this feature, we strongly recommend you either
 remove or set `.spec.monitoring.enablePodMonitor` to `false` and manually

website/docs/monitoring.md

@@ -118,9 +118,10 @@ spec:
 
 #### Deprecation of Automatic `PodMonitor` Creation
 
-!!!warning "Feature Deprecation Notice"
+:::warning[Feature Deprecation Notice]
     The `.spec.monitoring.enablePodMonitor` field in the `Cluster` resource is
     now deprecated and will be removed in a future version of the operator.
+:::
 
 If you are currently using this feature, we strongly recommend you either
 remove or set `.spec.monitoring.enablePodMonitor` to `false` and manually

website/docs/operator_conf.md

@@ -48,8 +48,9 @@ Name | Description
 `CERTIFICATE_DURATION` | Determines the lifetime of the generated certificates in days. Default is 90.
 `CLUSTERS_ROLLOUT_DELAY` | The duration (in seconds) to wait between the roll-outs of different clusters during an operator upgrade. This setting controls the timing of upgrades across clusters, spreading them out to reduce system impact. The default value is `0` which means no delay between PostgreSQL cluster upgrades.
 `CREATE_ANY_SERVICE` | When set to `true`, will create `-any` service for the cluster. Default is `false`
+`DRAIN_TAINTS` | Specifies the taint keys that should be interpreted as indicators of node drain. By default, it includes the taints commonly applied by [kubectl](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/), [Cluster Autoscaler](https://github.com/kubernetes/autoscaler), and [Karpenter](https://github.com/aws/karpenter-provider-aws): `node.kubernetes.io/unschedulable`, `ToBeDeletedByClusterAutoscaler`, `karpenter.sh/disrupted`, `karpenter.sh/disruption`.
 `ENABLE_INSTANCE_MANAGER_INPLACE_UPDATES` | When set to `true`, enables in-place updates of the instance manager after an update of the operator, avoiding rolling updates of the cluster (default `false`)
-`EXPIRING_CHECK_THRESHOLD` | Determines the threshold, in days, for identifying a certificate as expiring. Default is 7. 
+`EXPIRING_CHECK_THRESHOLD` | Determines the threshold, in days, for identifying a certificate as expiring. Default is 7.
 `INCLUDE_PLUGINS` | A comma-separated list of plugins to be always included in the Cluster's reconciliation.
 `INHERITED_ANNOTATIONS` | List of annotation names that, when defined in a `Cluster` metadata, will be inherited by all the generated resources, including pods
 `INHERITED_LABELS` | List of label names that, when defined in a `Cluster` metadata, will be inherited by all the generated resources, including pods
@@ -63,7 +64,7 @@ Name | Description
 `POSTGRES_IMAGE_NAME` | The name of the PostgreSQL image used by default for new clusters. Defaults to the version specified in the operator.
 `PULL_SECRET_NAME` | Name of an additional pull secret to be defined in the operator's namespace and to be used to download images
 `STANDBY_TCP_USER_TIMEOUT` | Defines the [`TCP_USER_TIMEOUT` socket option](https://www.postgresql.org/docs/current/runtime-config-connection.html#GUC-TCP-USER-TIMEOUT) in milliseconds for replication connections from standby instances to the primary. Default is 5000 (5 seconds). Set to `0` to use the system's default.
-`DRAIN_TAINTS` | Specifies the taint keys that should be interpreted as indicators of node drain. By default, it includes the taints commonly applied by [kubectl](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/), [Cluster Autoscaler](https://github.com/kubernetes/autoscaler), and [Karpenter](https://github.com/aws/karpenter-provider-aws): `node.kubernetes.io/unschedulable`, `ToBeDeletedByClusterAutoscaler`, `karpenter.sh/disrupted`, `karpenter.sh/disruption`.
+`WATCH_NAMESPACE` | Specifies the namespace(s) where the operator should watch for resources. Multiple namespaces can be specified separated by commas. If not set, the operator watches all namespaces (cluster-wide mode).
 
 Values in `INHERITED_ANNOTATIONS` and `INHERITED_LABELS` support path-like wildcards. For example, the value `example.com/*` will match
 both the value `example.com/one` and `example.com/two`.

website/docs/postgres_upgrades.md

@@ -135,9 +135,10 @@ If the upgrade is successful, CloudNativePG:
 :::warning
     Re-cloning replicas can be time-consuming, especially for very large
     databases. Plan accordingly to accommodate potential delays. After completing
-    the upgrade, it is strongly recommended to take a full backup. Existing backup
-    data (namely base backups and WAL files) is only available for the previous
-    minor PostgreSQL release.
+    the upgrade, take a new base backup as soon as possible. Pre-upgrade backups
+    and WAL files cannot be used for point-in-time recovery (PITR) across major
+    version boundaries. See [Backup and WAL Archive Considerations](#backup-and-wal-archive-considerations)
+    for more details.
 :::
 
 :::warning
@@ -156,6 +157,71 @@ automatically decide the rollback.
     Ensure you monitor the process closely and take corrective action if needed.
 :::
 
+### Backup and WAL Archive Considerations
+
+When performing a major upgrade, `pg_upgrade` creates a new database system
+with a new *System ID* and resets the PostgreSQL timeline to 1. This has
+implications for backup and WAL archiving:
+
+- **Timeline file conflicts**: New timeline 1 files may overwrite timeline 1
+  files from the original cluster.
+- **Mixed version archives**: Without intervention, the archive will contain
+  WAL files and backups from both PostgreSQL versions.
+
+:::warning
+Point-in-time recovery (PITR) is not supported across major PostgreSQL version
+boundaries. You cannot use pre-upgrade backups to recover to a point in time
+after the upgrade. Take a new base backup as soon as possible after upgrading
+to establish a recovery baseline for the new major version.
+:::
+
+How backup systems handle major upgrades depends on the plugin implementation.
+Some plugins may automatically manage archive separation during upgrades, while
+others require manual configuration to use different archive paths for each
+major version. Consult your backup plugin documentation for its specific
+behavior during major upgrades.
+
+#### Example: Manual archive path separation with the Barman Cloud plugin
+
+The Barman Cloud plugin does not automatically separate archives during major
+upgrades. To preserve pre-upgrade backups and keep archives clean, change the
+`serverName` parameter when you trigger the upgrade.
+
+Before upgrade (PostgreSQL 16):
+
+```yaml
+spec:
+  imageName: ghcr.io/cloudnative-pg/postgresql:16-minimal-trixie
+  plugins:
+    - name: plugin-barman-cloud
+      enabled: true
+      parameters:
+        destinationPath: s3://my-bucket/
+        serverName: cluster-example-pg16
+```
+
+To trigger the upgrade, change both `imageName` and `serverName` together:
+
+```yaml
+spec:
+  imageName: ghcr.io/cloudnative-pg/postgresql:17-minimal-trixie
+  plugins:
+    - name: plugin-barman-cloud
+      enabled: true
+      parameters:
+        destinationPath: s3://my-bucket/
+        serverName: cluster-example-pg17
+```
+
+With this configuration, the old archive at `cluster-example-pg16` remains
+intact for pre-upgrade recovery, while the upgraded cluster writes to
+`cluster-example-pg17`.
+
+:::info
+The deprecated in-tree `barmanObjectStore` implementation also requires manual
+`serverName` changes to separate archives during major upgrades.
+:::
+
 ### Example: Performing a Major Upgrade
 
 Consider the following PostgreSQL cluster running version 16:

website/docs/release_notes/old/v1.18.md

@@ -68,7 +68,7 @@ Fixes:
     CloudNativePG is dropping support for PostgreSQL 10, as PostgreSQL 10
     reached End-of-Life (EOL) in November 2022. Versions 11 and newer are
     supported. Please plan your migration to PostgreSQL 15 as soon as possible.
-    Refer to ["Importing Postgres databases"](https://cloudnative-pg.io/documentation/current/database_import/)
+    Refer to ["Importing Postgres databases"](https://cloudnative-pg.io/docs/devel/database_import/)
     for more information on PostgreSQL major offline upgrades.
 :::
 

website/docs/release_notes/old/v1.19.md

@@ -292,7 +292,7 @@ Important announcements:
 - PostgreSQL version 10 is no longer supported as it has reached its EOL.
   Versions 11 and newer are supported. Please plan your migration to
   PostgreSQL 15 as soon as possible. Refer to
-  ["Importing Postgres databases"](https://cloudnative-pg.io/documentation/current/database_import/)
+  ["Importing Postgres databases"](https://cloudnative-pg.io/docs/devel/database_import/)
   for more information on PostgreSQL major offline upgrades.
 
 Features:

website/docs/samples/k9s/plugins.yml

@@ -1,5 +1,5 @@
 # Move/add to $XDG_CONFIG_HOME/k9s/plugins.yaml
-# Requires the cnpg kubectl plugin. See https://cloudnative-pg.io/documentation/current/kubectl-plugin/
+# Requires the cnpg kubectl plugin. See https://cloudnative-pg.io/docs/devel/kubectl-plugin/
 #
 # Cluster actions:
 #   b         Request a new physical backup
@@ -131,4 +131,4 @@ plugins:
     background: false
     args:
       - -c
-      - "kubectl cnpg status $NAME -n $NAMESPACE --context \"$CONTEXT\" --verbose 2>&1 | less -R"
+      - "kubectl cnpg status $NAME -n $NAMESPACE --context \"$CONTEXT\" --verbose 2>&1 | less -R"