Shared Configuration Options

Learn how Coordimap shared configuration works, including data_source_id, scope_id, and crawl_interval for stable asset identity across cloud and database crawlers.

This page documents the configuration fields that appear across multiple Coordimap data sources. Use it as the reference for fields that affect identity, crawl timing, credentials, and cross-source relationship mapping.

What Is `scope_id`?

scope_id is the stable identity of the upstream system boundary that Coordimap is crawling.

Think about it this way:

data_source_id identifies the connector configuration you created in Coordimap.
scope_id identifies the real system that owns the assets.

That distinction matters because Coordimap builds internal asset IDs from the upstream identity, not from the connector record. If you delete and recreate a data source, keeping the same scope_id allows Coordimap to keep those asset identities stable.

Why this matters

A correct scope_id prevents duplicate assets, keeps internal names stable, and makes cross-source mappings such as flow telemetry attach to the right infrastructure.

`data_source_id`

data_source_id is created by Coordimap when you add a data source in the UI. Use it to tell the agent which connector configuration it should send data for.

Do not use data_source_id as a replacement for scope_id. They serve different purposes.

`scope_id`

Every data source should provide a scope_id that comes from the platform being crawled.

Use the most stable upstream identity available:

Kubernetes: cluster UID
GCP: project number
AWS: account ID
PostgreSQL: system identifier
MySQL or MariaDB: server UUID
MongoDB: replica set or cluster identity

What Is `external_mappings`?

external_mappings is used when one integration needs help relating observed identities back to another scoped system.

In plain terms, it is a manual hint that tells Coordimap, "when you see this value from one integration, treat it as belonging to that other identity boundary."

The format is:

<mapping-key>@<mapping-value>

Examples:

europe-west1-my-gke-cluster@6f5f56e3-0123-4567-89ab-6c8f1e2a0cde
*@6f5f56e3-0123-4567-89ab-6c8f1e2a0cde
gke-node-pool-a@gcp-production

Interpretation depends on the integration:

In GCP flow mappings, the key may be a GKE-related identifier seen in flow metadata, while the value should be the Kubernetes cluster UID used as scope_id.
In the eBPF flows datasource running in Kubernetes mode, the value should point to the Kubernetes cluster UID so runtime traffic attaches to the correct cluster assets.
In Kubernetes-related cloud mappings, the value may point to another datasource or stable external identity used for correlation.

The safest rules are:

keep the key exactly aligned with what the upstream system emits
keep the value stable
when mapping to Kubernetes scope, use the Kubernetes cluster UID

Recommended `scope_id` by Data Source

Data source	Recommended `scope_id`	Where it comes from	Typical asset path
Kubernetes	`cluster_uid`	Kubernetes API cluster identity	`namespace/type/name`, `type/name` for cluster-wide assets
GCP	`project_number`	GCP project metadata or API	`zone/vm_instance/name`, `region/bucket/name`, `region/sql/name`
AWS	`account_id`	AWS STS caller identity	`region/ec2/instance-id`, `region/rds/db-arn`, `global/s3/bucket-name`
PostgreSQL	`system_identifier`	PostgreSQL server or cluster identity	`database/schema/table`, `database/schema/index`
MySQL or MariaDB	`server_uuid`	MySQL or MariaDB server identity	`database/schema/table`, `database/schema/index`
MongoDB	replica set or cluster ID	Replica set or cluster identity	`database/collection`, `database/collection/index`

How To Find Your `scope_id`

Use these commands and conventions when you configure a new data source.

Kubernetes

Use the cluster UID:

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

GCP

Use the project number:

gcloud projects describe PROJECT_ID --format='value(projectNumber)'

AWS

Use the AWS account ID:

aws sts get-caller-identity --query Account --output text

PostgreSQL

Use the PostgreSQL system identifier:

SELECT system_identifier FROM pg_control_system();

If pg_control_system() is not available in your environment, retrieve the value with PostgreSQL system tooling such as pg_controldata.

MySQL Or MariaDB

Use the server UUID:

SHOW VARIABLES LIKE 'server_uuid';

If server_uuid is not available, use an explicitly configured stable value.

MongoDB

Use a replica set or cluster identity when your deployment exposes one:

rs.conf()
rs.status()

If no immutable ID is available, the replica set name is an acceptable fallback. For standalone MongoDB deployments, use an explicitly configured stable scope_id.

`crawl_interval`

crawl_interval controls how often the agent crawls a data source for changes.

Examples:

45s for 45 seconds
3m for 3 minutes

Default value

The default value is 30s.

Recommended value

For data sources that change infrequently, prefer a crawl interval of several minutes to reduce unnecessary API or database load.

Cloud Authentication And Region Fields

Some cloud data sources support additional environment and targeting options.

Field	Used by	Description
`in_cloud`	GCP	Set to `"true"` when the agent runs on Google Cloud and should use metadata-service authentication instead of a credentials file.
`include_regions`	GCP	Optional comma-separated list of regions to crawl, such as `europe-west1,us-central1`. Use this to limit crawl scope.
`policy_config`	AWS	Set to `"true"` when the agent should use the host's AWS credential chain or attached IAM role.

Cross-Source Mapping Fields

Some data sources can map database, Kubernetes, cloud, or flow assets back to another source. These fields should be used carefully because they affect graph relationships.

Field	Used by	Description
`cloud_data_source_id`	Kubernetes	Optional cloud data source identifier used for node-to-cloud mapping.
`mapping_data_source_id`	MariaDB and related database mappings	Optional external data source identifier for connecting database metadata to a cloud-side SQL instance.
`mapping_internal_id`	PostgreSQL, MariaDB, and related database mappings	Optional internal asset identifier for connecting a crawled database to an existing infrastructure object.
`external_mappings`	Kubernetes, GCP, eBPF flows, metric rules	Manual identity mappings in `<mapping-key>@<mapping-value>` format.

Prometheus And Metrics Fields

Kubernetes data sources can use Prometheus endpoints for metric rules and flow enrichment.

Field	Used by	Description
`prometheus_host`	Kubernetes	Optional Prometheus endpoint, commonly used for service metrics such as Istio request metrics.
`metrics_prometheus_host`	Kubernetes	Optional Prometheus endpoint used by metric rule evaluation when supported by the deployed agent version.
`retina_prometheus`	Kubernetes	Optional Retina Prometheus endpoint for Kubernetes flow telemetry.

`id` Versus `data_source_id`

Some public agent repository examples still show data source entries with id. These docs standardize on data_source_id because it names the Coordimap connector identifier more explicitly.

If your deployed agent version expects id, keep using the field your version supports. Do not confuse either field with scope_id; the scope_id must still come from the upstream system identity.