Kubectl apply vs. create: What's the difference?

Example of kubectl apply

Let's explore the details of both kubectl usages. First, let's look at kubectl apply. Listing 1 below is a manifest file that describes a Kubernetes deployment that has three replicas of a nginx container image.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mydeployment
  labels:
    app: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:latest
        ports:
        - containerPort: 80

The name of the deployment manifest file in Listing 1 is mydeployment.yaml. If you run the command below, it will create a deployment according to the contents of this manifest file.

kubectl apply -f mydeployment.yaml

Executing the command will create the following response:

deployment/mydeployment created

When you run the command kubectl get deployment, you'll get the following output:

NAME           READY   UP-TO-DATE   AVAILABLE   AGE
mydeployment   3/3     3            3           7m10s

Here, we've created the deployment named mydeployment, and it is running its three pods.

Example of kubectl create

Now, let's use kubectl create to try to create a deployment imperatively, like so:

kubectl create deployment mydeployment --image=nginx

When you execute the imperative command, you'll get the following result:

Error from server (AlreadyExists): deployments.apps "mydeployment" already exists

This makes sense. Remember, if you try to use kubectl create against a resource that already exists, you'll get an error.

However, let's try to execute kubectl create for a resource that doesn't exist. In this case, we'll create a Kubernetes deployment named yourdeployment. We'll create it using the following command:

kubectl create deployment yourdeployment --image=nginx

You'll get the following output, indicating success:

deployment.apps/yourdeployment created

Adjusted manifest file example

Let's adjust the first deployment we created: mydeployment. We can do this by updating the manifest file, mydeployment.yaml, as shown below in Listing 2. The number of replicas has been increased from three to four, as shown below in red.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mydeployment
  labels:
    app: nginx
spec:
  replicas: 4
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:latest
        ports:
        - containerPort: 80

To update the deployment from three replicas to four, we execute kubectl apply, like so:

kubectl apply -f mydeployment.yaml

You'll get the following output:

deployment.apps/mydeployment configured

The output reports that the deployment has been configured. This means a change has been applied to an existing deployment. Let's run the command set kubectl get deployment to confirm the deployment is indeed running four pods. You'll get an output similar to the following:

NAME           READY   UP-TO-DATE   AVAILABLE   AGE
mydeployment   4/4     4            4           18m

The important thing to understand about kubectl create vs. kubectl apply is that you use kubectl create to create Kubernetes resources imperatively at the command-line or declaratively against a manifest file. However, you can use kubectl create declaratively only to create a new resource.

On the other hand, you use kubectl apply to create a new Kubernetes resource declaratively using a manifest file. You can also use kubectl apply to update an existing resource by changing the configuration settings in the given manifest file.