Kubernetes Manifest

This guide covers deploying Qtap in cloud-connected mode using a Kubernetes manifest, managed through the Qplane control plane. Use this approach when you need full control over your Kubernetes resources or can't use Helm directly.

Preflight Check

If you'd like to verify your environment's compatibility, use the following script:

curl -sSL https://github.com/qpoint-io/preflight/releases/latest/download/preflight.sh | sudo bash

Prerequisites

• Kubernetes cluster on Linux hosts with supported kernel (5.10+)

• kubectl configured for your cluster

• helm (for generating the base manifest)

• A valid registration token from app.qpoint.io (Settings → Installation)

Generating the Base Manifest

Use the Helm chart to generate a static Kubernetes manifest:

helm repo add qpoint https://helm.qpoint.io/
helm repo update

Generate the manifest with your registration token stored in a Kubernetes secret:

helm template qtap qpoint/qtap \
  --set registrationTokenSecretRefName="qtap-token" \
  --set logLevel=warn \
  > qtap-manifest.yaml

To see all available chart values:

helm show values qpoint/qtap

Creating the Registration Token Secret

Store your registration token as a Kubernetes secret:

kubectl create namespace qpoint

kubectl create secret generic qtap-token \
  --from-literal=token='<your-registration-token>' \
  -n qpoint

Keep your registration token secure. Do not commit it to version control or include it directly in manifest files.

Deploying

Apply the generated manifest:

kubectl apply -f qtap-manifest.yaml -n qpoint

Verifying the Deployment

1. Check that pods are running:

kubectl get pods -n qpoint

You should see qtap-xxxx pods in the Running state — one per node (DaemonSet).

1. Check the logs:

kubectl logs -n qpoint daemonset/qtap --tail 30

Look for a successful registration message indicating the agent has connected to Qplane.

1. Confirm the agent appears in the Qplane dashboard under your environment.

Example Manifest

Here's a complete manifest for cloud-connected deployment with a registration token secret. You can use this directly instead of generating from Helm:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: qtap
  namespace: qpoint
  labels:
    app.kubernetes.io/name: qtap
    app.kubernetes.io/instance: qtap
automountServiceAccountToken: true
---
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: qtap
  namespace: qpoint
  labels:
    app.kubernetes.io/name: qtap
    app.kubernetes.io/instance: qtap
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: qtap
      app.kubernetes.io/instance: qtap
  template:
    metadata:
      labels:
        app.kubernetes.io/name: qtap
        app.kubernetes.io/instance: qtap
    spec:
      hostPID: true
      hostNetwork: true
      serviceAccountName: qtap
      containers:
        - name: qtap
          image: "us-docker.pkg.dev/qpoint-edge/public/qtap:v0"
          imagePullPolicy: IfNotPresent
          securityContext:
            privileged: true
            allowPrivilegeEscalation: true
            runAsUser: 0
            runAsGroup: 0
            runAsNonRoot: false
            readOnlyRootFilesystem: false
            capabilities:
              add:
                - CAP_BPF
                - CAP_SYS_ADMIN
          env:
            - name: REGISTRATION_TOKEN
              valueFrom:
                secretKeyRef:
                  name: qtap-token
                  key: token
            - name: STATUS_LISTEN
              value: "0.0.0.0:10001"
            - name: LOG_LEVEL
              value: "warn"
            - name: LOG_ENCODING
              value: "json"
            - name: TINI_SUBREAPER
              value: "1"
          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:
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              cpu: 1000m
              memory: 1Gi
          volumeMounts:
            - name: sys
              mountPath: /sys
              readOnly: true
            - name: containerd-socket
              mountPath: /run/containerd/containerd.sock
      volumes:
        - name: sys
          hostPath:
            path: /sys
            type: Directory
        - name: containerd-socket
          hostPath:
            path: /run/containerd/containerd.sock
            type: Socket

No ConfigMap is needed for cloud-connected mode. Qplane pushes configuration (stacks, plugins, filters) to the agent after registration. Any changes you make in the Qplane UI are applied automatically.

Adding Tags

Tags help you filter and organize agents in the Qplane dashboard. Add them as extra arguments in the container spec:

          args:
            - "--tags=Environment:Production,Cluster:EKS-1"

See Organizations & Environments for when to use tags vs separate installations.

Adding S3 Credentials

If your Qplane environment uses an S3 object store for payload storage, inject the credentials alongside the registration token:

kubectl create secret generic qpoint-s3-creds \
  --from-literal=AWS_ACCESS_KEY_ID='<access-key>' \
  --from-literal=AWS_SECRET_ACCESS_KEY='<secret-key>' \
  -n qpoint

Add envFrom to the container spec:

          envFrom:
            - secretRef:
                name: qpoint-s3-creds

Uninstalling

kubectl delete -f qtap-manifest.yaml -n qpoint
kubectl delete secret qtap-token -n qpoint

Understanding the Manifest

The manifest creates the following resources:

Resource	Purpose
ServiceAccount	Identity for Qtap pods
DaemonSet	Runs Qtap on every node in the cluster

Key DaemonSet settings:

• hostPID: true and hostNetwork: true — Required for eBPF to observe host processes and network traffic

• Privileged security context — Required for loading BPF programs (CAP_BPF, CAP_SYS_ADMIN)

• /sys mount — Access to kernel interfaces for eBPF

• containerd socket — Enables container attribution (maps traffic to container names and labels). Optional; remove if not using containerd.

• Probes — Startup, readiness, and liveness checks on the /readyz and /healthz endpoints

Common Customizations

• Node selectors or tolerations — Target specific nodes or schedule on tainted nodes

• Resource limits — Adjust CPU and memory based on your traffic volume

• Container runtime socket — Change from containerd to CRI-O (/var/run/crio/crio.sock) if applicable

• Image tag — Pin to a specific version (e.g., qtap:v0.17.1) instead of the rolling v0 tag

Troubleshooting

1. Pods not starting:

kubectl describe pod -n qpoint -l app.kubernetes.io/name=qtap

Check for security policy violations or missing secrets.

1. Agent not appearing in Qplane:

kubectl logs -n qpoint daemonset/qtap --tail 50

Verify the registration token is correct and the cluster can reach api.qpoint.io:443.

1. Kernel compatibility:

kubectl debug node/<node-name> -it --image=ubuntu -- uname -r

Kernel must be 5.10 or later.