Kubernetes Objects

In the context of k8s, objects are persistent records of intent. They describe the desired state of the cluster, and once created, the system will ensure that they exist.

However, there are some distinctions to be made.

K8s Objects != API Objects

Throughout most of the Kubernetes docs, the term Object refers to entities that are persistent (in etcd) but to qualify as a Kubernetes Object, an entity’s object schema (k8s kind field) must include several specific fields (Required K8s Object Fields). In the cases when it doesn’t, the entity is not an Object.

Not every entity in the type system has a kind, nor entities with the kind field are considered Objects (by K8s parlance) due to the lack of all required Object Fields in their schema:

• Example Non-Object entity without the kind field:

"io.k8s.api.admissionregistration.v1.AuditAnnotation": {
	"description": "...",
	"properties": {
		"key": {
			"description": "...",
			"type": "string"
		},
		"valueExpression": {
			"description": "...",
			"type": "string"
		}
	},
	"required": [
		"key",
		"valueExpression"
	],
	"type": "object"
},
 
// api/openapi-spec/swagger.json

• An example Object:

"io.k8s.api.core.v1.Pod": {
	"description": "...",
	"properties": {
		"apiVersion": {...},
		"kind": {
			"description": "...",
			"type": "string"
		},
		"metadata": {
			"$ref": "...",
			"description": "..."
		},
		"spec": {
			"$ref": "#/definitions/io.k8s.api.core.v1.PodSpec",
			"description": "..."
		},
		"status": {
			"$ref": "#/definitions/io.k8s.api.core.v1.PodStatus",
			"description": "..."
		}
	},
	"type": "object",
	"x-kubernetes-group-version-kind": [...]
},
 
// api/openapi-spec/swagger.json

• An example Non-Object entity with the kind field:

"io.k8s.api.admissionregistration.v1.MutatingWebhookConfigurationList": {
	"description": "...",
	"properties": {
		"apiVersion": {...},
		"items": {
			"description": "List of MutatingWebhookConfiguration.",
			"items": {
				"$ref": "..."
			},
			"type": "array"
		},
		"kind": {
			"description": "...",
			"type": "string"
		},
		"metadata": {
			"$ref": "...",
			"description": "..."
		}
	},
	"required": ["items"],
	"type": "object",
	"x-kubernetes-group-version-kind": [...]
},
 
// api/openapi-spec/swagger.json

So, only Objects have object schemas and everything else has just a schema? Well…

IMPORTANT

Even entities that are not considered Objects by K8s are Objects. In fact, when you look from the perspective of an API, every entity in the K8s API is an Object. These are called Swagger Objects.

NOTE

There are different kinds of objects in the Swagger Specification. Each defines a specific schema describing its expected syntax and structure. And just like these Swagger Objects, the Kubernetes API defines its own Kubernetes Objects (Pods, Deployments, Services) via the OpenAPI Definitions Object. This Swagger Object allows users to define schemas that they can reference later under the resources.

Required K8s Object Fields

From the docs:

• apiVersion - Which version of the Kubernetes API you’re using to create this object
• kind - What kind of object you want to create
• metadata - Data that helps uniquely identify the object, including a name string, UID, and optional namespace
• spec - What state you desire for the object

Anything that doesn’t have all of the above cannot be considered an Object — it is a Swagger Object, however.