Kubernetes Operators · Schema
Kubernetes Operator Resource
JSON Schema for Kubernetes Operator resources including CustomResourceDefinitions (apiextensions.k8s.io/v1) and Operator Lifecycle Manager resources (CatalogSource, OperatorGroup, Subscription, InstallPlan, ClusterServiceVersion from operators.coreos.com). Covers the complete data model for managing operator lifecycle on Kubernetes clusters.
AutomationCloud NativeDevOpsInfrastructureKubernetes
Properties
| Name | Type | Description |
|---|---|---|
| apiVersion | string | API group and version for this operator resource. |
| kind | string | Resource type identifier. |
| metadata | object | |
| spec | object | Desired state specification. Structure varies by resource kind. |
| status | object | Observed status populated by the system. |
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://raw.githubusercontent.com/api-evangelist/kubernetes-operators/main/json-schema/kubernetes-operator-schema.json",
"title": "Kubernetes Operator Resource",
"description": "JSON Schema for Kubernetes Operator resources including CustomResourceDefinitions (apiextensions.k8s.io/v1) and Operator Lifecycle Manager resources (CatalogSource, OperatorGroup, Subscription, InstallPlan, ClusterServiceVersion from operators.coreos.com). Covers the complete data model for managing operator lifecycle on Kubernetes clusters.",
"type": "object",
"required": ["apiVersion", "kind", "metadata"],
"properties": {
"apiVersion": {
"type": "string",
"description": "API group and version for this operator resource.",
"examples": [
"apiextensions.k8s.io/v1",
"operators.coreos.com/v1alpha1",
"operators.coreos.com/v1"
]
},
"kind": {
"type": "string",
"description": "Resource type identifier.",
"enum": [
"CustomResourceDefinition",
"CatalogSource",
"OperatorGroup",
"Subscription",
"InstallPlan",
"ClusterServiceVersion"
]
},
"metadata": {
"$ref": "#/$defs/ObjectMeta"
},
"spec": {
"type": "object",
"description": "Desired state specification. Structure varies by resource kind."
},
"status": {
"type": "object",
"description": "Observed status populated by the system."
}
},
"$defs": {
"ObjectMeta": {
"type": "object",
"description": "Standard Kubernetes object metadata present on all resources.",
"properties": {
"name": {
"type": "string",
"description": "Unique resource name. For CRDs, must be {plural}.{group}.",
"maxLength": 253
},
"namespace": {
"type": "string",
"description": "Namespace of the resource. Empty for cluster-scoped resources.",
"maxLength": 63
},
"uid": {
"type": "string",
"format": "uuid",
"description": "Unique identifier generated by the server."
},
"resourceVersion": {
"type": "string",
"description": "Opaque server version string for optimistic concurrency."
},
"generation": {
"type": "integer",
"minimum": 0,
"description": "Sequence number incremented on spec changes."
},
"creationTimestamp": {
"type": "string",
"format": "date-time",
"description": "RFC 3339 timestamp of resource creation."
},
"labels": {
"type": "object",
"description": "Key-value label pairs for selection and organization.",
"additionalProperties": {"type": "string"}
},
"annotations": {
"type": "object",
"description": "Non-identifying metadata for tools and controllers.",
"additionalProperties": {"type": "string"}
}
}
},
"CRDSpec": {
"type": "object",
"description": "Spec for a CustomResourceDefinition registering a new API resource type.",
"required": ["group", "names", "scope", "versions"],
"properties": {
"group": {
"type": "string",
"description": "API group for the custom resource. Must be a valid DNS domain.",
"pattern": "^[a-z][a-z0-9\\-\\.]*[a-z0-9]$",
"examples": ["example.com", "databases.operator.io"]
},
"names": {
"$ref": "#/$defs/CRDNames"
},
"scope": {
"type": "string",
"enum": ["Cluster", "Namespaced"],
"description": "Whether instances are cluster-scoped or namespaced."
},
"versions": {
"type": "array",
"description": "API versions this CRD serves. At least one required; exactly one must be the storage version.",
"minItems": 1,
"items": {
"$ref": "#/$defs/CRDVersion"
}
},
"conversion": {
"type": "object",
"description": "Strategy for converting between CRD versions.",
"properties": {
"strategy": {
"type": "string",
"enum": ["None", "Webhook"],
"description": "None for no conversion; Webhook for external conversion."
},
"webhook": {
"type": "object",
"description": "Webhook conversion configuration.",
"properties": {
"conversionReviewVersions": {
"type": "array",
"items": {"type": "string"},
"description": "ConversionReview API versions the webhook understands."
},
"clientConfig": {
"type": "object",
"description": "Connection details for the webhook.",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "URL of the webhook."
},
"service": {
"type": "object",
"description": "In-cluster service reference.",
"required": ["name", "namespace"],
"properties": {
"name": {"type": "string", "description": "Service name."},
"namespace": {"type": "string", "description": "Service namespace."},
"port": {"type": "integer", "description": "Service port."},
"path": {"type": "string", "description": "Service path."}
}
}
}
}
}
}
}
}
}
},
"CRDNames": {
"type": "object",
"description": "Naming configuration for the custom resource type.",
"required": ["kind", "plural"],
"properties": {
"kind": {
"type": "string",
"description": "PascalCase kind name used in API calls and manifests.",
"pattern": "^[A-Z][A-Za-z0-9]*$"
},
"plural": {
"type": "string",
"description": "Lowercase plural name used in REST URL paths.",
"pattern": "^[a-z][a-z0-9]*$"
},
"singular": {
"type": "string",
"description": "Lowercase singular name for kubectl.",
"pattern": "^[a-z][a-z0-9]*$"
},
"shortNames": {
"type": "array",
"description": "Abbreviated names for kubectl.",
"items": {"type": "string"}
},
"listKind": {
"type": "string",
"description": "List kind name. Defaults to {kind}List."
},
"categories": {
"type": "array",
"description": "Groups for kubectl get all and similar commands.",
"items": {"type": "string"}
}
}
},
"CRDVersion": {
"type": "object",
"description": "A single version of the custom resource API.",
"required": ["name", "served", "storage"],
"properties": {
"name": {
"type": "string",
"description": "Version name used in REST path.",
"pattern": "^v[0-9]+(alpha[0-9]+|beta[0-9]+)?$",
"examples": ["v1", "v1alpha1", "v1beta1"]
},
"served": {
"type": "boolean",
"description": "Whether this version is served via the REST API."
},
"storage": {
"type": "boolean",
"description": "Whether instances are stored using this version. Exactly one version must be true."
},
"deprecated": {
"type": "boolean",
"description": "Whether this version is deprecated.",
"default": false
},
"deprecationWarning": {
"type": "string",
"description": "Custom deprecation warning message.",
"maxLength": 256
},
"schema": {
"type": "object",
"description": "OpenAPI v3 validation schema for this version.",
"properties": {
"openAPIV3Schema": {
"type": "object",
"description": "JSON Schema-compatible OpenAPI v3 schema object."
}
}
},
"subresources": {
"type": "object",
"description": "Optional status and scale subresources.",
"properties": {
"status": {
"type": "object",
"description": "Enable the /status subresource for separate status updates."
},
"scale": {
"type": "object",
"description": "Enable the /scale subresource for HPA support.",
"properties": {
"specReplicasPath": {
"type": "string",
"description": "JSON path to the spec replicas field."
},
"statusReplicasPath": {
"type": "string",
"description": "JSON path to the status replicas field."
},
"labelSelectorPath": {
"type": "string",
"description": "JSON path to the status label selector field."
}
}
}
}
},
"additionalPrinterColumns": {
"type": "array",
"description": "Columns shown in kubectl get output.",
"items": {
"type": "object",
"required": ["name", "type", "jsonPath"],
"properties": {
"name": {
"type": "string",
"description": "Column header name."
},
"type": {
"type": "string",
"enum": ["integer", "number", "string", "boolean", "date"],
"description": "Column data type."
},
"jsonPath": {
"type": "string",
"description": "JSON path expression from the object root."
},
"format": {
"type": "string",
"description": "Optional display format (e.g. date-time)."
},
"description": {
"type": "string",
"description": "Human-readable column description."
},
"priority": {
"type": "integer",
"minimum": 0,
"description": "Display priority. 0 always shown; >0 shown with -o wide."
}
}
}
}
}
},
"CatalogSourceSpec": {
"type": "object",
"description": "Spec for an OLM CatalogSource pointing to an operator registry.",
"required": ["sourceType", "displayName"],
"properties": {
"sourceType": {
"type": "string",
"enum": ["grpc", "internal", "configmap"],
"description": "Type of catalog registry source."
},
"image": {
"type": "string",
"description": "Container image running the gRPC catalog API."
},
"address": {
"type": "string",
"description": "gRPC address of an existing catalog registry.",
"pattern": "^[a-z0-9\\-\\.]+:[0-9]+$"
},
"displayName": {
"type": "string",
"description": "Human-readable name for the catalog.",
"minLength": 1,
"maxLength": 256
},
"publisher": {
"type": "string",
"description": "Name of the organization publishing this catalog."
},
"description": {
"type": "string",
"description": "Description of the catalog contents."
},
"updateStrategy": {
"type": "object",
"description": "How frequently the catalog image is polled for updates.",
"properties": {
"registryPoll": {
"type": "object",
"properties": {
"interval": {
"type": "string",
"description": "Polling interval as a duration string.",
"examples": ["10m", "1h", "24h"],
"pattern": "^[0-9]+(s|m|h)$"
}
}
}
}
}
}
},
"OperatorGroupSpec": {
"type": "object",
"description": "Spec for an OLM OperatorGroup defining namespace watch scope for operators.",
"properties": {
"targetNamespaces": {
"type": "array",
"description": "Namespaces operators in this group may watch. Empty means all namespaces.",
"items": {
"type": "string",
"description": "Namespace name.",
"pattern": "^[a-z0-9][a-z0-9\\-]*[a-z0-9]$"
}
},
"selector": {
"type": "object",
"description": "Label selector for dynamically resolving target namespaces.",
"properties": {
"matchLabels": {
"type": "object",
"additionalProperties": {"type": "string"}
}
}
}
}
},
"SubscriptionSpec": {
"type": "object",
"description": "Spec for an OLM Subscription declaring intent to install and keep current an operator.",
"required": ["name", "source", "sourceNamespace"],
"properties": {
"name": {
"type": "string",
"description": "Operator package name in the catalog.",
"minLength": 1
},
"source": {
"type": "string",
"description": "Name of the CatalogSource to use."
},
"sourceNamespace": {
"type": "string",
"description": "Namespace of the CatalogSource."
},
"channel": {
"type": "string",
"description": "Channel in the operator package to subscribe to.",
"examples": ["stable", "alpha", "fast", "candidate"]
},
"startingCSV": {
"type": "string",
"description": "Specific CSV version to begin the subscription at. Example: my-operator.v1.2.3."
},
"installPlanApproval": {
"type": "string",
"enum": ["Automatic", "Manual"],
"description": "Whether InstallPlans are approved automatically or require manual approval.",
"default": "Automatic"
},
"config": {
"type": "object",
"description": "Configuration overrides applied to the operator's deployment.",
"properties": {
"env": {
"type": "array",
"description": "Environment variables to add to the operator's deployment.",
"items": {
"type": "object",
"required": ["name"],
"properties": {
"name": {"type": "string"},
"value": {"type": "string"}
}
}
},
"resources": {
"type": "object",
"description": "Resource requests and limits for the operator deployment."
}
}
}
}
},
"InstallPlanSpec": {
"type": "object",
"description": "Spec for an OLM InstallPlan listing resources to be created during operator installation.",
"required": ["clusterServiceVersionNames", "approval", "approved"],
"properties": {
"clusterServiceVersionNames": {
"type": "array",
"description": "List of CSV names to be installed by this plan.",
"items": {
"type": "string",
"description": "CSV name in {package}.{version} format."
}
},
"approval": {
"type": "string",
"enum": ["Automatic", "Manual"],
"description": "Approval mode for this InstallPlan."
},
"approved": {
"type": "boolean",
"description": "Whether this plan has been approved. Set to true to approve a Manual plan."
}
}
},
"CSVSpec": {
"type": "object",
"description": "Spec for a ClusterServiceVersion representing an installed operator version.",
"required": ["displayName", "install"],
"properties": {
"displayName": {
"type": "string",
"description": "Human-readable operator name.",
"minLength": 1
},
"description": {
"type": "string",
"description": "Markdown description of the operator."
},
"version": {
"type": "string",
"description": "Semantic version of the operator.",
"pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+([-+][a-zA-Z0-9\\.]+)?$",
"examples": ["1.0.0", "2.3.1-beta.1"]
},
"maturity": {
"type": "string",
"enum": ["alpha", "beta", "stable"],
"description": "Operator maturity level."
},
"replaces": {
"type": "string",
"description": "CSV name that this version replaces in the upgrade graph."
},
"skips": {
"type": "array",
"description": "CSV versions that are skipped in the upgrade graph.",
"items": {"type": "string"}
},
"installModes": {
"type": "array",
"description": "Namespace installation modes supported by this operator.",
"items": {
"type": "object",
"required": ["type", "supported"],
"properties": {
"type": {
"type": "string",
"enum": ["OwnNamespace", "SingleNamespace", "MultiNamespace", "AllNamespaces"],
"description": "Install mode type."
},
"supported": {
"type": "boolean",
"description": "Whether this mode is supported."
}
}
}
},
"install": {
"type": "object",
"description": "Install strategy for the operator deployment.",
"required": ["strategy"],
"properties": {
"strategy": {
"type": "string",
"enum": ["deployment"],
"description": "Install strategy type. Only 'deployment' is supported."
},
"spec": {
"type": "object",
"description": "Deployment and RBAC specification.",
"properties": {
"deployments": {
"type": "array",
"description": "Deployment specs for operator pods.",
"items": {
"type": "object",
"required": ["name", "spec"],
"properties": {
"name": {"type": "string", "description": "Deployment name."},
"spec": {"type": "object", "description": "Kubernetes Deployment spec."}
}
}
},
"permissions": {
"type": "array",
"description": "Namespace-scoped RBAC rules for the operator.",
"items": {"$ref": "#/$defs/StrategyPermission"}
},
"clusterPermissions": {
"type": "array",
"description": "Cluster-scoped RBAC rules for the operator.",
"items": {"$ref": "#/$defs/StrategyPermission"}
}
}
}
}
},
"customresourcedefinitions": {
"type": "object",
"description": "CRDs owned and required by this operator.",
"properties": {
"owned": {
"type": "array",
"description": "CRDs this operator manages.",
"items": {"$ref": "#/$defs/CRDDescription"}
},
"required": {
"type": "array",
"description": "CRDs this operator depends on.",
"items": {"$ref": "#/$defs/CRDDescription"}
}
}
},
"minKubeVersion": {
"type": "string",
"description": "Minimum Kubernetes version required.",
"pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"
}
}
},
"StrategyPermission": {
"type": "object",
"description": "RBAC permission set for an operator service account.",
"required": ["serviceAccountName", "rules"],
"properties": {
"serviceAccountName": {
"type": "string",
"description": "Service account name to bind the rules to."
},
"rules": {
"type": "array",
"description": "Policy rules granting access to API resources.",
"items": {
"type": "object",
"properties": {
"apiGroups": {
"type": "array",
"items": {"type": "string"},
"description": "API groups the rule applies to. Use '' for core group."
},
"resources": {
"type": "array",
"items": {"type": "string"},
"description": "Resource types the rule applies to."
},
"verbs": {
"type": "array",
"items": {"type": "string"},
"description": "HTTP verbs allowed. Examples: get, list, watch, create, update, patch, delete."
}
}
}
}
}
},
"CRDDescription": {
"type": "object",
"description": "Description of a CRD owned or required by a ClusterServiceVersion.",
"required": ["name", "version", "kind"],
"properties": {
"name": {
"type": "string",
"description": "CRD name in {plural}.{group} format."
},
"version": {
"type": "string",
"description": "API version for this CRD."
},
"kind": {
"type": "string",
"description": "Kind of the custom resource."
},
"displayName": {
"type": "string",
"description": "Human-readable display name."
},
"description": {
"type": "string",
"description": "Description of what this CRD represents."
},
"resources": {
"type": "array",
"description": "Kubernetes resources managed by this CRD.",
"items": {
"type": "object",
"properties": {
"version": {"type": "string"},
"kind": {"type": "string"},
"name": {"type": "string"}
}
}
},
"specDescriptors": {
"type": "array",
"description": "Descriptors for spec fields shown in the operator UI.",
"items": {
"type": "object",
"properties": {
"displayName": {"type": "string"},
"description": {"type": "string"},
"path": {"type": "string", "description": "JSON path to the field."},
"x-descriptors": {
"type": "array",
"items": {"type": "string"},
"description": "UI descriptor hints."
}
}
}
},
"statusDescriptors": {
"type": "array",
"description": "Descriptors for status fields shown in the operator UI.",
"items": {
"type": "object",
"properties": {
"displayName": {"type": "string"},
"description": {"type": "string"},
"path": {"type": "string"},
"x-descriptors": {
"type": "array",
"items": {"type": "string"}
}
}
}
}
}
},
"Condition": {
"type": "object",
"description": "A condition expressing an aspect of current resource state.",
"required": ["type", "status"],
"properties": {
"type": {
"type": "string",
"description": "Type of condition."
},
"status": {
"type": "string",
"enum": ["True", "False", "Unknown"],
"description": "Status of the condition."
},
"reason": {
"type": "string",
"description": "Machine-readable reason."
},
"message": {
"type": "string",
"description": "Human-readable details."
},
"lastTransitionTime": {
"type": "string",
"format": "date-time",
"description": "Last transition timestamp."
},
"observedGeneration": {
"type": "integer",
"description": "Generation at which the condition was last observed."
}
}
}
}
}