---
obj: concept
website: https://kubernetes.io
---

# Kubernetes

## Overview

Kubernetes is an open-source system for automating deployment, scaling, and management of containerized applications. It groups containers into logical units called **Pods**, which run on **Nodes** in a cluster. A simple solution to get up and running is [k3s](k3s.md).

You can manage k8s clusters via `kubectl`. Most things are defined via yaml manifest files decleratively. You can throw these into your cluster with `kubectl apply -f FILE`.

## Resources

### Namespace

Logical separation of resources within a cluster.

```yaml
apiVersion: v1
kind: Namespace
metadata:
  name: example-namespace
```

### Pod

The smallest deployable unit in Kubernetes.

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: full-example-pod
  namespace: example-namespace
  labels:
    app: web
    tier: frontend
  annotations:
    description: "A full-featured pod example for demonstration purposes"
spec:
  restartPolicy: Always

  # Init container (runs before main containers)
  initContainers:
    - name: init-permissions
      image: busybox
      command: ["sh", "-c", "chmod 777 /mnt/data"]
      volumeMounts:
        - name: data-volume
          mountPath: /mnt/data

  containers:
    - name: main-app
      image: nginx:1.25
      imagePullPolicy: IfNotPresent
      ports:
        - containerPort: 80
          name: http
      env:
        # Environment
        - name: ENVIRONMENT
          value: production
        
        # Env from ConfigMap
        - name: CONFIG_TIMEOUT
          valueFrom:
            configMapKeyRef:
              name: example-config
              key: TIMEOUT
        
        # Env from Secret
        - name: SECRET_PASSWORD
          valueFrom:
            secretKeyRef:
              name: example-secret
              key: password
      volumeMounts:
        - name: data-volume
          mountPath: /usr/share/nginx/html
        - name: config-volume
          mountPath: /etc/config
          readOnly: true
      resources:
        limits:
          cpu: "500m"
          memory: "256Mi"
        requests:
          cpu: "250m"
          memory: "128Mi"
      livenessProbe:
        httpGet:
          path: /
          port: 80
        initialDelaySeconds: 10
        periodSeconds: 10
      readinessProbe:
        httpGet:
          path: /
          port: 80
        initialDelaySeconds: 5
        periodSeconds: 5
      lifecycle:
        preStop:
          exec:
            command: ["sh", "-c", "echo stopping..."]

    - name: sidecar-logger
      image: busybox
      args: ["sh", "-c", "tail -f /var/log/app.log"]
      volumeMounts:
        - name: log-volume
          mountPath: /var/log

  # Volumes
  volumes:
    # ConfigMap - inject config files
    - name: config-volume
      configMap:
        name: example-config
        items:
          - key: config.json
            path: config.json

    # Secret - inject sensitive data
    - name: secret-volume
      secret:
        secretName: example-secret
        items:
          - key: password
            path: password.txt

    # EmptyDir - ephemeral shared storage between containers
    - name: log-volume
      emptyDir:
        medium: ""
        sizeLimit: 500Mi

    # HostPath - access host node's filesystem (example: logs)
    - name: host-logs
      hostPath:
        path: /var/log
        type: Directory
```

### Deployment

Ensures a specified number of identical Pods are running and up-to-date. Supports rolling updates and rollbacks.

```yml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: example-deployment
  namespace: example-namespace
spec:
  replicas: 3
  selector:
    matchLabels:
      app: example
  template:
    metadata:
      labels:
        app: example
    spec:
      containers:
        - name: web
          image: nginx:alpine
          ports:
            - containerPort: 80
```

### StatefulSet

Like a Deployment, but for workloads requiring stable network IDs, persistent storage, and ordered startup/shutdown.

```yml
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: example-statefulset
  namespace: example-namespace
spec:
  serviceName: "example"
  replicas: 2
  selector:
    matchLabels:
      app: stateful-app
  template:
    metadata:
      labels:
        app: stateful-app
    spec:
      containers:
        - name: web
          image: nginx:alpine
          volumeMounts:
            - name: data
              mountPath: /usr/share/nginx/html
```

### DaemonSet

Ensures a copy of a Pod runs on all (or some) Nodes in the cluster. Ideal for log collectors or system-level agents.

```yml
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: example-daemonset
  namespace: example-namespace
spec:
  selector:
    matchLabels:
      name: ds-app
  template:
    metadata:
      labels:
        name: ds-app
    spec:
      containers:
        - name: node-monitor
          image: busybox
          args: ["sh", "-c", "while true; do echo hello; sleep 10; done"]
```

### Job

Runs a Pod (or multiple) to completion. Used for batch processing or one-off tasks.

```yml
apiVersion: batch/v1
kind: Job
metadata:
  name: example-job
  namespace: example-namespace
spec:
  template:
    spec:
      containers:
        - name: pi
          image: perl
          command: ["perl", "-Mbignum=bpi", "-wle", "print bpi(2000)"]
      restartPolicy: Never
  backoffLimit: 4
```

### CronJob

Schedules Jobs to run periodically, similar to [UNIX cron](../linux/cron.md).

```yml
apiVersion: batch/v1
kind: CronJob
metadata:
  name: example-cronjob
  namespace: example-namespace
spec:
  schedule: "*/5 * * * *"
  jobTemplate:
    spec:
      template:
        spec:
          containers:
            - name: hello
              image: busybox
              args: ["echo", "Hello from the CronJob"]
          restartPolicy: OnFailure
```

> Note: You can quickly run CronJobs as a job with: `kubectl create job --from=cronjob.batch/my_cron_job new_job`

### Service

Defines a stable network endpoint to access a set of Pods. Supports different types like `ClusterIP`, `NodePort`, and `LoadBalancer`.

```yml
apiVersion: v1
kind: Service
metadata:
  name: example-service
  namespace: example-namespace
spec:
  selector:
    app: example
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80
  type: ClusterIP
```

### ConfigMap

Injects configuration data (as key-value pairs) into Pods, keeping config decoupled from code.

```yml
apiVersion: v1
kind: ConfigMap
metadata:
  name: example-config
  namespace: example-namespace
data:
  APP_ENV: production
  TIMEOUT: "30"
```

Usage in a Pod:

```yml
envFrom:
  - configMapRef:
      name: example-config
```

### Secret

Similar to ConfigMap, but for sensitive data like passwords, tokens, or keys.
If you want encryption on rest for your manifests, look at [sops](../tools/sops.md).

```yml
apiVersion: v1
kind: Secret
metadata:
  name: example-secret
  namespace: example-namespace
type: Opaque
data:
  username: YWRtaW4=   # base64 of 'admin'
  password: cGFzc3dvcmQ=   # base64 of 'password'
```

Usage in a Pod:

```yml
env:
  - name: USERNAME
    valueFrom:
      secretKeyRef:
        name: example-secret
        key: username
```