Deploy Your First App to Kubernetes Step by Step

This walkthrough takes a container image all the way to a running, scalable app on a local Kubernetes cluster.

1. Create a local cluster

# kind = Kubernetes in Docker
brew install kind kubectl        # or see each project's install docs
kind create cluster --name dev
kubectl get nodes

2. Load your image

docker build -t my-api:1.0 .
kind load docker-image my-api:1.0 --name dev   # make the local image available to the cluster

3. Describe the app

# k8s/app.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-api
spec:
  replicas: 2
  selector:
    matchLabels: { app: my-api }
  template:
    metadata:
      labels: { app: my-api }
    spec:
      containers:
        - name: my-api
          image: my-api:1.0
          ports: [{ containerPort: 3000 }]
          env:
            - name: NODE_ENV
              value: production
---
apiVersion: v1
kind: Service
metadata:
  name: my-api
spec:
  selector: { app: my-api }
  ports: [{ port: 80, targetPort: 3000 }]

4. Apply and check

kubectl apply -f k8s/app.yaml
kubectl get deploy,pods,svc
kubectl logs -l app=my-api --tail=20

5. Reach it

kubectl port-forward svc/my-api 8080:80
curl localhost:8080/healthz

6. Scale and update

kubectl scale deploy/my-api --replicas=4

docker build -t my-api:1.1 . && kind load docker-image my-api:1.1 --name dev
kubectl set image deploy/my-api my-api=my-api:1.1
kubectl rollout status deploy/my-api

Next steps

• Add readiness and liveness probes so traffic only reaches healthy Pods.
• Set resource requests and limits.
• Move configuration into a ConfigMap and credentials into a Secret.
• Keep manifests in Git and apply them from CI (or a GitOps tool like Argo CD or Flux).