DEV Community

Cover image for What Does Kubernetes Do? Complete Guide for Developers
Preecha
Preecha

Posted on

What Does Kubernetes Do? Complete Guide for Developers

Kubernetes automates how containerized applications are deployed, scaled, updated, and recovered. Instead of manually starting containers on servers, you describe the desired state of your app, and Kubernetes keeps the cluster aligned with that state.

Try Apidog today

[Deploying Apidog on Kubernetes using Deployment Manifest - Self-hosting ApidogDeploying Apidog on Kubernetes using Deployment Manifest - Self-hosting Apidog

Image

Self-hosting Apidog

Image](https://self-hosting.apidog.com/deploying-apidog-on-kubernetes-using-deployment-manifest-565353m0?ref=apidog.com)

What Kubernetes Does

Kubernetes is an open-source container orchestration platform. It runs containers across a cluster of machines and automates operational tasks such as:

  • Scheduling containers onto available nodes
  • Restarting failed containers
  • Replacing unhealthy workloads
  • Scaling replicas up or down
  • Exposing applications through stable networking
  • Rolling out new versions without downtime
  • Rolling back failed deployments
  • Managing configuration and secrets

In practice, Kubernetes lets you define infrastructure behavior in YAML files and apply those files consistently across environments.

The Problem Kubernetes Solves

Without Kubernetes, teams often need to manually handle:

  • Which server should run each container
  • How many instances of an app should be running
  • What happens when a container crashes
  • How traffic is routed between instances
  • How deployments happen without downtime
  • How apps scale during traffic spikes
  • How configuration differs between environments

Kubernetes turns these tasks into declarative configuration.

You tell Kubernetes what you want:

replicas: 3
image: my-api:1.0.0
Enter fullscreen mode Exit fullscreen mode

Kubernetes continuously works to make that state true.

Core Kubernetes Concepts

Before writing manifests, understand these core building blocks.

Component What it does
Cluster A group of machines managed by Kubernetes
Node A machine that runs workloads
Pod The smallest deployable unit in Kubernetes
Deployment Manages replicated pods and updates
Service Provides stable networking for pods
Ingress Routes external HTTP/HTTPS traffic
ConfigMap Stores non-sensitive configuration
Secret Stores sensitive values such as tokens or passwords

Example: Deploy an API with Kubernetes

Assume you have a containerized API image:

my-registry/example-api:1.0.0
Enter fullscreen mode Exit fullscreen mode

A basic Kubernetes Deployment looks like this:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: example-api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: example-api
  template:
    metadata:
      labels:
        app: example-api
    spec:
      containers:
        - name: example-api
          image: my-registry/example-api:1.0.0
          ports:
            - containerPort: 8080
Enter fullscreen mode Exit fullscreen mode

Apply it:

kubectl apply -f deployment.yaml
Enter fullscreen mode Exit fullscreen mode

Check the rollout:

kubectl rollout status deployment/example-api
Enter fullscreen mode Exit fullscreen mode

List the running pods:

kubectl get pods
Enter fullscreen mode Exit fullscreen mode

Kubernetes now ensures that three replicas of your API are running.

Expose the API with a Service

Pods are temporary. They can be restarted, replaced, or moved to another node. A Service gives them a stable network endpoint.

apiVersion: v1
kind: Service
metadata:
  name: example-api-service
spec:
  selector:
    app: example-api
  ports:
    - protocol: TCP
      port: 80
      targetPort: 8080
  type: ClusterIP
Enter fullscreen mode Exit fullscreen mode

Apply it:

kubectl apply -f service.yaml
Enter fullscreen mode Exit fullscreen mode

Now other workloads inside the cluster can reach the API through:

example-api-service
Enter fullscreen mode Exit fullscreen mode

Add Health Checks

Kubernetes can restart unhealthy containers automatically, but you need to define how health is checked.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: example-api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: example-api
  template:
    metadata:
      labels:
        app: example-api
    spec:
      containers:
        - name: example-api
          image: my-registry/example-api:1.0.0
          ports:
            - containerPort: 8080
          readinessProbe:
            httpGet:
              path: /health
              port: 8080
            initialDelaySeconds: 5
            periodSeconds: 10
          livenessProbe:
            httpGet:
              path: /health
              port: 8080
            initialDelaySeconds: 15
            periodSeconds: 20
Enter fullscreen mode Exit fullscreen mode

Use:

  • readinessProbe to decide whether a pod should receive traffic
  • livenessProbe to decide whether a container should be restarted

This is one of the main ways Kubernetes provides self-healing behavior.

Scale an Application

You can manually scale replicas with:

kubectl scale deployment example-api --replicas=5
Enter fullscreen mode Exit fullscreen mode

Verify:

kubectl get deployment example-api
Enter fullscreen mode Exit fullscreen mode

Kubernetes will create or remove pods until the Deployment matches the requested replica count.

Use Declarative Scaling

Instead of scaling manually, update the Deployment manifest:

spec:
  replicas: 5
Enter fullscreen mode Exit fullscreen mode

Then apply it:

kubectl apply -f deployment.yaml
Enter fullscreen mode Exit fullscreen mode

This keeps your desired state in version control.

Configure Rolling Updates

Kubernetes Deployments support rolling updates by default. When you change the container image, Kubernetes gradually replaces old pods with new ones.

Update the image:

kubectl set image deployment/example-api example-api=my-registry/example-api:1.1.0
Enter fullscreen mode Exit fullscreen mode

Watch the rollout:

kubectl rollout status deployment/example-api
Enter fullscreen mode Exit fullscreen mode

If the new version has a problem, roll back:

kubectl rollout undo deployment/example-api
Enter fullscreen mode Exit fullscreen mode

This is useful for API teams shipping frequent changes.

Manage Environment Configuration

Use a ConfigMap for non-sensitive values:

apiVersion: v1
kind: ConfigMap
metadata:
  name: example-api-config
data:
  APP_ENV: production
  LOG_LEVEL: info
Enter fullscreen mode Exit fullscreen mode

Reference it from a Deployment:

envFrom:
  - configMapRef:
      name: example-api-config
Enter fullscreen mode Exit fullscreen mode

Use a Secret for sensitive values:

apiVersion: v1
kind: Secret
metadata:
  name: example-api-secret
type: Opaque
stringData:
  API_KEY: your-api-key
Enter fullscreen mode Exit fullscreen mode

Reference it:

envFrom:
  - secretRef:
      name: example-api-secret
Enter fullscreen mode Exit fullscreen mode

In a real project, avoid committing raw secret values to source control.

What Kubernetes Does for API Development

For API-driven applications, Kubernetes helps with:

  • Keeping API containers running
  • Restarting failed instances
  • Scaling API replicas during traffic spikes
  • Routing traffic to healthy pods
  • Deploying new API versions with rolling updates
  • Rolling back broken releases
  • Separating configuration from application code

If you use Apidog for API design, testing, and documentation, Kubernetes fits into the deployment side of the workflow. Apidog helps define and validate APIs, while Kubernetes runs the containerized API services reliably.

A typical API workflow can look like this:

  1. Design or document the API.
  2. Test API behavior.
  3. Build the API application.
  4. Package it as a container image.
  5. Push the image to a registry.
  6. Deploy it with Kubernetes manifests.
  7. Use Kubernetes health checks, scaling, and rollout controls.

Real-World Kubernetes Examples

Example 1: Scaling an E-commerce API

An e-commerce API usually has variable traffic. During a sale, traffic can increase quickly.

With Kubernetes, you can increase replicas:

kubectl scale deployment checkout-api --replicas=10
Enter fullscreen mode Exit fullscreen mode

After traffic returns to normal:

kubectl scale deployment checkout-api --replicas=3
Enter fullscreen mode Exit fullscreen mode

Kubernetes handles creating and removing pods to match the desired replica count.

Example 2: Rolling Out a New API Version

A team releases a new API container image:

kubectl set image deployment/orders-api orders-api=my-registry/orders-api:2.0.0
Enter fullscreen mode Exit fullscreen mode

Kubernetes performs a rolling update. If the rollout fails:

kubectl rollout undo deployment/orders-api
Enter fullscreen mode Exit fullscreen mode

This reduces downtime risk during API releases.

Example 3: Running Across Different Environments

Kubernetes can run on cloud infrastructure, on-premises servers, or hybrid environments. The same core Kubernetes manifests can be adapted for each environment with different configuration values, storage classes, ingress rules, or secrets.

Kubernetes in a Developer Workflow

A practical Kubernetes-based development workflow usually looks like this:

  1. Build and test the application locally.
  2. Create a container image.
  3. Push the image to a container registry.
  4. Write or update Kubernetes manifests.
  5. Apply manifests to a cluster.
  6. Monitor pods, logs, and rollout status.
  7. Scale or roll back when needed.

Example commands:

docker build -t my-registry/example-api:1.0.0 .
docker push my-registry/example-api:1.0.0

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

kubectl get pods
kubectl logs deployment/example-api
kubectl rollout status deployment/example-api
Enter fullscreen mode Exit fullscreen mode

What Kubernetes Does Not Do

Kubernetes is powerful, but it does not replace every part of your stack.

Kubernetes does not:

  • Build your application code
  • Create container images by itself
  • Replace Dockerfiles or build pipelines
  • Automatically design your API
  • Replace API testing tools
  • Remove the need for observability
  • Eliminate the need to understand networking, storage, and security

Kubernetes orchestrates containers. You still need a complete development, CI/CD, testing, and monitoring workflow around it.

Using Kubernetes with Apidog

Apidog supports API design, testing, and documentation workflows. Kubernetes handles the runtime side after your API is containerized.

A practical integration flow is:

  1. Design and document API endpoints in Apidog.
  2. Test the API contract and behavior.
  3. Implement the API service.
  4. Containerize the service.
  5. Deploy it to Kubernetes.
  6. Use Kubernetes probes, Services, and Deployments to operate it reliably.

For example, after validating an API, you can deploy its container image using a Kubernetes Deployment and expose it through a Service. Kubernetes then manages replicas, health checks, and updates.

Conclusion

Kubernetes automates the operational work required to run containerized applications: deployment, scaling, health checks, networking, updates, and rollbacks.

For developers building APIs, Kubernetes is most useful when paired with a clear API workflow. Use tools like Apidog for API design, testing, and documentation, then deploy the finished API as containers managed by Kubernetes.

Frequently Asked Questions

Can I use Kubernetes for small projects?

Yes. Kubernetes is most valuable at scale, but small projects can also benefit if they need reliability, repeatable deployments, or room to grow.

Does Kubernetes only work with Docker?

No. Kubernetes supports multiple container runtimes. Docker is commonly used for building images, but Kubernetes itself can run containers through supported runtimes.

Is Kubernetes hard to learn?

Kubernetes has a learning curve because it includes concepts such as pods, services, deployments, ingress, storage, and cluster networking. Start with Deployments, Services, health checks, and rollbacks before moving into advanced topics.

Top comments (0)