Resource catalog configuration

Authority manages the resource catalog, resource attributes and the boundaries within which enrolled Connectors may publish. Connectors enumerate databases and Kubernetes objects through discovery sources.

A catalog entry identifies a resource for listing, authorization and routing. Its presence does not mean a Connector is currently serving it; inspect the serving column separately. See catalog lifecycle and publishing resources.

[catalog]

Used by: Authority. Fields below are relative to [catalog] or the named nested table. Validate a file with gdsgate config check <PATH> --role authority.

Configuration and API ownership

At startup each Authority upserts the resources and scopes declared in its file. Rows absent from that file remain in the shared store. Removing a declaration from the file therefore does not delete the catalog entry. Conversely, a row that remains declared in any Authority file is restored from that declaration when that instance starts.

For an API-managed catalog, keep catalog.resources and catalog.auto_scopes empty on every Authority. Manage rows with authority resources and boundaries with authority scopes. The other [catalog] settings can remain in the file. For file-managed declarations, keep every Authority's intended declarations consistent and persist API changes in those files too.

[[catalog.resources]]: declared resources

A [[connector.backends]] entry with kind = "cockroach" (CockroachDB, port 26257) is published as kind = "postgres" with port = 26257. The catalog has no cockroach kind.

Names are unique across the catalog, native_name included. A duplicate name, declared or taken from an id, is refused at start-up, as is a tcp, mcp, llm or web-egress resource without a port.

[[catalog.import_rules]]: label and environment rules

Rules apply in order to each declared resource whose id matches the glob. The environment defaults to dev; the last matching rule sets it. Labels merge across matches; a later rule wins per key.

Reserved labels

These labels also change gdsgate behavior. Like other labels, they merge across rules and are visible to Cedar through resource.getTag(...).

Optional tenant visibility

For the complete setup and operational walkthrough, see Capsule tenant visibility. This section is the Authority settings reference.

catalog.visibility_rules is empty by default. With no rules, catalog listing continues to use Cedar view alone and does not read membership facts. Enabling collection on a Connector does not enable filtering on Authority.

To protect one Kubernetes source, configure both its collection block and a rule naming the enrolled Connector UUID and exact source ID:

[[catalog.visibility_rules]]
connector_id = "12345678-1234-1234-1234-123456789abc"
source_id = "prod-kube"
provider = "capsule"
user_claim = "sub"
include_additional_role_bindings = false
max_staleness_secs = 90
on_error = "hide"

A member must also pass Cedar view. Missing membership hides discovery without changing connect, query or Kubernetes-operation policies. Knowing a resource ID can still allow a connection when its existing policy permits it. Source associations in status contain only visible targets. Administrative catalog inspection retains its existing authorization.

For a manually declared resource, add an explicit association to the selected service or pod under that rule:

[[catalog.visibility_rules.manual_bindings]]
resource_id = "orders-db"
object_id = "service/orders-dev/database"

Both fields are required strings. The source must observe the object and verify its namespace UID against the tenant association. The binding is an operator assertion about the manual resource; gdsgate does not infer it from an address or resource label. A bound parent also restricts its database children.

Authority stores signed facts in the shared database and reads them on each listing. Every serving Authority needs the same rules and integrity keys. Restart Authority to change its rules. Reading, restarting or increasing the configured lifetime does not extend a stored observation's fixed expiry. See Connector collection settings.

Publication modes

Publication follows the enrolled Connector's assignment. The initial catalog.publication value initializes the shared default only once. gdsgate authority publication set changes the default for future enrollments; existing Connectors keep their assigned mode and namespace.

gdsgate authority nodes list
gdsgate authority scopes list --wide

For an automatic Connector, retain its assigned prefix and node when changing scope limits with authority scopes set. For a manual Connector, a discovery source's scope must match the prefix of a boundary assigned to its Registry UUID.

Scopes restrict publication; resource visibility and session access are still controlled by policy. Associating a discovery source with an accessible backend adds no inherited permission to that backend or its children.

[[catalog.auto_scopes]]: publication boundaries

Each scope permits one enrolled node to write catalog rows inside its prefix, subject to kinds, attributes, limits and a renewable lease. This supports short-lived resources, including discovered databases and Kubernetes targets. Use the Registry UUID from authority nodes list for node.

A scope with ssh in kinds must specify onward_auth. A scope prefix cannot overlap a manually declared resource or another scope. Invalid declarations are refused at startup and by authority scopes set.

authority scopes set replaces a scope declaration: supply every intended kind, onward mode, label and limit. Disabling a scope removes its published rows. Keep file-managed declarations synchronized with API changes as described above.

Choosing max_live

A row missing from a new snapshot remains until its lease expires. A source that replaces all its targets on each pass can leave up to this many rows:

targets_per_pass × (1 + lease_secs / interval_secs)

For 300 targets, a 300-second probe interval and a 900-second lease, allow 1200 rows. A lower ceiling can refuse the full snapshot until earlier leases expire. Narrow discovery filters, reduce the lease or raise max_live.

A catalog row can remain for up to catalog.lease_sweep_secs after its lease expires. Listings show the remaining lease and mark an unswept row expired. A returning resource must be admitted again before it becomes available.

Connector discovery

Configure probe credentials, filters, intervals and backend connection settings on the Connector. The discovery-source guide covers PostgreSQL and Kubernetes source-only discovery and optional parent connections. The Connector reference lists the fields.

PostgreSQL list_databases sources publish separately accessible database resources. Kubernetes list_kube_targets sources publish the selected services, pods or nodes. A source itself has no connect address. An associated server or API is a separate resource with its own access decision.

For publication failures, check the Connector's refusal reason and authority scopes list --wide: the node, prefix, enabled state, allowed kinds and live-row ceiling must agree. Successful publication does not establish permission to connect; check resource policy and backend permissions separately.

A full catalog example

[catalog]
publication = "manual"
lease_sweep_secs = 60

[[catalog.resources]]
id = "orders-db"
kind = "postgres"
project = "payments"
min_approvers = 2

[[catalog.import_rules]]
match = "orders-*"
environment = "prod"
labels = { service = "orders" }

[[catalog.auto_scopes]]
id_prefix = "database."
node = "11111111-1111-4111-8111-111111111111"
kinds = ["postgres"]
project = "payments"
environment = "prod"
labels = { service = "orders" }
max_live = 100
lease_secs = 300

The declared resource and publication scope have separate IDs. The Connector uses scope = "database." for a manual database source; configure the probe and its session role using the discovery-source guide.

Migrating from [discovery]

[catalog] is the canonical name from 0.11.0-rc.8. The former top-level [discovery] section remains supported with a deprecation warning. Rename that section and its nested tables, keeping their values unchanged:

A document containing both top-level names is refused, including when either section is empty. Keep a single [catalog] section. Update the binary before renaming an existing file; rc.7 uses the previous spelling.

Connector discovery_sources and its nested discovery probe tables retain their names. Resource IDs, serving assignments, authorization rules and catalog lifecycle are unchanged by the section rename.