Salvar e carregar snapshots do ambiente

Airflow Gerenciado (Geração 3) | Airflow Gerenciado (Geração 2) | Airflow Gerenciado (Geração 1 legada)

Nesta página, explicamos como salvar e carregar o estado do ambiente usando snapshots.

Você pode configurar o ambiente para salvar snapshots automaticamente. Para mais informações, consulte Configurar snapshots programados.

Sobre snapshots de ambiente

Os snapshots de ambiente armazenam o estado do ambiente. É possível salvar e carregar snapshots de ambiente sob demanda.

Você pode usar snapshots para:

  • Restaurar o ambiente para um estado anterior. Crie backups do ambiente usando snapshots e carregue um deles para restaurar o ambiente. Por exemplo, é possível reverter uma operação de atualização que instala pacotes PyPI ou substitui opções de configuração do Airflow, mesmo depois que o ambiente é atualizado.

  • Realizar upgrades lado a lado e copiar ambientes. Crie um snapshot de um ambiente atual, crie um novo ambiente que use a mesma versão ou uma versão mais recente do Airflow Gerenciado e aplique o snapshot a esse novo ambiente. Esse procedimento é semelhante à migração. Pause os DAGs antes de criar o snapshot para evitar execuções duplicadas de DAGs.

  • Migrar seus ambientes para o Airflow Gerenciado (Geração 3).

Como os snapshots são armazenados

Um snapshot de ambiente é um conjunto de arquivos que descrevem o estado do ambiente e armazenam o backup dos dados do ambiente.

É possível criar vários snapshots do ambiente. Os snapshots de ambiente não são incrementais. Você pode usar qualquer snapshot de forma independente de outros snapshots.

O Airflow Gerenciado não exclui snapshots quando você exclui o ambiente.

Por padrão, o Airflow Gerenciado armazena snapshots na pasta snapshots/ no bucket do ambiente. Também é possível especificar um local personalizado ao criar um snapshot.

Embora a interface do Cloud Storage mostre os dados como pastas para facilitar o uso, os buckets funcionam em uma estrutura de arquivo simples. Isso não muda a forma como você trabalha com o salvamento e o carregamento de snapshots no Google Cloud console, mas tenha isso em mente ao realizar operações diretamente nos arquivos do bucket. Para mais informações, consulte Namespace de objetos.

Considerações de segurança para snapshots

Para mitigar esse risco de segurança, armazene informações confidenciais usadas por DAGs do Airflow, como chaves ou senhas, no Secret Manager. Para mais informações, consulte Configurar o Secret Manager para seu ambiente.

Verifique as permissões de segurança do bucket do ambiente. Se você armazenar snapshots de ambiente em um bucket personalizado, verifique se as permissões de acesso a ele estão configuradas corretamente no seu projeto. Ao atribuir permissões, verifique se a conta de serviço do ambiente tem permissões suficientes para salvar e carregar snapshots do bucket.

Quais dados são salvos em snapshots

O Airflow Gerenciado salva os seguintes dados em snapshots:

  • Substituições da configuração do Airflow.
  • Variáveis de ambiente.
  • Lista de pacotes PyPI personalizados, como requisitos.
  • Um backup do banco de dados do Airflow, incluindo estados de tarefas executadas e histórico de execuções de DAGs.
  • Um backup das pastas /dags, /data e /plugins do bucket do ambiente.
  • Chave fernet do ambiente.
  • Outras informações sobre a configuração do ambiente, como parâmetros de escala e desempenho. O Airflow Gerenciado não usa essas informações ao carregar snapshots.

Quais dados são carregados de snapshots

O Airflow Gerenciado carrega os seguintes dados de snapshots:

  • Substituições da configuração do Airflow.
  • Variáveis de ambiente.

  • Pacotes PyPI personalizados (a menos que você opte por pular a instalação).

  • O conteúdo do banco de dados do Airflow, incluindo estados de tarefas executadas e histórico de execuções de DAGs.

  • O conteúdo das pastas /dags, /data e /plugins do snapshot é carregado no bucket do ambiente.

  • A chave fernet do snapshot é usada para criptografar novamente os dados do snapshot com a própria chave fernet do ambiente. A chave fernet do ambiente permanece inalterada.

Embora o Airflow Gerenciado armazene algumas informações sobre a configuração do ambiente em snapshots, elas não são usadas ao carregar snapshots. Os parâmetros a seguir do ambiente não mudam quando você carrega um snapshot:

  • Configuração do ambiente, como parâmetros de escala e desempenho.
  • Configuração de rede do ambiente.
  • Conteúdo do bucket do ambiente fora das pastas /dags, /data e /plugins.
  • Rótulos de ambiente.

Todas as configurações aplicadas na infraestrutura do Airflow Gerenciado sem usar a API Composer podem ser perdidas ao carregar um snapshot.

Sobre operações parcialmente concluídas

Ao carregar um snapshot, a operação pode ser bem-sucedida, falhar ou ser parcialmente concluída:

  • As operações bem-sucedidas carregam todos os dados do snapshot.
  • As operações com falha não introduzem mudanças.
  • As operações parcialmente concluídas carregam um subconjunto de dados do snapshot. Essas operações são informadas como com falha, mas a mensagem de erro indica quais dados foram carregados. Por exemplo, se os pacotes PyPI forem instalados, mas as substituições da opção de configuração do Airflow não forem bem-sucedidas, a mensagem de erro indicará isso.

Para uma operação parcialmente concluída, tente carregar o mesmo snapshot novamente. O Airflow Gerenciado pula as etapas que foram bem-sucedidas na tentativa anterior. Por exemplo, se uma operação falhou em um tempo limite, mas o banco de dados foi carregado, a próxima tentativa não carregará o banco de dados novamente.

Antes de começar

  • Os snapshots são compatíveis com o Airflow Gerenciado (Geração 2) versão 2.0.9 e mais recentes. O Airflow Gerenciado (Geração 1 legada) oferece suporte ao salvamento de snapshots de ambiente na versão 1.18.5 e mais recentes.

  • Os snapshots não criam um ambiente. Se você quiser carregar um snapshot de um ambiente para outro, primeiro crie um novo ambiente e carregue o snapshot nele.

  • Não é possível carregar snapshots em ambientes que estão em estado de erro. Não é possível corrigir esses ambientes carregando um snapshot. Ainda é possível carregar um snapshot atual em um novo ambiente.

  • Só é possível carregar snapshots para a mesma versão ou uma versão mais recente do Airflow Gerenciado ou do Airflow. Por exemplo, não é possível carregar um snapshot do Airflow Gerenciado 2.8.4 para um ambiente com o Airflow Gerenciado 2.8.3. Como outro exemplo, não é possível carregar um snapshot do Airflow 2.7.3 para o Airflow 2.6.3.

  • Os snapshots não mudam a versão do Airflow Gerenciado. Se você fizer upgrade do ambiente para uma versão mais recente do Airflow Gerenciado e carregar um snapshot de uma versão anterior, o ambiente ainda manterá a versão atual do Airflow Gerenciado. Por exemplo, carregar um snapshot do Airflow Gerenciado 2.8.3 para o Airflow Gerenciado 2.8.4 não reverte o ambiente para o Airflow Gerenciado 2.8.3.

  • O tamanho máximo do banco de dados do Airflow que oferece suporte a snapshots é de 20 GB. Se o banco de dados do ambiente ocupar mais de 20 GB, reduza o tamanho do banco de dados do Airflow antes de salvar um snapshot.

  • O número total de objetos nas pastas /dags, /plugins e /data no bucket do ambiente precisa ser menor que 100.000 para criar snapshots.

  • Se você usar o mecanismo XCom para transferir arquivos, certifique-se de que você o use de acordo com as diretrizes do Airflow. A transferência de arquivos grandes ou de um grande número de arquivos usando o XCom afeta o desempenho do banco de dados do Airflow e pode levar a falhas ao carregar snapshots ou fazer upgrade do ambiente. Considere usar alternativas como o Cloud Storage para transferir grandes volumes de dados.

  • O comprimento máximo do nome de um objeto no bucket do ambiente não pode ser maior que 1.024 símbolos. Caso contrário, não será possível criar snapshots.

  • Se você salvar snapshots em um local fora do bucket do ambiente, a conta de serviço do ambiente precisará ter permissões de leitura e gravação para o local especificado. Por exemplo, o papel de Administrador de objetos do Storage tem essas permissões. É possível aplicá-lo a um projeto ou a um bucket específico.

  • A criação e o armazenamento de snapshots geram custos adicionais relacionados ao Cloud Storage. Para mais informações, consulte Preços.

Salvar um snapshot de ambiente

O Airflow Gerenciado salva snapshots de ambiente em uma subpasta, em relação à pasta especificada. O nome da pasta contém o ID do projeto, o local do ambiente, o nome do ambiente e o carimbo de data/hora em que o snapshot foi salvo. Por exemplo: /snapshots/example-project_us-central1_example-environment_2022-01-05T18-59-00.

Console

Para criar um snapshot do ambiente:

  1. No Google Cloud console, acesse a página Ambientes.

    Acessar "Ambientes"

  2. Na lista de ambientes, clique no nome do ambiente. A página Detalhes do ambiente será aberta.

  3. Clique em Salvar snapshot.

  4. Na caixa de diálogo Salvar snapshot, selecione onde armazenar o snapshot:

    • Para armazenar o snapshot na pasta /snapshots no bucket do ambiente, selecione Usar pasta de snapshots no bucket do ambiente (padrão).

    • Para armazenar o snapshot na pasta personalizada, selecione Usar pasta personalizada em outro bucket e especifique um local.

  5. Clique em Salvar.

gcloud

O comando gcloud composer environments snapshots save salva um snapshot do ambiente.

  • O argumento snapshot-location especifica uma pasta em que o snapshot é salvo. Por padrão, os snapshots são salvos na pasta /snapshots no bucket do ambiente. Por exemplo, gs://us-central1-example-916807e1-bucket/snapshots. Também é possível especificar qualquer outra pasta.

Para salvar um snapshot do ambiente, execute:

gcloud composer environments snapshots save \
  ENVIRONMENT_NAME \
  --location LOCATION \
  --snapshot-location "SNAPSHOTS_FOLDER"

Substitua:

  • ENVIRONMENT_NAME pelo nome do ambiente
  • LOCATION pela região em que o ambiente está localizado
  • (Opcional) SNAPSHOTS_FOLDER pelo URI de uma pasta de bucket em que o snapshot será armazenado. Se você omitir esse argumento, o Airflow Gerenciado salvará o snapshot na pasta /snapshots no bucket do ambiente.

O exemplo a seguir usa o local padrão:

gcloud composer environments snapshots save \
  example-environment \
  --location us-central1

O exemplo a seguir salva em uma pasta personalizada:

gcloud composer environments snapshots save \
  example-environment \
  --location us-central1 \
  --snapshot-location "gs://example-bucket/environment_snapshots"

API

  1. Crie uma solicitação de environments.saveSnapshot API.

  2. No corpo da solicitação, no campo snapshotLocation, especifique a pasta em que você quer salvar o snapshot.

{
  "snapshotLocation": "SNAPSHOTS_FOLDER"
}

Substitua:

  • SNAPSHOTS_FOLDER pelo URI de uma pasta de bucket em que o snapshot será salvo.

Exemplo:

// POST https://composer.googleapis.com/v1/projects/example-project/
// locations/us-central1/environments/example-environment:saveSnapshot

{
  "snapshotLocation": "gs://us-central1-example-916807e1-bucket/snapshots"
}

Terraform

Não é possível salvar e carregar snapshots de ambiente do Terraform.

Salvar e carregar snapshots são ações realizadas em um ambiente, e os snapshots resultantes não fazem parte da definição de um ambiente. Como o Terraform gerencia apenas a configuração do ambiente do Airflow Gerenciado, não é possível salvar ou carregar snapshots de ambiente.

Carregar um snapshot de ambiente

Considere a situação a seguir. Por exemplo, o catch-up está ativado e o Airflow executa um DAG em uma programação entre o momento em que o snapshot foi criado e quando foi carregado. Nesse caso, depois de carregar o snapshot, o Airflow não tem informações sobre a execução do DAG que ocorreu. Portanto, o Airflow executa o DAG novamente para o mesmo horário e dados.

Como outro exemplo, considere um DAG que é executado em uma programação diária. Você cria um snapshot, o Airflow executa esse DAG e, depois disso, você carrega o snapshot no mesmo dia. Nesse caso, o Airflow executa o DAG novamente, mesmo que o catch-up esteja desativado.

Console

Para carregar um snapshot no ambiente:

  1. No Google Cloud console, acesse a página Ambientes.

    Acessar "Ambientes"

  2. Na lista de ambientes, clique no nome do ambiente. A página Detalhes do ambiente será aberta.

  3. Clique em Carregar snapshot.

  4. Na caixa de diálogo Carregar snapshot, clique em Procurar.

  5. Selecione uma pasta que armazene o snapshot. O nome da pasta lista o ID do projeto, o local do ambiente e o carimbo de data/hora em que o snapshot foi salvo. Por exemplo, /snapshots/example-project_us-central1_example-environment_2022-01-05T18-59-00.

  6. (Opcional) Para pular a instalação de pacotes PyPI personalizados do snapshot, selecione Pular instalação dos pacotes PyPI. Se você carregar um snapshot de um ambiente com pacotes PyPI personalizados instalados , o Airflow Gerenciado não instalará esses pacotes personalizados.

  7. Clique em Carregar e aguarde até que o Airflow Gerenciado carregue o snapshot.

gcloud

O comando gcloud composer environments snapshots load carrega um snapshot no ambiente.

  • O argumento --snapshot-path especifica uma pasta em que o snapshot está localizado.

    O nome da pasta lista o ID do projeto, o local do ambiente e o carimbo de data/hora em que o snapshot foi salvo. Por exemplo, gs://us-central1-example-916807e1-bucket/snapshots/example-project_us-central1_example-environment_2022-01-05T18-59-00.

  • (Opcional) O argumento --skip-pypi-packages-installation pula a instalação de pacotes PyPI personalizados do snapshot. Se você carregar um snapshot de um ambiente com pacotes PyPI personalizados instalados , o Airflow Gerenciado não instalará esses pacotes personalizados.

gcloud composer environments snapshots load \
  DESTINATION_ENVIRONMENT_NAME \
  --location LOCATION \
  --snapshot-path "SNAPSHOT_PATH"

Substitua:

  • DESTINATION_ENVIRONMENT_NAME pelo nome do ambiente em que você quer carregar o snapshot.
  • LOCATION pela região em que o ambiente está localizado.
  • SNAPSHOT_PATH pelo URI de um bucket, seguido pelo caminho para o snapshot.

Exemplo:

gcloud composer environments snapshots load \
  example-environment \
  --location us-central1 \
  --snapshot-path "gs://us-central1-example-916807e1-bucket/snapshots/example-project_us-central1_example-environment_2022-01-05T18-59-00"

API

  1. Crie uma solicitação de environments.loadSnapshot API.

  2. No corpo da solicitação, no campo snapshotPath, especifique o URI de um bucket, seguido pelo caminho para o snapshot. O nome da pasta lista o ID do projeto, o local do ambiente e o carimbo de data/hora em que o snapshot foi salvo. Por exemplo, gs://us-central1-example-916807e1-bucket/snapshots/example-project_us-central1_example-environment_2022-01-05T18-59-00.

  3. (Opcional) No corpo da solicitação, no campo skipPypiPackagesInstallation, especifique se o Airflow Gerenciado precisa pular a instalação de pacotes PyPI personalizados do snapshot. Se você carregar um snapshot de um ambiente com pacotes PyPI personalizados instalados , o Airflow Gerenciado não instalará esses pacotes personalizados.

    Este campo é opcional. Se você omitir esse campo, o Airflow Gerenciado instalará pacotes PyPI do snapshot.

{
  "snapshotPath": "SNAPSHOT_PATH"
}

Substitua:

  • SNAPSHOT_PATH pelo URI de uma pasta de bucket em que o snapshot será armazenado.

Exemplo:

// POST https://composer.googleapis.com/v1/projects/example-project/
// locations/us-central1/environments/example-environment:loadSnapshot

{
  "snapshotPath": "gs://us-central1-example-916807e1-bucket/snapshots/example-project_us-central1_example-environment_2022-01-05T18-59-00",
  "skipPypiPackagesInstallation": "False"
}

Terraform

Não é possível salvar e carregar snapshots de ambiente usando o Terraform.

Salvar e carregar snapshots são ações realizadas em um ambiente, e os snapshots resultantes não fazem parte da definição de um ambiente. Como o Terraform gerencia apenas a configuração do ambiente do Airflow Gerenciado, não é possível salvar ou carregar snapshots de ambiente.

A seguir