Registering Kubernetes Clusters

Shoehorn discovers Kubernetes workloads through lightweight agents deployed to each cluster. This guide covers registering a cluster and deploying the agent.

Overview

The registration flow:

1. Register the cluster in Shoehorn (creates an agent token)
2. Deploy the K8s agent to the target cluster with the token
3. The agent watches workloads and pushes data to Shoehorn
4. Entities are automatically created in the service catalog

Register via UI

1. Navigate to Admin > K8s Agents
2. Click Register Cluster
3. Fill in:
   • Cluster ID: short slug used in the agent install (e.g. prod-eu)
   • Cluster Name: human-readable label shown in the UI (e.g. Production EU)
   • Description: optional notes
   • Token Expiration: how long the agent token is valid
4. Click Register
5. Copy the generated agent token. It is shown only once.

Register via API

curl -X POST https://shoehorn.example.com/api/v1/k8s/agents \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "cluster_id": "prod-eu",
    "cluster_name": "Production EU",
    "description": "Production cluster in EU",
    "token_expiration": "90d"
  }'

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "cluster_id": "prod-eu",
  "cluster_name": "Production EU",
  "agent_token": "shp_agent_xxxxxxxxxxxx",
  "status": "pending"
}

Deploy the Agent

See Deploying the K8s Agent for full Helm installation instructions.

Quick install:

helm install shoehorn-k8s-agent oci://ghcr.io/shoehorn-dev/helm-charts/shoehorn-k8s-agent \
  --namespace shoehorn --create-namespace \
  --set shoehorn.apiURL=https://shoehorn.example.com \
  --set shoehorn.apiToken=shp_agent_xxxxxxxxxxxx \
  --set shoehorn.cluster.id=prod-eu \
  --wait

Agent Status

Once deployed, the agent reports its status via heartbeats. View agent health in Admin > K8s Agents:

Status	Meaning
Connected	Agent is actively pushing data
Stale	No heartbeat in the last 5 minutes
Disconnected	No heartbeat in the last 15 minutes
Pending	Registered but agent not yet deployed

Namespace Filtering

By default, the agent watches all namespaces. To exclude system namespaces:

config:
  excludeNamespaces:
    - kube-system
    - kube-public
    - kube-node-lease
    - cert-manager

Entity Auto-Creation

When the agent discovers a workload, Shoehorn automatically:

1. Creates a catalog entity (if it does not exist)
2. Sets the entity type based on workload kind
3. Extracts metadata from annotations (see Annotations Reference)
4. Detects lifecycle stage from namespace name
5. Tags the entity with the cluster it came from
6. Links the entity to the cluster

Lifecycle Detection from Namespace

Namespace Pattern	Lifecycle
production, prod-*	production
staging, stage-*	staging
dev-*, develop*	development
test, qa, sandbox	experimental
kube-system, argocd, flux-system	experimental
All others	experimental

Managing Clusters

Rotate Agent Token

If a token is compromised:

1. Navigate to Admin > K8s Agents
2. Select the cluster
3. Click Rotate Token
4. Update the agent deployment with the new token

Remove a Cluster

1. Uninstall the agent from the cluster
2. Navigate to Admin > K8s Agents
3. Select the cluster and click Delete

Entities discovered from the cluster are not automatically deleted. Remove them manually or via the API if needed.

Multiple Clusters

Register each cluster separately, one ID per cluster. Pick IDs that read well in the UI:

prod-us
prod-eu
staging
dev

Each agent pushes independently. Entities are tagged with their source cluster for filtering.