Kubernetes Resource

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/kubernetes/main/json-schema/kubernetes-resource-schema.json",
  "title": "Kubernetes Resource",
  "description": "JSON Schema for Kubernetes resource objects including Pods, Deployments, Services, ConfigMaps, Secrets, Namespaces, and Nodes. Covers the core API group (v1) and apps/v1 group resources used to define and manage containerized workloads.",
  "type": "object",
  "required": ["apiVersion", "kind", "metadata"],
  "properties": {
    "apiVersion": {
      "type": "string",
      "description": "API version identifying the schema and group for this resource. Examples: v1 for core resources, apps/v1 for Deployments, rbac.authorization.k8s.io/v1 for RBAC resources.",
      "examples": ["v1", "apps/v1", "batch/v1", "networking.k8s.io/v1", "rbac.authorization.k8s.io/v1"]
    },
    "kind": {
      "type": "string",
      "description": "Resource type identifier. Determines which schema the spec and status fields follow.",
      "enum": [
        "Pod",
        "Deployment",
        "StatefulSet",
        "DaemonSet",
        "ReplicaSet",
        "Job",
        "CronJob",
        "Service",
        "Endpoints",
        "Ingress",
        "NetworkPolicy",
        "ConfigMap",
        "Secret",
        "PersistentVolume",
        "PersistentVolumeClaim",
        "StorageClass",
        "Namespace",
        "Node",
        "ServiceAccount",
        "Role",
        "RoleBinding",
        "ClusterRole",
        "ClusterRoleBinding",
        "HorizontalPodAutoscaler",
        "CustomResourceDefinition",
        "Event"
      ]
    },
    "metadata": {
      "$ref": "#/$defs/ObjectMeta"
    },
    "spec": {
      "type": "object",
      "description": "Specification of the desired state of the resource. The structure depends on the resource kind."
    },
    "status": {
      "type": "object",
      "description": "Most recently observed status of the resource. Populated by the system and read-only."
    }
  },
  "$defs": {
    "ObjectMeta": {
      "type": "object",
      "description": "Standard Kubernetes object metadata present on all persistent resources. Contains identification, versioning, labels, annotations, and ownership information.",
      "properties": {
        "name": {
          "type": "string",
          "description": "Unique name of the object within the namespace (or cluster, for cluster-scoped resources). Must be a valid DNS subdomain.",
          "maxLength": 253,
          "pattern": "^[a-z0-9][a-z0-9\\-\\.]*[a-z0-9]$"
        },
        "generateName": {
          "type": "string",
          "description": "Prefix for server-generated unique names. Used when name is not specified.",
          "maxLength": 253
        },
        "namespace": {
          "type": "string",
          "description": "Namespace that scopes the resource name. Only applies to namespaced resources. Defaults to 'default'.",
          "maxLength": 63,
          "pattern": "^[a-z0-9][a-z0-9\\-]*[a-z0-9]$"
        },
        "uid": {
          "type": "string",
          "description": "Unique identifier generated by the server upon resource creation. Immutable for the lifetime of the object.",
          "format": "uuid"
        },
        "resourceVersion": {
          "type": "string",
          "description": "Opaque string identifying the server-side version of the object. Used for optimistic concurrency and watch operations."
        },
        "generation": {
          "type": "integer",
          "minimum": 0,
          "description": "Sequence number for the desired state of the object. Incremented when the spec changes."
        },
        "creationTimestamp": {
          "type": "string",
          "format": "date-time",
          "description": "RFC 3339 timestamp indicating when the object was created."
        },
        "deletionTimestamp": {
          "type": "string",
          "format": "date-time",
          "description": "RFC 3339 timestamp at which the object will be deleted. Present when graceful deletion has been requested."
        },
        "deletionGracePeriodSeconds": {
          "type": "integer",
          "minimum": 0,
          "description": "Number of seconds until the object is forcefully terminated during graceful deletion."
        },
        "labels": {
          "type": "object",
          "description": "Map of string key-value pairs used to organize and identify resources. Queryable via label selectors.",
          "additionalProperties": {
            "type": "string"
          }
        },
        "annotations": {
          "type": "object",
          "description": "Map of non-identifying metadata. Arbitrary data that tools and libraries may attach to objects.",
          "additionalProperties": {
            "type": "string"
          }
        },
        "ownerReferences": {
          "type": "array",
          "description": "List of owning resources that manage this object's lifecycle via garbage collection.",
          "items": {
            "$ref": "#/$defs/OwnerReference"
          }
        },
        "finalizers": {
          "type": "array",
          "description": "List of finalizers that must be empty before the object is deleted from storage. Set by controllers to delay deletion.",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "OwnerReference": {
      "type": "object",
      "description": "Reference to an owning resource. Used by garbage collection to clean up owned resources when the owner is deleted.",
      "required": ["apiVersion", "kind", "name", "uid"],
      "properties": {
        "apiVersion": {
          "type": "string",
          "description": "API version of the owning resource."
        },
        "kind": {
          "type": "string",
          "description": "Kind of the owning resource."
        },
        "name": {
          "type": "string",
          "description": "Name of the owning resource."
        },
        "uid": {
          "type": "string",
          "format": "uuid",
          "description": "UID of the owning resource."
        },
        "controller": {
          "type": "boolean",
          "description": "If true, this reference points to the managing controller."
        },
        "blockOwnerDeletion": {
          "type": "boolean",
          "description": "If true, the owner cannot be deleted until this object is removed."
        }
      }
    },
    "PodSpec": {
      "type": "object",
      "description": "Specification of the desired behavior of a pod, including containers, volumes, scheduling constraints, and restart policy.",
      "required": ["containers"],
      "properties": {
        "containers": {
          "type": "array",
          "description": "List of containers to run in the pod. At least one container is required.",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/Container"
          }
        },
        "initContainers": {
          "type": "array",
          "description": "List of init containers that run and complete before the app containers start.",
          "items": {
            "$ref": "#/$defs/Container"
          }
        },
        "volumes": {
          "type": "array",
          "description": "List of volumes that can be mounted by containers in the pod.",
          "items": {
            "$ref": "#/$defs/Volume"
          }
        },
        "restartPolicy": {
          "type": "string",
          "enum": ["Always", "OnFailure", "Never"],
          "description": "Restart policy for all containers. Defaults to Always.",
          "default": "Always"
        },
        "terminationGracePeriodSeconds": {
          "type": "integer",
          "minimum": 0,
          "description": "Duration in seconds for graceful termination before SIGKILL. Defaults to 30.",
          "default": 30
        },
        "serviceAccountName": {
          "type": "string",
          "description": "Name of the service account for API access token projection."
        },
        "nodeName": {
          "type": "string",
          "description": "Node to schedule the pod on, bypassing the scheduler."
        },
        "nodeSelector": {
          "type": "object",
          "description": "Label key-value pairs that the node must match for scheduling.",
          "additionalProperties": {
            "type": "string"
          }
        },
        "hostNetwork": {
          "type": "boolean",
          "description": "Whether the pod uses the host's network namespace. Defaults to false."
        },
        "dnsPolicy": {
          "type": "string",
          "enum": ["ClusterFirst", "ClusterFirstWithHostNet", "Default", "None"],
          "description": "DNS policy for the pod. Defaults to ClusterFirst."
        }
      }
    },
    "Container": {
      "type": "object",
      "description": "A container definition specifying the image, command, resource requirements, ports, environment variables, and volume mounts for a single container running in a pod.",
      "required": ["name"],
      "properties": {
        "name": {
          "type": "string",
          "description": "Unique name of the container within the pod. Used to reference the container in logs, exec, and port-forward.",
          "pattern": "^[a-z0-9][a-z0-9\\-]*[a-z0-9]?$",
          "maxLength": 63
        },
        "image": {
          "type": "string",
          "description": "Container image name in the format [registry/][repository/]name[:tag|@digest]."
        },
        "command": {
          "type": "array",
          "description": "Entrypoint command. Overrides the ENTRYPOINT in the container image.",
          "items": {
            "type": "string"
          }
        },
        "args": {
          "type": "array",
          "description": "Arguments to the entrypoint. Overrides the CMD in the container image.",
          "items": {
            "type": "string"
          }
        },
        "workingDir": {
          "type": "string",
          "description": "Working directory in the container. Defaults to the image's working directory."
        },
        "ports": {
          "type": "array",
          "description": "List of ports to expose from the container for documentation and service selection.",
          "items": {
            "$ref": "#/$defs/ContainerPort"
          }
        },
        "env": {
          "type": "array",
          "description": "List of environment variables to set in the container.",
          "items": {
            "$ref": "#/$defs/EnvVar"
          }
        },
        "resources": {
          "$ref": "#/$defs/ResourceRequirements"
        },
        "volumeMounts": {
          "type": "array",
          "description": "Pod volumes to mount into the container's filesystem.",
          "items": {
            "$ref": "#/$defs/VolumeMount"
          }
        },
        "imagePullPolicy": {
          "type": "string",
          "enum": ["Always", "Never", "IfNotPresent"],
          "description": "When to pull the container image. Defaults to Always for :latest tag, IfNotPresent otherwise."
        },
        "livenessProbe": {
          "$ref": "#/$defs/Probe"
        },
        "readinessProbe": {
          "$ref": "#/$defs/Probe"
        },
        "startupProbe": {
          "$ref": "#/$defs/Probe"
        }
      }
    },
    "ContainerPort": {
      "type": "object",
      "description": "A network port exposed by the container.",
      "required": ["containerPort"],
      "properties": {
        "name": {
          "type": "string",
          "description": "Optional name for the port, referenced by services and NetworkPolicies.",
          "maxLength": 15
        },
        "containerPort": {
          "type": "integer",
          "minimum": 1,
          "maximum": 65535,
          "description": "Port number to expose on the container's IP address."
        },
        "protocol": {
          "type": "string",
          "enum": ["TCP", "UDP", "SCTP"],
          "description": "Network protocol. Defaults to TCP.",
          "default": "TCP"
        },
        "hostIP": {
          "type": "string",
          "description": "Host IP to bind the external port to."
        },
        "hostPort": {
          "type": "integer",
          "minimum": 1,
          "maximum": 65535,
          "description": "Port to expose on the host. Binds this container port to the host. Avoid use when possible."
        }
      }
    },
    "EnvVar": {
      "type": "object",
      "description": "An environment variable present in a container.",
      "required": ["name"],
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the environment variable. Must be a valid C identifier.",
          "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
        },
        "value": {
          "type": "string",
          "description": "Literal string value for the environment variable. Mutually exclusive with valueFrom."
        },
        "valueFrom": {
          "type": "object",
          "description": "Source for the environment variable's value. Mutually exclusive with value.",
          "properties": {
            "configMapKeyRef": {
              "type": "object",
              "description": "Reference to a ConfigMap key to populate the variable.",
              "required": ["name", "key"],
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Name of the ConfigMap."
                },
                "key": {
                  "type": "string",
                  "description": "Key in the ConfigMap."
                },
                "optional": {
                  "type": "boolean",
                  "description": "Whether the ConfigMap or its key must exist."
                }
              }
            },
            "secretKeyRef": {
              "type": "object",
              "description": "Reference to a Secret key to populate the variable.",
              "required": ["name", "key"],
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Name of the Secret."
                },
                "key": {
                  "type": "string",
                  "description": "Key in the Secret."
                },
                "optional": {
                  "type": "boolean",
                  "description": "Whether the Secret or its key must exist."
                }
              }
            },
            "fieldRef": {
              "type": "object",
              "description": "Reference to a field in the pod spec to populate the variable (e.g. metadata.name).",
              "required": ["fieldPath"],
              "properties": {
                "fieldPath": {
                  "type": "string",
                  "description": "JSONPath expression for the field in the pod spec."
                },
                "apiVersion": {
                  "type": "string",
                  "description": "API version for the field schema."
                }
              }
            }
          }
        }
      }
    },
    "ResourceRequirements": {
      "type": "object",
      "description": "Compute resource requirements for a container, specifying CPU and memory requests and limits.",
      "properties": {
        "requests": {
          "type": "object",
          "description": "Minimum resource amounts required for scheduling. The container is not placed on a node without these resources.",
          "additionalProperties": {
            "type": "string"
          },
          "examples": [
            {"cpu": "100m", "memory": "128Mi"}
          ]
        },
        "limits": {
          "type": "object",
          "description": "Maximum resource amounts the container may use. CPU is throttled; memory violations cause OOM kills.",
          "additionalProperties": {
            "type": "string"
          },
          "examples": [
            {"cpu": "500m", "memory": "512Mi"}
          ]
        }
      }
    },
    "VolumeMount": {
      "type": "object",
      "description": "Describes a volume mount from the pod's volume list into the container filesystem.",
      "required": ["name", "mountPath"],
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the volume to mount. Must match a volume defined in the pod spec."
        },
        "mountPath": {
          "type": "string",
          "description": "Absolute path in the container where the volume should be mounted."
        },
        "subPath": {
          "type": "string",
          "description": "Path within the volume to mount. Defaults to the volume root."
        },
        "readOnly": {
          "type": "boolean",
          "description": "Whether the volume is mounted read-only. Defaults to false."
        }
      }
    },
    "Probe": {
      "type": "object",
      "description": "A probe describes how the kubelet checks the health of a container. Used for liveness (restart on failure), readiness (traffic routing), and startup (initial delay) probes.",
      "properties": {
        "httpGet": {
          "type": "object",
          "description": "HTTP GET probe. Success is a response code in 200-399.",
          "required": ["port"],
          "properties": {
            "path": {
              "type": "string",
              "description": "URL path to GET."
            },
            "port": {
              "description": "Port to probe. Can be an integer or a named port.",
              "oneOf": [
                {"type": "integer", "minimum": 1, "maximum": 65535},
                {"type": "string"}
              ]
            },
            "scheme": {
              "type": "string",
              "enum": ["HTTP", "HTTPS"],
              "description": "Scheme to use. Defaults to HTTP."
            }
          }
        },
        "tcpSocket": {
          "type": "object",
          "description": "TCP socket probe. Success is a successful connection.",
          "required": ["port"],
          "properties": {
            "port": {
              "description": "Port to probe.",
              "oneOf": [
                {"type": "integer"},
                {"type": "string"}
              ]
            }
          }
        },
        "exec": {
          "type": "object",
          "description": "Execute a command in the container. Success is exit code 0.",
          "properties": {
            "command": {
              "type": "array",
              "description": "Command to execute.",
              "items": {"type": "string"}
            }
          }
        },
        "initialDelaySeconds": {
          "type": "integer",
          "minimum": 0,
          "description": "Seconds to wait after container start before probing."
        },
        "periodSeconds": {
          "type": "integer",
          "minimum": 1,
          "description": "Probe interval in seconds. Defaults to 10.",
          "default": 10
        },
        "timeoutSeconds": {
          "type": "integer",
          "minimum": 1,
          "description": "Seconds after which the probe times out. Defaults to 1.",
          "default": 1
        },
        "failureThreshold": {
          "type": "integer",
          "minimum": 1,
          "description": "Consecutive failures before the container is considered unhealthy. Defaults to 3.",
          "default": 3
        },
        "successThreshold": {
          "type": "integer",
          "minimum": 1,
          "description": "Consecutive successes required after a failure to be considered healthy. Defaults to 1.",
          "default": 1
        }
      }
    },
    "Volume": {
      "type": "object",
      "description": "A volume that can be mounted into one or more containers in the pod. Supports many source types including ConfigMaps, Secrets, PVCs, emptyDir, and hostPath.",
      "required": ["name"],
      "properties": {
        "name": {
          "type": "string",
          "description": "Volume name. Must be unique within the pod and match a VolumeMount name."
        },
        "emptyDir": {
          "type": "object",
          "description": "An empty directory scoped to the pod. Deleted when the pod is removed.",
          "properties": {
            "medium": {
              "type": "string",
              "enum": ["", "Memory"],
              "description": "Storage medium. Empty string uses node's default storage; Memory uses tmpfs RAM disk."
            },
            "sizeLimit": {
              "type": "string",
              "description": "Size limit for the emptyDir volume."
            }
          }
        },
        "configMap": {
          "type": "object",
          "description": "ConfigMap volume that mounts key-value pairs as files.",
          "required": ["name"],
          "properties": {
            "name": {
              "type": "string",
              "description": "Name of the ConfigMap to mount."
            },
            "defaultMode": {
              "type": "integer",
              "description": "File permission mode bits. Defaults to 0644.",
              "default": 420
            }
          }
        },
        "secret": {
          "type": "object",
          "description": "Secret volume that mounts secret data as files.",
          "properties": {
            "secretName": {
              "type": "string",
              "description": "Name of the Secret to mount."
            },
            "defaultMode": {
              "type": "integer",
              "description": "File permission mode bits. Defaults to 0644.",
              "default": 420
            }
          }
        },
        "persistentVolumeClaim": {
          "type": "object",
          "description": "PersistentVolumeClaim volume that mounts a claimed persistent volume.",
          "required": ["claimName"],
          "properties": {
            "claimName": {
              "type": "string",
              "description": "Name of the PersistentVolumeClaim in the same namespace."
            },
            "readOnly": {
              "type": "boolean",
              "description": "Whether to mount as read-only. Defaults to false."
            }
          }
        },
        "hostPath": {
          "type": "object",
          "description": "HostPath volume that mounts a file or directory from the host node filesystem.",
          "required": ["path"],
          "properties": {
            "path": {
              "type": "string",
              "description": "Path on the host to mount into the container."
            },
            "type": {
              "type": "string",
              "enum": ["", "DirectoryOrCreate", "Directory", "FileOrCreate", "File", "Socket", "CharDevice", "BlockDevice"],
              "description": "Type of host path mount. Empty string performs no checks."
            }
          }
        }
      }
    },
    "DeploymentSpec": {
      "type": "object",
      "description": "Specification of the desired behavior of a Deployment, including replica count, pod selector, pod template, and rollout strategy.",
      "required": ["selector", "template"],
      "properties": {
        "replicas": {
          "type": "integer",
          "minimum": 0,
          "description": "Desired number of pod replicas. Defaults to 1.",
          "default": 1
        },
        "selector": {
          "$ref": "#/$defs/LabelSelector"
        },
        "template": {
          "type": "object",
          "description": "Template for pods created by this deployment.",
          "properties": {
            "metadata": {
              "$ref": "#/$defs/ObjectMeta"
            },
            "spec": {
              "$ref": "#/$defs/PodSpec"
            }
          }
        },
        "strategy": {
          "type": "object",
          "description": "Update strategy for replacing existing pods.",
          "properties": {
            "type": {
              "type": "string",
              "enum": ["Recreate", "RollingUpdate"],
              "description": "Recreate terminates all pods before creating new ones. RollingUpdate incrementally replaces pods.",
              "default": "RollingUpdate"
            },
            "rollingUpdate": {
              "type": "object",
              "description": "Configuration for RollingUpdate strategy.",
              "properties": {
                "maxUnavailable": {
                  "description": "Maximum pods that can be unavailable during update. Absolute or percentage.",
                  "oneOf": [
                    {"type": "integer", "minimum": 0},
                    {"type": "string", "pattern": "^[0-9]+%$"}
                  ]
                },
                "maxSurge": {
                  "description": "Maximum pods that can be created above desired count during update.",
                  "oneOf": [
                    {"type": "integer", "minimum": 0},
                    {"type": "string", "pattern": "^[0-9]+%$"}
                  ]
                }
              }
            }
          }
        },
        "revisionHistoryLimit": {
          "type": "integer",
          "minimum": 0,
          "description": "Number of old ReplicaSets to retain for rollback. Defaults to 10.",
          "default": 10
        },
        "minReadySeconds": {
          "type": "integer",
          "minimum": 0,
          "description": "Minimum seconds a new pod must be ready before counting as available."
        }
      }
    },
    "LabelSelector": {
      "type": "object",
      "description": "A query over a set of resources by their labels, supporting equality-based and set-based requirements.",
      "properties": {
        "matchLabels": {
          "type": "object",
          "description": "Key-value pairs that must all match labels on the target resource.",
          "additionalProperties": {
            "type": "string"
          }
        },
        "matchExpressions": {
          "type": "array",
          "description": "Set-based label requirements applied with AND logic.",
          "items": {
            "type": "object",
            "required": ["key", "operator"],
            "properties": {
              "key": {
                "type": "string",
                "description": "Label key the selector applies to."
              },
              "operator": {
                "type": "string",
                "enum": ["In", "NotIn", "Exists", "DoesNotExist"],
                "description": "Relationship operator between the key and values."
              },
              "values": {
                "type": "array",
                "items": {"type": "string"},
                "description": "Values for In/NotIn operators. Must be empty for Exists/DoesNotExist."
              }
            }
          }
        }
      }
    },
    "ServiceSpec": {
      "type": "object",
      "description": "Specification of the desired behavior of a Service, including port mappings, pod selector, and service type for traffic routing.",
      "properties": {
        "type": {
          "type": "string",
          "enum": ["ClusterIP", "NodePort", "LoadBalancer", "ExternalName"],
          "description": "Service exposure type. ClusterIP (default) is internal-only; NodePort adds a host port; LoadBalancer adds a cloud load balancer; ExternalName maps to a DNS name.",
          "default": "ClusterIP"
        },
        "selector": {
          "type": "object",
          "description": "Label selector identifying pods this service routes traffic to.",
          "additionalProperties": {
            "type": "string"
          }
        },
        "ports": {
          "type": "array",
          "description": "Service port mappings from service port to pod target port.",
          "items": {
            "$ref": "#/$defs/ServicePort"
          }
        },
        "clusterIP": {
          "type": "string",
          "description": "Cluster-internal IP for the service. 'None' creates a headless service."
        },
        "sessionAffinity": {
          "type": "string",
          "enum": ["None", "ClientIP"],
          "description": "Session affinity type. ClientIP routes repeated requests from the same IP to the same pod.",
          "default": "None"
        },
        "externalName": {
          "type": "string",
          "description": "External DNS name to which the service maps. Only for ExternalName type."
        },
        "loadBalancerIP": {
          "type": "string",
          "description": "IP to request for a LoadBalancer service when supported by the cloud provider."
        }
      }
    },
    "ServicePort": {
      "type": "object",
      "description": "Port mapping within a service, defining the protocol, service-facing port, and pod target port.",
      "required": ["port"],
      "properties": {
        "name": {
          "type": "string",
          "description": "Port name. Required for multi-port services.",
          "maxLength": 15
        },
        "protocol": {
          "type": "string",
          "enum": ["TCP", "UDP", "SCTP"],
          "description": "IP protocol. Defaults to TCP.",
          "default": "TCP"
        },
        "port": {
          "type": "integer",
          "minimum": 1,
          "maximum": 65535,
          "description": "Port the service listens on."
        },
        "targetPort": {
          "description": "Port on the pods to forward traffic to. Defaults to the value of port.",
          "oneOf": [
            {"type": "integer", "minimum": 1, "maximum": 65535},
            {"type": "string"}
          ]
        },
        "nodePort": {
          "type": "integer",
          "minimum": 30000,
          "maximum": 32767,
          "description": "Node-level port for NodePort/LoadBalancer services. Allocated automatically if not specified."
        }
      }
    }
  }
}