DOCSEARCHbyAlgolia
Submit Docs

Caretta Documentation

repository·main·Indexed 24 days ago

https://github.com/groundcover-com/caretta

Caretta is a lightweight eBPF-based tool used to create visual network dependency maps of Kubernetes services, integrated with Grafana. It includes an eBPF agent, Victoria Metrics, and a pre-configured Grafana instance. The tool publishes metrics such as caretta_links_observed to provide visibility into network traffic between Kubernetes entities and external domains.

Tokens
1.3K
Snippets
5
Records
7
Agent score
35%

What's inside Caretta

  2. Access the built-in Grafana instance

    main

    Caretta ships with a pre-configured Grafana instance. To access the dashboard:

    1. Port-forward port 3000 from the Grafana pod in the caretta namespace: kubectl port-forward --namespace caretta <grafana-pod-name> 3000:3000
    2. Access the dashboard via your browser.

    Credentials:

    • Anonymous mode: Enabled by default for the main dashboard.
    • Admin access: To edit dashboards, use user admin and password caretta.
    kubectl port-forward --namespace caretta <grafana-pod-name> 3000:3000

  4. Install Caretta via Helm

    main

    Caretta is installed as a Helm chart. It is recommended to install it in a new, unique namespace. The installation includes an eBPF agent, Victoria Metrics, and Grafana by default.

    helm repo add groundcover https://helm.groundcover.com/
helm repo update
helm install caretta --namespace caretta --create-namespace groundcover/caretta

  5. Configure Caretta using Helm values

    main

    You can customize Caretta's behavior using Helm values. Key configuration options include:

    • pollIntervalSeconds: Specifies the polling and publishing interval of new metrics from the kernel (default: 5).
    • traverseUpHierarchy: If true (default), Caretta resolves Kubernetes entities to their owners (e.g., pods are resolved to their parent Deployment). Set to false to disable this.
    • tolerations: Used to ensure the eBPF agent runs on all nodes, including control-plane nodes. The default value tolerates common control-plane node annotations.
    • victoria-metrics-single.enabled: Enables or disables the built-in Victoria Metrics instance (default: true).
    • grafana.enabled: Enables or disables the built-in Grafana instance (default: true).
    • victoria-metrics-single.server.persistentVolume.enabled: If true, saves Victoria Metrics data to a persistent volume (default: false).
    pollIntervalSeconds: 15  # set metrics polling interval
traverseUpHierarchy: false  # disable resolving kubernetes entities to their owners

tolerations:             # set any desired tolerations
  - key: node-role.kubernetes.io/control-plane
    operator: Exists
    effect: NoSchedule

victoria-metrics-single:
  server:
    persistentVolume:
       enabled: true   # set to true to use persistent volume

  6. Query Caretta metrics with PromQL

    main

    Use these example queries to analyze network traffic in Prometheus/Grafana:

    Throughput between specific client and server (aggregated by port):

    increase ((sum (server_port) (caretta_links_observed{client_name="some-client", server_name="some-server}))[15m])

    Traffic rate from a client to all its servers:

    sum by (server_name) (rate(caretta_links_observed{client_name="some-client"}))

    Communication to external servers by client name (sorted descending):

    sort_desc(increase((sum by (client_name)(caretta_links_observed{server_namespace="external"}))[5m]))

  7. Reference: Caretta metrics and labels

    main

    Caretta publishes metrics to Victoria Metrics, which can be consumed by any Prometheus-compatible system. The primary metric is caretta_links_observed (Gauge).

    Labels for caretta_links_observed:

    • client_name: Name of Kubernetes entity, external domain, or IP address.
    • client_namespace: Namespace of the entity, or node or external.
    • client_kind: Kind of the entity, or node or external.
    • server_name: Name of the target entity, external domain, or IP address.
    • server_namespace: Namespace of the target, or node or external.
    • server_kind: Kind of the target, or node or external.
    • server_port: The destination port.
    • role: 1 for client, 2 for server.
    caretta_links_observed{client_id="1074587981",client_kind="Deployment",client_name="checkoutservice",client_namespace="demo-ng",link_id="198768460",role="1",server_id="1112713827",server_kind="Service",server_name="productcatalogservice",server_namespace="demo-ng",server_port="3550"} 2537