Annotations & Labels

Annotations and labels control how RGDs appear in the catalog, how users can deploy them, and who can see them.

• Annotations store catalog metadata and configuration (discovery, deployment modes)
• Labels control visibility scoping (organization, project membership)

Annotations

Required Annotation

Without this annotation, the RGD is invisible to everyone in the catalog.

metadata:
  annotations:
    knodex.io/catalog: "true" # Must be exactly "true" (string)

Metadata Annotations

Enhance how your RGD appears in the catalog UI:

The knodex.io/title annotation provides a human-readable display name for the catalog. When set, the title appears in place of the Kubernetes resource name on catalog cards, detail views, and the deploy page. The Kubernetes name is shown as a subtitle or tooltip for reference. Search also matches against the title. If the annotation is absent or empty, the metadata.name is used as the title (backward compatible).

Supported Categories and Icons

The knodex.io/category annotation determines both the category label and the icon displayed in the catalog:

Category values are case-insensitive. Database, DATABASE, and database are equivalent.

Deployment Mode Annotations

Control which deployment modes are available for an RGD.

Deployment Modes

GitOps Only (Production RGDs):

metadata:
  annotations:
    knodex.io/catalog: "true"
    knodex.io/deployment-modes: "gitops"

When only one mode is allowed, the UI:

• Auto-selects that mode
• Disables the mode selector
• Shows an info banner: "This RGD restricts deployment to: GitOps only"

Default Behavior

If knodex.io/deployment-modes is missing or empty, all deployment modes are allowed. This ensures existing RGDs continue to work without modification.

Parsing Rules

• Case-insensitive: GITOPS, GitOps, and gitops are equivalent
• Whitespace-tolerant: "direct, gitops" works the same as "direct,gitops"
• Invalid values ignored: Unknown modes are logged as warnings but don't cause errors
• Deduplication: Duplicate values are removed

Labels

Organization Label

Scope an RGD to a specific organization in multi-tenant deployments.

metadata:
  labels:
    knodex.io/organization: orgA # Only visible to orgA
  annotations:
    knodex.io/catalog: "true"

When set, the RGD is visible only to the matching organization. RGDs without this label are shared across all organizations.

knodex.io/organization must be a label, not an annotation. The server reads it from metadata.labels only.

See Organizations for the full multi-tenant configuration guide.

Project Label

Restrict RGD visibility to members of a specific project.

metadata:
  labels:
    knodex.io/project: proj-payments-team # Only project members can see this
  annotations:
    knodex.io/catalog: "true"

The label value must match the project namespace name exactly (e.g., proj-alpha-team), not the display name.

See Project Scoping for detailed visibility rules.

Complete Example

An RGD with all metadata annotations, organization scoping, and project visibility:

metadata:
  name: postgres-ha-cluster
  labels:
    knodex.io/organization: orgA # Enterprise: restricts to org
    knodex.io/project: proj-platform-team # Restricts to project members
  annotations:
    knodex.io/catalog: "true"
    knodex.io/title: "PostgreSQL HA Cluster"
    knodex.io/description: "Production-ready PostgreSQL with streaming replication"
    knodex.io/tags: "database,postgres,ha,production"
    knodex.io/category: "database"
    knodex.io/version: "2.1.0"
    knodex.io/deployment-modes: "gitops"

Reference

Annotation Summary

Label Summary

Visibility Filter Chain

Filters apply in this order:

1. Catalog flag - knodex.io/catalog: "true" required
2. Organization filter - Match knodex.io/organization label (Enterprise only)
3. Project filter - Match knodex.io/project label

An RGD must pass all applicable filters to appear in a user's catalog.

Next: Schema & UI →