4. First entity

The catalog is empty until you give it something to discover. Two paths, you can do both:

• Connect a Kubernetes cluster with the K8s agent. Every workload becomes an entity automatically.
• Drop a manifest in a Git repository. The crawler reads .shoehorn/manifest.yml and creates an entity.

Connect a cluster

If you used the Terraform module with deploy_agent = true, the agent is already running on the same cluster as the platform. Skip ahead to “Verify the agent.”

If not, install the agent.

Register the cluster

In the UI, go to Admin → K8s Agents → Register cluster. Fill in:

• ID: a short slug, for example prod-eu or dev-laptop
• Name: a human-readable label

You get a one-time token. Copy it. You won’t see it again.

Install the agent

helm install shoehorn-agent oci://ghcr.io/shoehorn-dev/helm-charts/shoehorn-k8s-agent \
  --namespace shoehorn --create-namespace \
  --set shoehorn.apiURL=https://<your-domain> \
  --set shoehorn.apiToken=<token-from-registration> \
  --set shoehorn.cluster.id=<cluster-id> \
  --wait

Verify the agent

kubectl get pods -n shoehorn -l app=shoehorn-k8s-agent
kubectl logs -n shoehorn -l app=shoehorn-k8s-agent --tail=20

Within about a minute, your workloads start appearing in the Shoehorn UI under Catalog. See the K8s Agent reference for namespace filtering, HA, and GitOps discovery.

Drop a manifest

If you don’t want to connect a cluster yet, you can register a service by hand. Add .shoehorn/manifest.yml to any repository the platform watches:

schemaVersion: 1

service:
  id: payment-api
  name: Payment API
  type: service
  tier: high

owner:
  - type: team
    id: payments

lifecycle: production

links:
  - name: Repository
    url: https://github.com/acme/payment-api
    icon: GitHub

The GitHub integration (set up in step 1) pulls in manifests on the next crawl. If you haven’t configured GitHub yet, register the entity via the API instead:

curl -X POST https://<your-domain>/api/v1/entities \
  -H "Authorization: Bearer $SHOEHORN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"payment-api","type":"service","lifecycle":"production","owner":"payments"}'

See Manifests and Entities for the full reference.

What you’ll do next

See what to set up next →