docs_tfgrid_get_started/docs/mycelium-cloud/kubernetes-basics.md

---
sidebar_position: 4
---

# Kubernetes Basics

Essential Kubernetes concepts for deploying applications on Mycelium Cloud.

## What is Kubernetes?

Kubernetes (K8s) is a container orchestration platform that automates deploying, scaling, and managing containerized applications. Mycelium Cloud uses **K3s**, a lightweight Kubernetes distribution perfect for edge and cloud environments.

### Why Kubernetes?

- **Automated Deployment** - Deploy containers across multiple nodes
- **Self-Healing** - Automatically restart failed containers
- **Horizontal Scaling** - Scale applications up or down based on demand
- **Service Discovery** - Automatic DNS and load balancing
- **Rolling Updates** - Update applications with zero downtime

## Core Concepts

### Pods

A **Pod** is the smallest deployable unit in Kubernetes. It represents one or more containers that share:
- Network namespace (same IP address)
- Storage volumes
- Configuration

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: nginx-pod
spec:
  containers:
  - name: nginx
    image: nginx:1.21
    ports:
    - containerPort: 80
```

```bash
# View pods
kubectl get pods

# View pod details
kubectl describe pod nginx-pod

# View pod logs
kubectl logs nginx-pod
```

### Deployments

A **Deployment** manages a replicated set of Pods and provides declarative updates.

Features:
- **Replica Management** - Maintain desired number of pods
- **Rolling Updates** - Update pods with zero downtime
- **Rollback** - Revert to previous versions
- **Self-Healing** - Replace failed pods automatically

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.21
        ports:
        - containerPort: 80
```

```bash
# Create deployment
kubectl apply -f deployment.yaml

# View deployments
kubectl get deployments

# Scale deployment
kubectl scale deployment nginx-deployment --replicas=5

# Update image
kubectl set image deployment/nginx-deployment nginx=nginx:1.22
```

### Services

**Services** provide stable network endpoints for accessing pods.

#### ClusterIP (Default)

Internal-only service, accessible within the cluster:

```yaml
apiVersion: v1
kind: Service
metadata:
  name: my-service
spec:
  type: ClusterIP
  selector:
    app: nginx
  ports:
  - port: 80
    targetPort: 80
```

#### NodePort

Exposes service on each node's IP at a static port:

```yaml
apiVersion: v1
kind: Service
metadata:
  name: my-service
spec:
  type: NodePort
  selector:
    app: nginx
  ports:
  - port: 80
    targetPort: 80
    nodePort: 30080  # 30000-32767
```

```bash
# View services
kubectl get services

# Describe service
kubectl describe service my-service
```

### Namespaces

**Namespaces** provide logical isolation for resources within a cluster.

```bash
# List namespaces
kubectl get namespaces

# Create namespace
kubectl create namespace my-app

# Use namespace
kubectl get pods -n my-app
```

## Storage

### Persistent Volumes

**PersistentVolumeClaim (PVC)** - Request for storage:

```yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: pvc-data
spec:
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
```

Use in pod:

```yaml
spec:
  containers:
  - name: app
    image: myapp:latest
    volumeMounts:
    - name: data
      mountPath: /data
  volumes:
  - name: data
    persistentVolumeClaim:
      claimName: pvc-data
```

## Configuration

### ConfigMaps

Store non-sensitive configuration data:

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  database_url: "postgres://db:5432/mydb"
  log_level: "info"
```

```bash
# Create from literal
kubectl create configmap app-config --from-literal=key=value

# View configmaps
kubectl get configmaps
```

### Secrets

Store sensitive data (passwords, tokens, keys):

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: app-secret
type: Opaque
data:
  password: cGFzc3dvcmQxMjM=  # base64 encoded
```

```bash
# Create secret
kubectl create secret generic app-secret --from-literal=password=password123

# View secrets
kubectl get secrets
```

## Essential kubectl Commands

```bash
# Cluster info
kubectl cluster-info
kubectl get nodes

# Pods
kubectl get pods
kubectl get pods -o wide
kubectl describe pod <pod-name>
kubectl logs <pod-name>
kubectl logs -f <pod-name>  # Follow logs
kubectl exec -it <pod-name> -- /bin/bash

# Deployments
kubectl get deployments
kubectl scale deployment <name> --replicas=5
kubectl rollout status deployment/<name>
kubectl rollout undo deployment/<name>

# Services
kubectl get services
kubectl describe service <service-name>

# Apply/Delete resources
kubectl apply -f file.yaml
kubectl delete -f file.yaml

# Port forwarding
kubectl port-forward pod/<pod-name> 8080:80
kubectl port-forward service/<service-name> 8080:80

# View all resources
kubectl get all --all-namespaces

# Check events
kubectl get events --sort-by=.metadata.creationTimestamp
```

## Labels and Selectors

**Labels** are key-value pairs attached to objects:

```yaml
metadata:
  labels:
    app: nginx
    environment: production
    tier: frontend
```

**Selectors** query objects by labels:

```bash
# Get pods with label
kubectl get pods -l app=nginx

# Get pods with multiple labels
kubectl get pods -l app=nginx,environment=production
```

## Best Practices

1. **Use Deployments** - Not bare pods, for self-healing and scaling
2. **Set Resource Limits** - Prevent resource exhaustion
   ```yaml
   resources:
     requests:
       memory: "64Mi"
       cpu: "250m"
     limits:
       memory: "128Mi"
       cpu: "500m"
   ```
3. **Use Health Checks** - Implement liveness and readiness probes
4. **Use Namespaces** - Organize resources logically
5. **Version Control** - Store manifests in Git
6. **Use Labels** - Tag resources for organization
7. **Secrets Management** - Never hardcode sensitive data

## Next Steps

- **[Tutorial](/getstarted/mycelium-cloud/tutorial)** - Deploy real applications
- **[FAQ](/getstarted/mycelium-cloud/faq)** - Common questions and answers

## Additional Resources

- **Kubernetes Documentation**: [kubernetes.io/docs](https://kubernetes.io/docs/)
- **kubectl Cheat Sheet**: [kubernetes.io/docs/reference/kubectl/cheatsheet](https://kubernetes.io/docs/reference/kubectl/cheatsheet/)
- **K3s Documentation**: [docs.k3s.io](https://docs.k3s.io/)

---

:::tip Want to Learn More?

This covers the basics to get you started. For advanced topics like StatefulSets, DaemonSets, Ingress, and RBAC, check out the comprehensive Kubernetes documentation linked above.
:::