ArgoCD Application vs ApplicationSet: quando usar cada um

Cenário

Você já tem o ArgoCD rodando e sincronizando pelo menos uma aplicação via manifesto Application. Em algum momento o número de clusters, ambientes ou times cresce, e manter um Application por combinação começa a gerar duplicação de YAML e divergência de configuração. A pergunta que aparece é: isso ainda é um caso para Application, ou já é hora de migrar para ApplicationSet?

Este post compara os dois recursos pelos critérios que normalmente pesam nessa decisão: escala, origem da configuração, esforço de manutenção e superfície de risco operacional.

Premissas

Este resumo de pesquisa não trouxe fontes específicas para embasar o post — não há benchmarks, incidentes ou casos reais citados aqui. O conteúdo descreve o comportamento documentado dos dois recursos do ArgoCD (Application e ApplicationSet) com base no conhecimento geral da ferramenta, não em testes executados neste ambiente. Nenhum manifesto abaixo foi aplicado ou validado num cluster real — trate-os como ponto de partida, não como receita pronta.

Para detalhes de sintaxe, versões suportadas e comportamento exato de cada generator, consulte a documentação oficial:

• Argo CD: https://argo-cd.readthedocs.io/
• ApplicationSet controller: https://argocd-applicationset.readthedocs.io/

O que cada recurso resolve

Um Application é a unidade básica do ArgoCD: ele aponta para um repositório Git (ou Helm chart, Kustomize, etc.) e para um cluster/namespace de destino, e o controller mantém esse destino sincronizado com o que está declarado no Git. É um recurso 1:1 — um Application cuida de uma combinação fonte/destino.

Um ApplicationSet é um gerador de Applications. Ele não substitui o Application, ele o produz em lote a partir de um template, combinado com uma lista de parâmetros vinda de um "generator" (lista estática, diretórios Git, clusters registrados, Pull Requests abertos, Matrix combinando dois generators, etc). O controller do ApplicationSet cria, atualiza e remove os Applications correspondentes conforme a fonte de parâmetros muda.

Em termos práticos: Application é a unidade de trabalho; ApplicationSet é a fábrica que decide quantas unidades existem e com quais parâmetros.

Critérios para decidir

Número de combinações fonte/destino

Se você tem uma aplicação indo para um cluster, ou um número pequeno e estável de combinações (ex.: 2-3 ambientes bem distintos, cada um com particularidades relevantes), escrever Applications manualmente ainda é administrável e dá controle fino sobre cada um.

Quando o número de combinações cresce de forma previsível e repetitiva — por exemplo, o mesmo chart Helm indo para N clusters de clientes, ou um app por diretório num monorepo — manter um Application por combinação vira trabalho mecânico e propenso a divergência (alguém atualiza um e esquece os outros nove).

Origem da variação

Pergunte de onde vem a lista de "o que deployar onde":

• Lista fixa e pequena, definida à mão → Application direto, sem necessidade de generator.
• Lista que já existe em outro lugar (clusters registrados no ArgoCD, diretórios num repositório, branches, PRs abertos) → ApplicationSet com o generator correspondente evita manter essa lista duplicada em dois lugares.

Os generators mais comuns cobrem esses casos: List (lista estática no próprio manifesto), Git (diretórios ou arquivos de um repo), Cluster (clusters já registrados no ArgoCD) e Matrix (combina dois generators, por exemplo clusters x ambientes).

Esforço de manutenção e drift

Com Applications manuais, cada novo cluster ou ambiente exige um novo arquivo YAML, revisão e merge. Isso é rastreável no Git, mas escala linearmente com esforço humano.

Com ApplicationSet, adicionar um cluster (via generator Cluster) ou um diretório (via generator Git) pode não exigir nenhum commit novo — o ApplicationSet controller detecta a mudança na fonte e gera o Application automaticamente. Isso reduz esforço, mas também reduz a visibilidade explícita no Git de "o que existe hoje", porque a lista de Applications não está mais toda declarada literalmente — ela é derivada.

Superfície de risco

Um ApplicationSet mal configurado tem efeito multiplicado: um erro no template se replica em todos os Applications gerados de uma vez. Isso é diferente de um erro num Application isolado, que afeta só aquele destino. Vale tratar o manifesto de ApplicationSet com a mesma revisão criteriosa que um script que roda em produção em N lugares simultaneamente — porque é exatamente isso que ele é.

Outro ponto de atenção documentado pelo projeto: a remoção de uma entrada do generator (um cluster desregistrado, um diretório removido do Git) leva à remoção do Application gerado, e dependendo da policy de sync, isso pode levar à remoção dos recursos no cluster de destino. Vale confirmar esse comportamento na documentação oficial antes de usar ApplicationSet em ambientes onde remoção acidental é cara.

Diferenças práticas, lado a lado

Recomendação condicionada

Comece com Application puro quando o número de combinações é pequeno, estável e você quer controle explícito e revisável de cada destino no Git. É a opção mais simples de auditar e de reverter.

Migre para ApplicationSet quando notar pelo menos um destes sinais:

• Você está copiando e colando o mesmo Application trocando só cluster ou namespace.
• A lista de destinos já existe em outro sistema (clusters registrados no ArgoCD, estrutura de diretórios no Git) e você está duplicando essa informação manualmente.
• Onboarding de um novo cluster/tenant deveria ser "adicionar uma linha", não "escrever um YAML novo".

Se a decisão for por ApplicationSet, trate o template e o generator como código crítico: revise como revisaria um script que aplica mudanças em produção em paralelo, e confirme antes de ativar em produção qual é o comportamento de remoção (prune) quando uma entrada desaparece do generator — esse é o detalhe que costuma surpreender quem migra sem ler a documentação com atenção.

Próximo passo prático: antes de escrever o primeiro ApplicationSet, liste exatamente de onde vem a variação (cluster, diretório, branch, PR) e escolha o generator que corresponde a essa fonte — isso evita desenhar um Matrix complexo quando um List simples já resolveria o problema.

Fontes

• Argo CD — documentação oficial: https://argo-cd.readthedocs.io/
• ApplicationSet controller — documentação oficial: https://argocd-applicationset.readthedocs.io/