Kubernetes Configuration

Configuring A Kubernetes Data Source In Coordimap

This guide explains how to configure the Coordimap agent to crawl a Kubernetes cluster. Once configured, Coordimap can discover namespaces, workloads, services, ingresses, and other cluster resources, then turn that inventory into diagrams that stay current as the cluster changes.

The most important Kubernetes-specific setting is scope_id. For Kubernetes, scope_id should be the cluster UID, not the Coordimap data source id and not a friendly label.

Prerequisites

Before you begin, make sure you have:

1. Installed the Coordimap agent in an environment that can reach the Kubernetes API server.
2. Added the Kubernetes data source in the Coordimap UI so you have an id.
3. Chosen whether the agent will connect in-cluster or through a kubeconfig file.

Find The Correct scope_id

Use the Kubernetes cluster UID:

kubectl get namespace kube-system -o jsonpath='{.metadata.uid}'

Use that value as the Kubernetes scope_id everywhere you need to refer to Kubernetes internal names.

Configuration File

coordimap:
  api_key: ${COORDIMAP_API_KEY}
  data_sources:
    - type: kubernetes
      id: <YOUR_DATA_SOURCE_ID_FROM_UI>
      config:
        - name: scope_id
          value: "<KUBERNETES_CLUSTER_UID>"
        - name: in_cluster
          value: "true"
        - name: config_file
          value: "/path/to/kubeconfig"
        - name: crawl_interval
          value: "5m"
        - name: cluster_name
          value: "production-cluster"
        - name: cloud_data_source_id
          value: "gcp-production"
        - name: prometheus_host
          value: "http://prometheus.istio-system.svc:9090"
        - name: metrics_prometheus_host
          value: "http://prometheus.monitoring.svc:9090"
        - name: retina_prometheus
          value: "http://retina-prometheus.monitoring.svc:9090"
        - name: external_mappings
          value: "gke-node-pool-a@<GCP_DATA_SOURCE_ID>"

Use either in_cluster or config_file based on where the agent runs. If the agent runs inside the cluster, in_cluster: "true" is the normal choice.

Configuration Options

Visualizing Network Flows With Retina

To visualize service-to-service and pod-to-pod traffic in Kubernetes, install Retina and configure the agent to read from the Retina Prometheus endpoint.

If you also configure cloud flow sources or external mappings, make sure those mappings reuse the same Kubernetes scope_id value. That is how Coordimap knows that the flow data and the discovered cluster objects belong to the same identity space.

Understanding external_mappings

external_mappings is used when Kubernetes-discovered assets need to be related to identities coming from outside the cluster.

The format is:

<mapping-key>@<mapping-value>

Example:

gke-node-pool-a@gcp-production

In practical terms, this tells Coordimap that a Kubernetes-side identity should be associated with an external cloud-side identity. The exact meaning of the mapping key depends on the integration producing the related flow or infrastructure metadata, so the safest rule is to keep the mapped values stable and aligned with the upstream system that owns them.

When you are mapping back to Kubernetes cluster scope from another integration, the target value must ultimately resolve to the Kubernetes cluster UID used as scope_id.

Learn how to install and configure Retina here: Kubernetes Retina Configuration.

Related Reading

• Shared Configuration Options
• Metric Trigger Rules
• GCP Flow Logs

Source References

• Coordimap Agent Example Configuration
• Kubernetes Namespace Documentation

FAQ

What should Kubernetes use as scope_id?

Use the Kubernetes cluster UID, retrieved from the kube-system namespace. This keeps Kubernetes internal names stable across Coordimap connector changes.

Should I use in_cluster or config_file?

Use in_cluster: "true" when the agent runs inside the target cluster. Use config_file when the agent runs outside the cluster and connects with a kubeconfig file.

How do Kubernetes flow mappings attach to the right cluster?

Mappings that refer back to Kubernetes should ultimately use the same cluster UID as the Kubernetes scope_id. If the values differ, flow telemetry may not attach to the expected Kubernetes objects.