Kubernetes Annotations Reference

The Shoehorn K8s Agent reads annotations and labels from Kubernetes workloads to enrich entity metadata in the service catalog. This document covers all supported annotations.

Entity File Annotation

Point to a manifest file in your repo for full entity enrichment (relations, links, runbooks, licenses, interfaces). The API fetches it server-side - no structured data stored in K8s.

annotations:
  # Relative path (resolved against known repo URL from ArgoCD/Flux/crawler)
  shoehorn.dev/entityFile: ".shoehorn/catalog.yaml"

  # Full URL (for files in a different repo)
  shoehorn.dev/entityFile: "https://github.com/acme/shared-configs/blob/main/.shoehorn/checkout.yaml"

  # Multi-service file with fragment selector
  shoehorn.dev/entityFile: ".shoehorn/platform.yaml#checkout-api"

For details on manifest file format and enrichment modes, see Entity Enrichment Modes.

Ownership Annotations

These annotations determine which team owns a workload. They are checked in priority order (first match wins):

Key	Type	Priority	Example
`shoehorn.dev/owner`	Label or Annotation	1	`platform-engineering`
`shoehorn.dev/team`	Label or Annotation	2	`infrastructure-team`
`owner`	Label or Annotation	3	`payments-team`
`app.kubernetes.io/owner`	Label only	4	`data-team`

If no annotation matches, the agent attempts namespace pattern matching (e.g., platform-team-production extracts platform). The final fallback is unassigned.

# Recommended approach
labels:
  shoehorn.dev/owner: "payments-team"

Description Annotation

Provides a human-readable description for the entity.

Key	Priority
`shoehorn.dev/description`	1
`description`	2
`app.kubernetes.io/description`	3

annotations:
  shoehorn.dev/description: "Handles payment processing and card transactions"

Tags Annotation

Comma-separated tags for categorizing entities.

Key	Format
`shoehorn.dev/tags`	Comma-separated values

annotations:
  shoehorn.dev/tags: "critical, financial, pci-compliant"

The agent also automatically adds tags from:

Cluster metadata: cluster:<name>, env:<environment>, provider:<provider>, region:<region>
Kubernetes labels: app, app.kubernetes.io/name, app.kubernetes.io/component, app.kubernetes.io/part-of

External Link Annotations

Link entities to external tools and dashboards. All link annotations use the link.shoehorn.dev/ prefix.

ArgoCD

annotations:
  link.shoehorn.dev/argocd-url: "https://argocd.example.com/applications/my-app"
  link.shoehorn.dev/argocd-name: "ArgoCD Application"  # Optional, default: "ArgoCD"
  link.shoehorn.dev/argocd-icon: "argocd"               # Optional, default: "argocd"

Grafana

annotations:
  link.shoehorn.dev/grafana-url: "https://grafana.example.com/d/abc123"
  link.shoehorn.dev/grafana-name: "Service Metrics"     # Optional, default: "Grafana Dashboard"
  link.shoehorn.dev/grafana-icon: "grafana"              # Optional, default: "grafana"

Prometheus

annotations:
  link.shoehorn.dev/prometheus-url: "https://prometheus.example.com"
  link.shoehorn.dev/prometheus-name: "Metrics Query"     # Optional, default: "Prometheus Metrics"
  link.shoehorn.dev/prometheus-icon: "prometheus"         # Optional, default: "prometheus"

Custom Links (Single)

annotations:
  link.shoehorn.dev/url: "https://docs.example.com/my-service"
  link.shoehorn.dev/name: "Documentation"               # Optional, default: "Custom Link"
  link.shoehorn.dev/icon: "docs"                         # Optional, default: "link"

Custom Links (Multiple)

Add numbered suffixes for additional links:

annotations:
  # First link (no suffix)
  link.shoehorn.dev/url: "https://docs.example.com"
  link.shoehorn.dev/name: "Documentation"
  link.shoehorn.dev/icon: "docs"

  # Second link
  link.shoehorn.dev/url.2: "https://status.example.com"
  link.shoehorn.dev/name.2: "Status Page"
  link.shoehorn.dev/icon.2: "dashboard"

  # Third link
  link.shoehorn.dev/url.3: "https://runbook.example.com"
  link.shoehorn.dev/name.3: "Runbook"
  link.shoehorn.dev/icon.3: "docs"

Supported Icon Values

Icons are case-insensitive. Supported values:

Category	Icons
Source Control	`github`, `gitlab`
Monitoring	`grafana`, `datadog`, `prometheus`, `sentry`, `jaeger`
CI/CD	`argocd`, `jenkins`
Cloud	`aws`, `azure`, `gcp`, `kubernetes`, `k8s`, `docker`, `dockerhub`, `terraform`
Communication	`slack`, `discord`, `teams`, `zoom`
Project Management	`jira`, `linear`, `pagerduty`
Documentation	`confluence`, `notion`, `docs`, `wiki`
Generic	`api`, `database`, `dashboard`, `monitor`, `source`, `repository`, `repo`, `url`, `link`, `external`, `code`, `http`

Interface Annotations

Define APIs and contracts for the entity.

HTTP / OpenAPI

annotations:
  shoehorn.dev/interface.http.openapi: "https://api.example.com/openapi.json"
  shoehorn.dev/interface.http.base-url: "https://api.example.com/v1"   # Optional
  shoehorn.dev/interface.http.version: "2.0.0"                         # Optional

gRPC

annotations:
  shoehorn.dev/interface.grpc.protos: "https://example.com/user.proto, https://example.com/auth.proto"
  shoehorn.dev/interface.grpc.package: "com.example.api"               # Optional
  shoehorn.dev/interface.grpc.services: "UserService, AuthService"     # Optional

GraphQL

annotations:
  shoehorn.dev/interface.graphql.schema: "https://example.com/schema.graphql"

AsyncAPI (Events)

annotations:
  shoehorn.dev/interface.events.asyncapi: "https://example.com/asyncapi.yaml"

Legacy

The legacy shoehorn.dev/definition-url annotation is supported for backward compatibility and maps to interface.http.openapi. New annotations take precedence.

annotations:
  shoehorn.dev/definition-url: "https://api.example.com/openapi.json"

Complete Example

A production deployment with all annotation categories:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: payment-service
  namespace: production
  labels:
    app: payment-service
    shoehorn.dev/owner: "payments-team"
  annotations:
    # Description
    shoehorn.dev/description: "Handles payment processing and card transactions"

    # Tags
    shoehorn.dev/tags: "critical, financial, pci-compliant"

    # External links
    link.shoehorn.dev/argocd-url: "https://argocd.example.com/applications/payment-service"
    link.shoehorn.dev/grafana-url: "https://grafana.example.com/d/payment-metrics"
    link.shoehorn.dev/url: "https://wiki.example.com/payment-service"
    link.shoehorn.dev/name: "Wiki"
    link.shoehorn.dev/icon: "wiki"

    # Interfaces
    shoehorn.dev/interface.http.openapi: "https://api.example.com/payment/openapi.json"
    shoehorn.dev/interface.http.base-url: "https://api.example.com/payment/v1"
    shoehorn.dev/interface.grpc.protos: "https://repo.example.com/protos/payment.proto"
    shoehorn.dev/interface.grpc.services: "PaymentService, RefundService"
spec:
  replicas: 3
  selector:
    matchLabels:
      app: payment-service
  template:
    metadata:
      labels:
        app: payment-service
    spec:
      containers:
        - name: payment-service
          image: ghcr.io/example/payment-service:v1.2.0

Summary Table

Annotation	Purpose	UI Location
`shoehorn.dev/entityFile`	Manifest file for full enrichment	All entity fields
`shoehorn.dev/owner`	Team ownership	Entity owner field
`shoehorn.dev/description`	Service description	Entity description
`shoehorn.dev/tags`	Categorization tags	Entity tags
`link.shoehorn.dev/argocd-url`	ArgoCD link	External links
`link.shoehorn.dev/grafana-url`	Grafana link	External links
`link.shoehorn.dev/prometheus-url`	Prometheus link	External links
`link.shoehorn.dev/url`	Custom link	External links
`link.shoehorn.dev/url.N`	Additional custom links	External links
`shoehorn.dev/interface.http.openapi`	OpenAPI spec URL	Interfaces tab
`shoehorn.dev/interface.http.base-url`	HTTP base URL	Interfaces tab
`shoehorn.dev/interface.http.version`	API version	Interfaces tab
`shoehorn.dev/interface.grpc.protos`	gRPC proto URLs	Interfaces tab
`shoehorn.dev/interface.grpc.package`	gRPC package	Interfaces tab
`shoehorn.dev/interface.grpc.services`	gRPC service names	Interfaces tab
`shoehorn.dev/interface.graphql.schema`	GraphQL schema URL	Interfaces tab
`shoehorn.dev/interface.events.asyncapi`	AsyncAPI spec URL	Interfaces tab
`shoehorn.dev/definition-url`	Legacy OpenAPI URL	Interfaces tab