Applying Manifests to the Cluster: A Practical Guide

Previously in this course, we covered the basics of defining infrastructure in Creating Your First Pod Manifest: A Kubernetes YAML Guide. Now that you have a valid manifest, it is time to transition from writing code to running it. In this lesson, we will use kubectl apply to submit your configuration to the Kubernetes API server and verify that your workload is active.

Moving from Definition to Execution

Kubernetes is a declarative system. You describe the "desired state" of your environment in a YAML file, and the cluster works to match the "actual state" to that description. The primary tool for this transition is kubectl apply.

When you run kubectl apply -f <filename>, you are sending your YAML manifest to the Kubernetes API server. The API server validates the request and stores your configuration in etcd, the cluster’s state store. From there, the controller manager detects a new resource—your Pod—and schedules it onto a worker node.

Worked Example: Launching Your First Pod

Let’s assume you have a file named nginx-pod.yaml in your current directory. If you haven't already, ensure your environment is configured by following the steps in Setting Up Your Local Environment: kubectl and Local Clusters.

1. Applying the Manifest

Execute the following command in your terminal:

Bash
kubectl apply -f nginx-pod.yaml

If successful, you will see a simple confirmation message: pod/nginx-pod created.

2. Verifying the Deployment

To check if the Pod is actually running, use the get command:

Bash
kubectl get pods

You should see a list showing your Pod status as Running. If it says ContainerCreating, wait a few seconds and run the command again. This delay is normal as the container runtime pulls the image from the registry.

3. Cleaning Up

Once you have finished exploring, it is good practice to clean up your environment to save resources:

Bash
kubectl delete -f nginx-pod.yaml

Hands-on Exercise: The Lifecycle Loop

1. Create a file named my-web-pod.yaml with a simple image (e.g., nginx:latest).
2. Apply the manifest to your cluster.
3. Run kubectl get pods and observe the transition from Pending to Running.
4. Delete the Pod using the YAML file.
5. Bonus: Try applying the file again. Notice how kubectl tracks the resource identity based on the metadata.name defined in your YAML.

Common Pitfalls

• Wrong Context: If kubectl apply fails with a connection error, verify your cluster context using the methods in Managing Kubeconfig and Contexts: Secure Cluster Switching. You might be pointing to the wrong cluster.
• Syntax Errors: YAML is indentation-sensitive. If you get a parsing error, ensure you are using spaces, not tabs, and that your indentation levels are consistent.
• Resource Already Exists: If you try to create a Pod with a name that is already taken in the same namespace, kubectl will throw an "already exists" error. You must delete the existing one first or change the name in your manifest.
• Wait Times: Beginners often assume a command failed because the status isn't "Running" immediately. Give the cluster a moment to pull the image and start the container before assuming something is broken.

Frequently Asked Questions

Why use apply instead of create?

kubectl create is an imperative command that fails if the resource already exists. kubectl apply is declarative; it updates the existing resource to match your current YAML, making it the standard for ongoing infrastructure management.

Can I apply an entire directory of files?

Yes. If you have a folder full of manifests, you can run kubectl apply -f ./my-manifests/ to apply everything in that directory at once.

How do I see more details if my Pod isn't starting?

Use kubectl describe pod <pod-name>. This command provides a wealth of information, including recent "Events" that often reveal exactly why a container is failing to start.

Recap

In this lesson, we moved from static files to active infrastructure. You learned that kubectl apply is the bridge between your intentions and the cluster's reality. By mastering the cycle of applying, verifying, and deleting resources, you have taken a foundational step in managing the lifecycle of your applications.

Up next: We will dive deeper into the Pod Lifecycle to understand the various phases a container goes through during its existence.