Deploying a Debug Pod to a Specific Node

Overview

While our application normally runs as a DaemonSet across all nodes, there are times when you need to debug issues on a specific node. This guide explains how to deploy a debug pod to a single node with enhanced logging.

Prerequisites

• kubectl access to your cluster

• Your QPoint registration token

• The name of the target node you want to debug

Steps

1. Identify Your Target Node

First, list all pods across namespaces to find the node you want to target:

kubectl get pods --all-namespaces -o wide

Or find pods running on a specific node:

kubectl get pods --all-namespaces --field-selector spec.nodeName=<node name>

2. Create Debug Pod Configuration

Create a file named debug-pod.yaml with the following configuration:

apiVersion: v1
kind: Pod
metadata:
  name: debug-tap
spec:
  nodeName: <Your Node Here>  # Replace with your target node name
  hostPID: true
  hostNetwork: true
  securityContext: null
  containers:
    - name: qpoint-tap
      securityContext:
        allowPrivilegeEscalation: true
        capabilities:
          add:
          - CAP_BPF
          - CAP_SYS_ADMIN
        privileged: true
        readOnlyRootFilesystem: false
        runAsGroup: 0
        runAsNonRoot: false
        runAsUser: 0
      image: "us-docker.pkg.dev/qpoint-edge/public/qpoint:v0"
      imagePullPolicy: IfNotPresent
      args:
        - tap
      env:
        - name: REGISTRATION_ENDPOINT
          value: "https://api.qpoint.io"
        - name: STATUS_LISTEN
          value: "0.0.0.0:10001"
        - name: LOG_LEVEL
          value: "debug"  # Set to debug for enhanced logging
        - name: LOG_ENCODING
          value: "json"
        - name: TINI_SUBREAPER
          value: "1"
        - name: REGISTRATION_TOKEN
          value: "<Your Token Here>"  # Replace with your registration token
      ports:
        - name: status
          containerPort: 10001
          protocol: TCP
      startupProbe:
        httpGet:
          path: /readyz
          port: status
        initialDelaySeconds: 3
        periodSeconds: 5
        timeoutSeconds: 2
        successThreshold: 1
        failureThreshold: 20
      readinessProbe:
        httpGet:
          path: /readyz
          port: status
        initialDelaySeconds: 3
        periodSeconds: 5
        timeoutSeconds: 2
        successThreshold: 1
        failureThreshold: 1
      livenessProbe:
        httpGet:
          path: /healthz
          port: status
        initialDelaySeconds: 3
        periodSeconds: 10
        timeoutSeconds: 2
        successThreshold: 1
        failureThreshold: 3
      resources:
        limits:
          cpu: 1000m
          memory: 1Gi
        requests:
          cpu: 100m
          memory: 128Mi
      volumeMounts:
        - mountPath: /sys
          name: sys
          readOnly: true
  volumes:
    - hostPath:
        path: /sys
        type: Directory
      name: sys

3. Deploy the Debug Pod

Before deploying the debug pod:

1. Replace <Your Node Here> with your target node name

2. Replace <Your Token Here> with your QPoint registration token

3. Deploy the pod:

kubectl apply -f debug-pod.yaml -n qpoint

4. Verify Pod Deployment

Check that your debug pod is running on the correct node:

kubectl get pods -n <your-namespace> -o wide

5. View Debug Logs

To view the debug logs from your pod:

kubectl logs -f debug-tap -n qpoint

Key Differences from DaemonSet

• Single pod deployment instead of cluster-wide DaemonSet

• Debug log level enabled

• Targeted to specific node using nodeName

• Maintains all necessary permissions and capabilities

• Same resource limits and probes as DaemonSet pods

Cleanup

When you're done debugging, remove the pod:

kubectl delete pod debug-tap -n qpoint