mirror of
https://github.com/gravitational/teleport.git
synced 2026-10-11 22:49:54 +00:00
Paul Gottschling
b19268b07b
* Add a Configuring Teleport docs section Make the how-to guides for managing Teleport resources with Infrastructure as Code tools more prominent by placing them in a Configuring Teleport section next to other foundational docs sections, e.g., Installation and Upgrading. Frame the task of managing Teleport with IaC as part of the broader task of configuring Teleport. To do so, move the introduction of the "Static and Dynamic Resources" page to a landing page for the new Configuration section. Move the remaining part of that page to the References section, since it's an advanced guide and more of a reference than a set of how-to instructions. This change also structures the Infrastructure as Code landing page into a Configure Teleport landing page by including links to guides for static as well as dynamic configuration. This adds clarity to the docs since users won't immediately know that Teleport exposes these two configuration variants. * Update internal links * Fix issues with the Configuring Teleport section - Update the static/dynamic field table to use the correct field name, `spec.mode`. - Change "Managing Resources" to "Resource Guides" for clarity, since all sections in Configuring Teleport would be about managing resources. - Reorder Configuration sidebar sections to move Resource Guides last and tctl before Terraform and Kubernetes.
192 lines
8.2 KiB
Plaintext
192 lines
8.2 KiB
Plaintext
---
|
|
title: Backup and Restore
|
|
description: How to back up and restore your Teleport cluster state.
|
|
tags:
|
|
- conceptual
|
|
- platform-wide
|
|
---
|
|
|
|
Operators must have a plan in place to back up self-hosted Teleport clusters.
|
|
While the Teleport Proxy Service and Teleport Agent services are stateless, you
|
|
should ensure that you can restore their configuration files. The Teleport Auth
|
|
Service manages state for the entire cluster, and it is critical that you can
|
|
back up its data. This guide explains the components of a Teleport Auth Service
|
|
deployment that must be backed up and lays out our recommended approach for
|
|
performing backups.
|
|
|
|
(!docs/pages/includes/cloud/call-to-action.mdx!)
|
|
|
|
## Data to back up
|
|
|
|
You must back up data that the Auth Service manages across its three backends:
|
|
|
|
- Cluster state backend
|
|
- Audit event backend
|
|
- Session recording backend
|
|
|
|
See [Storage Backends](../../reference/deployment/backends.mdx) for more information on
|
|
Teleport backends.
|
|
|
|
The following table summarizes the kinds of backend data the Auth Service
|
|
maintains:
|
|
|
|
| What | Where |
|
|
| - | - |
|
|
| Local Users (not SSO) | Cluster state backend |
|
|
| Certificate Authorities | Cluster state backend |
|
|
| Dynamic resources ([more information below](#versioning-dynamic-resources-with-infrastructure-as-code)) | Cluster state backend |
|
|
| teleport.yaml | File system |
|
|
| teleport.service | File system |
|
|
| license.pem | File system |
|
|
| TLS key/certificate | File system or third-party service (e.g., AWS Certificate Manager)|
|
|
| Audit log | Audit event backend |
|
|
| Session recordings | Session recording backend |
|
|
|
|
## Backing up Teleport backends
|
|
|
|
Your plan for backing up the Teleport cluster state and session recording
|
|
backends depends on the solution you use for each backend. The following table
|
|
includes instructions for backing up each backend solution. For backends not
|
|
listed here, consult the documentation for your backend:
|
|
|
|
### Cluster state and audit event backends
|
|
|
|
For the most part, you can use the same solution for both cluster state and
|
|
audit events, setting aside a separate table for each kind of backend. The
|
|
exception is etcd, which can only function as a cluster state backend. (See a
|
|
full explanation in [Storage Backends](../../reference/deployment/backends.mdx#etcd).)
|
|
|
|
| Backend | Recommended backup strategy |
|
|
| - | - |
|
|
| Local Filesystem | Back up the data directory (`/var/lib/teleport/` by default) |
|
|
| DynamoDB | [Amazon DynamoDB documentation](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Backup-and-Restore.html) |
|
|
| etcd | [etcd documentation](https://etcd.io/docs/v2.3/admin_guide/#disaster-recovery) |
|
|
| Firestore | [Firestore documentation](https://firebase.google.com/docs/database/backups) |
|
|
| Azure Database for PostgreSQL | [Azure Database for PostgreSQL documentation](https://learn.microsoft.com/en-us/azure/backup/backup-azure-database-postgresql) |
|
|
| Cloud SQL for PostgreSQL | [Cloud SQL for PostgreSQL documentation](https://cloud.google.com/sql/docs/postgres/backup-recovery/backups) |
|
|
|
|
### Session recording backends
|
|
|
|
| Backend | Recommended backup strategy |
|
|
| - | - |
|
|
| Local Filesystem | Back up the data directory (`/var/lib/teleport/` by default) |
|
|
| S3 | [Amazon S3 documentation](https://docs.aws.amazon.com/aws-backup/latest/devguide/s3-backups.html) |
|
|
| GCS | GCS has [built-in redundancy](https://cloud.google.com/storage/docs/availability-durability), but you may also use [cross-bucket replication](https://cloud.google.com/storage/docs/using-cross-bucket-replication) |
|
|
| Azure Blob Storage | [Azure Blob backup documentation](https://learn.microsoft.com/en-us/azure/backup/blob-backup-overview)|
|
|
|
|
## Versioning dynamic resources with infrastructure as code
|
|
|
|
Teleport uses [dynamic
|
|
resources](../../configuration/configuration.mdx) for roles, local users,
|
|
authentication connectors, and other configurations, and stores dynamic resource
|
|
data on the cluster state backend. Backing up the cluster state backend protects
|
|
your cluster against the loss of dynamic resource data.
|
|
|
|
For more control over the version of a dynamic resource that you back up and
|
|
restore, we recommend storing dynamic resource manifests in a code repository
|
|
that uses a version control system. You can use a continuous deployment pipeline
|
|
to apply configurations automatically, so your Teleport cluster always reflects
|
|
the latest state of your dynamic resources.
|
|
|
|
If you need to revert to an earlier version of a resource (e.g., to correct a
|
|
misconfiguration), you can restore the resource on your code repository without
|
|
conducting a full restore of the cluster state backend.
|
|
|
|
Teleport provides the following infrastructure as code tools for managing
|
|
dynamic resources:
|
|
|
|
- [Terraform
|
|
provider](../../configuration/terraform-provider/terraform-provider.mdx)
|
|
- [Kubernetes
|
|
operator](../../configuration/teleport-operator/teleport-operator.mdx)
|
|
|
|
## Cloning a backend
|
|
|
|
You can clone a Teleport Auth Service backend by instructing Teleport to
|
|
retrieve all items from one backend and store them in another backend. You can
|
|
use this operation to, for example, migrate data to a new backend or back up
|
|
data from one region to another.
|
|
|
|
This operation uses the `teleport backend clone` command with a configuration
|
|
file that includes information about the source and destination backends. The
|
|
`teleport` process running the clone must have access to credentials for both
|
|
backends. If you complete the instructions below on a virtual machine or
|
|
Kubernetes pod that usually runs the Teleport Auth Service, you can expect the
|
|
`teleport` process to have the required permissions.
|
|
|
|
1. Write a configuration file for the clone. Create a file called `clone.yaml`
|
|
that includes the following structure:
|
|
|
|
```yaml
|
|
# src is the configuration for the backend where data is cloned from.
|
|
src:
|
|
type: dynamodb
|
|
region: us-east-1
|
|
table_name: teleport_backend
|
|
# dst is the configuration for the backend where data is cloned to.
|
|
dst:
|
|
type: sqlite
|
|
path: /var/lib/teleport_data
|
|
# parallel is the amount of backend data cloned in parallel.
|
|
# If a clone operation is taking too long consider increasing this value.
|
|
parallel: 100
|
|
```
|
|
|
|
This example clones backend data in Amazon DynamoDB to a SQLite database.
|
|
|
|
1. Update the `src` and `dst` sections of the clone configuration file to
|
|
include information about the source and destination backends. Possible
|
|
values of `src` and `dst` are the same as the `teleport.storage` section in
|
|
the Teleport configuration file. See the [Storage
|
|
Backends](../../reference/deployment/backends.mdx) reference for the configuration
|
|
fields to assign for each backend.
|
|
|
|
1. Run the following command on an Auth Service instance to execute the clone
|
|
operation. The value of the `-c` flag is the configuration file you created
|
|
earlier:
|
|
|
|
```code
|
|
$ sudo teleport backend clone -c clone.yaml
|
|
```
|
|
|
|
You can run the `teleport backend clone` command on an Auth Service instance
|
|
without stopping your cluster. The command retrieves each item from the source
|
|
backend and writes it to the destination backend. Any items created on the
|
|
source backend after the initial retrieval will not be included in the clone.
|
|
|
|
|
|
## Rollbacks
|
|
|
|
Rollbacks can be performed without any backend corruption or data loss by leveraging
|
|
`teleport backend clone` to create a copy of an existing backend. For example, prior
|
|
to upgrading a cluster from Teleport v18 to v19 the following clone configuration can
|
|
be used to make a full clone of the Teleport backend state to a different key range of
|
|
the same etcd cluster using the `prefix` field. See the etcd storage backend
|
|
[configuration reference](../../reference/deployment/backends.mdx#etcd) for an explanation:
|
|
|
|
```yaml
|
|
src:
|
|
type: etcd
|
|
prefix: teleport
|
|
peers: [https://peer.example.com:2379]
|
|
dst:
|
|
type: etcd
|
|
prefix: teleport-v18-backup
|
|
peers: [https://peer.example.com:2379]
|
|
parallel: 100
|
|
```
|
|
|
|
Teleport major releases may alter the backend state in a way that
|
|
previous versions cannot reconcile. If the upgrade to v19 fails
|
|
and requires a rollback, this can be achieved by editing the
|
|
Auth Service configuration to point it at the prefix containing
|
|
the v18 backup.
|
|
|
|
```yaml
|
|
teleport:
|
|
storage:
|
|
type: etcd
|
|
prefix: teleport-v18-backup
|
|
peers: [https://peer.example.com:2379]
|
|
```
|