ReviseAlgo Logo

Kubernetes Architecture

Kubernetes Objects and the Declarative Model

Defining target states in YAML vs imperative commands.

Interview: Explain the difference between declarative and imperative models. Why is the declarative model preferred in GitOps? Be ready to define the four required root fields in any Kubernetes YAML file: apiVersion, kind, metadata, and spec.

Last Updated: June 15, 2026 • 15 min read

Introduction

In an Imperative model, you tell the system *what steps to execute* (e.g. "Create a network, then run this container, then map port 80"). In a Declarative model, you specify *the final desired state* (e.g. "I want 3 replicas of this container running and listening on port 80"), and the system automatically determines how to achieve and maintain that state.

Kubernetes is built from the ground up on the declarative model. Desired states are declared in structured YAML manifests, enabling GitOps workflows.

Why It Matters

Declarative models make infrastructure self-healing and reproducible. If a server node dies, the orchestrator refers to the declared target state and schedules replacements. It also acts as configuration-as-code, fitting cleanly into version control systems.

Real-World Analogy

An imperative approach is like giving turn-by-turn driving directions: "Go straight, turn right at the traffic lights, go 2 miles, stop at the third house." If there is a road closure, the driver gets lost. A declarative approach is like typing the address into your GPS: "Get me to 123 Main Street." If a bridge is closed, the GPS recalculates the route automatically to get you to your final destination.

How It Works

Every Kubernetes YAML object definition must include these four root fields:

  • apiVersion: Version of the Kubernetes API schema used to create this object (e.g. v1 or apps/v1).
  • kind: The schema object type to create (e.g. Pod, Service, Deployment).
  • metadata: Information that helps uniquely identify the object (e.g. name, namespace, and labels).
  • spec: Core configuration specification (the desired target state of the object).

Internal Architecture

Every active Kubernetes object contains two nested JSON schemas:
• spec: Provided by you, defining the desired state.
• status: Maintained and updated by the Kubernetes control plane, describing the current observed runtime state of the object.
The control plane continuously reconciles the difference between the spec and the status.

Visual Explanation

Loading diagram…

Practical Example

Here is a basic declarative Pod manifest in YAML:

Common Mistakes

1. Confusing apiVersion schemas: Using apiVersion: v1 for a Deployment. Deployments reside in the apps/v1 api group. Mixing these up causes validation errors.
2. Manual modifications: Running imperative commands on objects created declaratively. If you run kubectl scale deployment --replicas=5, but your Git repository still says replicas: 3, the next GitOps run will scale the app back down to 3, overwriting your manual changes.

Quick Quiz

Q1: Which root field contains the detailed target configuration representing your desired system state?

A) metadata

B) spec

C) status

Answer: B — The spec block is where the developer declares the desired target parameters of the resource.

Scenario-Based Challenge

Scenario:

Your manager wants to enforce GitOps so that any infrastructure change is reviewed via Pull Requests before executing in production. How do declarative manifests enable this workflow?

View Solution

Declarative manifests represent the desired state of your infrastructure as source code. You check these manifests into a Git repository. To make a change, developers submit a Pull Request. Once merged, a GitOps sync agent (like ArgoCD or Flux) reads the new manifests and applies them to the cluster, ensuring that the cluster state always matches the repository configuration.

Debugging Exercise

Failure Case:

You run kubectl apply -f deployment.yaml, but it fails with: error: error validating data: ValidationError(Deployment.spec): missing required field "selector".

How do you debug and fix this?

View Solution

The API schema for Deployments requires declaring a label selector to link the Deployment to its generated pods.
Fix: Add a selector.matchLabels block matching the pod template labels:

Interview Questions

1. What are the four required root fields in any Kubernetes object manifest?

apiVersion (schema version), kind (resource type), metadata (identifying keys like name/namespace), and spec (desired configuration).

2. What is the difference between the 'spec' and 'status' schemas of a Kubernetes object?

spec defines the desired state declared by the user. status describes the current observed runtime state maintained by the cluster control plane.

Production Considerations

Use dry-run commands (kubectl apply -f manifest.yaml --dry-run=client) or static validation tools (like kubeval or pluto) in your pipelines to catch schema syntax errors before committing manifests to your clusters.