Kubernetes YAML Validator

Kubernetes YAML Validation

Kubernetes manifests are declarative YAML documents that describe the desired state of your cluster resources. Every object — from Pods and Deployments to Services and ConfigMaps — is defined by a structured YAML file that the Kubernetes API server parses, validates, and stores in etcd. A single typo in a field name, a missing required property, or an incorrect API version string can cause kubectl apply to fail silently or create resources in an unexpected state. This validator checks your Kubernetes YAML manifests against the structural rules of the Kubernetes API specification, catching common errors before they reach your cluster.

Unlike generic YAML validators that only check syntax (indentation, colons, dashes), a Kubernetes-aware validator understands the schema of each resource type. It knows that a Deployment requires spec.selector.matchLabels, that a Service of type LoadBalancer accepts spec.loadBalancerIP, and that apiVersion: extensions/v1beta1 has been deprecated since Kubernetes 1.16. This level of semantic validation prevents runtime failures that pure syntax checking cannot detect.

Core Resource Types and Their Required Fields

Kubernetes defines dozens of resource types (also called "kinds"), each with a specific schema. The most commonly used resources in day-to-day operations include:

• Pod — The smallest deployable unit. Requires metadata.name and at least one container in spec.containers with name and image fields.
• Deployment — Manages ReplicaSets for stateless workloads. Requires spec.selector.matchLabels, spec.template.metadata.labels (must match the selector), and spec.template.spec.containers.
• Service — Exposes Pods via a stable network endpoint. Requires spec.selector to match Pod labels and spec.ports with at least one port definition including port and protocol.
• ConfigMap — Stores non-sensitive configuration data as key-value pairs. Requires metadata.name and either data or binaryData (both are optional individually, but at least one should be present for the ConfigMap to be useful).
• Ingress — Manages external HTTP/HTTPS access to Services. Uses networking.k8s.io/v1 and requires spec.rules with host and path definitions.

Every Kubernetes resource shares four top-level fields: apiVersion, kind, metadata, and spec (or data for ConfigMaps/Secrets). Missing any of the first three causes an immediate rejection by the API server.

API Version Rules and Group Conventions

The apiVersion field tells Kubernetes which API group and version to use for parsing the resource. Getting this wrong is one of the most frequent causes of deployment failures, especially when upgrading cluster versions. The format is group/version for grouped APIs and just version for core resources.

• v1 — Core API group (no group prefix). Used for Pods, Services, ConfigMaps, Secrets, Namespaces, PersistentVolumeClaims, and ServiceAccounts.
• apps/v1 — Application workload controllers. Used for Deployments, StatefulSets, DaemonSets, and ReplicaSets. This replaced extensions/v1beta1 and apps/v1beta2 which were removed in Kubernetes 1.16.
• networking.k8s.io/v1 — Networking resources. Used for Ingress and NetworkPolicy. The older extensions/v1beta1 Ingress was removed in Kubernetes 1.22.
• batch/v1 — Batch workloads. Used for Jobs and CronJobs (CronJobs moved from batch/v1beta1 to batch/v1 in Kubernetes 1.21).
• rbac.authorization.k8s.io/v1 — Role-Based Access Control. Used for Roles, ClusterRoles, RoleBindings, and ClusterRoleBindings.

A common mistake is using a deprecated or removed API version. For example, applying a manifest with apiVersion: extensions/v1beta1 and kind: Deployment on a Kubernetes 1.16+ cluster returns an error like "no matches for kind Deployment in version extensions/v1beta1". This validator flags deprecated versions and suggests the current stable alternative.

Common Validation Errors and How to Fix Them

Based on real-world Kubernetes deployments, these are the most frequently encountered validation errors and their solutions:

• Missing apiVersion — Every manifest must start with apiVersion. Without it, kubectl cannot determine which API endpoint to call. Fix: Add the appropriate version (e.g., apiVersion: apps/v1).
• Wrong or misspelled kind — The kind field is case-sensitive. deployment is invalid; it must be Deployment. Similarly, Configmap should be ConfigMap.
• Missing metadata.name — All resources require a name. Without metadata.name, the API server returns "name or generateName is required".
• Selector/label mismatch — In Deployments, spec.selector.matchLabels must exactly match spec.template.metadata.labels. A mismatch causes the Deployment controller to never find matching Pods, resulting in zero replicas.
• Invalid container port — Port numbers must be between 1 and 65535. containerPort: 0 or negative values are rejected.
• Indentation errors — YAML is indentation-sensitive. A misaligned containers block (indented under the wrong parent) produces confusing errors like "unknown field spec.containers" when it should be under spec.template.spec.

This validator detects these structural issues client-side, providing immediate feedback with specific line numbers and suggested corrections. Catching errors locally saves the round-trip to the cluster and avoids partial deployments that leave your cluster in an inconsistent state.

Label Selectors and Metadata Best Practices

Labels are key-value pairs attached to Kubernetes objects that enable grouping, filtering, and selection. Selectors use labels to identify which objects a controller manages. Understanding the relationship between labels and selectors is critical for writing valid manifests.

A label key has two parts: an optional prefix (a DNS subdomain, max 253 characters) and a name (max 63 characters, must start and end with alphanumeric characters). Valid examples include app: nginx, app.kubernetes.io/name: frontend, and tier: backend. Invalid labels like app: my app (spaces not allowed) or keys longer than 63 characters are rejected.

The recommended labeling convention from the Kubernetes documentation uses the app.kubernetes.io/ prefix with standard keys: name, instance, version, component, part-of, and managed-by. Following this convention makes your resources compatible with tools like Helm, Kustomize, and the Kubernetes Dashboard.

For Deployments and Services to work together, the Service's spec.selector must match at least one label on the Pods. A Service with selector: {app: web} routes traffic only to Pods that carry the label app: web. This validator verifies that selectors reference labels that exist in the same manifest, catching broken connections before deployment.

Code Examples

Valid Kubernetes Deployment manifest

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-server
  labels:
    app.kubernetes.io/name: web-server
    app.kubernetes.io/version: "1.0.0"
spec:
  replicas: 3
  selector:
    matchLabels:
      app: web-server
  template:
    metadata:
      labels:
        app: web-server
    spec:
      containers:
        - name: nginx
          image: nginx:1.25-alpine
          ports:
            - containerPort: 80
              protocol: TCP
          resources:
            requests:
              cpu: "100m"
              memory: "128Mi"
            limits:
              cpu: "500m"
              memory: "256Mi"
          livenessProbe:
            httpGet:
              path: /healthz
              port: 80
            initialDelaySeconds: 5
            periodSeconds: 10

Service exposing the Deployment above

apiVersion: v1
kind: Service
metadata:
  name: web-server-svc
spec:
  type: ClusterIP
  selector:
    app: web-server
  ports:
    - port: 80
      targetPort: 80
      protocol: TCP

Standards & Specifications

• Kubernetes API Reference — Official Kubernetes API reference documenting all resource types, their fields, and version history
• Kubernetes API Conventions — Design conventions for Kubernetes API objects including naming, metadata structure, and spec/status patterns
• Kubernetes Deprecation Policy — Rules governing API version lifecycle, deprecation timelines, and removal guarantees