Em 15 de setembro de 2026, todos os ambientes do Cloud Composer 1 e da versão 2.0.x do Cloud Composer 2 vão atingir o fim da vida útil planejado e não poderão mais ser usados. Recomendamos planejar a migração para o Cloud Composer 3.
Nesta página, explicamos como um ambiente pode ser atualizado.
Sobre as operações de atualização
Quando você muda os parâmetros do ambiente, como especificar novos parâmetros de escalonamento e desempenho ou instalar pacotes PyPI personalizados, o ambiente é atualizado.
Depois que essa operação for concluída, as mudanças vão estar disponíveis no seu
ambiente.
Para um único ambiente do Cloud Composer, só é possível iniciar uma operação de atualização por vez. Aguarde a conclusão de uma operação de atualização antes de iniciar outra operação de ambiente.
Como as atualizações afetam as tarefas do Airflow em execução
Quando você executa uma operação de atualização, os programadores e
workers do Airflow no seu ambiente podem precisar ser reiniciados. Nesse caso, todas as tarefas em execução são encerradas. Depois que a operação de atualização for
concluída, o Airflow vai programar essas tarefas para uma nova tentativa, dependendo da maneira como você
configura as novas tentativas para seus DAGs.
As seguintes mudanças causam o encerramento da tarefa do Airflow:
Fazendo upgrade do ambiente para uma nova versão.
Adicionar, mudar ou excluir pacotes personalizados do PyPI.
Mudar variáveis de ambiente do Cloud Composer.
Adicionar ou remover substituições de opções de configuração do Airflow ou mudar os valores delas.
Alterar a CPU, a memória ou o armazenamento dos workers do Airflow.
Reduzir o número máximo de workers do Airflow, se o novo valor for menor do que o número de workers em execução no momento. Por exemplo, se um ambiente estiver executando três workers e o máximo for reduzido para dois.
As seguintes mudanças não causam o encerramento da tarefa do Airflow:
Criar, atualizar ou excluir um DAG (não uma operação de atualização).
Pausar ou retomar DAGs (não é uma operação de atualização).
Mudar variáveis do Airflow (não é uma operação de atualização).
Alterar conexões do Airflow (não é uma operação de atualização).
Ativar ou desativar a integração da linhagem de dados do Universal Catalog do Dataplex.
Mudando o tamanho do ambiente.
Mudar o número de programadores.
Alterar a CPU, a memória ou o armazenamento dos programadores do Airflow.
Mudar o número de acionadores.
Alterar a CPU, a memória ou o armazenamento dos gatilhos do Airflow.
Alterar a CPU, a memória ou o armazenamento do servidor da Web do Airflow.
Aumentar ou diminuir o número mínimo de workers.
Reduzir o número máximo de workers do Airflow. Por exemplo, se um ambiente estiver executando dois workers e o máximo for reduzido para três.
Alterar janelas de manutenção.
Alterar as configurações de snapshots programados.
Como mudar os identificadores de ambiente.
Como atualizar com o Terraform
Execute terraform plan antes de terraform apply para ver se o Terraform cria um novo ambiente em vez de atualizá-lo.
Antes de começar
Verifique se sua conta, a conta de serviço do ambiente e a conta do agente de serviço do Cloud Composer no projeto têm as permissões necessárias:
O comando gcloud composer environments update termina quando a operação é concluída. Use a sinalização --async para evitar esperar a conclusão da operação.
Atualizar ambientes
Para mais informações sobre como atualizar seu ambiente, consulte outras páginas de documentação sobre operações de atualização específicas. Exemplo:
Em algumas situações raras, uma operação de atualização pode ser interrompida (por exemplo, devido a um tempo limite), e as mudanças solicitadas podem não ser revertidas em todos os componentes do ambiente, como o servidor da Web do Airflow.
Por exemplo, uma operação de atualização pode instalar ou remover módulos PyPI adicionais, redefinir ou definir uma nova variável de ambiente do Airflow ou do Cloud Composer ou mudar alguns parâmetros relacionados ao Airflow.
Essa situação pode ocorrer se uma operação de atualização for acionada quando outras
operações estiverem em andamento, por exemplo, o escalonamento automático ou uma operação de manutenção do cluster do Cloud Composer.
Nesse caso, recomendamos repetir a operação.
Duração das operações de atualização ou upgrade
A duração das operações de atualização e upgrade é afetada pelos seguintes fatores:
A maioria das operações de atualização ou upgrade exige a reinicialização de componentes do Airflow, como programadores, workers e servidores da Web. Depois que um componente é reiniciado, ele precisa ser inicializado. Durante a inicialização, os programadores e workers do Airflow baixam o conteúdo das pastas /dags e /plugins do bucket do ambiente. O processo de sincronização de arquivos com
programadores e workers do Airflow não é instantâneo e depende do tamanho
total e do número de todos os objetos nessas pastas.
Recomendamos manter apenas os arquivos DAG e de plug-in nas pastas /dags e /plugins (respectivamente) e remover todos os outros arquivos. Muitos dados nas pastas /dags e /plugins podem diminuir a velocidade da inicialização dos componentes do Airflow e, em alguns casos, impossibilitar a inicialização.
O tamanho do banco de dados do Airflow pode aumentar significativamente o tempo das operações de upgrade. Recomendamos manter o tamanho do banco de dados do Airflow configurando uma política de retenção de banco de dados.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Informações incorretas ou exemplo de código","incorrectInformationOrSampleCode","thumb-down"],["Não contém as informações/amostras de que eu preciso","missingTheInformationSamplesINeed","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-08-26 UTC."],[[["\u003cp\u003eThis page describes how to update Cloud Composer environments, noting that it currently reflects Cloud Composer 2 documentation.\u003c/p\u003e\n"],["\u003cp\u003eUpdating an environment can involve changes to parameters like scaling, performance, or custom PyPI packages, with only one update operation allowed at a time.\u003c/p\u003e\n"],["\u003cp\u003eCertain updates, such as upgrading the environment or modifying custom packages and configurations, will terminate all running Airflow tasks, while others like changes to DAGs or connections will not.\u003c/p\u003e\n"],["\u003cp\u003eUpdating with Terraform may result in the deletion and recreation of the environment if the parameter being changed is not supported for updates, and caution is advised.\u003c/p\u003e\n"],["\u003cp\u003eUpdate operations can be affected by the size of data in \u003ccode\u003e/dags\u003c/code\u003e and \u003ccode\u003e/plugins\u003c/code\u003e folders, and keeping it below 30MB, and never above 100 MB, is highly recommended to prevent slowdowns or initialization failures.\u003c/p\u003e\n"]]],[],null,["# Update Cloud Composer environments\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\n**Cloud Composer 3** \\| [Cloud Composer 2](/composer/docs/composer-2/update-environments \"View this page for Cloud Composer 2\") \\| [Cloud Composer 1](/composer/docs/composer-1/update-environments \"View this page for Cloud Composer 1\")\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nThis page explains how an environment can be updated.\n\nAbout update operations\n-----------------------\n\nWhen you change parameters of your environment, such as specifying new scaling\nand performance parameters, or installing custom PyPI packages, your\nenvironment updates.\n\nAfter this operation is completed, changes become available in your\nenvironment.\n\nFor a single Cloud Composer environment, you can start only one\nupdate operation at a time. You must wait for an update operation to complete\nbefore starting another environment operation.\n\nHow updates affect running Airflow tasks\n----------------------------------------\n\n| **Caution:** Some update operations **terminate all running tasks**.\n\nWhen you [run an update operation](#update-operations), Airflow schedulers and\nworkers in your environment might require a restart. In this case, all\ncurrently running tasks are terminated. After the update operation is\ncompleted, Airflow schedules these tasks for a retry, depending on the way you\nconfigure retries for your DAGs.\n| **Note:** Airflow workers can get restarted as part of the environment maintenance, during the maintenance windows.\n\nThe following changes **cause** Airflow task termination:\n\n- Upgrading your environment to a new version.\n- Adding, changing, or deleting custom PyPI packages.\n- Changing Cloud Composer environment variables.\n- Adding or removing Airflow configuration options overrides, or changing their values.\n- Changing Airflow workers' CPU, memory, or storage.\n- Reducing the maximum number of Airflow workers, if the new value is\n lower than the number of currently running workers. For example, if an\n environment currently runs three workers, and the maximum is reduced to two.\n\nThe following changes **don't cause** Airflow task termination:\n\n- Creating, updating, or deleting a DAG (not an update operation).\n- Pausing or unpausing DAGs (not an update operation).\n- Changing Airflow variables (not an update operation).\n- Changing Airflow connections (not an update operation).\n- Enabling or disabling Dataplex Universal Catalog Data Lineage integration.\n- Changing environment's size.\n- Changing the number of schedulers.\n- Changing Airflow schedulers' CPU, memory, or storage.\n- Changing the number of triggerers.\n- Changing Airflow triggerers' CPU, memory, or storage.\n- Changing Airflow web server's CPU, memory, or storage.\n- Increasing or decreasing the minimum number of workers.\n- Reducing the maximum number of Airflow workers. For example, if an environment currently runs two workers, and the maximum is reduced to three.\n- Changing maintenance windows.\n- Changing scheduled snapshots settings.\n- Changing environment labels.\n\nUpdating with Terraform\n-----------------------\n\n| **Warning:** If you attempt to change a configuration parameter that cannot be updated, Terraform **deletes your environment and creates a new one** with the new parameter value.\n\nRun `terraform plan` before `terraform apply` to see if Terraform creates a new\nenvironment instead of updating it.\n\nBefore you begin\n----------------\n\n- Check that your account, the service account of your environment, and\n the Cloud Composer Service Agent account in your project have\n required permissions:\n\n - Your account must have a role that\n [can trigger environment update operations](/composer/docs/composer-3/access-control#user-account).\n\n - The service account of your environment must have a role that\n [has enough permissions to perform update operations](/composer/docs/composer-3/access-control#service-account).\n\n- The `gcloud composer environments update` command terminates when the\n operation is finished. You can use the `--async` flag to avoid waiting for\n the operation to complete.\n\nUpdate environments\n-------------------\n\nFor more information about updating your environment, see other documentation\npages about specific update operations. For example:\n\n- [Override Airflow configuration options](/composer/docs/composer-3/override-airflow-configurations)\n- [Set environment variables](/composer/docs/composer-3/set-environment-variables)\n- [Install Python dependencies](/composer/docs/composer-3/install-python-dependencies)\n- [Scale environments](/composer/docs/composer-3/scale-environments)\n\nView environment details\n------------------------\n\n### Console\n\n1. In Google Cloud console, go to the **Environments** page.\n\n [Go to Environments](https://console.cloud.google.com/composer/environments)\n2. In the list of environments, click the name of your environment.\n The **Environment details** page opens.\n\n### gcloud\n\nRun the following `gcloud` command: \n\n gcloud composer environments describe \u003cvar translate=\"no\"\u003eENVIRONMENT_NAME\u003c/var\u003e \\\n --location \u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e\n\nReplace:\n\n- `ENVIRONMENT_NAME` with the name of the environment.\n- `LOCATION` with the region where the environment is located.\n\n### API\n\nConstruct an [`environments.get`](/composer/docs/reference/rest/v1/projects.locations.environments/get) API request.\n\nExample: \n\n GET https://composer.googleapis.com/v1/projects/example-project/\n locations/us-central1/environments/example-environment\n\n### Terraform\n\nRun the `terraform state show` command for your environment's resource.\n\nThe name of your environment's Terraform resource might be different than the\nname of your environment. \n\n terraform state show google_composer_environment.\u003cvar translate=\"no\"\u003eRESOURCE_NAME\u003c/var\u003e\n\nReplace:\n\n- `RESOURCE_NAME` with the name of your environment's resource.\n\n### Rolling back update changes\n\nIn some rare situations, an update operation might be interrupted\n(for example, because of a timeout) and the requested changes might not be\nrolled back in all environment components (such as the Airflow web server).\n\nFor example, an update operation might be installing or removing additional\nPyPI modules, re-defining or defining a new Airflow or Cloud Composer\nenvironment variable, or changing some Airflow-related parameters.\n\nSuch a situation might occur if an update operation is triggered when other\noperations are in progress, for example Cloud Composer cluster's\nautoscaling or a maintenance operation.\n\nIn such a situation, it's recommended to repeat the operation.\n\n### Duration of update or upgrade operations\n\nThe duration of update and upgrade operations is affected by the following\nfactors:\n\n- Most update or upgrade operations require restarting Airflow components\n like Airflow schedulers, workers and web servers. After a component is\n restarted, it must be initialized. During the initialization, Airflow\n schedulers and workers download the contents of `/dags` and `/plugins`\n folders from the environment's bucket. The process of syncing files to\n Airflow schedulers and workers isn't instantaneous and depends on the total\n size and number of all objects in these folders.\n\n We recommend to keep only DAG and plugin files in `/dags` and `/plugins`\n folders (respectively) and remove all other files. Too much data\n in `/dags` and `/plugins` folders might slow down the initialization of\n Airflow components and in certain cases might make the initialization not\n possible.\n\n We recommend to keep less than 30 MB of data in `/dags` and `/plugins`\n folders, and to definitely not exceed 100 MB size of data. For more\n information, also see\n [Handling large number of DAGs and plugins](/composer/docs/composer-2/troubleshooting-dags#large-number-of-dags)\n- The size of the Airflow database might significantly increase the time of\n upgrade operations. We recommend to maintain the Airflow database size by\n\n configuring a [database retention policy](/composer/docs/composer-3/configure-db-retention).\n\nWhat's next\n-----------\n\n- [Upgrade environments](/composer/docs/composer-3/upgrade-environments)\n- [Override Airflow configuration options](/composer/docs/composer-3/override-airflow-configurations)"]]
