Skip to content

Commit 7d57227

Browse files
authored
docs: Add zero data loss example to backup and restore guide (#60751)
A new section is added to the guide which describes how `teleport backend clone` can be leveraged to ensure that data loss is mitigated if a major version downgrade is required.
1 parent b83c932 commit 7d57227

File tree

1 file changed

+36
-4
lines changed

1 file changed

+36
-4
lines changed

docs/pages/zero-trust-access/management/operations/backup-restore.mdx

Lines changed: 36 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -130,10 +130,6 @@ Kubernetes pod that usually runs the Teleport Auth Service, you can expect the
130130
# parallel is the amount of backend data cloned in parallel.
131131
# If a clone operation is taking too long consider increasing this value.
132132
parallel: 100
133-
# force, if set to true, will continue cloning data to a destination
134-
# regardless of whether data is already present. By default this is false
135-
# to protect against overwriting the data of an existing Teleport cluster.
136-
force: false
137133
```
138134
139135
This example clones backend data in Amazon DynamoDB to a SQLite database.
@@ -157,3 +153,39 @@ You can run the `teleport backend clone` command on an Auth Service instance
157153
without stopping your cluster. The command retrieves each item from the source
158154
backend and writes it to the destination backend. Any items created on the
159155
source backend after the initial retrieval will not be included in the clone.
156+
157+
158+
## Rollbacks
159+
160+
Rollbacks can be performed without any backend corruption or data loss by leveraging
161+
`teleport backend clone` to create a copy of an existing backend. For example, prior
162+
to upgrading a cluster from Teleport v18 to v19 the following clone configuration can
163+
be used to make a full clone of the Teleport backend state to a different key range of
164+
the same etcd cluster using the `prefix` field. See the etcd storage backend
165+
[configuration reference](../../../reference/deployment/backends.mdx#etcd) for an explanation:
166+
167+
```yaml
168+
src:
169+
type: etcd
170+
prefix: teleport
171+
peers: [https://peer.example.com:2379]
172+
dst:
173+
type: etcd
174+
prefix: teleport-v18-backup
175+
peers: [https://peer.example.com:2379]
176+
parallel: 100
177+
```
178+
179+
Teleport major releases may alter the backend state in a way that
180+
previous versions cannot reconcile. If the upgrade to v19 fails
181+
and requires a rollback, this can be achieved by editing the
182+
Auth Service configuration to point it at the prefix containing
183+
the v18 backup.
184+
185+
```yaml
186+
teleport:
187+
storage:
188+
type: etcd
189+
prefix: teleport-v18-backup
190+
peers: [https://peer.example.com:2379]
191+
```

0 commit comments

Comments
 (0)