Chapter 4: Navigating the Kubernetes API and object model
The chapter introduction recalls how Deployments, Pods, and Services formed the previous chapter’s application and introduces the study of common Kubernetes object features.
After this chapter you will be able to
- Deployment Pod and Service roles. Explain that the previous chapter’s Deployment spawned multiple Pods, each representing an application instance, and that a Service exposed those instances through a load balancer.
- Cluster configuration through API objects. Explain that users and Kubernetes components interact with a cluster by manipulating objects through the Kubernetes API, and that those objects represent the cluster’s configuration.
- RESTful cluster configuration. Explain how users interact with cluster configuration through the Kubernetes API: resources expose state over HTTP, and standard methods perform create, read, update, and delete operations.
- Resources versus objects. Distinguish an API resource from an object using the section’s examples: collection and individual URIs can expose the same object, API versions can expose different representations of one object set, and some resources do not create objects.
- Object manifest sections. Describe the four sections found in most Kubernetes object manifests and what each contains.
- Controller use of spec and status. Trace how a controller uses an object's spec and status to manage it.
- Node Objects and Host State. Explain that each cluster host is represented by a Node object in the API, which can be listed with kubectl get nodes. Distinguish the host configuration in spec from its state in status.
- Object type metadata. Explain what apiVersion and kind identify in a Node manifest, including why a Node’s apiVersion is v1 rather than a group-qualified value.
- Node metadata and specification. Distinguish the metadata section, which identifies and describes this Node instance, from the kind-specific spec section, which includes its assigned pod IP range.
- Observed Node status. Explain what the status section represents and give examples of the Node information it reports.
- Exploring object fields with kubectl. Describe how to use kubectl explain to inspect an object kind and drill into a particular field. Distinguish the usual descriptions from the recursive field listing.
- Status condition fields. Describe how an object's status conditions are represented and what the fields of an individual condition tell you.
- Node condition interpretation. Explain what the four Node conditions indicate and how they help identify a node problem.
- Readable Node object inspection. Explain how kubectl describe helps inspect a Node object compared with viewing its complete YAML manifest, and name examples of information it displays.
- Related data in describe output. Explain why a Node's describe output can contain more than the Node object itself, and why its event list may be empty.
- Events as reconciliation signals. Explain that controllers generate events while reconciling an object’s actual state with the desired state in its spec. Distinguish Normal and Warning events, and describe how monitoring Warning events can reveal problems that prevent reconciliation.
- Standalone Event objects. Explain that events are separate Kubernetes API objects containing information about what happened to another object and the event’s source. Describe why they do not appear in that object’s YAML manifest and why they are deleted after a short time.
- Event listing and inspection. Distinguish the events shown by kubectl describe from those returned by kubectl get events, and describe what the -o wide option adds.
- Event manifest field organization. Explain why an Event object's YAML can look disorganized, and contrast it with the apparently orderly top-level fields of a Node object.
What it builds on
- Deploying your application (chapter 3) · Creating the application’s Deployment.
- Exposing your application to the world (chapter 3) · Exposing the application with a Service.
- Using kubectl (chapter 3) · Earlier experience interacting with Kubernetes using kubectl.
Section by section
Introduction
The chapter introduction recalls how Deployments, Pods, and Services formed the previous chapter’s application and introduces the study of common Kubernetes object features.
- Deployment Pod and Service roles: Explain that the previous chapter’s Deployment spawned multiple Pods, each representing an application instance, and that a Service exposed those instances through a load balancer.
Why it matters: This gives you a concrete example of how different Kubernetes objects work together.
Key terms: Deployment object, Pod objects, Service object, load balancer
4.1 Getting familiar with the Kubernetes API
The section introduces Kubernetes API objects as the way users and Kubernetes components configure a cluster.
- Cluster configuration through API objects: Explain that users and Kubernetes components interact with a cluster by manipulating objects through the Kubernetes API, and that those objects represent the cluster’s configuration.
Why it matters: This gives you a way to understand what Kubernetes commands and manifests act on.
Key terms: Kubernetes API, objects, configuration
4.1.1 Introducing the API
Introduces the Kubernetes API as a RESTful way to interact with cluster state, distinguishes API resources from objects, and explains how objects are represented in requests and responses.
- RESTful cluster configuration: Explain how users interact with cluster configuration through the Kubernetes API: resources expose state over HTTP, and standard methods perform create, read, update, and delete operations.
Why it matters: This connects API requests to the cluster configuration they read or change. - Resources versus objects: Distinguish an API resource from an object using the section’s examples: collection and individual URIs can expose the same object, API versions can expose different representations of one object set, and some resources do not create objects.
Why it matters: The distinction prevents treating every API URI as a separate stored object. - Object text representations: Describe how the API exchanges object state: GET returns structured text, JSON is the default data model, YAML can also be requested, and POST or PUT can specify new state in either format.
Why it matters: It explains why object state can be read and submitted as JSON or YAML.
Key terms: Kubernetes API, RESTful API, resources, objects, CRUD, resource, object, URI, collection, API versions
4.1.2 Understanding the structure of an object manifest
Explains the main parts of a Kubernetes object manifest, how controllers use spec and status, and why some objects lack those sections.
- Object manifest sections: Describe the four sections found in most Kubernetes object manifests and what each contains.
Why it matters: These sections give you a way to navigate a large object manifest. - Controller use of spec and status: Trace how a controller uses an object's spec and status to manage it.
Why it matters: It explains how an API object communicates both your request to Kubernetes and Kubernetes' progress back to you. - Objects without spec or status: Explain why some Kubernetes API objects have no spec or status sections.
Why it matters: It prevents you from expecting every manifest to have the same four sections.
Key terms: type metadata, object metadata, spec, status, controller, desired state, actual state, metadata, static data, Event object
4.2 Examining an object’s individual properties
This section uses Node objects to show how Kubernetes represents cluster machines and separates their configuration from their state.
- Node Objects and Host State: Explain that each cluster host is represented by a Node object in the API, which can be listed with kubectl get nodes. Distinguish the host configuration in spec from its state in status.
Why it matters: This distinction helps you interpret a Node object when inspecting a cluster. - Node Registration and Editing: Explain how a Node object is usually created when a machine joins the cluster, and what users can subsequently change.
Why it matters: It clarifies why a Node object appears when a machine joins and which part users may modify.
Key terms: Node object, host, spec, status, kubectl get nodes, Kubelet, node agent, registers the node
4.2.1 Exploring the full manifest of a Node object
This section uses a Node manifest to show how to inspect a Kubernetes object and interpret its main fields.
- Node manifest inspection: Describe how to list Nodes and retrieve one Node’s full YAML manifest with kubectl, or access it through the kubectl proxy.
Why it matters: Retrieving the full manifest lets you inspect fields that a brief Node listing does not show. - Object type metadata: Explain what apiVersion and kind identify in a Node manifest, including why a Node’s apiVersion is v1 rather than a group-qualified value.
Why it matters: These fields tell you how to interpret a manifest before you examine its object-specific fields. - Node metadata and specification: Distinguish the metadata section, which identifies and describes this Node instance, from the kind-specific spec section, which includes its assigned pod IP range.
Why it matters: Separating instance metadata from configuration makes the manifest easier to read. - Observed Node status: Explain what the status section represents and give examples of the Node information it reports.
Why it matters: Status tells you what has been observed about a Node, rather than what its specification configures.
Key terms: kubectl get nodes, kubectl get node <node-name> -o yaml, -o json, kubectl proxy, apiVersion, kind, schema, API group, core API group, metadata
4.2.2 Understanding individual object fields
This section shows how to inspect Kubernetes object fields with kubectl explain and how the selected API version affects the fields shown.
- Exploring object fields with kubectl: Describe how to use kubectl explain to inspect an object kind and drill into a particular field. Distinguish the usual descriptions from the recursive field listing.
Why it matters: You can inspect manifest fields from the command line rather than guessing their structure. - API version and field differences: Explain why the API version shown by kubectl explain matters and how to request a different version.
Why it matters: Checking the version helps you interpret field information for the API version you intend to use.
Key terms: kubectl explain, kind, field, --recursive, API version, --api-version
4.2.3 Understanding an object’s status conditions
Explains how status conditions describe different aspects of a Kubernetes object’s state, using Node conditions to show how to spot problems.
- Status condition fields: Describe how an object's status conditions are represented and what the fields of an individual condition tell you.
Why it matters: Condition fields help you read an object's status rather than relying on a single overall state. - Node condition interpretation: Explain what the four Node conditions indicate and how they help identify a node problem.
Why it matters: These conditions point you toward readiness or resource pressure when troubleshooting a node. - Multiple orthogonal conditions: Justify why many Kubernetes objects use a list of conditions rather than one state field.
Why it matters: Separate conditions let you interpret several aspects of an object's state without treating them as mutually exclusive.
Key terms: conditions, type, status, reason, message, lastTransitionTime, Ready, MemoryPressure, DiskPressure, PIDPressure
4.2.4 Inspecting objects using the kubectl describe command
This section shows how kubectl describe presents a Node object readably and adds related information gathered from other API objects.
- Readable Node object inspection: Explain how kubectl describe helps inspect a Node object compared with viewing its complete YAML manifest, and name examples of information it displays.
Why it matters: It gives you a readable way to inspect a node without working through its full YAML manifest. - Related data in describe output: Explain why a Node's describe output can contain more than the Node object itself, and why its event list may be empty.
Why it matters: It helps you interpret extra diagnostic details without mistaking them for fields stored in the Node object.
Key terms: kubectl describe, Node object, YAML manifest, Pod objects, events, allocated compute resources
4.3 Observing cluster events via Event objects
This section explains how controller-generated events make reconciliation activity and cluster problems visible.
- Events as reconciliation signals: Explain that controllers generate events while reconciling an object’s actual state with the desired state in its spec. Distinguish Normal and Warning events, and describe how monitoring Warning events can reveal problems that prevent reconciliation.
Why it matters: Events give you a way to notice when the cluster is having trouble bringing an object to its desired state.
Key terms: controllers, reconciling, spec field, Normal, Warning, events
4.3.1 Introducing the Event object
This section explains that Kubernetes events are short-lived Event objects and shows how to list and filter them with kubectl.
- Standalone Event objects: Explain that events are separate Kubernetes API objects containing information about what happened to another object and the event’s source. Describe why they do not appear in that object’s YAML manifest and why they are deleted after a short time.
Why it matters: This explains where to look for an event and why an older one may no longer be available. - Event listing and inspection: Distinguish the events shown by kubectl describe from those returned by kubectl get events, and describe what the -o wide option adds.
Why it matters: Choosing the right command helps you see either one object’s events or the broader cluster event listing. - Warning event filtering: Explain how to focus a kubectl event listing on warnings using a field selector, and how to check the Event field and its permitted values.
Why it matters: Filtering makes warnings easier to spot without treating every Normal event as a concern.
Key terms: Event object, Kubernetes API, YAML manifest, etcd, kubectl describe, kubectl get events, -o wide, field selector, --field-selector, kubectl explain events
4.3.2 Examining the YAML of the Event object
This section explains why Event object YAML is harder to read than a Node manifest and how alphabetical field ordering affects Kubernetes manifests generally.
- Event manifest field organization: Explain why an Event object's YAML can look disorganized, and contrast it with the apparently orderly top-level fields of a Node object.
Why it matters: It helps you read Kubernetes manifests without mistaking a convenient field order for a deliberate grouping.
Key terms: Event object, spec, status, Node object, YAML manifest, alphabetical order
4.4 Summary
Summarizes how Kubernetes API objects are represented and managed, and how their status and events help inspect cluster components.
Where this is used later
- Creating the Pod object from the YAML file (chapter 5) · Creating a Pod object from a file is an interaction with the Kubernetes API.
- Creating a YAML manifest for a pod (chapter 5) · Creating a Pod YAML manifest uses one of the object representations introduced here.
- Understanding the pod phase (chapter 6) · Reading individual fields of a Kubernetes object.
- Deleting namespaces (chapter 7) · Understanding that Kubernetes objects have fields, including status information.
- Understanding pod conditions (chapter 6) · Reading pod conditions uses the same condition-list concept.
- Checking the newly created pod (chapter 5) · Inspecting a newly created pod builds on reading information about an API object.
- Inspecting the StatefulSet, Pods, and PersistentVolumeClaims (chapter 16) · Using kubectl describe to inspect an object.
- Using a field selector in kubectl (chapter 7) · The same field-selector idea is used to filter objects with kubectl.
Concepts explained in this chapter
- statusStatus is the Kubernetes object field containing information about the current observed state of the represented component or resource.
- eventA Kubernetes Event is an API object that records an occurrence or state transition involving a cluster object.
- specA spec is the Kubernetes object field containing the declarative configuration of the desired state.
- versionAn API version identifies a versioned Kubernetes API schema for a resource kind, including its available fields and default values.
- Kubernetes worker nodeA Kubernetes node is a machine that runs kubelet, containers, and pods belonging to a cluster.
- kubectl explainkubectl explain is a Kubernetes command that displays documentation for the fields and structure of an API object type.
- schemaA schema is a formal description of the fields and structure used to represent an object.
- Kubernetes resourceA Kubernetes object is a persistent API resource representing a desired or observed aspect of an application or cluster.
- Kubernetes APIThe Kubernetes API is the programmatic interface through which clients and applications query and modify Kubernetes resources and cluster state.
- resourceAn API resource is an addressable Kubernetes API endpoint and representation associated with an object type.
- metadataMetadata is the Kubernetes object information describing an object, including identity, labels, annotations, and related attributes.
- kubectl getkubectl get is a kubectl command that retrieves Kubernetes objects of a specified type from the API.
- conditionA condition is a status entry representing one aspect of a Kubernetes object's current state.
- kind fieldAn object kind is the Kubernetes API identifier that specifies the type of an API object.
- Kubernetes manifestA manifest file is a YAML or JSON file that declares one or more Kubernetes objects.
- metadata sectionA metadata section is the part of a Kubernetes object definition containing identity and management metadata for an object instance.
- field selectorA field selector is a Kubernetes API query mechanism that filters objects by matching specified field values.
- ready conditionContainer readiness is the status indicating whether a container is ready to serve its intended workload.
- kubectl describekubectl describe is a kubectl command that displays detailed information about a Kubernetes object and related cluster information.
- kubeletThe kubelet is the agent on a Kubernetes node that manages the applications assigned to that node and reports their status.
← Chapter 3: Deploying your first application on Kubernetes
Chapter 5: Running applications with pods →
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.