====== Guia de Referência: Gerando Manifestos Kubernetes com ''kubectl --dry-run'' ======

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.

===== 1. Introdução ao ''kubectl --dry-run'' =====

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.

----
===== 2. Guia para Iniciantes: Comandos Essenciais =====

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

^ Recurso ^ Comando de Exemplo ^ Descrição ^
| **Deployment** | ''kubectl create deploy nginx --image=nginx --dry-run=client -o yaml'' | Gera um manifesto para um Deployment simples com a imagem do Nginx. |
| **Service** | ''kubectl expose deploy nginx --port=8080 --target-port=80 --dry-run=client -o yaml'' | Cria um Service do tipo ClusterIP para expor a porta 80 do Deployment ''nginx'' na porta 8080 do Service. |
| **Namespace** | ''kubectl create namespace meu-app --dry-run=client -o yaml'' | Gera o manifesto para a criação de um novo Namespace. |
| **Secret** | ''kubectl create secret generic db-secret --from-literal=USER=admin --from-literal=PASS=1234 --dry-run=client -o yaml'' | Cria um Secret com dados sensíveis passados diretamente como literais. |
| **Ingress** | ''kubectl create ingress meu-ingress --class=nginx --rule="app.com/*=meu-servico:80" --dry-run=client -o yaml'' | Gera uma regra de Ingress básica para rotear o tráfego para um Service. |


----
===== 3. Geração de Manifestos para Recursos Comuns =====

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

==== 3.1. Configuração e Armazenamento ====

<code bash>
# 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
</code>

==== 3.2. Cargas de Trabalho (Workloads) ====

<code bash>
# 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
</code>

==== 3.3. Rede (Networking) ====

<code bash>
# 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
</code>

==== 3.4. Políticas e Controle de Acesso ====

<code bash>
# 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
</code>

==== 3.5. Gerenciamento de Recursos e Alta Disponibilidade ====

<code bash>
# 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
</code>


----
===== 4. Fluxo de Trabalho Completo para phpIPAM =====

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

==== Passo 1: Geração Automática de Manifestos com Script ====

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.

<code bash>
#!/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 ."
</code>

==== Passo 2: Edição e Customização Manual ====

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:**

  - **Capabilities de Rede**: Adicionar ''NET_ADMIN'' e ''NET_RAW'' ao ''securityContext'' do container para permitir que o phpIPAM execute scans de rede.
  - **Variáveis de Ambiente Complexas**: Configurar variáveis que buscam valores de Secrets ou ConfigMaps (usando ''valueFrom'').
  - **Volumes e ''volumeMounts''**: Montar o ''PersistentVolumeClaim'' no Pod do banco de dados para garantir a persistência dos dados.
  - **''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.
  - **''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'':**

<code 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)
</code>

----
===== 5. Dicas e Limitações =====

==== Dicas Avançadas ====

  * **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''.

==== Limitações do ''dry-run'' ====

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

----
===== Conclusão =====

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.