Skip to content

Commit b647ce7

Browse files
gbartolinijsilvela
authored andcommitted
docs: explain snapshotOwnerReference field
Closes #2881 Signed-off-by: Gabriele Bartolini <[email protected]>
1 parent d916fae commit b647ce7

3 files changed

Lines changed: 52 additions & 5 deletions

File tree

‎api/v1/cluster_types.go‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -144,9 +144,9 @@ type VolumeSnapshotConfiguration struct {
144144
// WalClassName specifies the Snapshot Class to be used for the PG_WAL PersistentVolumeClaim.
145145
// +optional
146146
WalClassName string `json:"walClassName,omitempty"`
147-
// SnapshotOwnerReference indicates the type of owner reference the snapshot should have. .
147+
// SnapshotOwnerReference indicates the type of owner reference the snapshot should have
148148
// +optional
149-
// +kubebuilder:validation:Enum=none;cluster;backup
149+
// +kubebuilder:validation:Enum:=none;cluster;backup
150150
// +kubebuilder:default:=none
151151
SnapshotOwnerReference SnapshotOwnerReference `json:"snapshotOwnerReference,omitempty"`
152152
}
@@ -279,7 +279,7 @@ type ClusterSpec struct {
279279
MaxStopDelay int32 `json:"stopDelay,omitempty"`
280280

281281
// The time in seconds that controls the window of time reserved for the smart shutdown of Postgres to complete.
282-
// this formula to compute the timeout of smart shutdown is `max(stopDelay - smartStopDelay, 30)`,
282+
// this formula to compute the timeout of smart shutdown is `max(stopDelay - smartStopDelay, 30)`
283283
// +kubebuilder:default:=180
284284
// +optional
285285
SmartStopDelay int32 `json:"smartStopDelay,omitempty"`

‎docs/src/backup_volumesnapshot.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,9 +103,56 @@ As you can see, the `backup` section contains both the `volumeSnapshot` stanza
103103
both volume snapshot and object store backup strategies simultaneously
104104
to take physical backups.
105105

106+
The `volumeSnapshot.className` option allows you to reference the default
107+
`VolumeSnapshotClass` object used for all the storage volumes you have
108+
defined in your PostgreSQL cluster.
109+
110+
!!! Info
111+
In case you are using a different storage class for `PGDATA` and
112+
WAL files, you can specify a separate `VolumeSnapshotClass` for
113+
that volume through the `walClassName` option (by default set to
114+
`className`).
115+
106116
Once a cluster is defined for volume snapshot backups, you need to define
107117
a `ScheduledBackup` resource that requests such backups on a periodic basis.
108118

119+
## Persistence of volume snapshot objects
120+
121+
By default, `VolumeSnapshot` objects created by CloudNativePG are retained after
122+
deleting the `Backup` object that originated them, or the `Cluster` they refer to.
123+
Such behavior is controlled by the `.spec.backup.volumeSnapshot.snapshotOwnerReference`
124+
option which accepts the following values:
125+
126+
- `none`: no ownership is set, meaning that `VolumeSnapshot` objects persist
127+
after the `Backup` and/or the `Cluster` resources are removed
128+
- `backup`: the `VolumeSnapshot` object is owned by the `Backup` resource that
129+
originated it, and when the backup object is removed, the volume snapshot is
130+
also removed
131+
- `cluster`: the `VolumeSnapshot` object is owned by the `Cluster` resource that
132+
is backed up, and when the Postgres cluster is removed, the volume snapshot is
133+
also removed
134+
135+
In case a `VolumeSnapshot` is deleted, the `deletionPolicy` specified in the
136+
`VolumeSnapshotContent` is evaluated:
137+
138+
- if set to `Retain`, the `VolumeSnapshotContent` object is kept
139+
- if set to `Delete`, the `VolumeSnapshotContent` object is removed as well
140+
141+
!!! Warning
142+
`VolumeSnapshotContent` object do not keep all the information regarding the
143+
backup and the cluster they refer to (like the annotations and labels that
144+
are contained in the `VolumeSnapshot` object). Although possible, it might not be
145+
straightforward to restore from just this kind of objects. For this reason,
146+
our recommendation is to always backup the `VolumeSnapshot` definitions somewhere,
147+
even using a Kubernetes level data protection solution.
148+
149+
The value in `VolumeSnapshotContent` is determined by the `deletionPolicy` set
150+
in the corresponding `VolumeSnapshotClass` definition, the one that you
151+
have referenced in the `.spec.backup.volumeSnapshot.className` option.
152+
153+
Please refer to the [Kubernetes documentation on Volume Snapshot Classes](https://kubernetes.io/docs/concepts/storage/volume-snapshot-classes/)
154+
for details on this standard behavior.
155+
109156
## Example
110157

111158
The following example shows how to configure volume snapshot base backups on an

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1469,7 +1469,7 @@ gracefully shutdown (default 1800)</p>
14691469
</td>
14701470
<td>
14711471
<p>The time in seconds that controls the window of time reserved for the smart shutdown of Postgres to complete.
1472-
this formula to compute the timeout of smart shutdown is <code>max(stopDelay - smartStopDelay, 30)</code>,</p>
1472+
this formula to compute the timeout of smart shutdown is <code>max(stopDelay - smartStopDelay, 30)</code></p>
14731473
</td>
14741474
</tr>
14751475
<tr><td><code>switchoverDelay</code><br/>
@@ -4243,7 +4243,7 @@ It is the default class for the other types if no specific class is present</p>
42434243
<a href="#postgresql-cnpg-io-v1-SnapshotOwnerReference"><i>SnapshotOwnerReference</i></a>
42444244
</td>
42454245
<td>
4246-
<p>SnapshotOwnerReference indicates the type of owner reference the snapshot should have. .</p>
4246+
<p>SnapshotOwnerReference indicates the type of owner reference the snapshot should have</p>
42474247
</td>
42484248
</tr>
42494249
</tbody>

0 commit comments

Comments
 (0)