Kubernetes Configuration Reference

Overview

Kubernetes configuration spans multiple layers: kubectl client config (~/.kube/config), kubelet config on each node, static pod manifests, and cluster-level audit and logging policies. This reference covers each layer with practical examples.

kubectl configuration

kubeconfig file (`~/.kube/config`)

The kubeconfig file is the client configuration that kubectl (and other clients like Helm) reads to connect to a cluster. It defines the API server endpoint, the credentials to present, and the default namespace — organized into named clusters, users, and contexts so you can switch between environments without rewriting the file.

apiVersion: v1
kind: Config
current-context: prod-cluster
clusters:
  - name: prod-cluster
    cluster:
      server: https://k8s-api.prod.example.com:6443
      certificate-authority-data: LS0tLS... # Base64 CA cert
users:
  - name: prod-admin
    user:
      client-certificate-data: LS0tLS... # Base64 client cert
      client-key-data: LS0tLS...          # Base64 client key
contexts:
  - name: prod-cluster
    context:
      cluster: prod-cluster
      user: prod-admin
      namespace: production

kubectl config commands

Use the kubectl config subcommands to inspect and modify the kubeconfig — for example, switching between clusters, changing the default namespace for the current context, or merging several kubeconfig files into one. These are the commands you'll reach for when a context is wrong or missing.

# View current config
kubectl config view
kubectl config view --minify     # current context only
kubectl config view --raw        # full config with sensitive data

# Context management
kubectl config get-contexts
kubectl config current-context
kubectl config use-context staging-cluster
kubectl config rename-context old-name new-name
kubectl config delete-context staging-cluster

# Set namespace for current context
kubectl config set-context --current --namespace=team-a

# Manage clusters, users, credentials
kubectl config set-cluster dev --server=https://dev.example.com:6443
kubectl config set-credentials dev-user --token=eyJhbG...
kubectl config set-context dev --cluster=dev --user=dev-user

# Merge kubeconfig files
KUBECONFIG=~/.kube/config:~/other-config kubectl config view --flatten > ~/.kube/merged

Useful aliases and helpers

Add these shell aliases and functions to your .bashrc to cut down on typing the most common kubectl commands. They are purely a local convenience — a short alias for get/describe and a function for switching namespaces on the fly.

# kubectl alias (add to .bashrc)
alias k="kubectl"
alias kg="kubectl get"
alias kd="kubectl describe"

# Quick namespace switching (add to .bashrc)
kns() { kubectl config set-context --current --namespace="$1"; }

# Stream updates for a resource (great for watching a rollout)
kubectl get pods -w

Kubelet configuration

Configuration file

The kubelet reads its primary settings from a YAML configuration file, conventionally at /var/lib/kubelet/config.yaml. Keeping settings in a file rather than on the command line makes the node's behavior declarative, versionable, and easy to audit.

# /var/lib/kubelet/config.yaml

apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration

# Node identity
hostnameOverride: "worker-1"
registerNode: true

# Resource reservation
systemReserved:
  cpu: "500m"
  memory: "512Mi"
kubeReserved:
  cpu: "500m"
  memory: "512Mi"

# Pod settings
maxPods: 110
podCIDR: "10.244.1.0/24"

# Logging
logging:
  format: json
  flushFrequency: 5s

# Container runtime
containerRuntimeEndpoint: "unix:///run/containerd/containerd.sock"

# Image pulling
imageMinimumGCAge: "2m0s"
imageGCHighThresholdPercent: 85
imageGCLowThresholdPercent: 80

Kubelet startup flags

A few settings must still be passed as flags when the kubelet service starts — most importantly the path to the config file and the kubeconfig it uses to register the node. On systemd systems these live in /etc/systemd/system/kubelet.service.d/ or /etc/default/kubelet.

# /etc/systemd/system/kubelet.service or /etc/default/kubelet
KUBELET_EXTRA_ARGS="--config=/var/lib/kubelet/config.yaml \
  --kubeconfig=/etc/kubernetes/kubelet.conf \
  --container-runtime-endpoint=unix:///run/containerd/containerd.sock \
  --node-ip=10.0.1.50"

Common kubelet operations

The kubelet is the agent that runs pods on a node, so when a node misbehaves its service status and logs are the first place to look. Use these commands to check whether it's running and to tail recent errors.

systemctl status kubelet
journalctl -u kubelet -f
journalctl -u kubelet --since "10 minutes ago"

# Check kubelet/kube-proxy versions from the API server's view
kubectl get nodes -o wide

Static pods

Static pods are managed directly by the kubelet, not the API server. They're defined as YAML manifests in a watched directory.

Configuration

Static pod manifests must live in a directory the kubelet is configured to watch. Any YAML file placed there becomes a pod managed directly by the kubelet on that node — independent of the API server.

# Default static pod path (configurable in kubelet)
/etc/kubernetes/manifests/

# Any .yaml file placed here is automatically managed by kubelet

Static pod example

A static pod manifest is an ordinary Pod YAML placed in the watch directory. This example runs nginx from a hostPath volume on the node — the kubelet sees the file and starts the pod without the API server being involved.

# /etc/kubernetes/manifests/nginx-static.yaml

apiVersion: v1
kind: Pod
metadata:
  name: nginx-static
  namespace: kube-system
  labels:
    app: nginx-static
spec:
  containers:
    - name: nginx
      image: nginx:alpine
      ports:
        - containerPort: 80
      volumeMounts:
        - name: html
          mountPath: /usr/share/nginx/html
  volumes:
    - name: html
      hostPath:
        path: /var/www/static
        type: DirectoryOrCreate

Managing static pods

Because static pods aren't tracked by the API server, you manage them by moving manifest files in and out of the watch directory. The kubelet detects the change and recreates the pod, which is also the way to restart one.

# Restart a static pod (delete the manifest and re-add it)
mv /etc/kubernetes/manifests/nginx-static.yaml /tmp/
sleep 5
mv /tmp/nginx-static.yaml /etc/kubernetes/manifests/

# View static pods via API server (prefixed with node name)
kubectl get pods -n kube-system | grep <node-name>

Cluster logging

Control plane component logs

The API server, controller manager, scheduler, and etcd each emit their own logs. Where you read them depends on how the cluster was deployed — as systemd services or as static pods in kube-system.

# Via journald (if running as systemd services)
journalctl -u kube-apiserver -f
journalctl -u kube-controller-manager -f
journalctl -u kube-scheduler -f
journalctl -u etcd -f

# If running as static pods
kubectl logs -n kube-system kube-apiserver-<node>

Audit logging

Audit logging records every request the API server receives, which is essential for security, compliance, and incident forensics. An audit policy defines how much detail is captured per request — from metadata only for most traffic up to full request/response bodies for sensitive resources like Secrets.

# Kube API server audit policy
apiVersion: audit.k8s.io/v1
kind: Policy
rules:
  # Log all metadata for every request
  - level: Metadata

  # Log request/response bodies for changes to secrets
  - level: RequestResponse
    resources:
      - group: ""
        resources: ["secrets"]

  # Don't log read-only requests
  - level: None
    verbs: ["get", "list", "watch"]
    resources:
      - group: ""
        resources: ["pods", "services", "configmaps"]

Pass to API server: --audit-policy-file=/etc/kubernetes/audit-policy.yaml --audit-log-path=/var/log/kube-audit.log

Node logs

Node logs fall into two categories: application logs captured by the kubelet (readable via kubectl logs) and container log files on the node's filesystem, which are useful when the kubelet or API server is unavailable.

# Container logs (kubectl)
kubectl logs <pod> -n <namespace>
kubectl logs <pod> -c <container> -n <namespace>
kubectl logs --previous <pod> -n <namespace>    # previous crashed container
kubectl logs --tail=100 <pod> -n <namespace>
kubectl logs -f <pod> -n <namespace>            # follow
kubectl logs -l app=nginx --all-containers -n default

# Node-level container logs
ls /var/log/containers/
ls /var/log/pods/

Overview​

kubectl configuration​

kubeconfig file (~/.kube/config)​

kubectl config commands​

Useful aliases and helpers​

Kubelet configuration​

Configuration file​

Kubelet startup flags​

Common kubelet operations​

Static pods​

Configuration​

Static pod example​

Managing static pods​

Cluster logging​

Control plane component logs​

Audit logging​

Node logs​

See also​