feat(postgres): add serverName parameter for backup recovery (#2362)

## Summary

Add `serverName` field to bootstrap configuration to support backup
recovery when the Barman server name in `backup.info` differs from the
Kubernetes cluster name.

This fixes "no target backup found" errors during CloudNativePG recovery
operations.

## Problem

CloudNativePG forms the backup path as `destinationPath + "postgres-" +
oldName`, but searches for backups using the `server_name` field from
`backup.info`. When these values don't match (e.g., cluster name is
`grafana` but `server_name` is `cloud`), recovery fails with "no target
backup found".

## Solution

- Add optional `serverName` parameter to `bootstrap` configuration
- When specified, CloudNativePG uses this value to search for backups in
S3
- Falls back to `oldName` when `serverName` is not provided (backwards
compatible)

## Changes

- Add `ServerName` field to PostgreSQL CRD type definition
- Add conditional `serverName` to Cluster `externalClusters` template  
- Update `values.yaml` and README.md with `serverName` documentation
- Regenerate `values.schema.json` and `postgres.yaml` CRD

## Test plan

- [ ] Deploy postgres cluster with backups enabled
- [ ] Create backup
- [ ] Create new postgres instance with `bootstrap.enabled=true`,
`bootstrap.oldName=<original-name>`, and
`bootstrap.serverName=<value-from-backup.info>`
- [ ] Verify recovery completes successfully

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added an optional bootstrap.serverName setting to specify the Barman
server name from the original cluster’s backup.info (used when that
server name differs from the Kubernetes cluster name).

* **Documentation**
* Clarified that bootstrap.oldName must match the serverName value
recorded in backup.info; updated docs and examples to reflect the new
bootstrap.serverName option.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

api/apps/v1alpha1/postgresql/types.go

@@ -92,6 +92,9 @@ type Bootstrap struct {
 	// Timestamp (RFC3339) for point-in-time recovery; empty means latest.
 	// +kubebuilder:default:=""
 	RecoveryTime string `json:"recoveryTime,omitempty"`
+	// Barman server name (S3 path prefix) used by the original cluster when writing backups. Set this only when the original cluster had an explicit barmanObjectStore.serverName that differed from its Kubernetes resource name.
+	// +kubebuilder:default:=""
+	ServerName string `json:"serverName,omitempty"`
 }
 
 type Database struct {

packages/apps/postgres/README.md

@@ -133,12 +133,13 @@ See:
 
 ### Bootstrap (recovery) parameters
 
-| Name                     | Description                                                         | Type     | Value   |
-| ------------------------ | ------------------------------------------------------------------- | -------- | ------- |
-| `bootstrap`              | Bootstrap configuration.                                            | `object` | `{}`    |
-| `bootstrap.enabled`      | Whether to restore from a backup.                                   | `bool`   | `false` |
-| `bootstrap.recoveryTime` | Timestamp (RFC3339) for point-in-time recovery; empty means latest. | `string` | `""`    |
-| `bootstrap.oldName`      | Previous cluster name before deletion.                              | `string` | `""`    |
+| Name                     | Description                                                                                                                                                                                                                  | Type     | Value   |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- |
+| `bootstrap`              | Bootstrap configuration.                                                                                                                                                                                                     | `object` | `{}`    |
+| `bootstrap.enabled`      | Whether to restore from a backup.                                                                                                                                                                                            | `bool`   | `false` |
+| `bootstrap.recoveryTime` | Timestamp (RFC3339) for point-in-time recovery; empty means latest.                                                                                                                                                          | `string` | `""`    |
+| `bootstrap.oldName`      | Previous cluster name before deletion.                                                                                                                                                                                       | `string` | `""`    |
+| `bootstrap.serverName`   | Barman server name (S3 path prefix) used by the original cluster when writing backups. Set this only when the original cluster had an explicit barmanObjectStore.serverName that differed from its Kubernetes resource name. | `string` | `""`    |
 
 
 ## Parameter examples and reference

packages/apps/postgres/templates/db.yaml

@@ -32,6 +32,9 @@ spec:
     - name: {{ .Values.bootstrap.oldName }}
       barmanObjectStore:
         destinationPath: {{ .Values.backup.destinationPath }}
+        {{- if .Values.bootstrap.serverName }}
+        serverName: {{ .Values.bootstrap.serverName }}
+        {{- end }}
         endpointURL: {{ .Values.backup.endpointURL }}
         s3Credentials:
           accessKeyId:

packages/apps/postgres/values.schema.json

@@ -254,6 +254,11 @@
           "description": "Timestamp (RFC3339) for point-in-time recovery; empty means latest.",
           "type": "string",
           "default": ""
+        },
+        "serverName": {
+          "description": "Barman server name (S3 path prefix) used by the original cluster when writing backups. Set this only when the original cluster had an explicit barmanObjectStore.serverName that differed from its Kubernetes resource name.",
+          "type": "string",
+          "default": ""
         }
       }
     }

packages/apps/postgres/values.yaml

@@ -154,6 +154,7 @@ backup:
 ## @field {bool} enabled - Whether to restore from a backup.
 ## @field {string} [recoveryTime] - Timestamp (RFC3339) for point-in-time recovery; empty means latest.
 ## @field {string} oldName - Previous cluster name before deletion.
+## @field {string} [serverName] - Barman server name (S3 path prefix) used by the original cluster when writing backups. Set this only when the original cluster had an explicit barmanObjectStore.serverName that differed from its Kubernetes resource name.
 
 ## @param {Bootstrap} bootstrap - Bootstrap configuration.
 bootstrap:
@@ -161,3 +162,4 @@ bootstrap:
   # example: 2020-11-26 15:22:00.00000+00
   recoveryTime: ""
   oldName: ""
+  serverName: ""