Kubernetes objects: Imperative vs declarative creation explained

Everything in Kubernetes happens through objects. Whether you are deploying an application, scaling it, or exposing it to traffic, you are creating and managing Kubernetes objects. These objects represent the desired state of your cluster, and Kubernetes continuously works to ensure the actual state matches what you have defined.

Two ways to create objects

There are two approaches to creating Kubernetes objects: imperative and declarative.

• Imperative means telling Kubernetes exactly what to do right now using a direct command. It is fast for experimentation and debugging but not repeatable or version-controllable.
• Declarative means defining the desired state in a YAML file and applying it. Kubernetes figures out how to get from the current state to the desired state. This is the recommended approach for production because it works with version control and GitOps workflows.

Imperative creation

Create a deployment directly with a command:

1kubectl create deploy nginx --image=nginx --port=80

Verify the deployment was created:

1kubectl get deploy

Expected output:

1NAME    READY   UP-TO-DATE   AVAILABLE   AGE
2nginx   1/1     1            1           10s

Delete the deployment:

1kubectl delete deploy nginx

Declarative creation

The declarative approach uses YAML files applied with kubectl apply. Rather than writing YAML from scratch, use the --dry-run=client -o yaml flag to generate a starting template.

Generating a YAML template without creating the resource

This is one of the most useful kubectl techniques. The --dry-run=client flag runs the command locally without sending anything to the API server, so nothing gets created. Combined with -o yaml it outputs a valid manifest you can save and edit:

1kubectl create deploy nginx --image=nginx --port=80 --dry-run=client -o yaml > deploy.yaml

This generates a complete Deployment YAML file saved to deploy.yaml. Open it, make any changes you need, then apply it:

1kubectl apply -f deploy.yaml

Expected output:

1deployment.apps/nginx created

To update the deployment later, edit the YAML file and run kubectl apply -f deploy.yaml again. Unlike kubectl create, kubectl apply is idempotent — it creates the resource if it does not exist, or updates it if it does.

Structure of a Kubernetes object

Every Kubernetes object is defined by four fields:

1apiVersion: apps/v1       # The Kubernetes API version for this resource
2kind: Deployment          # The type of object to create
3metadata:                 # Data that identifies the object
4  name: nginx
5  labels:
6    app: nginx
7spec:                     # The desired state of the object
8  replicas: 1
9  selector:
10    matchLabels:
11      app: nginx
12  template:
13    metadata:
14      labels:
15        app: nginx
16    spec:
17      containers:
18      - name: nginx
19        image: nginx
20        ports:
21        - containerPort: 80

• apiVersion specifies which version of the Kubernetes API to use. Different object types use different API versions — for example Deployments use apps/v1 while Pods use v1.
• kind specifies the type of object. Common values include Pod, Deployment, Service, ConfigMap, and Namespace.
• metadata contains identifying information including the object name, namespace, and labels.
• spec defines the desired state. The contents of spec vary by object type — a Deployment spec defines replicas and pod templates, a Service spec defines ports and selectors.

Viewing available API resources

To see every resource type available in your cluster including short names, API groups, and whether they are namespaced:

1kubectl api-resources

Expected output (abbreviated):

1NAME                   SHORTNAMES   APIVERSION   NAMESPACED   KIND
2pods                   po           v1           true         Pod
3deployments            deploy       apps/v1      true         Deployment
4services               svc          v1           true         Service
5namespaces             ns           v1           false        Namespace
6nodes                  no           v1           false        Node

This is useful when you cannot remember the exact resource name or want to check what custom resource definitions (CRDs) are installed in the cluster.

View all namespaces:

1kubectl get ns