Este documento foi traduzido usando tecnologia de tradução automática de máquina. Sempre trabalhamos para apresentar traduções precisas, mas não oferecemos nenhuma garantia em relação à integridade, precisão ou confiabilidade do conteúdo traduzido. Em caso de qualquer discrepância, a versão original em inglês prevalecerá e constituirá o texto official.

k3s etcd-snapshot

Esta página descreve como usar a ferramenta CLI k3s etcd-snapshot para gerenciar instantâneos do etcd e como restaurar a partir de um instantâneo do etcd.

Os instantâneos do etcd do K3s são armazenados no sistema de arquivos do nó e podem ser opcionalmente enviados para um armazenamento de objetos compatível com S3 para cenários de recuperação de desastres. Os instantâneos podem ser automatizados em um cronograma recorrente e também podem ser feitos manualmente sob demanda. A ferramenta CLI k3s etcd-snapshot oferece um conjunto de subcomandos que podem ser usados para criar, excluir e gerenciar instantâneos.

Subcomando Descrição

Subcomando	Descrição
`delete`	Excluir instantâneo(s) fornecido(s)
`ls`, `list`, `l`	Listar instantâneos
`prune`	Remover instantâneos que excedem a contagem de retenção configurada
`save`	Acionar um instantâneo do etcd sob demanda

delete

Excluir instantâneo(s) fornecido(s)

ls, list, l

Listar instantâneos

prune

Remover instantâneos que excedem a contagem de retenção configurada

save

Acionar um instantâneo do etcd sob demanda

Para informações adicionais sobre os subcomandos de instantâneo do etcd, execute k3s etcd-snapshot --help.

Criando instantâneos

Programados
Sob demanda

Instantâneos programados estão habilitados por padrão, às 00:00 e 12:00 no horário do sistema, com 5 instantâneos retidos. Instantâneos programados têm um nome que começa com etcd-snapshot, seguido pelo nome do nó e pelo timestamp.

As seguintes opções controlam a operação dos instantâneos programados:

Flag Descrição

Flag	Descrição
`--etcd-disable-snapshots`	Desativar instantâneos programados.
`--etcd-snapshot-name`	Define o nome base dos instantâneos programados do etcd. (Padrão: `etcd-snapshot`)
`--etcd-snapshot-compress`	Comprimir instantâneos do etcd.
`--etcd-snapshot-dir`	Diretório para salvar instantâneos do banco de dados. (Local padrão: `$<data-dir>/db/snapshots`)
`--etcd-snapshot-retention`	Número de instantâneos a serem mantidos. (Padrão: 5)
`--etcd-snapshot-schedule-cron`	Tempo de intervalo de instantâneo na especificação cron. Por exemplo, a cada 5 horas `0 /5 * ` (padrão: `0 /12 * * *`).

--etcd-disable-snapshots

Desativar instantâneos programados.

--etcd-snapshot-name

Define o nome base dos instantâneos programados do etcd. (Padrão: etcd-snapshot)

--etcd-snapshot-compress

Comprimir instantâneos do etcd.

--etcd-snapshot-dir

Diretório para salvar instantâneos do banco de dados. (Local padrão: $<data-dir>/db/snapshots)

--etcd-snapshot-retention

Número de instantâneos a serem mantidos. (Padrão: 5)

--etcd-snapshot-schedule-cron

Tempo de intervalo de instantâneo na especificação cron. Por exemplo, a cada 5 horas 0 */5 * * * (padrão: 0 */12 * * *).

O valor de data-dir é, por padrão, /var/lib/rancher/k3s, podendo ser alterado independentemente definindo a flag --data-dir.

Instantâneos agendados são salvos no caminho definido pelo valor --etcd-snapshot-dir do servidor. Se você quiser que eles sejam replicados em armazenamentos de objetos compatíveis com S3, consulte opções de configuração do S3.

Os instantâneos podem ser salvos manualmente executando o comando k3s etcd-snapshot save. Não há retenção para esses instantâneos sob demanda e o usuário precisa removê-los manualmente usando os comandos k3s etcd-snapshot delete ou k3s etcd-snapshot prune. Instantâneos sob demanda têm um nome que começa com on-demand, seguido pelo nome do nó e timestamp.

As seguintes opções controlam a operação de instantâneos sob demanda:

Flag Descrição

Flag	Descrição
`--name`	Define o nome base dos instantâneos sob demanda do etcd. (Padrão: `on-demand`)
`--etcd-snapshot-compress`	Comprimir instantâneos do etcd.
`--etcd-snapshot-dir`	Diretório para salvar instantâneos do banco de dados. (Local padrão: `$<data-dir>/db/snapshots`)

--name

Define o nome base dos instantâneos sob demanda do etcd. (Padrão: on-demand)

--etcd-snapshot-compress

Comprimir instantâneos do etcd.

--etcd-snapshot-dir

Diretório para salvar instantâneos do banco de dados. (Local padrão: $<data-dir>/db/snapshots)

O valor de data-dir é, por padrão, /var/lib/rancher/k3s, podendo ser alterado independentemente definindo a flag --data-dir.

A flag --name só pode ser definida ao executar o comando k3s etcd-snapshot save. Os outros dois também podem fazer parte do k3s server arquivo de configuração.

Instantâneos sob demanda são salvos no caminho definido pelo valor --etcd-snapshot-dir do servidor. Se você quiser que eles sejam replicados em armazenamentos de objetos compatíveis com S3, consulte opções de configuração do S3.

Apagando instantâneos

Instantâneos agendados são excluídos automaticamente quando o número de instantâneos excede a contagem de retenção configurada (5 por padrão). Os instantâneos mais antigos são removidos primeiro.

Para excluir manualmente instantâneo(s) agendado(s) ou instantâneo(s) sob demanda, você pode usar o comando k3s etcd-snapshot delete:

k3s etcd-snapshot delete <SNAPSHOT-NAME-1> <SNAPSHOT-NAME-2> ...

O subcomando prune remove instantâneos que correspondem ao prefixo do nome (on-demand por padrão) e excedem a contagem de retenção configurada. Inclui a flag --snapshot-retention para definir a contagem de retenção. Para instantâneos agendados, substitui a política de retenção padrão. Instantâneos sob demanda não têm política de retenção e, portanto, essa flag é necessária.

Reduzir os instantâneos "sob demanda" para uma quantidade menor:

k3s etcd-snapshot prune --snapshot-retention  <NUM-OF-SNAPSHOTS-TO-RETAIN>

Reduzir os instantâneos "agendados" para uma quantidade menor:

k3s etcd-snapshot prune --name etcd-snapshot --etcd-snapshot-retention <NUM-OF-SNAPSHOTS-TO-RETAIN>

Suporte a Armazenamento de Objetos Compatível com S3

K3s suporta replicar instantâneos etcd para e restaurar instantâneos etcd de armazenamentos de objetos compatíveis com S3. O suporte a S3 está disponível tanto para instantâneos sob demanda quanto agendados.

Flag Descrição

Flag	Descrição
`--etcd-s3`	Habilitar Backup para S3
`--etcd-s3-endpoint`	URL do endpoint S3
`--etcd-s3-endpoint-ca`	Certificado CA personalizado do S3 para conectar ao endpoint S3
`--etcd-s3-skip-ssl-verify`	Desabilita a validação do certificado SSL do S3
`--etcd-s3-access-key`	Chave de acesso S3
`--etcd-s3-secret-key`	Chave secreta S3
`--etcd-s3-bucket`	Nome do bucket S3
`--etcd-s3-region`	Região do S3 / localização do bucket (opcional). Padrão: `us-east-1`.
`--etcd-s3-folder`	Pasta S3
`--etcd-s3-proxy`	Servidor Proxy a ser usado ao conectar ao S3, substituindo quaisquer variáveis de ambiente relacionadas a proxy
`--etcd-s3-insecure`	Desabilita S3 sobre HTTPS
`--etcd-s3-timeout`	Tempo limite do S3 (padrão: `5m0s`)
`--etcd-s3-config-secret`	Nome do segredo no namespace kube-system usado para configurar o S3, se o etcd-s3 estiver habilitado e nenhuma outra opção do etcd-s3 estiver definida

--etcd-s3

Habilitar Backup para S3

--etcd-s3-endpoint

URL do endpoint S3

--etcd-s3-endpoint-ca

Certificado CA personalizado do S3 para conectar ao endpoint S3

--etcd-s3-skip-ssl-verify

Desabilita a validação do certificado SSL do S3

--etcd-s3-access-key

Chave de acesso S3

--etcd-s3-secret-key

Chave secreta S3

--etcd-s3-bucket

Nome do bucket S3

--etcd-s3-region

Região do S3 / localização do bucket (opcional). Padrão: us-east-1.

--etcd-s3-folder

Pasta S3

--etcd-s3-proxy

Servidor Proxy a ser usado ao conectar ao S3, substituindo quaisquer variáveis de ambiente relacionadas a proxy

--etcd-s3-insecure

Desabilita S3 sobre HTTPS

--etcd-s3-timeout

Tempo limite do S3 (padrão: 5m0s)

--etcd-s3-config-secret

Nome do segredo no namespace kube-system usado para configurar o S3, se o etcd-s3 estiver habilitado e nenhuma outra opção do etcd-s3 estiver definida

Por exemplo, é assim que a criação e exclusão de instantâneos etcd sob demanda no S3 funcionariam:

$ k3s etcd-snapshot --s3 --s3-bucket=test-bucket --s3-access-key=test --s3-secret-key=secret save
INFO[0155] Snapshot on-demand-server-0-1753178523 saved.
INFO[0155] Snapshot on-demand-server-0-1753178523 saved.

$ k3s etcd-snapshot --s3 --s3-bucket=test-bucket --s3-access-key=test --s3-secret-key=secret ls
Name                              Location                                                                          Size    Created
on-demand-server-0-1753178523     s3://test-bucket/test-folder/on-demand-server-0-1753178523                        5062688 2025-07-22T10:02:03Z
on-demand-server-0-1753178523     file:///var/lib/rancher/k3s/server/db/snapshots/on-demand-server-0-1753178523     5062688 2025-07-22T10:02:03Z

$ k3s etcd-snapshot --s3 --s3-bucket=test-bucket --s3-access-key=test --s3-secret-key=secret delete on-demand-server-0-1753178523
INFO[0000] Snapshot on-demand-server-0-1753178523 deleted.

$ k3s etcd-snapshot --s3 --s3-bucket=test-bucket --s3-access-key=test --s3-secret-key=secret ls
Name                              Location                                                                          Size    Created

Retenção do S3

Versão Gate

A partir das versões v1.34.0+k3s1, v1.33.4+k3s1, v1.32.8+k3s1, v1.31.12+k3s1, o K3s inclui uma nova flag para retenção do S3. Possui o mesmo valor padrão que a retenção de instantâneos local.

Flag Descrição

Flag	Descrição
`--etcd-s3-retention`	Número de instantâneos no S3 a serem retidos. (Padrão: `5`)

--etcd-s3-retention

Número de instantâneos no S3 a serem retidos. (Padrão: 5)

Suporte a Segredo de configuração do S3

Versão Gate

O suporte a Segredo de configuração do S3 está disponível a partir das versões de agosto de 2024: v1.30.4+k3s1, v1.29.8+k3s1, v1.28.13+k3s1.

O K3s suporta a leitura da configuração de instantâneo do etcd S3 a partir de um Segredo do Kubernetes. Isso pode ser preferido em vez de codificar credenciais nas flags da CLI do K3s ou em arquivos de configuração por razões de segurança, ou se as credenciais precisarem ser rotacionadas sem reiniciar o K3s. Para passar a configuração do instantâneo do S3 via um Segredo, inicie o K3s com --etcd-s3 e --etcd-s3-config-secret=<SECRET-NAME>. O Segredo não precisa existir quando o K3s é iniciado, mas será verificado toda vez que uma operação de salvar/listar/excluir/podar snapshot for realizada.

O Segredo de configuração do S3 não pode ser usado ao restaurar um snapshot, pois o apiserver não está disponível para fornecer o segredo durante uma restauração. A configuração do S3 deve ser passada via CLI ao restaurar um snapshot armazenado no S3.

Passe apenas as flags --etcd-s3 e --etcd-s3-config-secret para habilitar o Segredo. Se qualquer outra flag de configuração do S3 estiver definida, o Segredo será ignorado.

As chaves no Segredo correspondem às flags da CLI --etcd-s3-* listadas acima. A chave etcd-s3-endpoint-ca aceita um pacote CA codificado em PEM, ou a chave etcd-s3-endpoint-ca-name pode ser usada para especificar o nome de um ConfigMap no namespace kube-system contendo um ou mais pacotes CA codificados em PEM.

apiVersion: v1
kind: Secret
metadata:
  name: k3s-etcd-snapshot-s3-config
  namespace: kube-system
type: etcd.k3s.cattle.io/s3-config-secret
stringData:
  etcd-s3-endpoint: ""
  etcd-s3-endpoint-ca: ""
  etcd-s3-endpoint-ca-name: ""
  etcd-s3-skip-ssl-verify: "false"
  etcd-s3-access-key: "AWS_ACCESS_KEY_ID"
  etcd-s3-secret-key: "AWS_SECRET_ACCESS_KEY"
  etcd-s3-bucket: "bucket"
  etcd-s3-folder: "folder"
  etcd-s3-region: "us-east-1"
  etcd-s3-insecure: "false"
  etcd-s3-timeout: "5m"
  etcd-s3-proxy: ""

Restaurando instantâneos

O K3s passa por várias etapas ao restaurar um instantâneo:

Se o instantâneo estiver armazenado no S3, o arquivo é baixado para o diretório de instantâneos.
Se o instantâneo estiver compactado, ele é descompactado.
Se presente, os arquivos de banco de dados etcd atuais são movidos para <data-dir>/server/db/etcd-old-$TIMESTAMP/.
O conteúdo do instantâneo é extraído para o disco e o checksum é verificado.
O etcd é iniciado e todos os membros do cluster etcd, exceto o nó atual, são removidos do cluster.
Os certificados CA e outros dados confidenciais são extraídos do datastore e gravados no disco, para uso posterior.
A restauração está completa e o K3s pode ser reiniciado e usado normalmente no servidor onde a restauração foi realizada.
(opcional) Agentes e servidores de controle podem ser iniciados normalmente.
(opcional) Servidores etcd podem ser reiniciados para reingressar no cluster após a remoção de arquivos de banco de dados antigos.

Ao restaurar um instantâneo, você não precisa usar a mesma versão do K3s que o criou; uma versão minor superior também é aceitável.

Etapas de restauração de instantâneo

Selecione a aba abaixo que corresponde à configuração do seu cluster.

Servidor Único
Múltiplos Servidores

Pare o serviço K3s:
```
systemctl stop k3s
```
Execute k3s server com a flag --cluster-reset, e --cluster-reset-restore-path indicando o caminho para o instantâneo a ser restaurado. Se o instantâneo estiver armazenado no S3, forneça as flags de configuração do S3 (--etcd-s3, --etcd-s3-bucket, e assim por diante), e forneça apenas o nome do arquivo do instantâneo como o caminho de restauração.

Usar a flag --cluster-reset sem especificar um instantâneo para restaurar simplesmente redefine o cluster etcd para um único membro sem restaurar um instantâneo.
```
k3s server \
  --cluster-reset \
  --cluster-reset-restore-path=<PATH-TO-SNAPSHOT>
```
Resultado: O K3s restaura o instantâneo e redefine a membresia do cluster, então imprime uma mensagem indicando que está pronto para ser reiniciado:
Managed etcd cluster membership has been reset, restart without --cluster-reset flag now.
Inicie o K3s novamente:
```
systemctl start k3s
```

Se uma configuração de backup etcd-s3 estiver definida no arquivo de configuração do K3s, a restauração do K3s tentará puxar o arquivo do instantâneo do bucket S3 configurado. Neste caso, apenas o nome do arquivo do instantâneo deve ser passado no argumento --cluster-reset-restore-path. Para restaurar de um arquivo de instantâneo local, onde uma configuração de backup etcd-s3 está presente, adicione o argumento --etcd-s3=false e passe o caminho completo para o arquivo de instantâneo local no argumento --cluster-reset-restore-path.

Como um mecanismo de segurança, quando o K3s redefine o cluster, ele cria um arquivo vazio em /var/lib/rancher/k3s/server/db/reset-flag que impede os usuários de acidentalmente executar várias redefinições de cluster em sucessão. Este arquivo é excluído quando o K3s inicia normalmente.

Neste exemplo, há 3 servidores, S1, S2 e S3. O instantâneo está localizado em S1.

Parar o K3s em todos os servidores:
```
systemctl stop k3s
```
No S1, execute k3s server com a opção --cluster-reset, e --cluster-reset-restore-path indicando o caminho para o instantâneo a ser restaurado. Se o instantâneo estiver armazenado no S3, forneça as flags de configuração do S3 (--etcd-s3, --etcd-s3-bucket, e assim por diante), e forneça apenas o nome do arquivo do instantâneo como o caminho de restauração.

Usar a flag --cluster-reset sem especificar um instantâneo para restaurar simplesmente redefine o cluster etcd para um único membro sem restaurar um instantâneo.
```
k3s server \
  --cluster-reset \
  --cluster-reset-restore-path=<PATH-TO-SNAPSHOT>
```
Resultado: O K3s restaura o instantâneo e redefine a associação do cluster, então imprime uma mensagem indicando que está pronto para ser reiniciado: Managed etcd cluster membership has been reset, restart without --cluster-reset flag now. Backup and delete ${datadir}/server/db on each peer etcd server and rejoin the nodes.
No S1, inicie o K3s novamente:
```
systemctl start k3s
```
No S2 e S3, exclua o diretório de dados, /var/lib/rancher/k3s/server/db/:
```
rm -rf /var/lib/rancher/k3s/server/db/
```
No S2 e S3, inicie o K3s novamente para se juntar ao cluster restaurado:
```
systemctl start k3s
```

Se uma configuração de backup etcd-s3 estiver definida no arquivo de configuração do K3s, a restauração do K3s tenta extrair o arquivo de instantâneo do bucket S3 configurado. Neste caso, apenas o nome do arquivo de instantâneo deve ser passado no argumento --cluster-reset-restore-path. Para restaurar de um arquivo de instantâneo local, onde uma configuração de backup etcd-s3 está presente, adicione o argumento --etcd-s3=false e passe o caminho completo para o arquivo de instantâneo local no argumento --cluster-reset-restore-path.

Restaurando Para Novos Hosts

É possível restaurar um instantâneo etcd em um host diferente de onde foi tirado. Ao fazer isso, você deve passar o token do servidor que foi usado originalmente ao tirar o instantâneo, pois ele é usado para descriptografar os dados de inicialização dentro do instantâneo. O processo é o mesmo que acima, mas mudando o passo 2 para:

No nó que tirou o instantâneo, salve o valor de: /var/lib/rancher/k3s/server/token. Isto é <BACKED-UP-TOKEN-VALUE> no passo 3.
Copie o instantâneo para o novo nó. O caminho no nó é <PATH-TO-SNAPSHOT> no passo 3.
Inicie a restauração do instantâneo no primeiro nó do servidor com os seguintes comandos:
```
k3s server \
  --cluster-reset \
  --cluster-reset-restore-path=<PATH-TO-SNAPSHOT>
  --token=<BACKED-UP-TOKEN-VALUE>
```
O valor do token também pode ser definido no arquivo de configuração do K3s.

Os recursos do nó também estão incluídos no instantâneo do etcd. Se estiver restaurando para um novo conjunto de nós, você precisa excluir manualmente quaisquer nós antigos que não estão mais presentes no cluster.
Se houver um token definido no arquivo de configuração do K3s, certifique-se de que seja o mesmo que o <BACKED-UP-TOKEN-VALUE>, caso contrário, o K3s não consegue iniciar.

Recursos Personalizados do ETCDSnapshotFile

Versão Gate

Os ETCDSnapshotFiles estão disponíveis a partir das versões de novembro de 2023: v1.28.4+k3s2, v1.27.8+k3s2, v1.26.11+k3s2, v1.25.16+k3s4.

Os instantâneos podem ser visualizados remotamente usando qualquer cliente Kubernetes, listando ou descrevendo recursos ETCDSnapshotFile com escopo de cluster. Diferente do comando k3s etcd-snapshot list, que mostra apenas instantâneos visíveis para aquele nó, os recursos ETCDSnapshotFile rastreiam todos os instantâneos presentes nos membros do cluster.

$ kubectl get etcdsnapshotfile
NAME                                             SNAPSHOTNAME                        NODE           LOCATION                                                                            SIZE      CREATIONTIME
local-on-demand-k3s-server-1-1730308816-3e9290   on-demand-k3s-server-1-1730308816   k3s-server-1   file:///var/lib/rancher/k3s/server/db/snapshots/on-demand-k3s-server-1-1730308816   2891808   2024-10-30T17:20:16Z
s3-on-demand-k3s-server-1-1730308816-79b15c      on-demand-k3s-server-1-1730308816   s3             s3://etcd/k3s-test/on-demand-k3s-server-1-1730308816                                2891808   2024-10-30T17:20:16Z

$ kubectl describe etcdsnapshotfile s3-on-demand-k3s-server-1-1730308816-79b15c
Name:         s3-on-demand-k3s-server-1-1730308816-79b15c
Namespace:
Labels:       etcd.k3s.cattle.io/snapshot-storage-node=s3
Annotations:  etcd.k3s.cattle.io/snapshot-token-hash: b4b83cda3099
API Version:  k3s.cattle.io/v1
Kind:         ETCDSnapshotFile
Metadata:
  Creation Timestamp:  2024-10-30T17:20:16Z
  Finalizers:
    wrangler.cattle.io/managed-etcd-snapshots-controller
  Generation:        1
  Resource Version:  790
  UID:               bec9a51c-dbbe-4746-922e-a5136bef53fc
Spec:
  Location:   s3://etcd/k3s-test/on-demand-k3s-server-1-1730308816
  Node Name:  s3
  s3:
    Bucket:           etcd
    Endpoint:         s3.example.com
    Prefix:           k3s-test
    Region:           us-east-1
    Skip SSL Verify:  true
  Snapshot Name:      on-demand-k3s-server-1-1730308816
Status:
  Creation Time:  2024-10-30T17:20:16Z
  Ready To Use:   true
  Size:           2891808
Events:
  Type    Reason               Age   From            Message
  ----    ------               ----  ----            -------
  Normal  ETCDSnapshotCreated  113s  k3s-supervisor  Snapshot on-demand-k3s-server-1-1730308816 saved on S3