kubectl apply vs create in Kubernetes - Trade-offs & Expert Analysis

Overview - kubectl apply vs create

What is it?

kubectl is a command-line tool to manage Kubernetes clusters. The commands 'kubectl create' and 'kubectl apply' both help you add resources like pods or services to your cluster. 'kubectl create' makes a new resource from a file or command, while 'kubectl apply' creates or updates resources based on a file. They look similar but behave differently when the resource already exists.

Why it matters

Without understanding the difference, you might accidentally overwrite or fail to update your cluster resources, causing downtime or configuration drift. Knowing when to use each command helps keep your cluster stable and your deployments smooth. It solves the problem of managing changes safely and efficiently in a live system.

Where it fits

Before this, you should know basic Kubernetes concepts like pods, deployments, and YAML resource files. After this, you can learn about advanced deployment strategies, rolling updates, and GitOps workflows that rely heavily on 'kubectl apply'.

Mental Model

Core Idea

'kubectl create' makes a resource once, while 'kubectl apply' manages the resource’s full lifecycle by creating or updating it as needed.

Think of it like...

Imagine planting a tree: 'create' is like planting a new tree seed in empty soil, and if a tree is already there, you can't plant again. 'apply' is like tending the tree—if it’s not there, you plant it; if it is, you prune or water it to keep it healthy.

┌───────────────┐       ┌───────────────┐
│ kubectl create│──────▶│ Creates only  │
│               │       │ new resource  │
└───────────────┘       └───────────────┘
         │
         │ If resource exists
         ▼
┌───────────────┐       ┌───────────────┐
│ kubectl apply │──────▶│ Creates or    │
│               │       │ updates       │
└───────────────┘       └───────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding kubectl basics

Concept: Learn what kubectl is and how it interacts with Kubernetes resources.

kubectl is the main tool to talk to Kubernetes clusters. You use it to create, update, delete, and inspect resources like pods, services, and deployments. It reads YAML files that describe these resources and sends instructions to the cluster.

Result

You can manage Kubernetes resources from your terminal using YAML files.

Knowing kubectl is the gateway to controlling Kubernetes clusters is essential before learning specific commands.

2

Foundation

Creating resources with kubectl create

Concept: 'kubectl create' adds a new resource to the cluster from a YAML file or command.

When you run 'kubectl create -f resource.yaml', Kubernetes makes the resource described in the file. If the resource already exists, the command fails with an error. This command is simple and only works for new resources.

Result

A new resource appears in the cluster if it did not exist before.

Understanding that 'create' only works once per resource helps avoid errors when managing existing resources.

3

Intermediate

Updating resources with kubectl apply

🤔Before reading on: do you think 'kubectl apply' can update existing resources or only create new ones? Commit to your answer.

Concept: 'kubectl apply' can create a resource if missing or update it if it exists, based on the YAML file.

'kubectl apply -f resource.yaml' compares the current cluster state with the file and changes only what differs. It uses a 'declarative' approach, meaning you declare the desired state, and Kubernetes makes it so. This lets you safely update resources without deleting them first.

Result

The resource is created if missing or updated to match the YAML file if it exists.

Knowing 'apply' manages the full lifecycle of a resource prevents accidental overwrites and supports safe updates.

4

Intermediate

How kubectl apply tracks changes

🤔Before reading on: do you think 'kubectl apply' remembers previous changes or just overwrites blindly? Commit to your answer.

Concept: 'kubectl apply' stores a snapshot of the last applied configuration to detect changes.

When you apply a file, kubectl saves the configuration in an annotation on the resource. Next time you apply, it compares the new file with this saved version to find differences. This lets it update only what changed, avoiding conflicts with manual edits.

Result

Updates are precise and avoid overwriting unrelated changes.

Understanding this tracking mechanism explains why 'apply' is safer for ongoing resource management.

5

Intermediate

Limitations of kubectl create

Concept: 'kubectl create' cannot update existing resources and will error if the resource exists.

If you try 'kubectl create' on a resource that already exists, Kubernetes returns an error like 'AlreadyExists'. This means you must delete the resource first or use 'apply' to update it. 'create' is best for one-time resource creation.

Result

Errors occur if you try to create duplicates.

Knowing this limitation helps choose the right command to avoid deployment failures.

6

Advanced

Using kubectl apply in GitOps workflows

🤔Before reading on: do you think 'kubectl apply' alone is enough for full GitOps automation? Commit to your answer.

Concept: 'kubectl apply' is the foundation for GitOps, where desired states are stored in Git and applied automatically.

In GitOps, you store YAML files in Git repositories as the source of truth. Automated tools run 'kubectl apply' to sync the cluster with Git. This ensures the cluster matches the declared state and supports version control, rollback, and audit trails.

Result

Clusters stay consistent with Git repositories automatically.

Understanding 'apply' as a declarative sync tool unlocks modern infrastructure automation practices.

7

Expert

Surprises in kubectl apply patching behavior

🤔Before reading on: do you think 'kubectl apply' always merges changes perfectly? Commit to your answer.

Concept: 'kubectl apply' uses a strategic merge patch that can sometimes cause unexpected overwrites or conflicts.

The patching method tries to merge changes intelligently but can overwrite fields if the YAML file omits them. Also, manual edits outside 'apply' can be lost if not reflected in the applied file. Understanding patch types and annotations helps avoid these pitfalls.

Result

Unexpected resource changes or lost manual edits can happen without careful management.

Knowing the patching internals prevents subtle bugs and data loss in production clusters.

Under the Hood

'kubectl create' sends a create request to the Kubernetes API server, which rejects duplicates. 'kubectl apply' reads the resource's last applied configuration stored in annotations, calculates a patch by comparing it with the new YAML, and sends a patch request to update only changed fields. This declarative approach lets Kubernetes reconcile desired and actual states efficiently.

Why designed this way?

Initially, Kubernetes only supported imperative commands like 'create' and 'update', which risked overwriting manual changes. 'kubectl apply' was designed to enable declarative management, allowing users to declare desired states and let Kubernetes handle updates safely. This design supports automation, version control, and collaboration.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ YAML file     │──────▶│ kubectl apply │──────▶│ API Server    │
└───────────────┘       └───────────────┘       └───────────────┘
         │                      │                      │
         ▼                      ▼                      ▼
┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ Last applied  │◀─────│ Patch calc    │──────▶│ Resource store│
│ config stored │       │ (diff old/new)│       └───────────────┘
└───────────────┘       └───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does 'kubectl create' update existing resources if they exist? Commit to yes or no.

Common Belief: 'kubectl create' can update resources if they already exist.

Reality: 'kubectl create' fails with an error if the resource already exists; it cannot update existing resources.

Why it matters: Trying to use 'create' to update causes deployment failures and confusion.

Quick: Does 'kubectl apply' overwrite manual changes made outside of kubectl? Commit to yes or no.

Common Belief: 'kubectl apply' always preserves manual changes made directly on the cluster.

Reality: 'kubectl apply' overwrites manual changes if they are not reflected in the applied YAML file.

Why it matters: Manual edits can be lost unexpectedly, causing configuration drift and outages.

Quick: Is 'kubectl apply' slower or more resource-heavy than 'kubectl create'? Commit to yes or no.

Common Belief: 'kubectl apply' is just a simple create command and has no overhead.

Reality: 'kubectl apply' does extra work to calculate patches and track last applied configs, making it slightly more complex but safer.

Why it matters: Understanding this helps optimize automation pipelines and troubleshoot performance.

Quick: Can 'kubectl apply' handle all resource types equally well? Commit to yes or no.

Common Belief: 'kubectl apply' works perfectly with every Kubernetes resource type.

Reality: 'kubectl apply' works best with resources that support strategic merge patch; some custom resources may behave unexpectedly.

Why it matters: Knowing this prevents surprises when managing custom or third-party resources.

Expert Zone

1

'kubectl apply' stores the last applied configuration in an annotation, which can grow large and affect resource metadata size.

2

Strategic merge patch used by 'apply' can behave differently depending on resource schema, causing subtle merge conflicts.

3

Manual edits outside of 'apply' require careful syncing or risk being overwritten, so teams often restrict direct edits.

When NOT to use

'kubectl create' is not suitable for updating resources; use 'kubectl apply' instead. For complex patching or partial updates, 'kubectl patch' or server-side apply may be better. In CI/CD pipelines, declarative tools like Helm or Kustomize combined with 'apply' provide more control.

Production Patterns

Teams use 'kubectl apply' in GitOps workflows to sync cluster state with Git repositories. 'kubectl create' is used for one-time resource provisioning or scripts. Advanced users combine 'apply' with Kustomize overlays or Helm charts for environment-specific configurations.

Connections

GitOps

'kubectl apply' is the core command used in GitOps to sync cluster state with Git repositories.

Understanding 'apply' clarifies how GitOps automates Kubernetes deployments by declaring desired states.

Declarative vs Imperative Configuration

'kubectl create' is imperative (do this now), while 'kubectl apply' is declarative (declare desired state).

Knowing this distinction helps choose the right approach for managing infrastructure and software.

Version Control Systems

'kubectl apply' works well with version-controlled YAML files, enabling traceability and rollback.

This connection shows how software development practices improve infrastructure management.

Common Pitfalls

#1 Trying to update an existing resource with 'kubectl create' causes errors.

Wrong approach:

kubectl create -f deployment.yaml

Correct approach:

kubectl apply -f deployment.yaml

Root cause:

Misunderstanding that 'create' only works for new resources and cannot update existing ones.

#2 Manually editing a resource in the cluster and then applying an outdated YAML file causes loss of manual changes.

Wrong approach:

kubectl apply -f old-config.yaml

Correct approach:

Update the YAML file to match manual changes before applying or avoid manual edits.

Root cause:

Not realizing 'apply' overwrites cluster state to match the YAML file exactly.

#3 Using 'kubectl apply' without understanding patch behavior leads to unexpected overwrites.

Wrong approach:

kubectl apply -f partial-resource.yaml (missing some fields)

Correct approach:

Ensure YAML files are complete or use server-side apply for better merge handling.

Root cause:

Ignoring how strategic merge patch works and that missing fields may be removed.

Key Takeaways

'kubectl create' is for making new resources and fails if the resource exists.

'kubectl apply' creates or updates resources by declaring the desired state in YAML files.

'kubectl apply' tracks changes using stored configurations to safely update resources without overwriting unrelated changes.

Understanding the difference prevents deployment errors and supports modern Kubernetes workflows like GitOps.

Be aware of patching behavior and manual edits to avoid losing changes or causing conflicts.