Deploy Containers on EKS with kubectl: YAML, Logs, and Rollbacks

Simple explanation

kubectl is a command-line tool that talks to your Kubernetes cluster’s API server. Every action you take (deploying an app, scaling it, reading logs, deleting a pod) is an HTTP request to that API server.

On EKS, AWS runs the control plane (the API server, scheduler, and controllers) so you do not have to manage it. You point kubectl at the cluster and start giving it instructions. When you apply a Deployment manifest, the API server stores your desired state, the scheduler finds nodes with capacity, and the Deployment controller creates pods on those nodes. Each pod pulls your container image, starts the process, and begins accepting traffic once it passes its readiness probe.

The key difference from docker run is that you declare what you want, not how to do it. You say “I want 3 replicas of this container running.” If one crashes, Kubernetes restarts it. If a node fails, Kubernetes reschedules the affected pods.

Before you start

You will need all of the following before the commands in this guide will work:

• An EKS cluster already running. See Creating your first EKS cluster if you have not done this yet.
• kubectl installed (kubectl version --client should return a version)
• AWS CLI installed and configured (aws sts get-caller-identity should return your account)
• kubeconfig updated for the cluster (covered in step 1 below)
• A container image available in Amazon ECR or another accessible registry
• Optionally: a namespace already chosen for your workload

How it works on EKS

When you run kubectl apply, here is what actually happens:

1. kubectl reads your YAML and sends an HTTP request to the EKS API server
2. The API server validates the manifest and stores the desired state in etcd
3. The Deployment controller notices the new desired state and creates a ReplicaSet
4. The scheduler assigns each pod to a node based on resource availability
5. The kubelet on each node pulls the container image from ECR (or your registry) and starts it
6. Once the pod passes its readiness probe, the Service starts routing traffic to it

The EKS control plane handles steps 2 through 4 for you. You interact only with the API server via kubectl.

Step-by-step: deploy a container to EKS with kubectl

Step 1: Configure kubectl for the cluster

Before running any kubectl commands, point kubectl at your EKS cluster:

aws eks update-kubeconfig \
  --region eu-west-1 \
  --name my-cluster

This writes an entry to ~/.kube/config and sets it as the active context. Verify it worked:

# Show the active context
kubectl config current-context
# Expected: arn:aws:eks:eu-west-1:123456789012:cluster/my-cluster

# List all configured contexts
kubectl config get-contexts

# Switch to a different context
kubectl config use-context arn:aws:eks:eu-west-1:123456789012:cluster/my-cluster

Step 2: Create or choose a namespace

Namespaces separate workloads inside the same cluster. Keeping production and staging in different namespaces on the same cluster is a common pattern.

Create a namespace with a manifest (recommended for anything tracked in version control):

# namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: production

kubectl apply -f namespace.yaml

Or create it directly:

kubectl create namespace production

Every command in this guide uses -n production. Omitting the flag defaults to the default namespace, which is why pods “disappear” after forgetting to include it.

Step 3: Create the Deployment manifest

A Deployment is the standard way to run a containerised application on Kubernetes. It manages the desired replica count, handles rolling updates, and restarts failed pods automatically.

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: demo-app
  namespace: production
  labels:
    app: demo-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: demo-app
  template:
    metadata:
      labels:
        app: demo-app
    spec:
      containers:
        - name: demo-app
          image: 123456789012.dkr.ecr.eu-west-1.amazonaws.com/demo-app:1.2.0
          ports:
            - containerPort: 8080
          resources:
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              cpu: 500m
              memory: 256Mi

A few things worth noting:

• The selector.matchLabels must match the template.metadata.labels. This is how the Deployment knows which pods it owns.
• Always include resources.requests and resources.limits. Without them the scheduler cannot make good placement decisions and a runaway pod can starve other workloads.
• Use an explicit image tag (1.2.0) rather than latest. See the common mistakes section for why this matters.

The ECR image URI format is: <account-id>.dkr.ecr.<region>.amazonaws.com/<repo-name>:<tag>. See Amazon ECR for how to build and push images.

Step 4: Create the Service manifest

A Deployment alone does not make your app reachable. Pod IP addresses change every time a pod restarts or is rescheduled. A Service gives you a stable virtual IP and DNS name that always routes to whichever pods are currently healthy.

# service.yaml
apiVersion: v1
kind: Service
metadata:
  name: demo-app
  namespace: production
spec:
  selector:
    app: demo-app
  ports:
    - protocol: TCP
      port: 80
      targetPort: 8080
  type: ClusterIP

ClusterIP is reachable only inside the cluster. This is the right default for an internal API or backend. To expose the app externally, add a LoadBalancer type Service or an Ingress controller. The Ingress controllers page covers that next step.

The selector: app: demo-app connects the Service to the pods. It must match the pod labels in the Deployment template exactly. A mismatch here is one of the most common reasons apps are unreachable after deployment.

Step 5: Apply the manifests

Apply both files:

kubectl apply -f deployment.yaml
kubectl apply -f service.yaml

Or apply an entire directory at once:

kubectl apply -f ./k8s/

kubectl apply is idempotent. Running it a second time with no changes makes no changes. Running it after updating the image tag triggers a rolling update. This is why apply is the standard approach: it works the same way whether you are creating a resource for the first time or updating an existing one.

Step 6: Verify the rollout

After applying, confirm the Deployment and pods came up correctly:

# Check the Deployment
kubectl get deployments -n production
# NAME       READY   UP-TO-DATE   AVAILABLE   AGE
# demo-app   3/3     3            3           45s

# Check the pods
kubectl get pods -n production
# NAME                        READY   STATUS    RESTARTS   AGE
# demo-app-7d9f8b-x4klm       1/1     Running   0          45s
# demo-app-7d9f8b-p9wrt       1/1     Running   0          45s
# demo-app-7d9f8b-m2zkq       1/1     Running   0          44s

# Wait for the rollout to complete (blocks until done or failed)
kubectl rollout status deployment/demo-app -n production
# deployment "demo-app" successfully rolled out

If a pod is not healthy, kubectl describe gives you the detail you need:

kubectl describe pod demo-app-7d9f8b-x4klm -n production

Look at the Events section at the bottom of the output. Image pull failures, scheduling failures, and OOMKilled events all appear there first.

Step 7: View logs and debug problems

Once pods are running, use kubectl logs to read their output:

# View current logs for a pod
kubectl logs demo-app-7d9f8b-x4klm -n production

# Stream logs in real time
kubectl logs -f demo-app-7d9f8b-x4klm -n production

# View logs across all pods with a label
kubectl logs -l app=demo-app -n production

# View logs from a previous container instance after a crash
kubectl logs demo-app-7d9f8b-x4klm -n production --previous

# View logs from a specific container in a multi-container pod
kubectl logs demo-app-7d9f8b-x4klm -n production -c sidecar

When a container will not start, check in this order:

1. kubectl describe pod: look at Events for image pull errors or scheduling failures
2. kubectl logs --previous: check for application startup errors
3. Check resource limits: is the pod being OOMKilled?
4. Check the image URI and tag: does the image actually exist in ECR?

For CrashLoopBackOff specifically, the EKS CrashLoopBackOff troubleshooting guide covers the most common causes.

For structured, persistent log storage, see Logging in Kubernetes on EKS.

Step 8: Port-forward for local testing

Port forwarding lets you reach a pod or Service from your local machine without any external exposure.

# Forward to a pod directly (stops working if that pod is replaced)
kubectl port-forward pod/demo-app-7d9f8b-x4klm 8080:8080 -n production

# Forward to the Service (recommended: works with any healthy pod)
kubectl port-forward service/demo-app 8080:80 -n production

With either command running, open http://localhost:8080 in a browser or run curl http://localhost:8080.

Prefer Service port-forwarding over pod port-forwarding. Pod names include a random suffix that changes when the pod is replaced. Service port-forwarding forwards to any currently healthy pod and keeps working across restarts.

Step 9: Update the image and roll back safely

Updating the image (declarative, preferred)

Update the image tag in deployment.yaml then apply:

# Edit deployment.yaml: change image tag from 1.2.0 to 1.3.0
kubectl apply -f deployment.yaml

The Deployment performs a rolling update, starting new pods before stopping old ones so the app stays online throughout.

Updating the image (imperative, good for quick one-offs)

kubectl set image deployment/demo-app \
  demo-app=123456789012.dkr.ecr.eu-west-1.amazonaws.com/demo-app:1.3.0 \
  -n production

Use this for quick experiments. For anything repeatable or tracked, update the YAML and apply it.

Monitor the rollout

kubectl rollout status deployment/demo-app -n production
# deployment "demo-app" successfully rolled out

View rollout history

kubectl rollout history deployment/demo-app -n production
# REVISION  CHANGE-CAUSE
# 1         <none>
# 2         <none>

Roll back to the previous version

kubectl rollout undo deployment/demo-app -n production

Roll back to a specific revision

kubectl rollout undo deployment/demo-app --to-revision=1 -n production

Rollback works because Kubernetes keeps the old ReplicaSet after a rolling update. kubectl rollout undo reactivates it instantly without rebuilding the image.

When to use this approach

Use raw kubectl when:

• Learning Kubernetes and want to see exactly what each object does
• Debugging a live cluster problem
• Testing a single manifest change quickly
• Validating a small workload before productionising it

Do not rely on raw imperative kubectl as your long-term deployment method when:

• You have multiple environments (dev, staging, production). See Dev vs Staging vs Production for environment management patterns.
• Deployments need approvals or audit trails
• You need repeatability across multiple engineers
• A CI/CD system like GitHub Actions should be the source of truth

Raw kubectl apply against a live cluster is fine for learning and small teams. At scale, it becomes hard to track who deployed what and when. That is where GitOps and CI/CD pipelines take over.

kubectl vs Helm on EKS

Both kubectl and Helm deploy to Kubernetes. They serve different purposes and most teams use both.

kubectl is better for:

• Understanding the raw Kubernetes objects (Deployments, Services, ConfigMaps)
• Direct cluster inspection and debugging
• Simple apps where templating adds no value
• One-off changes and quick rollback commands

Helm is better for:

• Packaging an app with configurable values across environments
• Installing third-party tools (Prometheus, cert-manager, the AWS Load Balancer Controller)
• Distributing apps as versioned, shareable charts
• Teams that want a single helm rollback to undo all related resources together

The practical split most teams land on: use kubectl to understand what Kubernetes objects exist and debug live problems; use Helm to install and upgrade applications where you need templated values or chart versioning. You will still use kubectl get, kubectl describe, and kubectl logs even in a fully Helm-managed cluster.