Declarative Versus Imperative Object Management

Foundations / Guide 5 of 103 / Beginner

• Kubernetes1.36.4
• Cluster4 nodes
• Runtimecontainerd 2.2.6
• CNICalico v3.32.1
• TimeAbout 25 min

Temporary paths and timestamps in the diff output are from this run and will differ on yours.

This guide includes

Use this when you are choosing between kubectl create and kubectl apply, or when a later apply overwrites something you set by hand. This matters because only one of them records what you asked for, and that record is what makes diffs and safe re-applies possible.

• generating YAML with create --dry-run=client -o yaml rather than writing it from memory
• creating imperatively and finding no last-applied annotation left behind
• applying declaratively and reading the annotation that records your intent
• running kubectl diff to see a change before you make it
• seeing the trap in mixing the two approaches on one object

Before you start

• A working cluster and kubectl.
• The kubectl session guide, mainly for kubectl explain, which is how you find field names without looking them up.
• The Pods guide, so the Deployment spec below is recognisable.

1. 1

   The imperative shortcut, and how to make it write YAML for you

2. 2

   Run it for real, then ask what it remembered

3. 3

   The declarative form, and the annotation it leaves behind

4. 4

   Why that annotation matters: kubectl diff

5. 5

   Which to use, and the trap in mixing them

Official sources

• Declarative management with configuration files
• Imperative management with configuration files
• Kubernetes object management
• kubectl apply reference
• kubectl diff reference
• Server-side apply