Appearance

From kubectl to a running Pod

Trace API acceptance, scheduling, image preparation, and status without conflating them.

What you will understand

  • Follow the complete ordinary Pod creation path
  • Locate failure before or after node binding
  • Interpret Running and Ready as separate observations

Builds on: Desired state and reconciliation

Mental model: one intention, several asynchronous owners

When kubectl apply returns “created,” the API request has completed: the API server accepted and persisted a Pod object. The response does not confirm application startup. Scheduling and worker preparation proceed independently and may still be incomplete, although fast observers can already have advanced the Pod before the response reaches your terminal. This separation explains why a command can succeed while a Pod remains Pending or its application immediately exits.

kubectl reads a kubeconfig context, connects to the configured API endpoint, and sends authenticated requests. The API server checks permissions, admission requirements, and the object’s schema. Admission can supply defaults or reject a request. Successful persistence makes the object observable to other components. kubectl does not log into a worker and execute the image itself, and the API server does not synchronously wait for a web request to succeed before acknowledging creation.

For an ordinary unassigned Pod, the scheduler observes the object, evaluates feasible nodes, and records a binding. The selected node’s kubelet observes that assignment. Its local preparation includes volumes and the Pod sandbox, with networking performed through the installed network integration and runtime path. The kubelet uses CRI to request image and container operations from the runtime. Precise preparation steps can overlap and differ by implementation; the responsibility boundary is the important invariant.

Accepted does not mean started

Trace kubectl through API persistence and scheduler binding.

Flow viewStep 1 of 3
kubectl submits the PodThe configured context identifies the API endpoint and credentials. The API validates and admits the requested Pod.. kubectl apply, active. API server, active. Pod request, idlekubectl apply
kubectl applyIn focus
API server
API serverIn focus
Pod request
Pod requestContext
kubectl applyIn focus
API serverIn focus
Pod requestContext
Animation controls
Speed
0.5×
1×
2×
Explore a scenario
Normal behavior
Failure: admission rejects the write
kubectl submits the Pod

The configured context identifies the API endpoint and credentials. The API validates and admits the requested Pod.

Read the complete visual sequence
  1. kubectl submits the Pod

    The configured context identifies the API endpoint and credentials. The API validates and admits the requested Pod.

  2. Creation acknowledges accepted intent

    The Pod object is persisted, so kubectl can return created without waiting for binding or startup. Observers may already have advanced the Pod by the time the client receives that response.

  3. Scheduler records placement

    The scheduler selects an eligible worker and binds the Pod. The worker now has an assignment to observe.

Failure: admission rejects the write

Failure: admission rejects the write

  1. Submit an invalid request

    An invalid field or a violated admission requirement can reject the request before any Pod is persisted.

  2. No Pod exists to schedule

    The API returns an error. The scheduler has no accepted object from this request.

  3. Correct and resubmit

    Read the API error, correct the manifest or required policy inputs, and retry the write before investigating worker execution.

About this model

One ordinary Pod uses default scheduling; admission and persistence are drawn as one API stage. Frames show responsibilities, not an exact ordering of client receipt and observer actions.

Walkthrough: capture evidence at each boundary

Create a disposable namespace and save the following object as path-demo.yaml. The namespace is an API organization boundary explained in the next module. All commands explicitly name it so the experiment does not depend on your current default namespace.

apiVersion: v1
kind: Pod
metadata:
  name: path-demo
  namespace: path-lab
  labels:
    app: path-demo
spec:
  containers:
    - name: web
      image: nginx:1.27.5
      ports:
        - containerPort: 80 # Documentation; nginx supplies the listener.
kubectl create namespace path-lab
kubectl apply -f path-demo.yaml
# Node and Pod IP appear only when the relevant work has completed.
kubectl -n path-lab get pod path-demo -o wide -w
# In another terminal, inspect conditions and event reasons.
kubectl -n path-lab describe pod path-demo
kubectl -n path-lab get pod path-demo -o yaml

A healthy lab should eventually show a node assignment, a Pod IP, and a running web container. “Pending” covers more than the scheduler queue: a bound Pod can still be preparing images or volumes. Check spec.nodeName, conditions, container waiting reasons, and events instead of deciding the cause from the phase column alone.

The kubelet reports container states and Pod conditions through the API. A container may be Waiting, Running, or Terminated. Pod phase is a coarser summary. Running means the Pod has been bound, all its containers have been created, and at least one is running or being started/restarted; it is not an end-to-end availability test. The Ready condition expresses a different usability signal. Without deliberate application probes, that signal may be much weaker than your service’s real business readiness requirements.

Assigned, prepared, reported

Show local image preparation, executable startup, and status reporting.

Lifecycle viewStep 1 of 3
Kubelet observes its assignmentThe kubelet on node-a sees the bound Pod and prepares local dependencies, including the Pod sandbox and required mounts.. Bound Pod, active. Kubelet node-a, active. CRI runtime, idleBound Pod
Bound PodIn focus
Kubelet node-a
Kubelet node-aIn focus
CRI runtime
CRI runtimeContext
Bound PodIn focus
Kubelet node-aIn focus
CRI runtimeContext
Animation controls
Speed
0.5×
1×
2×
Explore a scenario
Normal behavior
Failure: executable exits after a successful pull
Kubelet observes its assignment

The kubelet on node-a sees the bound Pod and prepares local dependencies, including the Pod sandbox and required mounts.

Read the complete visual sequence
  1. Kubelet observes its assignment

    The kubelet on node-a sees the bound Pod and prepares local dependencies, including the Pod sandbox and required mounts.

  2. Runtime starts the container

    The runtime ensures the image is available and launches the configured executable. A valid image can still contain a failing command.

  3. Status is reported to the API

    The kubelet reports observed states and conditions. Running and Ready are separate fields, and neither replaces an actual request test.

Failure: executable exits after a successful pull

Failure: executable exits after a successful pull

  1. Image preparation succeeds

    The required image is available and the runtime launches the command. The image may have been cached locally; a container start alone does not prove current registry reachability.

  2. Application exits

    The command fails and terminates. Under the usual Always Pod restart policy, the kubelet attempts a container restart with backoff as appropriate.

  3. Inspect execution evidence

    Read logs and previous-container logs plus the termination reason. This failure follows successful scheduling and image preparation, whether the image was pulled or reused locally.

About this model

Networking and volume implementations are collapsed into local preparation; one container is shown.

Practice: compare before and after binding

Use an invalid image tag in a second disposable Pod. Its object can be accepted and bound, but the runtime cannot retrieve the image. Expect an assigned node and image-pull failure evidence. Contrast that with a Pod that requests an impossible amount of memory in the later resource lab: that Pod may remain unassigned with FailedScheduling events. The visible “not running” symptom is similar, but different components own the next useful action.

Wait deliberately for a condition when automation needs one:

kubectl -n path-lab wait --for=condition=Ready pod/path-demo --timeout=90s
kubectl -n path-lab logs path-demo -c web --tail=20
# Local access for this named Pod; not a Service or external load balancer.
kubectl -n path-lab port-forward pod/path-demo 8080:80

While port-forward runs, request http://127.0.0.1:8080/ from another terminal. An HTTP response tests the selected Pod through a debugging tunnel. It does not establish that Service selection, cluster DNS, or external exposure works. A wait timeout similarly means the requested condition did not arrive before the deadline; inspect evidence rather than treating the timeout as a diagnosis.

Pitfalls

A status listing is an observation that can become stale. Use watches and repeat inspection when state changes. Events are useful, time-limited records and can be aggregated; do not assume every internal operation creates one or that the oldest evidence remains forever. For a failed process, logs and termination state complement events, while a failed image pull may have no application logs at all.

Check your understanding

A Pod has a node name but reports ImagePullBackOff. Should you replace the scheduler?

No. Placement has already completed for this Pod. Investigate the image reference, credentials, registry access, and runtime-side error details. The scheduler does not resolve registry tags or start containers. Correct the responsible layer, then observe whether the kubelet can advance startup.

Use the module lab to label each observation with its responsible component. Stop port-forward and delete the disposable namespace after the experiment.

Primary documentation

Go to the source

Reviewed 2026-10-27 · Kubernetes 1.37 · Related local exercise

Search the book

Search loads when you open it.