Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 37 ยท Architecture and Concepts

API Objects and Inspecting Them with oc

Learn how every OpenShift object is described by apiVersion, kind, metadata, spec and status, and use oc api-resources, explain, get, describe and events to inspect them.

Everything in OpenShift is an API object: a Pod, a Route, a Secret, even a cluster Operator's settings. Each object is stored as structured data and has the same top-level shape. Once you can read that shape, you can read any manifest and debug almost any problem.

The four parts of an object

YAML
apiVersion: apps/v1
kind: Deployment
metadata:
  name: hello
  namespace: hello-demo
  labels:
    app: hello
spec:
  replicas: 2
  selector:
    matchLabels:
      app: hello
  template:
    metadata:
      labels:
        app: hello
    spec:
      containers:
        - name: web
          image: quay.io/example/hello-web:1.0
          ports:
            - containerPort: 8080
status:
  readyReplicas: 2
Field Purpose
apiVersion The API group and version that defines the kind, such as apps/v1 or route.openshift.io/v1. Core objects use plain v1.
kind The type of object.
metadata Name, namespace, labels, annotations, UID, creation time, owner references.
spec The desired state. You write this.
status The observed state. Controllers write this; you read it.

Some kinds such as ConfigMap have data instead of spec. The rule "you write spec, controllers write status" is worth remembering: if status disagrees with spec, a controller is still working or is stuck.

Names, labels and annotations

  • name identifies the object inside its namespace for its kind.
  • labels are short key/value pairs used for selection: app=hello, tier=frontend. Services, Deployments and NetworkPolicies find Pods by label.
  • annotations are free-form metadata that tools read, such as openshift.io/display-name or a route's haproxy.router.openshift.io/timeout. They are not used for selection.

Discovering kinds

You do not need to memorize kinds. Ask the cluster:

Terminal
oc api-resources
oc api-resources --api-group=route.openshift.io
oc api-resources --namespaced=false
oc explain route
oc explain route.spec.tls
oc explain deployment.spec.strategy --recursive

oc api-resources prints the NAME, short names (deploy, svc, cm, pvc), API group, whether the kind is namespaced and its KIND. oc explain prints the built-in documentation for a field, so you rarely need a browser.

Operator-added kinds show up too. Installing an Operator for a database makes oc explain work for its custom resource definitions (CRDs).

Inspecting objects

Terminal
oc get deployment hello
oc get deployment hello -o yaml
oc get deployment hello -o jsonpath='{.spec.replicas}'
oc describe deployment hello
oc get events --sort-by=.lastTimestamp
oc get pods --show-labels
  • get is brief; -o yaml is complete, including status.
  • describe is a human-friendly summary and ends with the Events, which is where most explanations for failures live (scheduling errors, image pull errors, failed probes).
  • oc get events shows recent events for the project; sort them to see the newest.

Two useful tricks:

Terminal
oc get deployment hello -o yaml --show-managed-fields=false
oc get pod <name> -o jsonpath='{.status.containerStatuses[*].state}'

Creating objects: imperative and declarative

There are two styles. Imperative commands such as oc create deployment, oc expose and oc scale do one thing now. Declarative work means you keep YAML files and oc apply -f them (see YAML manifests and oc apply). You can get a starting manifest from an imperative command without creating anything:

Terminal
oc create deployment hello --image=quay.io/example/hello-web:1.0 --dry-run=client -o yaml

Owner references and garbage collection

Controllers mark what they create. A Deployment owns a ReplicaSet, which owns Pods; each child carries an ownerReferences entry. Delete the owner and Kubernetes automatically deletes its children (garbage collection). This is why deleting a single Pod of a Deployment just makes a new one: the owner wants the Pod to exist.

flowchart TB
  D["Deployment hello"] --> RS["ReplicaSet hello-6d5f"]
  RS --> P1["Pod hello-6d5f-aaaa"]
  RS --> P2["Pod hello-6d5f-bbbb"]

Figure: owner references form a tree used for cleanup.

Stand-in: reading a manifest

The stand-in below parses a tiny YAML-like dictionary into the five parts and prints what a reviewer would check first. Python dictionaries stand in for YAML here.

Python Stand-in: split an object into its parts

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Stand-in: label selectors

Label selection is simple but central. This stand-in implements equality-based selection, the same rule oc get pods -l app=hello,tier=web uses.

Python Stand-in: select Pods by label

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Checking permissions with oc auth

When a command fails with "forbidden", ask the API what you may do:

Terminal
oc auth can-i create deployments
oc auth can-i delete pods -n other-project
oc whoami

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which part of an object describes the desired state?

    You write spec to say what you want. Controllers write status to report what exists.
  2. 2. Which command lists the fields of a Route's TLS settings with documentation?

    oc explain prints API documentation for a field path.
  3. 3. Where do you most often find the reason a Pod will not start?

    Scheduling, image pull and probe failures are recorded as Events, shown by oc describe and oc get events.
  4. 4. What are labels mainly used for?

    Services, Deployments and queries such as oc get -l use labels to select objects.

Summary

  • Objects have apiVersion, kind, metadata, spec (desired) and status (observed).
  • Labels select, annotations carry tool metadata.
  • Use oc api-resources and oc explain to discover kinds and fields.
  • oc describe shows Events, which usually explain failures.
  • Owner references link Deployments, ReplicaSets and Pods for automatic cleanup.

Next: Projects and Namespaces