Skip to main content

Operator reference

Everyday language

For day-to-day product terms (environment, instance, copies, connection file, public URL), see Terms we use. This page is an advanced operator reference and may use Kubernetes object names when describing low-level setup. Day-one readers should stay on the Quickstart.

Building on the Quickstart cluster setup, this guide covers deeper sizing, troubleshooting, and advanced scenarios.

Prerequisites deep dive​

System requirements analysis​

Before setting up any cluster, understand your workload requirements:

Control plane specifications​

Development environment:

  • CPU: 2 vCPUs minimum, 4 vCPUs recommended
  • RAM: 4GB minimum, 8GB recommended
  • Storage: 40GB SSD minimum, 60GB recommended
  • Network: 1Gbps minimum

Production environment:

  • CPU: 4 vCPUs minimum, 8 vCPUs recommended
  • RAM: 8GB minimum, 16GB recommended
  • Storage: 50GB SSD minimum, 100GB recommended
  • Network: 10Gbps recommended

Worker node specifications​

Development environment:

  • CPU: 2 vCPUs minimum, 4 vCPUs recommended
  • RAM: 4GB minimum, 8GB recommended
  • Storage: 40GB SSD minimum, 60GB recommended

Production environment:

  • CPU: 4 vCPUs minimum, 8+ vCPUs recommended
  • RAM: 8GB minimum, 16GB+ recommended
  • Storage: 50GB SSD minimum, 100GB+ recommended
Resource Planning

Always plan for 20-30% overhead beyond your application requirements for system processes and scaling.

Advanced Cluster Configuration​

Network Architecture Deep Dive​

Pod Network Configuration​

# Example Calico network policy
apiVersion: projectcalico.org/v3
kind: NetworkPolicy
metadata:
  name: allow-app-traffic
  namespace: production
spec:
  selector: app == "web-app"
  ingress:
    - action: Allow
      protocol: TCP
      destination:
        ports: [80, 443]
  egress:
    - action: Allow
      protocol: TCP
      destination:
        ports: [53, 3306, 6379]

Service Mesh Integration​

For advanced networking, consider service mesh options:

Istio Configuration:

apiVersion: networking.istio.io/v1alpha3
kind: VirtualService
metadata:
  name: web-app-vs
spec:
  hosts:
    - web-app
  http:
    - match:
        - headers:
            version:
              exact: "v2"
      route:
        - destination:
            host: web-app
            subset: v2
    - route:
        - destination:
            host: web-app
            subset: v1

Storage Configuration​

Persistent Volume Setup​

Local Storage (Development):

apiVersion: v1
kind: PersistentVolume
metadata:
  name: local-pv
spec:
  capacity:
    storage: 10Gi
  accessModes:
    - ReadWriteOnce
  persistentVolumeReclaimPolicy: Retain
  storageClassName: local-storage
  local:
    path: /mnt/data
  nodeAffinity:
    required:
      nodeSelectorTerms:
        - matchExpressions:
            - key: kubernetes.io/hostname
              operator: In
              values:
                - worker-1

Cloud Storage (Production):

apiVersion: v1
kind: PersistentVolume
metadata:
  name: cloud-pv
spec:
  capacity:
    storage: 100Gi
  accessModes:
    - ReadWriteOnce
  persistentVolumeReclaimPolicy: Delete
  storageClassName: cloud-ssd
  awsElasticBlockStore:
    volumeID: vol-1234567890abcdef0
    fsType: ext4

Security Hardening​

RBAC Configuration​

Custom Role for Application Deployment:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: production
  name: app-deployer
rules:
  - apiGroups: ["apps"]
    resources: ["deployments", "replicasets"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
  - apiGroups: [""]
    resources: ["pods", "services", "configmaps", "secrets"]
    verbs: ["get", "list", "watch", "create", "update", "patch"]

Pod Security Standards​

apiVersion: v1
kind: Pod
metadata:
  name: secure-app
spec:
  securityContext:
    runAsNonRoot: true
    runAsUser: 1000
    fsGroup: 2000
  containers:
    - name: app
      image: myapp:latest
      securityContext:
        allowPrivilegeEscalation: false
        readOnlyRootFilesystem: true
        capabilities:
          drop:
            - ALL

Troubleshooting Guide​

Common Cluster Issues​

Node Not Ready​

Symptoms:

  • Node shows "NotReady" status
  • Pods stuck in "Pending" state

Diagnosis:

# Check node status
kubectl describe node <node-name>

# Check kubelet logs
journalctl -u kubelet -f

# Verify container runtime
systemctl status containerd

Solutions:

  1. Disk Space Issues:

    # Clean up unused images
    docker system prune -a

    # Check disk usage
    df -h

  2. Memory Pressure:

    # Check memory usage
    free -h

    # Identify memory-heavy processes
    ps aux --sort=-%mem | head

  3. Network Issues:

    # Test connectivity
    ping <master-ip>

    # Check firewall rules
    iptables -L

Pod Startup Failures​

Common Causes:

  1. Image Pull Errors:

    # Check image availability
    docker pull <image-name>

    # Verify registry credentials
    kubectl get secrets

  2. Resource Constraints:

    # Check resource requests vs limits
    kubectl describe pod <pod-name>

    # Verify node capacity
    kubectl top nodes

  3. Configuration Issues:

    # Validate YAML syntax
    kubectl apply --dry-run=client -f <config-file>

    # Check ConfigMap/Secret references
    kubectl get configmap <config-name> -o yaml

Performance Optimization​

Cluster Resource Optimization​

Node Resource Management:

apiVersion: v1
kind: Node
metadata:
  name: worker-1
spec:
  # Reserve resources for system processes
  systemReserved:
    cpu: "100m"
    memory: "100Mi"
    ephemeral-storage: "1Gi"
  kubeReserved:
    cpu: "100m"
    memory: "100Mi"
    ephemeral-storage: "1Gi"

Pod Resource Limits:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: optimized-app
spec:
  template:
    spec:
      containers:
        - name: app
          image: myapp:latest
          resources:
            requests:
              cpu: "100m"
              memory: "128Mi"
            limits:
              cpu: "500m"
              memory: "512Mi"

Horizontal Pod Autoscaling​

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: app-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: my-app
  minReplicas: 2
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70
    - type: Resource
      resource:
        name: memory
        target:
          type: Utilization
          averageUtilization: 80

Advanced Scenarios​

Multi-Cluster Management​

Cluster Federation Setup​

apiVersion: v1
kind: ConfigMap
metadata:
  name: cluster-config
  namespace: kube-system
data:
  clusters.yaml: |
    clusters:
    - name: production-us
      server: https://prod-us.example.com
    - name: production-eu
      server: https://prod-eu.example.com

Cross-Cluster Service Discovery​

apiVersion: v1
kind: Service
metadata:
  name: cross-cluster-service
  annotations:
    federation.kubernetes.io/service: "true"
spec:
  type: ClusterIP
  ports:
    - port: 80
      targetPort: 8080

Disaster Recovery​

Backup Strategy​

ETCD Backup:

#!/bin/bash
# Automated etcd backup script
ETCDCTL_API=3 etcdctl snapshot save /backup/etcd-$(date +%Y%m%d-%H%M%S).db \
  --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key

Application Data Backup:

apiVersion: batch/v1
kind: CronJob
metadata:
  name: db-backup
spec:
  schedule: "0 2 * * *" # Daily at 2 AM
  jobTemplate:
    spec:
      template:
        spec:
          containers:
            - name: backup
              image: postgres:13
              command:
                - /bin/bash
                - -c
                - |
                  pg_dump $DATABASE_URL > /backup/db-$(date +%Y%m%d).sql
                  aws s3 cp /backup/db-$(date +%Y%m%d).sql s3://my-backup-bucket/
              volumeMounts:
                - name: backup-storage
                  mountPath: /backup
          volumes:
            - name: backup-storage
              persistentVolumeClaim:
                claimName: backup-pvc
          restartPolicy: OnFailure

Monitoring and Observability​

Cluster Monitoring Setup​

Prometheus Configuration​

apiVersion: v1
kind: ConfigMap
metadata:
  name: prometheus-config
data:
  prometheus.yml: |
    global:
      scrape_interval: 15s
    scrape_configs:
    - job_name: 'kubernetes-nodes'
      kubernetes_sd_configs:
      - role: node
    - job_name: 'kubernetes-pods'
      kubernetes_sd_configs:
      - role: pod

Grafana Dashboards​

apiVersion: v1
kind: ConfigMap
metadata:
  name: grafana-dashboard
data:
  dashboard.json: |
    {
      "dashboard": {
        "title": "Kubernetes Cluster Overview",
        "panels": [
          {
            "title": "CPU Usage",
            "type": "graph",
            "targets": [
              {
                "expr": "100 - (avg(rate(node_cpu_seconds_total{mode=\"idle\"}[5m])) * 100)"
              }
            ]
          }
        ]
      }
    }

Next Steps​

With your cluster properly configured and optimized: