YAML Over CLI: Production Reality vs. Tutorial Simplicity

As a platform engineer, you’re not alone in preferring YAML over ad-hoc CLI commands. The question isn’t whether it’s uncommon—it’s whether you’re optimizing for tutorial simplicity or production safety. Here’s the breakdown:

Why YAML Dominates Production Workflows

CLI commands like kubectl create deployment are training wheels. They’re great for learning but dangerous in production:

• No audit trail: Who created that resource? When? Why?
• No versioning: Drift between environments is inevitable.
• No automation: CI/CD pipelines can’t reliably consume one-off CLI commands.

YAML files address these gaps:

• Declarative history: Git commits show exactly what changed.
• Consistency: Same manifests apply across dev/staging/prod.
• GitOps compatibility: Tools like ArgoCD or Flux thrive on YAML repositories.

Most guides skip YAML because tutorials prioritize “getting started” over “staying safe.” Real-world teams use YAML because it’s the foundation for:

• Peer review via pull requests
• Automated rollbacks
• Policy enforcement (e.g., OPA Gatekeeper)

Actionable Workflow: CLI to YAML

Convert CLI habits to YAML with minimal friction:

1. Generate YAML:

   kubectl create deployment myapp --image=nginx --dry-run=client -o yaml > deployment.yaml  
   

2. Edit and commit:
   • Add labels, resource limits, and annotations.
   • Store in Git with a clear directory structure (e.g., clusters/prod/namespaces/default/).
3. Apply via GitOps:
   Use ArgoCD or Flux to sync the repository. Manual kubectl apply is a last resort.

Policy Example: Enforce YAML for Critical Resources

Adopt a policy like this in your GitOps pipeline:

# policy.yaml  
apiVersion: constraints.gatekeeper.sh/v1  
kind: K8sRequiredYAML  
metadata:  
  name: deployment-manifests  
spec:  
  match:  
    kinds:  
      - apiGroups: ["apps"]  
        kinds: ["Deployment"]  
  parameters:  
    enforcement: "must exist in Git repository"  

This ensures all deployments are tracked in Git, not created via CLI.

Tooling That Makes YAML Practical

• kubectl: Use --dry-run=client -o yaml religiously.
• kubebuilder: Scaffold complex CRDs with YAML skeletons.
• Helm: Package YAML for reusable, parameterized deployments.
• pre-commit: Enforce YAML linting and K8s schema validation in Git hooks.
• ArgoCD: Sync YAML repos to clusters automatically.

Avoid tools that hide YAML (e.g., GUI clickops). They create knowledge silos and make debugging harder.

Conclusion

Using YAML over CLI isn’t uncommon—it’s production-grade standard practice. The gap in documentation stems from tutorials prioritizing speed over safety.

Your workflow should be:

1. Start with CLI for exploration.
2. Immediately capture results as YAML in Git.
3. Automate apply/sync with GitOps tooling.

This approach reduces risk, enforces governance, and scales with your team. If a guide doesn’t provide YAML manifests, generate them yourself—it’s a sign you’re moving beyond beginner territory.

Source thread: Is using YAML over the CLI uncommon?