Kubernetes Validation

GitOpsHQ validates Kubernetes manifests against the official Kubernetes API schema before deployment, catching configuration errors, deprecated API versions, and structural issues early — before they reach your clusters. This validation acts as a pre-flight safety check across the entire deployment lifecycle.

Validation Architecture

Schema Lookup

The schema browser lets you explore the full Kubernetes API specification for any supported version.

{ "versions": ["1.25", "1.26", "1.27", "1.28", "1.29", "1.30", "1.31", "1.32"] }

Deployment (apps/v1)
├── apiVersion: string [required]
├── kind: string [required]
├── metadata: ObjectMeta [required]
│   ├── name: string
│   ├── namespace: string
│   ├── labels: map[string]string
│   └── annotations: map[string]string
└── spec: DeploymentSpec [required]
    ├── replicas: integer (default: 1)
    ├── selector: LabelSelector [required]
    ├── strategy: DeploymentStrategy
    │   ├── type: enum [RollingUpdate, Recreate]
    │   └── rollingUpdate: RollingUpdateDeployment
    └── template: PodTemplateSpec [required]
        └── ...

Manifest Validation

Submit any Kubernetes YAML for validation against a specific Kubernetes version.

Validation API

Endpoint: POST /api/v2/k8s/validate

Request:

{
  "yaml": "apiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: my-app\nspec:\n  replicas: 3\n  selector:\n    matchLabels:\n      app: my-app\n  template:\n    metadata:\n      labels:\n        app: my-app\n    spec:\n      containers:\n      - name: app\n        image: my-app:latest",
  "version": "1.30"
}

Response:

{
  "valid": true,
  "results": [
    {
      "severity": "warning",
      "message": "Using 'latest' tag is not recommended for production",
      "path": "spec.template.spec.containers[0].image",
      "resource": "Deployment/my-app"
    }
  ],
  "summary": {
    "errors": 0,
    "warnings": 1,
    "info": 0
  }
}

What Gets Validated

Validation Workflow

Deprecation Detection

Kubernetes regularly deprecates API versions as resources move from beta to stable or are replaced by newer alternatives. GitOpsHQ automatically detects deprecated API versions in your manifests.

Deprecation API

Endpoint: GET /api/v2/k8s/deprecations?version=1.29

Response:

{
  "version": "1.29",
  "deprecations": [
    {
      "kind": "HorizontalPodAutoscaler",
      "deprecatedApiVersion": "autoscaling/v2beta2",
      "replacementApiVersion": "autoscaling/v2",
      "removedInVersion": "1.32",
      "message": "autoscaling/v2beta2 is deprecated; use autoscaling/v2"
    },
    {
      "kind": "FlowSchema",
      "deprecatedApiVersion": "flowcontrol.apiserver.k8s.io/v1beta3",
      "replacementApiVersion": "flowcontrol.apiserver.k8s.io/v1",
      "removedInVersion": "1.32",
      "message": "flowcontrol.apiserver.k8s.io/v1beta3 is deprecated"
    }
  ]
}

Deprecation Table

The deprecation view presents a table of all deprecated resources for the selected Kubernetes version:

CRD Support (Enterprise)

Custom Resource Definitions (CRDs) extend the Kubernetes API with organization-specific resource types. GitOpsHQ Enterprise supports uploading CRDs to extend the validation engine.

Uploading CRDs

Endpoint: POST /api/v2/k8s/crd

{
  "yaml": "apiVersion: apiextensions.k8s.io/v1\nkind: CustomResourceDefinition\nmetadata:\n  name: certificates.cert-manager.io\nspec:\n  group: cert-manager.io\n  names:\n    kind: Certificate\n    plural: certificates\n  scope: Namespaced\n  versions:\n    - name: v1\n      served: true\n      storage: true\n      schema:\n        openAPIV3Schema:\n          type: object\n          properties:\n            spec:\n              type: object\n              ..."
}

CRD Validation Flow

Integration with Release Workflow

Kubernetes validation is integrated into the release creation pipeline:

Policy-Driven Validation Behavior

You can configure whether validation outcomes are hard stops or advisory:

Validation in Delivery Generator

When the delivery generator renders manifests, it can optionally validate the output against the target Kubernetes version:

When validation is enabled during generation:

1. The delivery generator renders all manifests
2. Each manifest is validated against the target K8s version
3. Validation errors are reported in the generation output
4. Depending on policy, errors may block the generation commit

Validation via CI/CD

Use the validation API in your CI/CD pipelines to catch issues before they enter the GitOps workflow:

# Validate a manifest file against K8s 1.30
curl -X POST https://gitopshq.example.com/api/v2/k8s/validate \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "yaml": "'"$(cat deployment.yaml)"'",
    "version": "1.30"
  }'

# Check deprecations for K8s 1.30
curl "https://gitopshq.example.com/api/v2/k8s/deprecations?version=1.30" \
  -H "Authorization: Bearer <api-key>"

Troubleshooting

Best Practices

1. Always validate before deploying — Use validation as a mandatory gate in your release workflow
2. Upload CRDs for custom resources — Extend validation coverage to catch errors in custom resource manifests
3. Check deprecations before K8s upgrades — Run the deprecation check against the target version before upgrading clusters
4. Use validation in CI pipelines — Catch manifest errors as early as possible via the validation API
5. Match the target version to your cluster — Validate against the exact Kubernetes version your cluster runs
6. Address warnings proactively — Deprecation warnings become errors when the Kubernetes version removes the API
7. Enable validation in the delivery generator — Validate generated manifests automatically during preview and generation
8. Review unknown field warnings — These often indicate typos in field names that silently do nothing