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 != General 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 must include several specific fields (see Required K8s Object Fields). In the cases when it doesn’t, the entity is not considered an Object in the context of the K8s terminology.

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

Note

It could be easier to think of Objects as a category of Object Schemas with specific requirements (which they are, see k8s kind field). Anything that doesn’t have all of the above cannot be considered an Object Kind — it is an API Object, however.

Note

In the context of the K8s type system, a General API Object is any other object without the necessary fields but still defined under the Swagger Specification (see OpenAPI Schema) as an Object. 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.

There are many examples of Object and Non-Object Kinds throughout the K8s API Swagger definition (see OpenAPI Schema) but here are a few interesting instances to observe:

• 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 actual 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

• Non-Object entity without the spec field but with kind:

"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