Kubeshark

Overview

This document provides a complete, beginner-friendly guide to integrating Kubeshark with Callgoose SQIBS using direct webhook notifications.

Kubeshark acts as a deep network observability tool for Kubernetes clusters. When Kubeshark detects issues, anomalies, or conditions (defined using hooks or custom scripts), it can send webhook payloads directly to Callgoose SQIBS. Callgoose will automatically create, update, and resolve incidents based on these payloads.

This integration enables:

• Real-time incident creation in Callgoose SQIBS
• Automatic resolution when Kubeshark detects recovery
• End-to-end observability from raw Kubernetes traffic → SQIBS incidents
• Support for advanced detection logic using Kubeshark’s scripting engine

Prerequisites

Before proceeding, ensure you have the following:

• A running Kubernetes cluster
• Kubeshark installed locally or in-cluster
• A Callgoose SQIBS Webhook URL with API Token
• Admin access to the Callgoose SQIBS API Filters section
• Basic understanding of Kubernetes objects (ConfigMaps, Deployments, kubectl)

1. Install Kubeshark

Kubeshark can be installed using Helm (recommended), a single YAML manifest, or Docker. Use Method A for production-grade Kubernetes deployments.

1.1. Install Kubeshark using Helm (Recommended)

Step 1 Add the Helm Repository

helm repo add kubeshark https://kubeshark.github.io/helm-charts
helm repo update

Step 2 Create a Namespace

kubectl create namespace kubeshark

Step 3 Install Kubeshark

helm install kubeshark kubeshark/kubeshark \
  --namespace kubeshark \
  --set service.type=ClusterIP \
  --set ui.service.port=8080 \
  --wait

Step 4 Verify Installation

kubectl get pods -n kubeshark
kubectl get svc -n kubeshark

All pods should show as Running.

Step 5 Access the Dashboard

kubectl port-forward svc/kubeshark -n kubeshark 8080:8080

Open:

http://localhost:8080

1.2. Install with YAML Manifest (Alternative)

If you have a single manifest file:

kubectl apply -f kubeshark.yaml -n kubeshark
kubectl get pods -n kubeshark

1.3. Local (Developer) Mode via Docker

For non-Kubernetes testing:

docker run --rm -it -p 8080:8080 kubeshark/kubeshark:latest

Open:

http://localhost:8080

2. Obtain the Callgoose SQIBS Webhook URL

1. Log in to Callgoose SQIBS
2. Navigate to:
3. Settings → Integrations → Webhooks / API
4. Create a new webhook endpoint
5. Copy the full URL, which looks like:

https://****.callgoose.com/v1/process?from=FromValue&token=xxxx

You will paste this URL into Kubeshark scripts.

Keep this token secret.

3. Add a Kubeshark → Callgoose Alert Script

Kubeshark allows executing scripts when certain traffic conditions or events are detected.

You will deploy a JavaScript file that:

• Sends a trigger notification when a problem is detected
• Sends a resolve notification when the condition clears

3.1. Create the Hook Script (JavaScript)

Save this as:

kubeshark-to-callgoose.js

// Function to send data to Callgoose SQIBS
function sendToCallgoose(status, alertId, title, description, extra) {
  var payload = {
    source: "kubeshark",
    status: status,                 // "firing" or "resolved"alert_id: alertId,
    summary: title,
    description: description,
    startsAt: new Date().toISOString(),
    endsAt: (status === "resolved" ? new Date().toISOString() : null),
    details: extra || {}
  };

  var response = vendor.webhook(
    "POST",
    "https://****.callgoose.com/v1/process?from=FromValue&token=xxxx",
    JSON.stringify(payload),
    { "content-type": "application/json" }
  );

  console.log("Callgoose response:", response);
}

// Example Trigger Condition (replace with your logic)
sendToCallgoose(
  "firing",
  "svc-orders-500-error",
  "Service Orders returning 500",
  "Detected more than 10 HTTP 500 responses in last 60 seconds.",
  { service: "orders", count: 12 }
);

// Example Resolve Condition
sendToCallgoose(
  "resolved",
  "svc-orders-500-error",
  "Resolved: Service Orders 500 spike",
  "Service has returned to healthy state.",
  { service: "orders", count: 0 }
);

Replace:

• Webhook URL with your own api endpoint.

4. Deploy the Hook Script into Kubeshark

4.1. Option A Using ConfigMap (Recommended for Clusters)

Step 1 Create ConfigMap

Save this file as:

kubeshark-hook-configmap.yaml

apiVersion: v1
kind: ConfigMap
metadata:name: kubeshark-hooksnamespace: kubeshark
data:kubeshark-to-callgoose.js: |
    // (paste the full script from above)

Apply:

kubectl apply -f kubeshark-hook-configmap.yaml

Step 2 Mount It into Kubeshark Deployment

Edit the Kubeshark Deployment:

kubectl edit deployment kubeshark -n kubeshark

Under spec.template.spec.containers[0] add:

volumeMounts:
- name: kubeshark-hooksmountPath: /opt/kubeshark/hooks

Under spec.template.spec add:

volumes:
- name: kubeshark-hooksconfigMap:name: kubeshark-hooks

Step 3 Restart the Deployment

kubectl rollout restart deployment kubeshark -n kubeshark

4.2. Option B Using Helm values.yaml (If Using Helm Already)

Add to your values.yaml:

hooks:enabled: truescripts:- name: kubeshark-to-callgoose.jscontent: |
        // paste full script here

Upgrade:

helm upgrade kubeshark kubeshark/kubeshark -n kubeshark -f values.yaml

5. Example Payloads from Kubeshark

5.1. Trigger Payload (Problem Detected)

{
  "source": "kubeshark",
  "status": "firing",
  "alert_id": "svc-orders-500-error",
  "summary": "Service Orders returning 500",
  "description": "Detected more than 10 HTTP 500 responses.",
  "startsAt": "2025-11-17T10:00:00Z",
  "endsAt": null,
  "details": {
    "service": "orders",
    "count": 12
  }
}

5.2. Resolve Payload

{
  "source": "kubeshark",
  "status": "resolved",
  "alert_id": "svc-orders-500-error",
  "summary": "Resolved: Service Orders 500 spike",
  "description": "Service recovered.",
  "startsAt": "2025-11-17T10:00:00Z",
  "endsAt": "2025-11-17T10:12:00Z",
  "details": {
    "service": "orders",
    "count": 0
  }
}

6. Configure API Filters in Callgoose SQIBS

Set up two filters: Trigger and Resolve.

6.1. Trigger Filter (Create Incident)

• Payload JSON Key: status
• Key Value Contains: firing
• Map Incident With: alert_id
• Incident Title From: summary
• Incident Description From: description (or leave empty for full JSON)

6.2. Resolve Filter (Resolve Incident)

• Payload JSON Key: status
• Key Value Contains: resolved
• Incident Mapped With: alert_id

This ensures the same alert ID resolves the correct incident.

7. Testing the Integration

Step 1 Trigger a Test Event

You can manually call the firing function from the Kubeshark script.

Step 2 Check Callgoose Webhook Logs

Verify:

• Payload received
• No authentication errors
• Incident created

Step 3 Trigger Resolve Event

Confirm incident auto-resolves.

8. Troubleshooting

No incident created

• Check webhook logs in Callgoose
• Verify status: "firing" is correctly mapped
• Ensure API token is valid

Incident not resolving

• Ensure the alert_id is identical
• Resolve filter must match status: resolved

Kubeshark not sending webhooks

• Check pod logs
• Verify script loaded under /opt/kubeshark/hooks
• Ensure the webhook call is not blocked by cluster egress policies

9. Conclusion

You now have a fully operational integration between Kubeshark and Callgoose SQIBS using direct webhooks. Kubeshark detects real-time Kubernetes traffic anomalies, sends structured payloads, and Callgoose handles automated incident creation and resolution.

For further customization or advanced use cases, refer to the official documentation for both Kubeshark and Callgoose SQIBS:

• Kubeshark Documentation
• Callgoose SQIBS API Token Documentation
• Callgoose SQIBS API Endpoint Documentation
• API Filter Instructions and FAQ
• How to Send API