Skip to content

Commit 278677a

Browse files
gbartolinimnenciafcanovai
authored
docs(cnpg-i): deprecate backup metrics and fields in Cluster status (#8091)
Due to the transition to a plugin-based, backup-agnostic architecture in CloudNativePG, we are deprecating: - `firstRecoverabilityPoint`, `firstRecoverabilityPointByMethod`, `lastSuccessfulBackup`, `lastSuccessfulBackupByMethod`, and `lastFailedBackup` in `Cluster.status` - `cnpg_collector_first_recoverability_point`, `cnpg_collector_last_failed_backup_timestamp`, `cnpg_collector_last_available_backup_timestamp` metrics If you have migrated to a plugin-based backup and recovery solution such as Barman Cloud, these fields/metrics are no longer synchronized and will not be updated. Users still relying on the in-core support for Barman Cloud and volume snapshots can continue to use these fields for the time being. Closes #8051 Signed-off-by: Gabriele Bartolini <[email protected]> Signed-off-by: Marco Nenciarini <[email protected]> Signed-off-by: Francesco Canovai <[email protected]> Co-authored-by: Marco Nenciarini <[email protected]> Co-authored-by: Francesco Canovai <[email protected]>
1 parent 801825b commit 278677a

16 files changed

Lines changed: 157 additions & 63 deletions

File tree

‎api/v1/cluster_types.go‎

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -905,24 +905,34 @@ type ClusterStatus struct {
905905
Certificates CertificatesStatus `json:"certificates,omitempty"`
906906

907907
// The first recoverability point, stored as a date in RFC3339 format.
908-
// This field is calculated from the content of FirstRecoverabilityPointByMethod
908+
// This field is calculated from the content of FirstRecoverabilityPointByMethod.
909+
//
910+
// Deprecated: the field is not set for backup plugins.
909911
// +optional
910912
FirstRecoverabilityPoint string `json:"firstRecoverabilityPoint,omitempty"`
911913

912-
// The first recoverability point, stored as a date in RFC3339 format, per backup method type
914+
// The first recoverability point, stored as a date in RFC3339 format, per backup method type.
915+
//
916+
// Deprecated: the field is not set for backup plugins.
913917
// +optional
914918
FirstRecoverabilityPointByMethod map[BackupMethod]metav1.Time `json:"firstRecoverabilityPointByMethod,omitempty"`
915919

916-
// Last successful backup, stored as a date in RFC3339 format
917-
// This field is calculated from the content of LastSuccessfulBackupByMethod
920+
// Last successful backup, stored as a date in RFC3339 format.
921+
// This field is calculated from the content of LastSuccessfulBackupByMethod.
922+
//
923+
// Deprecated: the field is not set for backup plugins.
918924
// +optional
919925
LastSuccessfulBackup string `json:"lastSuccessfulBackup,omitempty"`
920926

921-
// Last successful backup, stored as a date in RFC3339 format, per backup method type
927+
// Last successful backup, stored as a date in RFC3339 format, per backup method type.
928+
//
929+
// Deprecated: the field is not set for backup plugins.
922930
// +optional
923931
LastSuccessfulBackupByMethod map[BackupMethod]metav1.Time `json:"lastSuccessfulBackupByMethod,omitempty"`
924932

925-
// Stored as a date in RFC3339 format
933+
// Last failed backup, stored as a date in RFC3339 format.
934+
//
935+
// Deprecated: the field is not set for backup plugins.
926936
// +optional
927937
LastFailedBackup string `json:"lastFailedBackup,omitempty"`
928938

‎config/crd/bases/postgresql.cnpg.io_clusters.yaml‎

Lines changed: 19 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -6110,14 +6110,18 @@ spec:
61106110
firstRecoverabilityPoint:
61116111
description: |-
61126112
The first recoverability point, stored as a date in RFC3339 format.
6113-
This field is calculated from the content of FirstRecoverabilityPointByMethod
6113+
This field is calculated from the content of FirstRecoverabilityPointByMethod.
6114+
6115+
Deprecated: the field is not set for backup plugins.
61146116
type: string
61156117
firstRecoverabilityPointByMethod:
61166118
additionalProperties:
61176119
format: date-time
61186120
type: string
6119-
description: The first recoverability point, stored as a date in RFC3339
6120-
format, per backup method type
6121+
description: |-
6122+
The first recoverability point, stored as a date in RFC3339 format, per backup method type.
6123+
6124+
Deprecated: the field is not set for backup plugins.
61216125
type: object
61226126
healthyPVC:
61236127
description: List of all the PVCs not dangling nor initializing
@@ -6175,7 +6179,10 @@ spec:
61756179
format: int32
61766180
type: integer
61776181
lastFailedBackup:
6178-
description: Stored as a date in RFC3339 format
6182+
description: |-
6183+
Last failed backup, stored as a date in RFC3339 format.
6184+
6185+
Deprecated: the field is not set for backup plugins.
61796186
type: string
61806187
lastPromotionToken:
61816188
description: |-
@@ -6184,15 +6191,19 @@ spec:
61846191
type: string
61856192
lastSuccessfulBackup:
61866193
description: |-
6187-
Last successful backup, stored as a date in RFC3339 format
6188-
This field is calculated from the content of LastSuccessfulBackupByMethod
6194+
Last successful backup, stored as a date in RFC3339 format.
6195+
This field is calculated from the content of LastSuccessfulBackupByMethod.
6196+
6197+
Deprecated: the field is not set for backup plugins.
61896198
type: string
61906199
lastSuccessfulBackupByMethod:
61916200
additionalProperties:
61926201
format: date-time
61936202
type: string
6194-
description: Last successful backup, stored as a date in RFC3339 format,
6195-
per backup method type
6203+
description: |-
6204+
Last successful backup, stored as a date in RFC3339 format, per backup method type.
6205+
6206+
Deprecated: the field is not set for backup plugins.
61966207
type: object
61976208
latestGeneratedNode:
61986209
description: ID of the latest generated node (used to avoid node name

‎docs/src/cloudnative-pg.v1.md‎

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2148,36 +2148,41 @@ configmap data</p>
21482148
</td>
21492149
<td>
21502150
<p>The first recoverability point, stored as a date in RFC3339 format.
2151-
This field is calculated from the content of FirstRecoverabilityPointByMethod</p>
2151+
This field is calculated from the content of FirstRecoverabilityPointByMethod.</p>
2152+
<p>Deprecated: the field is not set for backup plugins.</p>
21522153
</td>
21532154
</tr>
21542155
<tr><td><code>firstRecoverabilityPointByMethod</code><br/>
21552156
<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta"><i>map[BackupMethod]meta/v1.Time</i></a>
21562157
</td>
21572158
<td>
2158-
<p>The first recoverability point, stored as a date in RFC3339 format, per backup method type</p>
2159+
<p>The first recoverability point, stored as a date in RFC3339 format, per backup method type.</p>
2160+
<p>Deprecated: the field is not set for backup plugins.</p>
21592161
</td>
21602162
</tr>
21612163
<tr><td><code>lastSuccessfulBackup</code><br/>
21622164
<i>string</i>
21632165
</td>
21642166
<td>
2165-
<p>Last successful backup, stored as a date in RFC3339 format
2166-
This field is calculated from the content of LastSuccessfulBackupByMethod</p>
2167+
<p>Last successful backup, stored as a date in RFC3339 format.
2168+
This field is calculated from the content of LastSuccessfulBackupByMethod.</p>
2169+
<p>Deprecated: the field is not set for backup plugins.</p>
21672170
</td>
21682171
</tr>
21692172
<tr><td><code>lastSuccessfulBackupByMethod</code><br/>
21702173
<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta"><i>map[BackupMethod]meta/v1.Time</i></a>
21712174
</td>
21722175
<td>
2173-
<p>Last successful backup, stored as a date in RFC3339 format, per backup method type</p>
2176+
<p>Last successful backup, stored as a date in RFC3339 format, per backup method type.</p>
2177+
<p>Deprecated: the field is not set for backup plugins.</p>
21742178
</td>
21752179
</tr>
21762180
<tr><td><code>lastFailedBackup</code><br/>
21772181
<i>string</i>
21782182
</td>
21792183
<td>
2180-
<p>Stored as a date in RFC3339 format</p>
2184+
<p>Last failed backup, stored as a date in RFC3339 format.</p>
2185+
<p>Deprecated: the field is not set for backup plugins.</p>
21812186
</td>
21822187
</tr>
21832188
<tr><td><code>cloudNativePGCommitHash</code><br/>

‎docs/src/installation_upgrade.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -293,6 +293,47 @@ spec:
293293
even if in-place updates are enabled (`ENABLE_INSTANCE_MANAGER_INPLACE_UPDATES=true`).
294294
Your applications will need to reconnect to PostgreSQL after the upgrade.
295295

296+
#### Deprecation of backup metrics and fields in the `Cluster` `.status`
297+
298+
With the transition to a backup and recovery agnostic approach based on CNPG-I
299+
plugins in CloudNativePG, which began with version 1.26.0 for Barman Cloud, we
300+
are starting the deprecation period for the following fields in the `.status`
301+
section of the `Cluster` resource:
302+
303+
- `firstRecoverabilityPoint`
304+
- `firstRecoverabilityPointByMethod`
305+
- `lastSuccessfulBackup`
306+
- `lastSuccessfulBackupByMethod`
307+
- `lastFailedBackup`
308+
309+
The following Prometheus metrics are also deprecated:
310+
311+
- `cnpg_collector_first_recoverability_point`
312+
- `cnpg_collector_last_failed_backup_timestamp`
313+
- `cnpg_collector_last_available_backup_timestamp`
314+
315+
!!! Warning
316+
If you have migrated to a plugin-based backup and recovery solution such as
317+
Barman Cloud, these fields and metrics are no longer synchronized and will
318+
not be updated. Users still relying on the in-core support for Barman Cloud
319+
and volume snapshots can continue to use these fields for the time being.
320+
321+
Under the new plugin-based approach, multiple backup methods can operate
322+
simultaneously, each with its own timeline for backup and recovery. For
323+
example, some plugins may provide snapshots without WAL archiving, while others
324+
support continuous archiving.
325+
326+
Because of this flexibility, maintaining centralized status fields in the
327+
`Cluster` resource could be misleading or confusing, as they would not
328+
accurately represent the state across all configured backup methods.
329+
For this reason, these fields are being deprecated.
330+
331+
Instead, each plugin is responsible for exposing its own backup status
332+
information and providing metrics back to the instance manager for monitoring
333+
and operational awareness.
334+
335+
#### Declarative Hibernation in the `cnpg` plugin
336+
296337
In this release, the `cnpg` plugin for `kubectl` transitions from an imperative
297338
to a [declarative approach for cluster hibernation](declarative_hibernation.md).
298339
The `hibernate on` and `hibernate off` commands are now convenient shortcuts

‎docs/src/monitoring.md‎

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -220,15 +220,15 @@ cnpg_collector_up{cluster="cluster-example"} 1
220220
# TYPE cnpg_collector_postgres_version gauge
221221
cnpg_collector_postgres_version{cluster="cluster-example",full="17.5"} 17.5
222222
223-
# HELP cnpg_collector_last_failed_backup_timestamp The last failed backup as a unix timestamp
223+
# HELP cnpg_collector_last_failed_backup_timestamp The last failed backup as a unix timestamp (Deprecated)
224224
# TYPE cnpg_collector_last_failed_backup_timestamp gauge
225225
cnpg_collector_last_failed_backup_timestamp 0
226226
227-
# HELP cnpg_collector_last_available_backup_timestamp The last available backup as a unix timestamp
227+
# HELP cnpg_collector_last_available_backup_timestamp The last available backup as a unix timestamp (Deprecated)
228228
# TYPE cnpg_collector_last_available_backup_timestamp gauge
229229
cnpg_collector_last_available_backup_timestamp 1.63238406e+09
230230
231-
# HELP cnpg_collector_first_recoverability_point The first point of recoverability for the cluster as a unix timestamp
231+
# HELP cnpg_collector_first_recoverability_point The first point of recoverability for the cluster as a unix timestamp (Deprecated)
232232
# TYPE cnpg_collector_first_recoverability_point gauge
233233
cnpg_collector_first_recoverability_point 1.63238406e+09
234234
@@ -398,9 +398,16 @@ go_threads 18
398398
`Major.Minor.Patch` can be found inside one of its label field
399399
named `full`.
400400

401-
!!! Note
402-
`cnpg_collector_first_recoverability_point` and `cnpg_collector_last_available_backup_timestamp`
403-
will be zero until your first backup to the object store. This is separate from the WAL archival.
401+
!!! Warning
402+
The metrics `cnpg_collector_last_failed_backup_timestamp`,
403+
`cnpg_collector_last_available_backup_timestamp`, and
404+
`cnpg_collector_first_recoverability_point` have been deprecated starting
405+
from version 1.26. These metrics will continue to function with native backup
406+
solutions such as in-core Barman Cloud (deprecated) and volume snapshots. Note
407+
that for these cases, `cnpg_collector_first_recoverability_point` and
408+
`cnpg_collector_last_available_backup_timestamp` will remain zero until the
409+
first backup is completed to the object store. This is separate from WAL
410+
archiving.
404411

405412
### User defined metrics
406413

‎docs/src/troubleshooting.md‎

Lines changed: 0 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -60,17 +60,6 @@ Please refer to the [plugin document](kubectl-plugin.md) for complete instructio
6060
After getting the cluster manifest with the plugin, you should verify if backups
6161
are set up and working.
6262

63-
In a cluster with backups set up, you will find, in the cluster Status, the fields
64-
`lastSuccessfulBackup` and `firstRecoverabilityPoint`. You should make sure
65-
there is a recent `lastSuccessfulBackup`.
66-
67-
A cluster lacking the `.spec.backup` stanza won't have backups.
68-
An insistent message will appear in the PostgreSQL logs:
69-
70-
```
71-
Backup not configured, skip WAL archiving.
72-
```
73-
7463
Before proceeding with troubleshooting operations, it may be advisable
7564
to perform an emergency backup depending on your findings regarding backups.
7665
Refer to the following section for instructions.

‎internal/cmd/plugin/status/status.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -520,7 +520,7 @@ func (fullStatus *PostgresqlStatus) printBackupStatus() {
520520
return
521521
}
522522
status := tabby.New()
523-
FPoR := cluster.Status.FirstRecoverabilityPoint
523+
FPoR := cluster.Status.FirstRecoverabilityPoint //nolint:staticcheck
524524
if FPoR == "" {
525525
FPoR = "Not Available"
526526
}

‎internal/controller/backup_controller_test.go‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -336,9 +336,13 @@ var _ = Describe("update snapshot backup metadata", func() {
336336
})
337337

338338
It("should update cluster with no metadata", func(ctx context.Context) {
339+
//nolint:staticcheck
339340
Expect(cluster.Status.FirstRecoverabilityPoint).To(BeEmpty())
341+
//nolint:staticcheck
340342
Expect(cluster.Status.FirstRecoverabilityPointByMethod).To(BeEmpty())
343+
//nolint:staticcheck
341344
Expect(cluster.Status.LastSuccessfulBackup).To(BeEmpty())
345+
//nolint:staticcheck
342346
Expect(cluster.Status.LastSuccessfulBackupByMethod).To(BeEmpty())
343347
fakeClient := fake.NewClientBuilder().WithScheme(schemeBuilder.BuildWithAllKnownScheme()).
344348
WithObjects(cluster).
@@ -354,24 +358,34 @@ var _ = Describe("update snapshot backup metadata", func() {
354358
Name: cluster.Name,
355359
}, &updatedCluster)
356360
Expect(err).ToNot(HaveOccurred())
361+
//nolint:staticcheck
357362
Expect(updatedCluster.Status.FirstRecoverabilityPoint).To(Equal(twoHoursAgo.Format(time.RFC3339)))
363+
//nolint:staticcheck
358364
Expect(updatedCluster.Status.FirstRecoverabilityPointByMethod).
359365
ToNot(HaveKey(apiv1.BackupMethodBarmanObjectStore))
366+
//nolint:staticcheck
360367
Expect(updatedCluster.Status.FirstRecoverabilityPointByMethod[apiv1.BackupMethodVolumeSnapshot]).
361368
To(Equal(twoHoursAgo))
369+
//nolint:staticcheck
362370
Expect(updatedCluster.Status.LastSuccessfulBackup).To(Equal(oneHourAgo.Format(time.RFC3339)))
371+
//nolint:staticcheck
363372
Expect(updatedCluster.Status.LastSuccessfulBackupByMethod).
364373
ToNot(HaveKey(apiv1.BackupMethodBarmanObjectStore))
374+
//nolint:staticcheck
365375
Expect(updatedCluster.Status.LastSuccessfulBackupByMethod[apiv1.BackupMethodVolumeSnapshot]).
366376
To(Equal(oneHourAgo))
367377
})
368378

369379
It("should consider other methods when update the metadata", func(ctx context.Context) {
380+
//nolint:staticcheck
370381
cluster.Status.FirstRecoverabilityPoint = threeHoursAgo.Format(time.RFC3339)
382+
//nolint:staticcheck
371383
cluster.Status.FirstRecoverabilityPointByMethod = map[apiv1.BackupMethod]metav1.Time{
372384
apiv1.BackupMethodBarmanObjectStore: threeHoursAgo,
373385
}
386+
//nolint:staticcheck
374387
cluster.Status.LastSuccessfulBackup = now.Format(time.RFC3339)
388+
//nolint:staticcheck
375389
cluster.Status.LastSuccessfulBackupByMethod = map[apiv1.BackupMethod]metav1.Time{
376390
apiv1.BackupMethodBarmanObjectStore: now,
377391
}
@@ -389,25 +403,35 @@ var _ = Describe("update snapshot backup metadata", func() {
389403
Name: cluster.Name,
390404
}, &updatedCluster)
391405
Expect(err).ToNot(HaveOccurred())
406+
//nolint:staticcheck
392407
Expect(updatedCluster.Status.FirstRecoverabilityPoint).To(Equal(threeHoursAgo.Format(time.RFC3339)))
408+
//nolint:staticcheck
393409
Expect(updatedCluster.Status.FirstRecoverabilityPointByMethod[apiv1.BackupMethodBarmanObjectStore]).
394410
To(Equal(threeHoursAgo))
411+
//nolint:staticcheck
395412
Expect(updatedCluster.Status.FirstRecoverabilityPointByMethod[apiv1.BackupMethodVolumeSnapshot]).
396413
To(Equal(twoHoursAgo))
414+
//nolint:staticcheck
397415
Expect(updatedCluster.Status.LastSuccessfulBackup).To(Equal(now.Format(time.RFC3339)))
416+
//nolint:staticcheck
398417
Expect(updatedCluster.Status.LastSuccessfulBackupByMethod[apiv1.BackupMethodBarmanObjectStore]).
399418
To(Equal(now))
419+
//nolint:staticcheck
400420
Expect(updatedCluster.Status.LastSuccessfulBackupByMethod[apiv1.BackupMethodVolumeSnapshot]).
401421
To(Equal(oneHourAgo))
402422
})
403423

404424
It("should override other method metadata when appropriate", func(ctx context.Context) {
425+
//nolint:staticcheck
405426
cluster.Status.FirstRecoverabilityPoint = oneHourAgo.Format(time.RFC3339)
427+
//nolint:staticcheck
406428
cluster.Status.FirstRecoverabilityPointByMethod = map[apiv1.BackupMethod]metav1.Time{
407429
apiv1.BackupMethodBarmanObjectStore: oneHourAgo,
408430
apiv1.BackupMethodVolumeSnapshot: now,
409431
}
432+
//nolint:staticcheck
410433
cluster.Status.LastSuccessfulBackup = oneHourAgo.Format(time.RFC3339)
434+
//nolint:staticcheck
411435
cluster.Status.LastSuccessfulBackupByMethod = map[apiv1.BackupMethod]metav1.Time{
412436
apiv1.BackupMethodBarmanObjectStore: twoHoursAgo,
413437
apiv1.BackupMethodVolumeSnapshot: threeHoursAgo,
@@ -426,14 +450,20 @@ var _ = Describe("update snapshot backup metadata", func() {
426450
Name: cluster.Name,
427451
}, &updatedCluster)
428452
Expect(err).ToNot(HaveOccurred())
453+
//nolint:staticcheck
429454
Expect(updatedCluster.Status.FirstRecoverabilityPoint).To(Equal(twoHoursAgo.Format(time.RFC3339)))
455+
//nolint:staticcheck
430456
Expect(updatedCluster.Status.FirstRecoverabilityPointByMethod[apiv1.BackupMethodBarmanObjectStore]).
431457
To(Equal(oneHourAgo))
458+
//nolint:staticcheck
432459
Expect(updatedCluster.Status.FirstRecoverabilityPointByMethod[apiv1.BackupMethodVolumeSnapshot]).
433460
To(Equal(twoHoursAgo))
461+
//nolint:staticcheck
434462
Expect(updatedCluster.Status.LastSuccessfulBackup).To(Equal(oneHourAgo.Format(time.RFC3339)))
463+
//nolint:staticcheck
435464
Expect(updatedCluster.Status.LastSuccessfulBackupByMethod[apiv1.BackupMethodBarmanObjectStore]).
436465
To(Equal(twoHoursAgo))
466+
//nolint:staticcheck
437467
Expect(updatedCluster.Status.LastSuccessfulBackupByMethod[apiv1.BackupMethodVolumeSnapshot]).
438468
To(Equal(oneHourAgo))
439469
})

‎pkg/management/postgres/backup_test.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -136,7 +136,7 @@ var _ = Describe("testing backup command", func() {
136136

137137
It("should fail and update cluster and backup resource", func() {
138138
backupCommand.run(context.Background())
139-
Expect(cluster.Status.LastFailedBackup).ToNot(BeEmpty())
139+
Expect(cluster.Status.LastFailedBackup).ToNot(BeEmpty()) //nolint:staticcheck
140140

141141
clusterCond := meta.FindStatusCondition(cluster.Status.Conditions, string(apiv1.ConditionBackup))
142142
Expect(clusterCond.Status).To(Equal(metav1.ConditionFalse))

0 commit comments

Comments
 (0)