manifest-validator

name	manifest-validator
description	Validates Kubernetes manifests using kubeconform, kube-score, and custom homelab policies. Use when creating or modifying YAML files, Helm values, or ArgoCD applications.
allowed-tools	Bash, Read, Grep, Glob, Write

Manifest Validator

Validate Kubernetes manifests against schemas, best practices, and homelab standards.

Trigger Phrases

• "validate", "검증해줘", "체크해줘"
• "manifest 확인", "yaml 검사"
• Before committing K8s YAML changes

Validation Pipeline

1. YAML Syntax Check

# Basic YAML syntax
yamllint -d relaxed <file.yaml>

# Or with yq
yq eval '.' <file.yaml> > /dev/null && echo "Valid YAML"

2. Kubernetes Schema Validation (kubeconform)

# Single file
kubeconform -summary -output pretty <file.yaml>

# Directory
kubeconform -summary -output pretty platform/stacks/**/*.yaml

# With CRD schemas
kubeconform -summary \
  -schema-location default \
  -schema-location 'https://raw.githubusercontent.com/datreeio/CRDs-catalog/main/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json' \
  <file.yaml>

3. Best Practices (kube-score)

# Score a manifest
kube-score score <file.yaml>

# With specific checks
kube-score score --ignore-test container-resources <file.yaml>

4. Helm Template Validation

# Render and validate
helm template <release> <chart> -f values.yaml | kubeconform -summary

# With helmfile
cd bootstrap && helmfile -e home template | kubeconform -summary

Homelab Policy Checks

Required Fields

# Every Deployment/StatefulSet must have:
spec:
  template:
    spec:
      containers:
        - resources:        # REQUIRED
            requests:
              cpu: "..."
              memory: "..."
            limits:
              cpu: "..."
              memory: "..."
          securityContext:  # REQUIRED
            runAsNonRoot: true
            readOnlyRootFilesystem: true
            allowPrivilegeEscalation: false

Label Requirements

metadata:
  labels:
    app.kubernetes.io/name: <app>        # REQUIRED
    app.kubernetes.io/instance: <app>    # REQUIRED
    app.kubernetes.io/managed-by: argocd # REQUIRED for platform apps

GPU Workload Checks

# If nvidia.com/gpu is requested:
tolerations:
  - key: nvidia.com/gpu  # REQUIRED
    operator: Exists
    effect: NoSchedule
nodeSelector:
  nvidia.com/gpu.present: "true"  # RECOMMENDED

Secret Validation

• No hardcoded secrets in values
• Must use Infisical or external secrets
• No base64-encoded sensitive data in manifests

ArgoCD Application Validation

Required Structure

apps:
  - name: <app-name>           # REQUIRED
    namespace: <namespace>      # REQUIRED
    chart: <chart>             # REQUIRED (or path for kustomize)
    repoURL: <url>             # REQUIRED
    targetRevision: "<version>" # REQUIRED, must be quoted string

Values Validation

# Extract and validate values
yq '.apps[].values' <app.yaml> | kubeconform -summary

Output Format

## Validation Results

### ✅ Passed
- YAML syntax valid
- Kubernetes schema valid
- Labels present

### ⚠️ Warnings
- [kube-score] Container has no readiness probe
- [policy] Missing recommended nodeSelector

### ❌ Errors
- [kubeconform] Invalid apiVersion: apps/v1beta1
- [policy] Missing required resource limits

### Fixes Required
1. Update apiVersion to apps/v1
2. Add resource limits to container spec

Integration with CI

# Pre-commit hook
#!/bin/bash
set -e
changed_yamls=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.ya?ml$' || true)
if [ -n "$changed_yamls" ]; then
  echo "$changed_yamls" | xargs kubeconform -summary -output pretty
fi

Reference

• @.claude/rules/kubernetes.md
• @.claude/rules/argocd-apps.md
• https://github.com/yannh/kubeconform
• https://github.com/zegl/kube-score