Este guia consolida uma série de comandos e exemplos práticos para a geração de manifestos Kubernetes utilizando a flag –dry-run=client. O objetivo é fornecer um material de referência estruturado que abrange desde conceitos básicos para iniciantes até um fluxo de trabalho completo para a implantação de uma aplicação como o phpIPAM.

A flag –dry-run é uma ferramenta poderosa do kubectl que permite simular a execução de um comando sem que ele realize qualquer alteração real no cluster. Isso é extremamente útil para gerar, validar e inspecionar os manifestos YAML que serão aplicados.

• –dry-run=client: O comando é processado inteiramente no lado do cliente. Ele gera o objeto da API em formato YAML ou JSON, mas não o envia para o servidor da API do Kubernetes. É ideal para criar esqueletos de manifestos que serão posteriormente editados.
• –dry-run=server: O comando é enviado ao servidor da API, que executa todas as etapas de validação (como autenticação, autorização e verificação de admission controllers), mas não persiste o objeto no etcd. Isso é útil para validar se um manifesto seria aceito pelo cluster.

Para quem está começando, os comandos imperativos simplificados são uma ótima maneira de gerar manifestos básicos rapidamente.

À medida que a complexidade aumenta, comandos mais detalhados são necessários para configurar todos os aspectos dos recursos do Kubernetes.

# ConfigMap com múltiplos valores literais
kubectl create configmap phpipam-config \
  --from-literal=TZ="America/Sao_Paulo" \
  --from-literal=SCAN_INTERVAL="1h" \
  -n phpipam-system --dry-run=client -o yaml
 
# Secret TLS a partir de arquivos de certificado e chave
kubectl create secret tls tls-secret-phpipam \
  --cert=path/to/cert.crt \
  --key=path/to/cert.key \
  -n phpipam-system --dry-run=client -o yaml
 
# PersistentVolumeClaim (PVC) para armazenamento persistente
kubectl create pvc phpipam-db-pvc \
  --namespace=phpipam-system \
  --storage-class=default-storageclass \
  --access-mode=ReadWriteOnce \
  --requests=storage=15Gi \
  --dry-run=client -o yaml

# Deployment com réplicas e variáveis de ambiente
kubectl create deployment phpipam-web \
  --image=phpipam/phpipam-www:v1.7.4 \
  --namespace=phpipam-system \
  --replicas=1 \
  --port=80 \
  --env="TZ=America/Sao_Paulo" \
  --dry-run=client -o yaml
 
# StatefulSet para aplicações com estado, como bancos de dados
kubectl create statefulset phpipam-db \
  --image=mariadb:11.8 \
  --namespace=phpipam-system \
  --service=phpipam-db \
  --dry-run=client -o yaml
 
# CronJob para tarefas agendadas, como backups
kubectl create cronjob phpipam-backup \
  --image=mariadb:11.8 \
  --namespace=phpipam-system \
  --schedule="0 2 * * *" \
  --dry-run=client -o yaml

# Service do tipo ClusterIP (padrão, para comunicação interna)
kubectl create service clusterip phpipam-web \
  --tcp=80:80 \
  --namespace=phpipam-system --dry-run=client -o yaml
 
# Service do tipo NodePort (expõe em uma porta estática em cada nó)
kubectl create service nodeport phpipam-web \
  --tcp=80:80 \
  --node-port=30080 \
  --namespace=phpipam-system --dry-run=client -o yaml
 
# Service Headless (para descoberta de serviço com StatefulSets)
kubectl create service clusterip phpipam-db \
  --tcp=3306:3306 \
  --clusterip="None" \
  --namespace=phpipam-system --dry-run=client -o yaml

# ServiceAccount, Role e RoleBinding (RBAC)
kubectl create serviceaccount phpipam-sa -n phpipam-system --dry-run=client -o yaml
kubecl create role phpipam-role --verb=get,list --resource=pods -n phpipam-system --dry-run=client -o yaml
kubectl create rolebinding phpipam-rb --role=phpipam-role --serviceaccount=phpipam-system:phpipam-sa -n phpipam-system --dry-run=client -o yaml
 
# NetworkPolicy para restringir o tráfego de rede
kubectl create networkpolicy phpipam-netpol \
  --pod-selector=app=phpipam-web \
  --ingress='[{"from":[{"podSelector":{"matchLabels":{"app":"ingress"}}}]}]' \
  -n phpipam-system --dry-run=client -o yaml

# ResourceQuota para limitar o consumo de recursos em um Namespace
kubectl create quota phpipam-quota \
  --hard=pods=10,cpu=2,memory=4Gi \
  -n phpipam-system --dry-run=client -o yaml
 
# HorizontalPodAutoscaler (HPA) para escalar automaticamente os Pods
kubectl autoscale deployment phpipam-web \
  --min=1 --max=3 --cpu-percent=80 \
  -n phpipam-system --dry-run=client -o yaml
 
# PodDisruptionBudget (PDB) para garantir a disponibilidade durante manutenções
kubectl create poddisruptionbudget phpipam-pdb \
  --selector=app=phpipam-web \
  --max-unavailable=1 \
  -n phpipam-system --dry-run=client -o yaml

Este fluxo demonstra como usar o dry-run para gerar a base de uma aplicação completa e, em seguida, customizá-la.

O script a seguir gera todos os manifestos básicos necessários para a aplicação phpIPAM, incluindo Namespace, ConfigMap, Secret, PVC, Deployments e Services.

#!/bin/bash
# generate-phpipam-manifests.sh
 
NAMESPACE="phpipam-system"
 
echo "=== Gerando todos os manifests para phpIPAM no namespace $NAMESPACE ==="
 
mkdir -p phpipam-manifests
cd phpipam-manifests
 
# Namespace
kubectl create namespace $NAMESPACE --dry-run=client -o yaml > 00-namespace.yaml
 
# ConfigMap
kubectl create configmap phpipam-config \
  --from-literal=TZ="America/Sao_Paulo" \
  --from-literal=IPAM_DATABASE_HOST="phpipam-db" \
  -n $NAMESPACE --dry-run=client -o yaml > 01-configmap.yaml
 
# Secret (com placeholders)
kubectl create secret generic phpipam-secrets \
  --from-literal=DB_ROOT_PASSWORD="CHANGE_ME" \
  --from-literal=DB_PASSWORD="CHANGE_ME" \
  -n $NAMESPACE --dry-run=client -o yaml > 02-secrets.yaml
 
# PVC
kubectl create pvc phpipam-db-pvc \
  --namespace=$NAMESPACE \
  --access-mode=ReadWriteOnce \
  --requests=storage=15Gi \
  --dry-run=client -o yaml > 03-pvc-db.yaml
 
# Deployment e Service do Banco de Dados (MariaDB)
kubectl create deployment phpipam-db --image=mariadb:11.8 -n $NAMESPACE --dry-run=client -o yaml > 04-deployment-db.yaml
kubectl create service clusterip phpipam-db --tcp=3306:3306 -n $NAMESPACE --dry-run=client -o yaml > 05-service-db.yaml
 
# Deployment e Service da Aplicação Web (phpIPAM)
kubectl create deployment phpipam-web --image=phpipam/phpipam-www:v1.7.4 -n $NAMESPACE --dry-run=client -o yaml > 06-deployment-web.yaml
kubectl create service clusterip phpipam-web --tcp=80:80 -n $NAMESPACE --dry-run=client -o yaml > 07-service-web.yaml
 
# Ingress
kubectl create ingress phpipam-ingress \
  --class=nginx \
  --rule="ipam.example.com/*=phpipam-web:80" \
  -n $NAMESPACE --dry-run=client -o yaml > 08-ingress.yaml
 
echo "
Manifests gerados em 'phpipam-manifests/'!"
 
echo "
=== PRÓXIMOS PASSOS ==="
echo "1. Edite os arquivos gerados para adicionar configurações avançadas."
echo "2. Gere senhas seguras e atualize '02-secrets.yaml' (use codificação base64)."
echo "3. Aplique os manifestos: kubectl apply -f ."

O dry-run gera uma base sólida, mas não cobre todas as configurações. Após a geração, é crucial editar os manifestos para adicionar detalhes específicos da aplicação.

Principais edições necessárias para o phpIPAM:

1. Capabilities de Rede: Adicionar NET_ADMIN e NET_RAW ao securityContext do container para permitir que o phpIPAM execute scans de rede.
2. Variáveis de Ambiente Complexas: Configurar variáveis que buscam valores de Secrets ou ConfigMaps (usando valueFrom).
3. Volumes e volumeMounts: Montar o PersistentVolumeClaim no Pod do banco de dados para garantir a persistência dos dados.
4. Resources (requests/limits): Definir requisições e limites de CPU e memória para garantir a estabilidade e o bom uso dos recursos do cluster.
5. Probes (liveness/readiness): Configurar verificações de saúde para que o Kubernetes saiba quando um container está pronto para receber tráfego ou precisa ser reiniciado.

Exemplo de edição no 06-deployment-web.yaml:

# ... (início do arquivo)
spec:
  template:
    spec:
      containers:
      - name: phpipam-web
        image: phpipam/phpipam-www:v1.7.4
        # ADIÇÕES MANUAIS ABAIXO
        ports:
        - containerPort: 80
        env:
        - name: IPAM_DATABASE_PASS
          valueFrom:
            secretKeyRef:
              name: phpipam-secrets
              key: DB_PASSWORD
        resources:
          requests:
            cpu: "250m"
            memory: "256Mi"
          limits:
            cpu: "500m"
            memory: "512Mi"
        readinessProbe:
          httpGet:
            path: /login
            port: 80
          initialDelaySeconds: 10
          periodSeconds: 5
        securityContext:
          capabilities:
            add: ["NET_ADMIN", "NET_RAW"]
# ... (resto do arquivo)

• Visualizar diferenças: Antes de aplicar uma alteração, veja o que mudará com kubectl diff -f seu-arquivo.yaml.
• Validar no servidor: Para uma validação mais completa, use –dry-run=server.
• Mudar formato de saída: Gere a saída em JSON com -o json ou em um formato mais detalhado com -o wide.

1. Não gera configurações complexas: securityContext, probes, volumeMounts e outras seções avançadas geralmente precisam ser adicionadas manualmente.
2. Não valida referências: O dry-run=client não verifica se os Secrets ou ConfigMaps referenciados realmente existem no cluster.
3. Suporte limitado: Alguns recursos mais novos ou Custom Resource Definitions (CRDs) podem não ter suporte completo para geração via comandos imperativos.

O kubectl –dry-run é uma ferramenta indispensável no fluxo de trabalho de um administrador Kubernetes. Ele acelera a criação de manifestos, reduz erros e serve como um excelente ponto de partida para a configuração de aplicações. A abordagem recomendada é usar o dry-run para gerar o esqueleto dos manifestos e, em seguida, investir tempo na revisão e customização manual para atender aos requisitos específicos de produção, segurança e resiliência da sua aplicação.