Versões de software e reconstruções

Duas variáveis do Terraform definem o software de um Customer Edge: ce_os_version para o sistema operacional e ce_sw_version para o build do F5 Distributed Cloud. Ambas se comportam de maneira oposta à leitura óbvia — um campo vazio resulta no build mais recente em vez de nenhum, e uma versão que instala em um nó pode falhar em outro idêntico com um disco menor.

O que os campos de versão fazem, em duas fases

Separar as fases é o ponto central. Quando confundidas, o comportamento parece contraditório.

Na primeira inicialização, um nó instala o que ce_sw_version nomeia. terraform/modules/ce-node implanta a imagem do marketplace com version = "latest", portanto o build com o qual um nó chega é o que essa imagem atualmente fornece — e isso muda ao longo do tempo. ce_sw_version escolhe o destino, não se algo acontece, e deixá-lo vazio significa que o servidor escolhe, e não que o nó permanece parado. O mesmo vale para ce_os_version.

Não presuma que a direção dessa mudança é para cima. Observado em 2026-07-28, a imagem fornecia um build marcado como 20260703-e2c462a — mais recente que o crt-20250613-3382 desta frota e mais recente que o crt-20260201-0179 que o tenant estava anunciando. Nomear um build mais antigo do que o que a imagem carrega solicita que o nó retroceda, e isso é rotineiro: esta frota foi criada dessa forma e está em execução.

Deixar um campo de versão vazio é a escolha mais arriscada, não a neutra. Na criação, o servidor não deixa um campo vazio em paz — ele o preenche com a versão mais recente anunciada e instala essa versão. Um site criado com ambos os campos não definidos retornou fixado em crt-20260201-0179 e OS 9.2026.14, as duas versões que o tenant estava anunciando, e a instalação então falhou. Observado em 2026-07-29.

Há duas consequências. Vazio significa “me dê o mais recente”, portanto uma implantação sem fixação é a mais propensa a encontrar o limite de disco descrito abaixo. E você não pode isolar um campo deixando o outro vazio, porque o servidor o preenche — defina ambos deliberadamente, ou aceite o mais recente de cada um.

Após a primeira inicialização, nada atualiza por conta própria. O F5 Distributed Cloud anuncia um build mais recente e aguarda. É aí que vale “o nó permanece onde pousou” — após a criação, não durante ela.

Ambas as fases são visíveis no objeto do site. Observado em 2026-07-28, esta frota:

volterra_software_status.available_version   crt-20260201-0179
operating_system_status.available_version    9.2026.14

enquanto os nós executam crt-20250613-3382 e OS 9.2024.6. Um build mais recente está disponível e não foi aceito — o estado estável, não uma atualização travada.

O Terraform não pode alterar uma versão. A API pode

Esses são dois fatos separados, e confundi-los produz o plano errado.

O Terraform não pode. ce_os_version e ce_sw_version são efetivamente apenas para o momento da criação. Altere qualquer um e aplique, e a API rejeita a atualização com [BAD_REQUEST] Invalid request parameters. Observado em 2026-07-29 em sites descartáveis, em todas as três direções — fixando para frente para um build mais recente, fixando para trás para um mais antigo, e desfixando ao limpar ambos os campos. Para frente não é um caso especial.

A API pode. O F5 Distributed Cloud expõe uma ação de atualização dedicada por site, que inicia a mudança no local — sem reconstrução e sem envolvimento do Terraform:

# build de software
curl -X POST -H "Authorization: APIToken $TOKEN" -H 'Content-Type: application/json' \
  --data '{"version": "<software-version>"}' \
  "$API_URL/api/config/namespaces/system/sites/<site-name>/upgrade_sw"

# sistema operacional
curl -X POST -H "Authorization: APIToken $TOKEN" -H 'Content-Type: application/json' \
  --data '{"version": "<os-version>"}' \
  "$API_URL/api/config/namespaces/system/sites/<site-name>/upgrade_os"

Observado em 2026-07-29: a chamada de software retornou 200, o site passou para UPGRADING com deployment_state.phase UPGRADE_IN_PROGRESS, e a versão solicitada no objeto do site mudou para a que foi enviada. Omitir o campo retorna 400 com version empty in the request, que é como o nome do campo foi confirmado.

Reserve horas, não minutos, e não entre em pânico com uma falha. Em um nó com disco padrão, a atualização para crt-20260201-0179 durou aproximadamente uma hora, reportou UPGRADE_FAILED com result Failed no meio do processo, e então completou com sucesso no novo build. A plataforma tenta novamente.

Isso tem uma consequência direta para quem está monitorando uma atualização ou criando um script: um resultado Failed é um estado pelo qual se deve aguardar, não um veredicto. Tratar o primeiro como definitivo reporta uma falha para uma atualização que vai ter sucesso.

Observe o grupo nesse caminho: estes ficam sob config, não operate. Os mesmos caminhos sob operate retornam 404 API Group could not be determined, que é uma mensagem de roteamento e não uma afirmação de que nenhuma atualização existe — uma distinção que custou a este projeto uma conclusão errada.

Atualizar pela API coloca o Terraform fora de sincronia

As variáveis fixadas ainda dizem o que sempre disseram, portanto o site em execução agora usa uma versão que a configuração não nomeia. O Terraform não vai reconciliá-la — não pode, já que a atualização é rejeitada — portanto trate uma atualização via API como um passo deliberado fora do controle do Terraform, e atualize as fixações para corresponder na próxima reconstrução.

Duas afirmações anteriores nesta página, retiradas

Esta página dizia anteriormente que mover um CE para uma versão diferente significa recriar o site, e que uma atualização rejeitada “ainda limpa o campo no servidor”, deixando o Terraform propondo uma mudança que falhará para sempre. Nenhuma das duas sobreviveu aos testes: a atualização via API acima inicia uma mudança de versão no local, sem recriar nada, e após cada uma das três atualizações rejeitadas a especificação do site estava inalterada e o site permaneceu ONLINE. A divergência descrita na issue do provider xcsh#1387 foi observada em um site que já havia feito auto-atualização além de sua fixação, portanto pode precisar desse estado de partida divergente; não foi reproduzida em um site cuja especificação correspondia à sua fixação.

Se você reconstruir em vez de atualizar, todas as consequências de substituir um CE se aplicam.

Todas as consequências de substituir um CE se aplicam

Novas chaves de host SSH, endereços internos reatribuídos, um novo registro e a perda de tudo que existia apenas no nó. O Cloud-init é executado novamente na nova VM, portanto o acesso SSH configurado dessa forma sobrevive — mas ele é executado somente na primeira inicialização, então qualquer coisa adicionada ao nó antigo manualmente é perdida.

Leia SSH sobre as consequências da chave de host e do endereço antes de agendar isso.

Um build fixado pode falhar na instalação, e o site fica travado

Aceitar a fixação não é o mesmo que instalá-la. Em um Customer Edge de nó único recém-criado no Azure Secure Mesh v2 fixado em crt-20260201-0179, o objeto do site reportou a versão fixada imediatamente — e a instalação então falhou:

site_state        PROVISIONING
phase             UPGRADE_FAILED
result            Failed
last_installed    (empty)
message           stage: 10, app: voucher obj: voucher objKind: DaemonSet failed ...
                  required replicas: 1, current replicas: 0

Observado em 2026-07-28, e reproduzido duas vezes em 2026-07-29. A fixação do sistema operacional instalou normalmente na mesma execução (9.2024.6 para 9.2026.14, UPGRADE_COMPLETED); apenas a instalação do software falhou. O site nunca atingiu ONLINE e last_installed_version permaneceu vazio, portanto nada reverteu para um build funcional — não havia uma instalação anterior bem-sucedida para reverter.

Uma falha na criação não é como uma falha durante uma atualização. As duas se comportam de forma diferente e a diferença importa quando você está decidindo se deve intervir:

	na criação	durante uma atualização via API
tenta novamente até o sucesso?	não — manteve Failed por mais de 20 minutos, duas vezes	sim — recuperou e completou
onde o nó termina?	PROVISIONING, nada instalado	ONLINE em um build funcional
é seguro aguardar?	não, está travado	sim, recupera ou mantém o build antigo

Portanto, uma falha no momento da criação precisa de uma reconstrução com um disco maior, enquanto uma atualização reportando Failed deve ser aguardada por um tempo antes de se chegar a qualquer conclusão.

A causa é o disco, não a versão. Uma matriz de software × OS × tamanho de disco, um site descartável de nó único do Azure Secure Mesh v2 por combinação e todos da mesma imagem do marketplace, isola o problema. Observado em 2026-07-29:

software	OS 9.2024.6 (o que a imagem fornece)	OS 9.2026.14
crt-20250613-3382	instala	instala
crt-20260201-0179	instala	falha, somente no disco padrão

Nenhuma versão falha sozinha. Somente o par falha, e somente no disco padrão da imagem — o mesmo par instala em 33 GB e em todos os tamanhos maiores testados. Portanto, o build mais recente não tem falta de suporte aqui, e o sistema operacional mais recente também não; juntos eles precisam de um pouco mais de disco do que um nó padrão tem.

terraform/modules/ce-node não define disk_size_gb, portanto cada Customer Edge recebe o padrão da imagem — o único tamanho em que este par falha. Para executá-lo, aumente o disco.

A margem é a parte surpreendente, e é por isso que isso pareceu um problema de versão por tanto tempo. O padrão é 31 GiB (o comando health reporta size_gb: 31, e /var tem 29 G com 3,5 G livres em um nó no estado de falha). 33 GB instala corretamente. Portanto, o padrão está curto em cerca de dois gigabytes, não por uma margem ampla.

Não defina o mínimo medido

33 GB é o menor tamanho observado a funcionar — para este par de versões, nesta imagem, hoje. Um build com um payload ligeiramente maior falharia novamente em 33 GB sem nenhuma alteração de configuração e sem causa óbvia, exatamente como o padrão faz agora. Escolha folga em vez do limite mínimo: os tamanhos verificados aqui são 33, 36, 40, 48 e 64 GB, e o custo dos maiores é alguns gigabytes de disco gerenciado.

Teste uma mudança de versão em um site descartável antes de aplicá-la a uma frota independentemente: uma frota que falha dessa forma fica presa em PROVISIONING com a recriação como única saída.

Não dimensione o disco com base na estimativa pré-atualização da F5

A verificação pré-atualização documentada pela F5 requer 20 GB mais 15% de capacidade livre. Essa verificação controla as atualizações pela interface do Console e explicitamente não se aplica às iniciadas via API, portanto ela não descreve essa falha. Aplicada aqui, ela prevê que um disco de 48 GB falharia; 48 GB instala corretamente. Dimensione com base nos resultados medidos acima, não nessa fórmula.

Uma explicação que esta página oferecia anteriormente, agora retirada

Uma versão anterior desta página sugeria que a instalação falhou porque o build solicitado era mais antigo que o da imagem — que o nó foi solicitado a retroceder. Isso está errado. Esta frota foi criada a partir da mesma imagem com uma fixação treze meses mais antiga e instalou normalmente, e crt-20260201-0179 também instala quando a fixação do OS é deixada na versão da própria imagem. A direção do percurso não é a variável.

Qual build a documentação descreve

A referência de comandos neste site descreve crt-20250613-3382, o build que esta frota executa. Comandos que existem apenas em builds mais recentes estão registrados em sitecli/command-classification.json sob not_on_this_build e documentados separadamente, como comandos em builds mais recentes, portanto nada lá é apresentado como executável aqui. Veja também comandos no dispositivo.

Atingir um build mais recente está resolvido, e não requer reconstrução

Isso foi registrado anteriormente aqui como não resolvido, com um relato do build mais recente falhando em sites Azure Secure Mesh v2 de nó único contra uma contra-observação de um executando-o. Ambos estão agora explicados: o build mais recente instala nessa topologia, e a falha era o limite de disco acima, não o build.

Portanto, há duas rotas e nenhuma requer uma reconstrução por si mesma — crie um nó com um disco grande o suficiente, ou atualize um existente pela API. Observado em 2026-07-29.