kubectl apply vs set: Escolhendo o Comando Certo para Atualizações de Recursos

Kubernetes, a principal plataforma de orquestração de contêineres, oferece ferramentas poderosas para gerenciar o ciclo de vida das aplicações. Um aspecto central desse gerenciamento envolve a atualização de recursos existentes como Deployments, Services ou ConfigMaps. Enquanto kubectl oferece vários comandos para esse fim, kubectl apply e a família kubectl set/kubectl edit representam duas filosofias fundamentalmente diferentes: atualizações declarativas vs. imperativas.

Compreender quando e como usar cada abordagem é crucial para manter implantações Kubernetes estáveis, confiáveis e auditáveis. O uso indevido desses comandos pode levar a desvios de configuração, depuração difícil e inconsistências operacionais. Este artigo se aprofundará nas nuances de kubectl apply, kubectl set e kubectl edit, equipando você com o conhecimento para tomar decisões informadas para suas estratégias de atualização de recursos.

O Desafio Central: Gerenciando o Estado do Recurso

No Kubernetes, cada componente—de um Pod em execução a um Service de rede—é representado como um objeto de API. Esses objetos têm um estado desejado, que você define em arquivos de manifesto YAML ou JSON, e um estado observado, que reflete sua realidade atual dentro do cluster. O objetivo principal de qualquer comando de atualização do kubectl é reconciliar esses dois estados, mas o método de reconciliação varia significativamente.

Compreendendo kubectl apply: A Abordagem Declarativa

kubectl apply é a base do gerenciamento declarativo de recursos no Kubernetes. Com essa abordagem, você define o estado desejado de seus recursos em um arquivo de configuração local (ou diretório de arquivos) e, em seguida, instrui o Kubernetes a fazer com que o estado do cluster corresponda a essa definição.

Como kubectl apply Funciona (Merge de 3 Vias)

Quando você executa kubectl apply -f seu-manifesto.yaml, o Kubernetes realiza um sofisticado merge de três vias:

1. Configuração Aplicada por Último: O estado do recurso como foi aplicado por último usando kubectl apply. Este estado é armazenado em uma anotação (kubectl.kubernetes.io/last-applied-configuration) no objeto em tempo real.
2. Configuração em Tempo Real: O estado atual do recurso no servidor de API do Kubernetes.
3. Nova Configuração: O estado definido em seu arquivo seu-manifesto.yaml.

O algoritmo de merge compara essas três versões para determinar quais alterações precisam ser feitas. Ele lida inteligentemente com conflitos, priorizando alterações da nova configuração enquanto respeita os campos que foram modificados imperativamente desde a última apply (embora isso possa levar a problemas, como discutido abaixo).

Este processo garante idempotência: aplicar o mesmo manifesto várias vezes resultará no mesmo estado do cluster sem efeitos colaterais não intencionais, desde que nenhuma outra alteração tenha ocorrido.

Exemplo Prático: Aplicando um Deployment

Vamos supor que você tenha um arquivo deployment.yaml:

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: meu-webapp
  labels:
    app: meu-webapp
spec:
  replicas: 3
  selector:
    matchLabels:
      app: meu-webapp
  template:
    metadata:
      labels:
        app: meu-webapp
    spec:
      containers:
      - name: container-webapp
        image: nginx:1.21.0
        ports:
        - containerPort: 80

Para criar ou atualizar este deployment, você executaria:

kubectl apply -f deployment.yaml

Se mais tarde você alterar a image para nginx:1.22.0 em deployment.yaml e executar kubectl apply novamente, o Kubernetes atualizará o Deployment para usar a nova imagem, preservando outras configurações.

Benefícios do kubectl apply

• Fonte da Verdade: Seus arquivos de configuração se tornam a única fonte da verdade para o estado desejado do seu cluster. Isso se alinha bem com os princípios do GitOps.
• Auditabilidade e Controle de Versão: As alterações são rastreadas em seu sistema de controle de versão (por exemplo, Git), fornecendo uma trilha de auditoria clara e rollbacks fáceis.
• Consistência: Garante consistência entre ambientes (desenvolvimento, staging, produção).
• Idempotência: Operações repetidas de apply têm o mesmo efeito, prevenindo modificações não intencionais.
• Atualizações Complexas: Lida com atualizações complexas envolvendo múltiplos tipos de recursos ou alterações significativas em muitos campos.

Quando Usar kubectl apply

• Método principal para toda criação e atualização de recursos.
• Ao implantar aplicações via pipelines de CI/CD.
• Para gerenciar infraestrutura como código.
• Ao trabalhar em equipes para garantir configurações consistentes.

Dicas e Avisos para kubectl apply

• Sempre mantenha seus arquivos de manifesto atualizados com o estado desejado. Quaisquer alterações feitas com kubectl set ou kubectl edit que não sejam refletidas em seus arquivos de manifesto serão substituídas ou causarão conflitos na próxima apply.
• Gerentes de Campo (Field Managers): O Kubernetes 1.16+ introduziu o Server-Side Apply (SSA), que rastreia o "gerente de campo" (por exemplo, kubectl, um controlador) responsável por cada campo em um recurso. Isso ajuda a prevenir conflitos quando várias fontes modificam o mesmo recurso. Embora poderoso, esteja ciente de como diferentes ferramentas podem interagir com o gerenciamento de campos.

Compreendendo kubectl set e kubectl edit: A Abordagem Imperativa

kubectl set e kubectl edit pertencem à família de comandos imperativos. Em vez de definir o estado desejado em um arquivo, você instrui diretamente o Kubernetes a executar ações específicas ou modificar objetos em tempo real dentro do cluster. Esses comandos são excelentes para alterações rápidas e ad hoc, mas vêm com certas ressalvas.

kubectl set: Modificações Imperativas Focadas

kubectl set foi projetado para fazer modificações específicas e comuns em recursos sem a necessidade de editar um arquivo de manifesto. Ele oferece vários subcomandos para modificar campos particulares.

Como kubectl set Funciona

kubectl set modifica diretamente o objeto em tempo real no servidor de API do Kubernetes com base nos argumentos de linha de comando que você fornece. Ele não interage com arquivos de manifesto locais nem atualiza a anotação last-applied-configuration.

Exemplo Prático: Definindo uma Imagem

Para atualizar a imagem de um contêiner dentro de um deployment chamado meu-webapp:

kubeclt set image deployment/meu-webapp container-webapp=nginx:1.22.0

Este comando modifica diretamente o campo image para o container-webapp dentro do Deployment meu-webapp. Se você tivesse previamente gerenciado meu-webapp com kubectl apply, essa alteração criaria um "desvio" entre seu deployment.yaml local e o estado real do cluster.

Outros comandos comuns do kubectl set:

• kubectl set resources: Para definir requests/limits de recursos.
• kubectl set env: Para adicionar ou atualizar variáveis de ambiente.
• kubectl set selector: Para modificar o seletor de um recurso.

kubectl edit: Modificações Imperativas Interativas

kubectl edit permite que você modifique diretamente qualquer campo de um objeto de recurso em tempo real em seu cluster, usando seu editor de texto padrão configurado (por exemplo, vi, nano).

Como kubectl edit Funciona

Quando você executa kubectl edit <tipo-recurso>/<nome-recurso>:

1. kubectl obtém a definição YAML atual do recurso em tempo real do servidor de API.
2. Ele abre essa definição em seu editor de texto local.
3. Você faz as alterações desejadas e salva o arquivo.
4. kubectl então envia a definição modificada de volta para o servidor de API, que tenta aplicar as alterações. Se houver erros de sintaxe ou campos inválidos, as alterações serão rejeitadas.

Assim como kubectl set, kubectl edit também opera diretamente no objeto em tempo real e não atualiza arquivos de manifesto locais nem a anotação last-applied-configuration.

Exemplo Prático: Editando um Deployment

Para abrir o deployment meu-webapp em seu editor:

kubeclt edit deployment/meu-webapp

Seu editor abrirá com uma representação YAML do deployment em tempo real. Você pode então alterar campos como replicas, image, ou adicionar novas anotações/labels. Assim que você salvar e fechar o editor, kubectl tentará aplicar essas alterações.

Benefícios do kubectl set e kubectl edit

• Velocidade: Excelente para correções rápidas e pontuais ou depuração em um ambiente de desenvolvimento.
• Flexibilidade: Modifique diretamente qualquer campo de um recurso (com edit).
• Alterações Ad Hoc: Útil quando você não tem um arquivo de manifesto prontamente disponível ou não quer criar um para uma alteração trivial.

Quando Usar kubectl set/kubectl edit

• Depuração em um cluster de desenvolvimento: Aumentar temporariamente a contagem de réplicas ou alterar uma imagem para testar uma correção.
• Alterações pequenas, não críticas e temporárias em ambientes não produtivos.
• Explorando definições de recursos: kubectl edit é uma maneira conveniente de ver o YAML completo e em tempo real de um recurso.

Avisos para kubectl set e kubectl edit

• Desvio de Configuração: Alterações feitas com set ou edit não são refletidas em seus arquivos de manifesto locais. O próximo kubectl apply a partir do seu manifesto sobrescreverá essas alterações imperativas ou causará conflitos.
• Falta de Auditabilidade: Essas alterações não são rastreadas em controle de versão, tornando difícil saber quem mudou o quê e quando, dificultando a depuração e a conformidade.
• Não Idempotente: Fazer repetidamente a mesma alteração imperativa pode levar a comportamentos inesperados se o estado inicial for desconhecido.
• Risco de Erros: Edição manual (especialmente com edit) aumenta a chance de introduzir erros de sintaxe ou configurações inválidas.

Principais Diferenças: kubectl apply vs. kubectl set/kubectl edit

Para resumir as distinções centrais:

Característica	kubectl apply (Declarativo)	kubectl set/kubectl edit (Imperativo)
Abordagem	Define o estado desejado no arquivo, o Kubernetes reconcilia.	Manipula diretamente objetos em tempo real ou campos específicos.
Fonte da Verdade	Arquivos de configuração locais (por exemplo, repositório Git).	O próprio objeto do cluster em tempo real (efêmero).
Idempotência	Sim, aplicar o mesmo arquivo produz o mesmo resultado.	Não, não inerentemente. Cada comando é uma ação explícita.
Auditabilidade	Alta (alterações rastreadas no Git, last-applied-configuration).	Baixa (sem controle de versão, alterações são imediatas no cluster).
Gerenciamento de Conflitos	Merge de 3 vias, usa anotação last-applied-configuration.	Sobrescreve diretamente (para set) ou faz merge interativamente (para edit).
Caso de Uso	Implantações de produção, CI/CD, GitOps, colaboração em equipe.	Correções rápidas, depuração, alterações ad hoc em não produção.
Risco de Desvio	Baixo, desde que os arquivos sejam mantidos atualizados.	Alto, muito provável de causar desvio de configuração dos arquivos de origem.

Escolhendo o Comando Certo: Melhores Práticas

Para ambientes de produção e equipes colaborativas, a escolha é clara:

• Prefira sempre kubectl apply (ou ferramentas GitOps construídas sobre ele como Argo CD ou Flux CD) para gerenciar seus recursos Kubernetes. Isso garante que o estado do seu cluster seja versionado, auditável e consistente.
• Trate seus arquivos de manifesto Kubernetes como sua única fonte de verdade. Todas as alterações nas configurações de recursos devem idealmente originar-se desses arquivos e ser commitadas no controle de versão.

Comandos imperativos como kubectl set e kubectl edit devem ser reservados para:

• Depuração temporária ou testes em clusters de desenvolvimento/staging. Se você os usar, certifique-se de reverter a alteração ou atualizar imediatamente seus arquivos de manifesto de origem para refletir o novo estado.
• Operações pontuais e efêmeras que não representam um estado desejado a longo prazo (por exemplo, pausar um deployment por um breve momento).

Abordagem Híbrida (Use com Cautela)

Em alguns cenários, você pode precisar fazer um hotfix rápido em produção. Embora geralmente desencorajado, se você precisar usar kubectl edit:

1. Entenda as implicações do desvio de configuração.
2. Capture imediatamente as alterações executando kubectl get <recurso> -o yaml > novo-manifesto.yaml.
3. Integre essas alterações de volta aos seus arquivos de manifesto versionados o mais rápido possível.

Aviso: O uso regular de kubectl edit ou kubectl set em produção sem atualizar seus manifestos de origem levará a um estado de cluster incontrolável e irrecuperável, onde a configuração real diverge drasticamente do que sua equipe pensa que deveria ser.

Conclusão

kubectl apply, kubectl set e kubectl edit são ferramentas poderosas para interagir com seu cluster Kubernetes. No entanto, elas servem a propósitos diferentes e incorporam filosofias distintas de gerenciamento de recursos. Ao entender a natureza declarativa do kubectl apply e a natureza imperativa do kubectl set e kubectl edit, você pode adotar melhores práticas que levam a implantações Kubernetes mais estáveis, confiáveis e sustentáveis.

Para quase todo o gerenciamento persistente de recursos, especialmente em produção, abrace o kubectl apply e controle a versão de seus arquivos de configuração. Reserve comandos imperativos para solução de problemas temporária e ad hoc e certifique-se de que quaisquer alterações críticas sejam rapidamente refletidas de volta em seus manifestos declarativos. Essa disciplina será inestimável para operações tranquilas e colaboração contínua em seu ambiente Kubernetes.