{
	"id": "d350099c-2d4f-491a-8614-47acb196c8a6",
	"created_at": "2026-04-06T00:16:46.749064Z",
	"updated_at": "2026-04-10T03:21:19.139739Z",
	"deleted_at": null,
	"sha1_hash": "c1e9da11513b690587d5b7ae90c0e686c613bfc8",
	"title": "The Kubernetes API",
	"llm_title": "",
	"authors": "",
	"file_creation_date": "0001-01-01T00:00:00Z",
	"file_modification_date": "0001-01-01T00:00:00Z",
	"file_size": 92476,
	"plain_text": "The Kubernetes API\r\nArchived: 2026-04-05 20:23:27 UTC\r\nThe Kubernetes API lets you query and manipulate the state of objects in Kubernetes. The core of Kubernetes'\r\ncontrol plane is the API server and the HTTP API that it exposes. Users, the different parts of your cluster, and\r\nexternal components all communicate with one another through the API server.\r\nThe core of Kubernetes' control plane is the API server. The API server exposes an HTTP API that lets end users,\r\ndifferent parts of your cluster, and external components communicate with one another.\r\nThe Kubernetes API lets you query and manipulate the state of API objects in Kubernetes (for example: Pods,\r\nNamespaces, ConfigMaps, and Events).\r\nMost operations can be performed through the kubectl command-line interface or other command-line tools, such\r\nas kubeadm, which in turn use the API. However, you can also access the API directly using REST calls.\r\nKubernetes provides a set of client libraries for those looking to write applications using the Kubernetes API.\r\nEach Kubernetes cluster publishes the specification of the APIs that the cluster serves. There are two mechanisms\r\nthat Kubernetes uses to publish these API specifications; both are useful to enable automatic interoperability. For\r\nexample, the kubectl tool fetches and caches the API specification for enabling command-line completion and\r\nother features. The two supported mechanisms are as follows:\r\nThe Discovery API provides information about the Kubernetes APIs: API names, resources, versions, and\r\nsupported operations. This is a Kubernetes specific term as it is a separate API from the Kubernetes\r\nOpenAPI. It is intended to be a brief summary of the available resources and it does not detail specific\r\nschema for the resources. For reference about resource schemas, please refer to the OpenAPI document.\r\nThe Kubernetes OpenAPI Document provides (full) OpenAPI v2.0 and 3.0 schemas for all Kubernetes API\r\nendpoints. The OpenAPI v3 is the preferred method for accessing OpenAPI as it provides a more\r\ncomprehensive and accurate view of the API. It includes all the available API paths, as well as all resources\r\nconsumed and produced for every operations on every endpoints. It also includes any extensibility\r\ncomponents that a cluster supports. The data is a complete specification and is significantly larger than that\r\nfrom the Discovery API.\r\nDiscovery API\r\nKubernetes publishes a list of all group versions and resources supported via the Discovery API. This includes the\r\nfollowing for each resource:\r\nName\r\nCluster or namespaced scope\r\nEndpoint URL and supported verbs\r\nAlternative names\r\nhttps://kubernetes.io/docs/concepts/overview/kubernetes-api/\r\nPage 1 of 7\n\nGroup, version, kind\r\nThe API is available in both aggregated and unaggregated form. The aggregated discovery serves two endpoints,\r\nwhile the unaggregated discovery serves a separate endpoint for each group version.\r\nAggregated discovery\r\nFEATURE STATE: Kubernetes v1.30 [stable] (enabled by default)\r\nKubernetes offers stable support for aggregated discovery, publishing all resources supported by a cluster through\r\ntwo endpoints ( /api and /apis ). Requesting this endpoint drastically reduces the number of requests sent to\r\nfetch the discovery data from the cluster. You can access the data by requesting the respective endpoints with an\r\nAccept header indicating the aggregated discovery resource: Accept:\r\napplication/json;v=v2;g=apidiscovery.k8s.io;as=APIGroupDiscoveryList .\r\nWithout indicating the resource type using the Accept header, the default response for the /api and /apis\r\nendpoint is an unaggregated discovery document.\r\nThe discovery document for the built-in resources can be found in the Kubernetes GitHub repository. This Github\r\ndocument can be used as a reference of the base set of the available resources if a Kubernetes cluster is not\r\navailable to query.\r\nThe endpoint also supports ETag and protobuf encoding.\r\nUnaggregated discovery\r\nWithout discovery aggregation, discovery is published in levels, with the root endpoints publishing discovery\r\ninformation for downstream documents.\r\nA list of all group versions supported by a cluster is published at the /api and /apis endpoints. Example:\r\n{\r\n \"kind\": \"APIGroupList\",\r\n \"apiVersion\": \"v1\",\r\n \"groups\": [\r\n {\r\n \"name\": \"apiregistration.k8s.io\",\r\n \"versions\": [\r\n {\r\n \"groupVersion\": \"apiregistration.k8s.io/v1\",\r\n \"version\": \"v1\"\r\n }\r\n ],\r\n \"preferredVersion\": {\r\n \"groupVersion\": \"apiregistration.k8s.io/v1\",\r\n \"version\": \"v1\"\r\n }\r\nhttps://kubernetes.io/docs/concepts/overview/kubernetes-api/\r\nPage 2 of 7\n\n},\r\n {\r\n \"name\": \"apps\",\r\n \"versions\": [\r\n {\r\n \"groupVersion\": \"apps/v1\",\r\n \"version\": \"v1\"\r\n }\r\n ],\r\n \"preferredVersion\": {\r\n \"groupVersion\": \"apps/v1\",\r\n \"version\": \"v1\"\r\n }\r\n },\r\n ...\r\n}\r\nAdditional requests are needed to obtain the discovery document for each group version at\r\n/apis/\u003cgroup\u003e/\u003cversion\u003e (for example: /apis/rbac.authorization.k8s.io/v1alpha1 ), which advertises the\r\nlist of resources served under a particular group version. These endpoints are used by kubectl to fetch the list of\r\nresources supported by a cluster.\r\nOpenAPI interface definition\r\nFor details about the OpenAPI specifications, see the OpenAPI documentation.\r\nKubernetes serves both OpenAPI v2.0 and OpenAPI v3.0. OpenAPI v3 is the preferred method of accessing the\r\nOpenAPI because it offers a more comprehensive (lossless) representation of Kubernetes resources. Due to\r\nlimitations of OpenAPI version 2, certain fields are dropped from the published OpenAPI including but not\r\nlimited to default , nullable , oneOf .\r\nOpenAPI V2\r\nThe Kubernetes API server serves an aggregated OpenAPI v2 spec via the /openapi/v2 endpoint. You can\r\nrequest the response format using request headers as follows:\r\nHeader Possible values Notes\r\nAccept-Encoding\r\ngzip\r\nnot supplying this header is also\r\nacceptable\r\nAccept application/com.github.proto-openapi.spec.v2@v1.0+protobuf\r\nmainly for intra-cluster use\r\napplication/json default\r\nhttps://kubernetes.io/docs/concepts/overview/kubernetes-api/\r\nPage 3 of 7\n\nHeader Possible values Notes\r\n* serves application/json\r\nWarning:\r\nThe validation rules published as part of OpenAPI schemas may not be complete, and usually aren't. Additional\r\nvalidation occurs within the API server. If you want precise and complete verification, a kubectl apply --dry-run=server runs all the applicable validation (and also activates admission-time checks).\r\nOpenAPI V3\r\nFEATURE STATE: Kubernetes v1.27 [stable] (enabled by default)\r\nKubernetes supports publishing a description of its APIs as OpenAPI v3.\r\nA discovery endpoint /openapi/v3 is provided to see a list of all group/versions available. This endpoint only\r\nreturns JSON. These group/versions are provided in the following format:\r\n{\r\n \"paths\": {\r\n ...,\r\n \"api/v1\": {\r\n \"serverRelativeURL\": \"/openapi/v3/api/v1?hash=CC0E9BFD992D8C59AEC98A1E2336F899E8318D3CF4C68944C3DEC6\r\n },\r\n \"apis/admissionregistration.k8s.io/v1\": {\r\n \"serverRelativeURL\": \"/openapi/v3/apis/admissionregistration.k8s.io/v1?hash=E19CC93A116982CE5422FC42\r\n },\r\n ....\r\n }\r\n}\r\nThe relative URLs are pointing to immutable OpenAPI descriptions, in order to improve client-side caching. The\r\nproper HTTP caching headers are also set by the API server for that purpose ( Expires to 1 year in the future, and\r\nCache-Control to immutable ). When an obsolete URL is used, the API server returns a redirect to the newest\r\nURL.\r\nThe Kubernetes API server publishes an OpenAPI v3 spec per Kubernetes group version at the\r\n/openapi/v3/apis/\u003cgroup\u003e/\u003cversion\u003e?hash=\u003chash\u003e endpoint.\r\nRefer to the table below for accepted request headers.\r\nhttps://kubernetes.io/docs/concepts/overview/kubernetes-api/\r\nPage 4 of 7\n\nHeader Possible values Notes\r\nAccept-Encoding\r\ngzip\r\nnot supplying this header is also\r\nacceptable\r\nAccept\r\napplication/com.github.proto-openapi.spec.v3@v1.0+protobuf\r\nmainly for intra-cluster use\r\napplication/json default\r\n* serves application/json\r\nA Golang implementation to fetch the OpenAPI V3 is provided in the package k8s.io/client-go/openapi3 .\r\nKubernetes 1.35 publishes OpenAPI v2.0 and v3.0; there are no plans to support 3.1 in the near future.\r\nProtobuf serialization\r\nKubernetes implements an alternative Protobuf based serialization format that is primarily intended for intra-cluster communication. For more information about this format, see the Kubernetes Protobuf serialization design\r\nproposal and the Interface Definition Language (IDL) files for each schema located in the Go packages that define\r\nthe API objects.\r\nPersistence\r\nKubernetes stores the serialized state of objects by writing them into etcd.\r\nAPI groups and versioning\r\nTo make it easier to eliminate fields or restructure resource representations, Kubernetes supports multiple API\r\nversions, each at a different API path, such as /api/v1 or /apis/rbac.authorization.k8s.io/v1alpha1 .\r\nVersioning is done at the API level rather than at the resource or field level to ensure that the API presents a clear,\r\nconsistent view of system resources and behavior, and to enable controlling access to end-of-life and/or\r\nexperimental APIs.\r\nTo make it easier to evolve and to extend its API, Kubernetes implements API groups that can be enabled or\r\ndisabled.\r\nAPI resources are distinguished by their API group, resource type, namespace (for namespaced resources), and\r\nname. The API server handles the conversion between API versions transparently: all the different versions are\r\nactually representations of the same persisted data. The API server may serve the same underlying data through\r\nmultiple API versions.\r\nFor example, suppose there are two API versions, v1 and v1beta1 , for the same resource. If you originally\r\ncreated an object using the v1beta1 version of its API, you can later read, update, or delete that object using\r\nhttps://kubernetes.io/docs/concepts/overview/kubernetes-api/\r\nPage 5 of 7\n\neither the v1beta1 or the v1 API version, until the v1beta1 version is deprecated and removed. At that point\r\nyou can continue accessing and modifying the object using the v1 API.\r\nAPI changes\r\nAny system that is successful needs to grow and change as new use cases emerge or existing ones change.\r\nTherefore, Kubernetes has designed the Kubernetes API to continuously change and grow. The Kubernetes project\r\naims to not break compatibility with existing clients, and to maintain that compatibility for a length of time so that\r\nother projects have an opportunity to adapt.\r\nIn general, new API resources and new resource fields can be added often and frequently. Elimination of resources\r\nor fields requires following the API deprecation policy.\r\nKubernetes makes a strong commitment to maintain compatibility for official Kubernetes APIs once they reach\r\ngeneral availability (GA), typically at API version v1 . Additionally, Kubernetes maintains compatibility with\r\ndata persisted via beta API versions of official Kubernetes APIs, and ensures that data can be converted and\r\naccessed via GA API versions when the feature goes stable.\r\nIf you adopt a beta API version, you will need to transition to a subsequent beta or stable API version once the API\r\ngraduates. The best time to do this is while the beta API is in its deprecation period, since objects are\r\nsimultaneously accessible via both API versions. Once the beta API completes its deprecation period and is no\r\nlonger served, the replacement API version must be used.\r\nNote:\r\nAlthough Kubernetes also aims to maintain compatibility for alpha APIs versions, in some circumstances this is\r\nnot possible. If you use any alpha API versions, check the release notes for Kubernetes when upgrading your\r\ncluster, in case the API did change in incompatible ways that require deleting all existing alpha objects prior to\r\nupgrade.\r\nRefer to API versions reference for more details on the API version level definitions.\r\nAPI Extension\r\nThe Kubernetes API can be extended in one of two ways:\r\n1. Custom resources let you declaratively define how the API server should provide your chosen resource\r\nAPI.\r\n2. You can also extend the Kubernetes API by implementing an aggregation layer.\r\nWhat's next\r\nLearn how to extend the Kubernetes API by adding your own CustomResourceDefinition.\r\nControlling Access To The Kubernetes API describes how the cluster manages authentication and\r\nauthorization for API access.\r\nLearn about API endpoints, resource types and samples by reading API Reference.\r\nhttps://kubernetes.io/docs/concepts/overview/kubernetes-api/\r\nPage 6 of 7\n\nLearn about what constitutes a compatible change, and how to change the API, from API changes.\r\nSource: https://kubernetes.io/docs/concepts/overview/kubernetes-api/\r\nhttps://kubernetes.io/docs/concepts/overview/kubernetes-api/\r\nPage 7 of 7",
	"extraction_quality": 1,
	"language": "EN",
	"sources": [
		"MITRE"
	],
	"references": [
		"https://kubernetes.io/docs/concepts/overview/kubernetes-api/"
	],
	"report_names": [
		"kubernetes-api"
	],
	"threat_actors": [],
	"ts_created_at": 1775434606,
	"ts_updated_at": 1775791279,
	"ts_creation_date": 0,
	"ts_modification_date": 0,
	"files": {
		"pdf": "https://archive.orkl.eu/c1e9da11513b690587d5b7ae90c0e686c613bfc8.pdf",
		"text": "https://archive.orkl.eu/c1e9da11513b690587d5b7ae90c0e686c613bfc8.txt",
		"img": "https://archive.orkl.eu/c1e9da11513b690587d5b7ae90c0e686c613bfc8.jpg"
	}
}